Merge pull request #60 from chargebee/dev

Dev

.gitignore

@@ -19,3 +19,4 @@ hs_err_pid*
 /build
 /.idea/
 /generated/
+/.DS_Store

README.md

@@ -1,73 +1,40 @@
-## Chargebee's Open API Spec
-Service Provider Interfaces for Chargebee's capabilities
-- [Open api tax_spec](spec/spi/openapi_tax.yml)
-- [Open api trn_validation_spec](spec/spi/openapi_trn.yml)
-- To view open api spec visit https://editor.swagger.io/ and place generated yaml content
-
-## Add new open api spec
-- Add **openapi.yml** file under `spec/spi/` folder, like spec/spi/**abc**
-- Add config details in [spec.config](spec.config) file
-- Command to validate open api spec `sh gradlew validateSpec_abc --warning-mode all --stacktrace`
-- Command to generate open api spec `sh gradlew generateSpec_abc --warning-mode all --stacktrace`
-- Java models, clients and doc will be generated under `generated/abc` folder
-- 
-
-## Commands
-- Validate the open api spec `sh gradlew validateSpec --warning-mode all --stacktrace`
-- Generate models, api client, docs etc `sh gradlew generateSpec --warning-mode all --stacktrace`
-    - New folder `generated` will be created which will have all models, clients, docs etc
-- Build `sh gradlew build` spi jar will be generated to ./build/libs/cb-provider-spi.jar
-- Publish jar to local maven repo `sh gradlew build publishToMavenLocal`
-
-## Working on Service Adapter SPI for first time
-
-Follow the below steps for generating jar
-
-Clone repository in local
-```shell
-  git clone git@github.com:chargebee/cb-provider-spi.git
-```
+## What is Partner SPIs?
+Chargebee supports a wide range of third-party integrations to deliver enhanced functionalities to its customers. To facilitate this, Chargebee provides Service Provider Interfaces (SPIs), defined in the OpenAPI specification, for various capabilities.
 
-Validate open api specs using below command
-```shell
-sh gradlew validateSpec  --warning-mode all --stacktrace
-```
+Chargebee Partners can leverage these SPIs to develop apps that seamlessly integrate with Chargebee, extending its core capabilities to meet diverse business needs.
 
-Validate specific open api spec using below command
-```shell
- sh gradlew validateSpec_tax  --warning-mode all --stacktrace
-```
 
-Generate models of all open api specs using below command
-```shell
-sh gradlew generateSpec  --warning-mode all --stacktrace
-```
+## What are the available Chargebee Partner SPIs? 
+Currently, Chargebee offer SPIs for the following capabilities:
 
-Generate models specific open api spec using below command
-```shell
-sh gradlew generateSpec_tax  --warning-mode all --stacktrace
-```
+- [Tax](https://chargebee.mintlify.app/api-reference/v2/docs/Overview) <!-- should we have a better name for this? -->
+- [Tax Registration Number Validation](https://chargebee.mintlify.app/api-reference/v2/docs/Overview)
 
-When models are generated successfully, generate jar using below command
-```shell
-sh gradlew clean build
-```
-If no build issue, and if jar is successfully created, go to **./build/libs/cb-provider-spi.jar**
+These SPIs allow partners to build custom apps by implementing the SPI-defined endpoints. The detailed OpenAPI specifications for these SPIs can be found in the spec/spi folder of the repository:
 
+- [Tax SPI](./spec/spi/openapi_tax.yml) 
+- [Tax Registration Number Validation SPI](./spec/spi/openapi_trn.yml)
 
 ## Getting Started
 
-Please follow the installation instruction of generated readme to generate the jar of this project. Currently, this jar is used as a dependency in chargebee-app too to use APIs as well as models.
+This jar can be added as a dependency in your Java application to use APIs as well as models.
+
+### Maven
 
-Add dependency
 ```maven
 <dependency>
-    <groupId>org.chargebee.spi</groupId>
-    <artifactId>cb-provider-spi</artifactId>
+    <groupId>com.chargebee</groupId>
+    <artifactId>cb-partner-spis</artifactId>
     <version>${version}</version>
 </dependency>
 ```
 
+### Gradle
+
+```gradle
+implementation 'com.chargebee:cb-partner-spis:${version}'
+```
+
 Following sample Java code demonstrates how to use the APIs and models from this project:
 
 ```java
@@ -112,19 +79,23 @@ public class Example {
 
 ```
 
-
 ## JSON Schema validation
-Tax provider capabilities for new tax providers will be validated against a constantly updating JSON Schema, to validate the correctness and completeness of configurations. JSON Schema can be referenced below.
-- [TaxProviderCapabilities JSONSchema](spec/capabilities/tax-provider.schema.json)
+The capabilities of the built apps will be validated against a constantly updating JSON Schema, to validate the correctness and completeness of configurations. JSON Schema can be referenced [here](spec/capabilities/tax-provider.schema.json).
 
-## Steps to follow release
 
+Run the below script to perform json schema validation:
+```shell
+  sh json_schema_validation.sh <path to json file>
+```
+Example:
+```shell
+  sh json_schema_validation.sh spec/capabilities/tax-provider.file.json
+```
+
+## Chargebee Developer Docs
 
-1. Assume release is 0.0.9. (find release from git page release section)
-2. create a new branch called release/<release> so this would be release/0.0.9
-3. create new branch for ticket feat/<ticket-number>
-4. commit to  feat/<ticket-number>
-5. Raise PR from feat/<ticket-number> to release/0.0.9
-6. After PR is approved and merged
-7. Raise PR from release/0.0.9 to dev. Once PR is merged it will auto release the 0.0.9 version of SPI for dev code base
-8. After that raise PR from release/0.0.9 to main. Once PR is merged it will auto release the 0.0.9 version of SPI for prod codebase
+- [Local Setup](docs/local-setup.md)
+- [Add or Update a SPI](docs/add-update-spi.md)
+- [Update Mintlify Files](docs/mintlify-files.md)
+- [Postman Collection](docs/postman-collection.md)
+- [Release](docs/release.md)

api-reference/partner-spis/overview.mdx

@@ -0,0 +1,17 @@
+---
+title: 'Overview'
+---
+
+**Partner SPIs** are designed to enable seamless integration with Chargebee, allowing partners to extend and enhance the platform's functionality. These SPIs offer a standardized interface for partners to connect their services, enabling efficient workflows and exceptional user experience.
+They are built for scalability and easy integration, helping partners deliver specialized functionality that caters to Chargebee's diverse customer needs.
+
+You can explore the OpenAPI specifications for Partner SPIs in the GitHub repository [here](https://github.com/chargebee/cb-provider-spi).
+
+## Key Features of Partner SPIs
+
+1. **Tax Calculation**  
+   Integrate tax computation services effortlessly to ensure compliance and achieve real-time accuracy.
+2. **Tax Reconciliation**
+   Submit invoice and credit note data to external systems for tax reconciliation.
+3. **Tax Registration Number Validation**  
+   Validate tax registration numbers instantly to simplify customer onboarding and meet compliance requirements.

api-reference/tax-reg-number-validate/docs/overview.mdx

@@ -0,0 +1,14 @@
+# Tax Registration Number Validate SPI Integration
+
+The **Tax Registration Number Validate Service Provider Interface (SPI)** enables seamless communication between Chargebee and external API platforms offering tax-related services.
+
+You can refer the spec file for this spi [here](https://github.com/chargebee/cb-provider-spi/blob/main/spec/spi/openapi_trn.yml).
+
+This SPI allows Chargebee to efficiently validate tax registration numbers for merchants, supporting both individual and batch validation processes.
+
+This document provides a comprehensive overview for third-party users looking to integrate their API platforms with Chargebee's Tax Registration Number Validation Service, ensuring a secure and smooth validation experience for merchants within the Chargebee ecosystem.
+
+## Key Services Provided
+
+- **Individual Tax Registration Number Validation**: Validates the accuracy and legitimacy of tax registration numbers on a one-by-one basis.
+- **Batch Tax Registration Number Validation**: Enabling bulk validation simplifies the validation process for merchants handling large datasets.

api-reference/tax-reg-number-validate/docs/testing-with-postman.mdx

@@ -0,0 +1,23 @@
+---
+title: Testing with Postman
+---
+Postman is an API development environment that simplifies running and testing API requests. With Postman, you won’t have to copy and paste data from one endpoint to another.
+
+[![Run In Postman](https://run.pstmn.io/button.svg)](https://chargebee.postman.co/collection/19303335-f9503437-0c58-4967-8aa7-3626090ec486?source=rip_markdown&active-environment=19303335-298da9ef-c95b-451f-99c6-b107d6740f05)
+
+1. **Download and Install Postman**
+    - Download Postman from the [Postman Downloads page](https://www.postman.com/downloads/).
+    - Install the application on your system by following the setup instructions.
+
+2. **Access Tax Registration Validation SPIs**
+    - Visit the [Tax Registration Number Validate SPI Workspace](https://chargebee.postman.co/collection/19303335-f9503437-0c58-4967-8aa7-3626090ec486?source=rip_markdown&active-environment=19303335-298da9ef-c95b-451f-99c6-b107d6740f05).
+
+3. **Select the Environment**
+    - Choose the "Tax Registration Number Validate" environment from the Postman workspace.
+
+4. **Configure Environment Variables**
+   - Add the following environment variables:
+      - `url` - The base URL of the app.
+      -  `authorization_header` - The value for the authorization header required for API authentication. Refer to the [Authorization section](../docs/Authorization) to know more about this.
+
+Now, you're ready to interact with Tax Registration Number SPI endpoints using Postman.

api-reference/tax-reg-number-validate/endpoints/v1/delete-the-request-of-batch-of-tax-registration-numbers-validation.mdx

@@ -0,0 +1,3 @@
+---
+openapi: delete /trn/validate/batch/{batchId}
+---

api-reference/tax-reg-number-validate/endpoints/v1/fetch-the-health-status-of-the-service-provider.mdx

@@ -0,0 +1,3 @@
+---
+openapi: get /health
+---

api-reference/tax-reg-number-validate/endpoints/v1/get-the-response-of-batch-of-tax-registration-numbers.mdx

@@ -0,0 +1,3 @@
+---
+openapi: get /trn/validate/batch/{batchId}
+---

api-reference/tax-reg-number-validate/endpoints/v1/get-the-response-of-tax-registration-number-validate-request.mdx

@@ -0,0 +1,3 @@
+---
+openapi: get /trn/validate/{requestId}
+---

api-reference/tax-reg-number-validate/endpoints/v1/validate-credentials.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /credentials/validate
+---

api-reference/tax-reg-number-validate/endpoints/v1/validate-the-tax-registration-number.mdx

@@ -0,0 +1,4 @@
+---
+openapi: post /trn/validate
+---
+

api-reference/tax-reg-number-validate/endpoints/v1/validate-the-tax-registration-numbers-in-batch.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /trn/validate/batch
+---

api-reference/tax-spi/docs/authorization.mdx

@@ -0,0 +1,62 @@
+---
+stoplight-id: upohpgnjav634
+---
+
+## Overview
+Chargebee uses [**HTTP header-based authorization**](https://datatracker.ietf.org/doc/html/rfc7235) for all API endpoints related to the Service Adapter. This approach ensures secure and dynamic management of authorization credentials during API interactions.
+
+## How It Works
+- The **Authorization Key** for API calls is dynamically passed in the HTTP header, enabling secure and seamless integration.
+- This key is specified in the `[api_configuration](url)` object, which is part of the JSON configuration used during onboarding in Chargebee's marketplace. (Attach link)
+- During the application onboarding process in Chargebee, merchants provide the necessary authorization parameter values.
+- The Chargebee application uses these values to authenticate and make API calls to the Service Adapter.
+
+
+## Structure of `credential_configuration`
+- The `credential_configuration` is an array of objects, where each object represents a credential parameter.
+- Each object includes the following attributes:
+    - **`id`**: A unique identifier for the credential. For example, `authorization_key` or `client_secret`.
+    - **`name`**: A descriptive label of the credential.
+    - **`type`**:The credential type. For example, `text`.
+    - **`is_sensitive`**: Indicates whether the credential is sensitive.
+
+## JSON Configuration Example
+
+```json
+{
+  "api_configuration": {
+    "api_base_url": "https://chargebee.partnerX.com/v1",
+    "credential_configuration": [ 
+      {
+        "id": "api_key",
+        "name": "API Key", 
+        "type": "text",
+        "is_sensitive": true 
+      },
+      {
+        "id": "company_code",
+        "name": "Company code",
+        "type": "text",
+        "is_sensitive": false
+      }
+    ]
+  }
+}
+```
+
+## Authorization Header
+
+Below is the structure of authorization header that will be passed from Chargebee app to Service Adapter. Some of the 
+parameters are sent by default by Chargebee as mentioned in the example below:
+
+```json
+{
+--header 'Authorization: 
+{
+  "api_key": "api_keyX", 
+  "merchant_id": "merchant_id_partnerX", //sent by Chargebee by default
+  "company_code": "company_code_partnerX", //sent by Chargebee by default
+  "trace_id": "12345-abcde-67890" //sent by Chargebee by default
+}
+'
+}

api-reference/tax-spi/docs/overview.mdx

@@ -0,0 +1,52 @@
+# Tax SPI Integration
+
+Chargebee simplifies tax management during checkout sessions and invoice generation throughout the subscription lifecycle by performing the following operations:
+
+### 1. Validating Customer Shipping Address
+Validates shipping addresses to ensure accurate tax calculation and product delivery.
+
+### 2. Tax Estimation
+Calculates applicable taxes for invoices and their line items.
+
+### 3. Tax Reconciliation
+Submits invoice and credit note data to external systems for tax reconciliation.
+
+Chargebee leverages external tax services to execute these operations effectively. These services can be categorized as:
+
+- **Third-Party Tax Service Providers:**  
+  APIs provided by third-party tax service vendors for tax calculation and reconciliation.
+
+- **Merchant's In-House Tax Software:**  
+  Custom-built tax management solutions used internally by merchants.
+
+## The Role of the Tax Service Adapter App
+
+To connect with external tax services, Chargebee requires a tax service adapter—a bridge facilitating seamless communication between Chargebee and the tax service. This connection is established using the **Tax Service Provider Interface (SPI)**.
+
+## Building a Tax Service Adapter App
+
+To integrate a tax service with Chargebee, you must implement the Tax SPI (you can refer the spec file for this spi [here](https://github.com/chargebee/cb-provider-spi/blob/main/spec/spi/openapi_tax.yml)) by developing a tax service adapter app. This is essential for one of the following scenarios:
+
+- **As a Tax Service Provider:**  
+  Connect your tax service with Chargebee to provide seamless tax calculation capabilities to merchants.
+
+- **As a Merchant:**  
+  Connect your in-house tax software to Chargebee for tailored tax management.
+
+- **As a System Integrator:**  
+  Develop a connector to bridge a tax service provider and Chargebee, enabling integration for merchants.
+
+By implementing the Tax SPI, you enable Chargebee to perform tax-related operations efficiently, ensuring accurate compliance and streamlined workflows.
+
+![How Chargebee interacts with the tax service via the adapter](./images/tax_spi_workflow.png)
+
+## JSON Schema for Tax Provider
+
+
+JSON (JavaScript Object Notation) is a lightweight, text-based format commonly used to transmit data between web applications and servers. It is both human-readable and machine-parsable.
+
+JSON Schema, a standard established by the [Internet Engineering Task Force (IETF)](https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04#:~:text=JSON%20Schema%20is%20a%20JSON,interaction%20control%20of%20JSON%20data), defines the structure and constraints of a JSON document. It describes the expected properties, data types, and rules for interacting with JSON data, ensuring consistency and validity.
+
+Below is the Chargebee Tax Provider JSON Schema. Using this schema ensures that your tax provider data is structured accurately and complies with Chargebee’s platform requirements. This improves data consistency and simplifies integration with other systems or applications.
+
+[View Full Tax Provider JSON Schema](https://github.com/chargebee/cb-provider-spi/blob/main/spec/capabilities/tax-provider.schema.json)

api-reference/tax-spi/docs/testing-with-postman.mdx

@@ -0,0 +1,22 @@
+---
+title: Testing with Postman
+---
+Postman is an API development environment that simplifies running and testing API requests. With Postman, you won’t have to copy and paste data from one endpoint to another.
+
+[![Run In Postman](https://run.pstmn.io/button.svg)](https://chargebee.postman.co/collection/19303335-eef7d7e8-4c3a-44f0-bb20-f25dad404186?source=rip_markdown&active-environment=19303335-bb889063-006c-486c-8675-ac66c55b84a3)
+
+1. **Download and Install Postman**
+    - Download Postman from the [Postman Downloads page](https://www.postman.com/downloads/).
+    - Install the application on your system by following the setup instructions.
+
+2. **Access Tax SPIs**
+    - Visit the [Tax SPIs Workspace](https://chargebee.postman.co/collection/19303335-eef7d7e8-4c3a-44f0-bb20-f25dad404186?source=rip_markdown&active-environment=19303335-bb889063-006c-486c-8675-ac66c55b84a3).
+3. **Select the Environment**
+    - Choose the "Tax_Provider" environment from the Postman workspace.
+
+4. **Configure Environment Variables**
+    - Add the following environment variables:
+        - `url` - The base URL of the app.
+        -  `authorization_header` - The value for the authorization header required for API authentication. Refer to the [Authorization section](../docs/Authorization) to know more about this. 
+
+Now, you're ready to interact with Tax SPI endpoints using Postman.

api-reference/tax-spi/endpoints/v1/address-validation.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /address/validate
+---

api-reference/tax-spi/endpoints/v1/check-taxability.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /address/check-taxability
+---