Step 1: Supplier creates the Standard Business Document

Every invoice sent to Sovos must be part of a Standard Business Document (SBD). This document includes a Standard Business Document Header (SBDH) and a Sovos Document node, which in turn includes a Sovos Canonical Invoice (SCI). To create the SBD, follow the detailed instructions in the SBDH, Sovos Document, and SCI pages.

Here are some key elements that should be included in the SBD:

SBD sample

Below is a sample of the SBD. In addition, there's a full sample of the SBD on the Postman Samples page.

<sbd:StandardBusinessDocument xmlns="http://uri.etsi.org/01903/v1.4.1#" xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" xmlns:sbd="http://www.unece.org/cefact/namespaces/StandardBusinessDocumentHeader" xmlns:xades="http://uri.etsi.org/01903/v1.3.2#" xmlns:ad="http://www.sovos.com/namespaces/additionalData" xmlns:sci="http://www.sovos.com/namespaces/sovosCanonicalInvoice" xmlns:svs="http://www.sovos.com/namespaces/sovosDocument" xmlns:sov="http://www.sovos.com/namespaces/sovosExtensions" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:ext="urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2" xmlns:inv="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2">
	<sbd:StandardBusinessDocumentHeader>
		<sbd:HeaderVersion>1.0</sbd:HeaderVersion>
		<sbd:Sender>
			<sbd:Identifier Authority="IN">YOUR-TAXID</sbd:Identifier>
			<sbd:ContactInformation>
				<sbd:Contact>YOUR-TAXID</sbd:Contact>
				<sbd:EmailAddress/>
				<sbd:FaxNumber/>
				<sbd:TelephoneNumber/>
				<sbd:ContactTypeIdentifier/>
			</sbd:ContactInformation>
		</sbd:Sender>
		<sbd:Receiver>
			<sbd:Identifier Authority="IN"/>
			<sbd:ContactInformation>
				<sbd:Contact/>
				<sbd:EmailAddress/>
				<sbd:FaxNumber/>
				<sbd:TelephoneNumber/>
				<sbd:ContactTypeIdentifier/>
			</sbd:ContactInformation>
		</sbd:Receiver>
		<sbd:DocumentIdentification>
			<sbd:Standard>urn:oasis:names:specification:ubl:schema:xsd:Invoice-2</sbd:Standard>
			<sbd:TypeVersion>2.1</sbd:TypeVersion>
			<sbd:InstanceIdentifier/>
			<sbd:Type>Invoice</sbd:Type>
			<sbd:MultipleType>false</sbd:MultipleType>
			<sbd:CreationDateAndTime>2020-06-16T00:31:52Z</sbd:CreationDateAndTime>
		</sbd:DocumentIdentification>
		<sbd:BusinessScope>
			<sbd:Scope>
				<sbd:Type>Version</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>1.1</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>SenderDocumentId</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>DOCUMENT-ID</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>SenderSystemId</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>SystemERP</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
                <sbd:Type>CompanyCode</sbd:Type>
                <sbd:InstanceIdentifier/>
                <sbd:Identifier>YOUR-TAXID</sbd:Identifier>
            </sbd:Scope>
			<sbd:Scope>
				<sbd:Type>Country</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>IN</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>ProcessType</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>Outbound</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>Mapping.TransformDocument</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>SCI-TO-LEGAL_INVOICE</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>Mapping.OutputSchema</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>GSTInvoice</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>BusinessCategory</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>B2B</sbd:Identifier>
			</sbd:Scope>
		 	<sbd:Scope>
                <sbd:Type>BusinessProcess</sbd:Type>
                <sbd:InstanceIdentifier/>
                <sbd:BusinessService>
                    <sbd:BusinessServiceName>Default</sbd:BusinessServiceName>
                </sbd:BusinessService>
            </sbd:Scope>
		</sbd:BusinessScope>
	</sbd:StandardBusinessDocumentHeader>
	<svs:SovosDocument>
		<sci:SovosCanonicalInvoice>
			<inv:Invoice>
			    *UBL Elements*
			</inv:Invoice>
		</sci:SovosCanonicalInvoice>
	</svs:SovosDocument>
</sbd:StandardBusinessDocument>

Step 2: Supplier sends the SBD to Sovos

The supplier sends a POST request to the /documents endpoint.

The request must include the following request body parameters:

After receiving the document, Sovos performs a structure/schema validation of both the SCI and the SBD parts.

Request sample

curl --location --request POST 'https://api-test.sovos.com/v1/documents' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--data-raw '{
	"data": "PD9...d4=",
	"dataEncoding" : "base64"
}'

Response sample

{
    "timestamp": 1605282724079,
    "status": 202,
    "success": true,
    "message": "Document Received",
    "data": {
        "documentId": "DOCUMENT-ID"
    }
}

Step 3: Sovos maps the SCI into JSON

Step 4: Sovos performs the schema validation

Sovos performs a schema validation to determine whether the JSON file conforms to the expected structure by validating the file against the official JSON schema.

Step 5: Sovos transmits the JSON

Sovos transmits the JSON file to the tax authority.

Step 6: Tax authority processes the JSON

The tax authority checks for duplicate invoices, then performs a schema validation and several business validations.

If the document fails the checks and validations, the tax authority rejects it. Then, they generate a rejection response error message along with an error message, where applicable.

If the tax authority approves the document, they generate an approval message, generate a hash (which becomes the IRN), sign the JSON with its private key, then proceed to generate and sign the QR code. They store the signed JSON in the central registry and can use it for duplication checks.

Step 7: Tax authority sends the response to Sovos

After performing its services, the tax authority sends the response to Sovos. The application response contains the signed JSON, the signed QR code data, the formal identifiers, IRN, acknowledgment number, and acknowledgment date.

Step 8: Supplier retrieves the application responses

As a response to the initial sending of the document, the client receives a JSON response message with an HTTP status code of 202 (asynchronous transaction). This means that the supplier must retrieve the application responses that become available during the transaction, which provide status information and the cleared XML encoded in Base64 after it's available during the process.

Additionally, you must consider the following details included in the response:

Transmission message

It maps to the SCIGovtStatusCode and StatusReason elements in the response message, as described in the application responses documentation, which details any warnings or additional notes to consider. The tax authority doesn't define any specific set of rules about what action to take on each warning. Depending on the type of message, you may have to modify the invoice, take some additional action, or simply make a note for the future.

Options for retrieving application responses (notifications):

Fetch everything in one single response (notification)

When polling for responses, Sovos only returns one final notification with SCICloudStatusCode of 209 that contains all the relevant attachments and data. Detailed description follows.

Fetch multiple responses (notifications) containing different information

When polling for responses, Sovos returns multiple notifications with different SCICloudStatusCode values containing different attachments and data until the final one (with status 209) is returned. Detailed description follows.

	<cac:DocumentResponse>
		<cac:Response>
			<cbc:ReferenceID/>
			<cbc:ResponseCode listID="SCIResponseCode">AP</cbc:ResponseCode>
			<cac:Status>
				<cbc:StatusReasonCode listID="SCICloudStatusCode">209</cbc:StatusReasonCode>
				<cbc:StatusReason>Workflow Successfully Completed</cbc:StatusReason>
			</cac:Status>
			<cac:Status>
				<cbc:StatusReasonCode listID="SCIStatusAction">NOA</cbc:StatusReasonCode>
				<cbc:StatusReason>No action required</cbc:StatusReason>
			</cac:Status>
			<cac:Status>
				<cbc:StatusReasonCode listID="SCIERPStatusCode"/>
				<cbc:StatusReason>Workflow Successfully Completed</cbc:StatusReason>
			</cac:Status>
		</cac:Response>

	<cac:DocumentResponse>
		<cac:Response>
			<cbc:ReferenceID/>
			<cbc:ResponseCode listID="SCIResponseCode">RE</cbc:ResponseCode>
			<cac:Status>
				<cbc:StatusReasonCode listID="SCICloudStatusCode">209</cbc:StatusReasonCode>
				<cbc:StatusReason>Workflow Successfully Completed</cbc:StatusReason>
			</cac:Status>
			<cac:Status>
				<cbc:StatusReasonCode listID="SCIStatusAction">NOA</cbc:StatusReasonCode>
				<cbc:StatusReason>No action required</cbc:StatusReason>
			</cac:Status>
			<cac:Status>
				<cbc:StatusReasonCode listID="SCIERPStatusCode"/>
				<cbc:StatusReason>Workflow Successfully Completed</cbc:StatusReason>
			</cac:Status>
			<cac:Status>
				<cbc:StatusReasonCode listID="SCIGovtStatusCode">2150</cbc:StatusReasonCode>
				<cbc:StatusReason>Duplicate IRN</cbc:StatusReason>
			</cac:Status>
		</cac:Response>

	<cac:DocumentResponse>
		<cac:Response>
			<cbc:ReferenceID/>
			<cbc:ResponseCode listID="SCIResponseCode">IP</cbc:ResponseCode>
			<cac:Status>
				<cbc:StatusReasonCode listID="SCICloudStatusCode">100</cbc:StatusReasonCode>
				<cbc:StatusReason>Document received successfully</cbc:StatusReason>
			</cac:Status>
			<cac:Status>
				<cbc:StatusReasonCode listID="SCIStatusAction">NOA</cbc:StatusReasonCode>
				<cbc:StatusReason>No action required</cbc:StatusReason>
			</cac:Status>
			<cac:Status>
				<cbc:StatusReasonCode listID="SCIERPStatusCode">100-Received successfully</cbc:StatusReasonCode>
				<cbc:StatusReason>Document received successfully</cbc:StatusReason>
			</cac:Status>
		</cac:Response>

	<cac:DocumentResponse>
		<cac:Response>
			<cbc:ReferenceID/>
			<cbc:ResponseCode listID="SCIResponseCode">IP</cbc:ResponseCode>
			<cac:Status>
				<cbc:StatusReasonCode listID="SCICloudStatusCode">101</cbc:StatusReasonCode>
				<cbc:StatusReason>Document mapped successfully</cbc:StatusReason>
			</cac:Status>
			<cac:Status>
				<cbc:StatusReasonCode listID="SCIStatusAction">NOA</cbc:StatusReasonCode>
				<cbc:StatusReason>No action required</cbc:StatusReason>
			</cac:Status>
			<cac:Status>
				<cbc:StatusReasonCode listID="SCIERPStatusCode">101-Mapped successfully</cbc:StatusReasonCode>
				<cbc:StatusReason>Document mapped successfully</cbc:StatusReason>
			</cac:Status>
		</cac:Response>

  <cac:DocumentResponse>
    <cac:Response>
      <cbc:ReferenceID></cbc:ReferenceID>
      <cbc:ResponseCode listID="SCIResponseCode">AP</cbc:ResponseCode>
      <cac:Status>
        <cbc:StatusReasonCode listID="SCICloudStatusCode">200</cbc:StatusReasonCode>
        <cbc:StatusReason>Authorized by the tax authority</cbc:StatusReason>
      </cac:Status>
      <cac:Status>
        <cbc:StatusReasonCode listID="SCIStatusAction">NOA</cbc:StatusReasonCode>
        <cbc:StatusReason>No action required</cbc:StatusReason>
      </cac:Status>
      <cac:Status>
        <cbc:StatusReasonCode listID="SCIERPStatusCode">200-Authorized</cbc:StatusReasonCode>
        <cbc:StatusReason>Authorized by the tax authority</cbc:StatusReason>
      </cac:Status>
    </cac:Response>

	<cac:DocumentResponse>
		<cac:Response>
			<cbc:ReferenceID/>
			<cbc:ResponseCode listID="SCIResponseCode">AP</cbc:ResponseCode>
			<cac:Status>
				<cbc:StatusReasonCode listID="SCICloudStatusCode">209</cbc:StatusReasonCode>
				<cbc:StatusReason>Workflow Successfully Completed</cbc:StatusReason>
			</cac:Status>
			<cac:Status>
				<cbc:StatusReasonCode listID="SCIStatusAction">NOA</cbc:StatusReasonCode>
				<cbc:StatusReason>No action required</cbc:StatusReason>
			</cac:Status>
			<cac:Status>
				<cbc:StatusReasonCode listID="SCIERPStatusCode">209-Completed successfully</cbc:StatusReasonCode>
				<cbc:StatusReason>Workflow Successfully Completed</cbc:StatusReason>
			</cac:Status>
		</cac:Response>

	<cac:DocumentResponse>
		<cac:Response>
			<cbc:ReferenceID/>
			<cbc:ResponseCode listID="SCIResponseCode">RE</cbc:ResponseCode>
			<cac:Status>
				<cbc:StatusReasonCode listID="SCICloudStatusCode">400</cbc:StatusReasonCode>
				<cbc:StatusReason>Rejected by the tax authority or the counter party</cbc:StatusReason>
			</cac:Status>
			<cac:Status>
				<cbc:StatusReasonCode listID="SCIStatusAction">NIN</cbc:StatusReasonCode>
				<cbc:StatusReason>Request to re-issue a corrected new invoice (or other document) or fix the error and resend the document</cbc:StatusReason>
			</cac:Status>
			<cac:Status>
				<cbc:StatusReasonCode listID="SCIERPStatusCode">400-Rejected</cbc:StatusReasonCode>
				<cbc:StatusReason>Rejected by the tax authority or the counter party</cbc:StatusReason>
			</cac:Status>
			<cac:Status>
				<cbc:StatusReasonCode listID="SCIGovtStatusCode">1015</cbc:StatusReasonCode>
				<cbc:StatusReason>Invalid GSTIN for this user</cbc:StatusReason>
			</cac:Status>
		</cac:Response>

	<cac:DocumentResponse>
		<cac:Response>
			<cbc:ReferenceID/>
			<cbc:ResponseCode listID="SCIResponseCode">RE</cbc:ResponseCode>
			<cac:Status>
				<cbc:StatusReasonCode listID="SCICloudStatusCode">401</cbc:StatusReasonCode>
				<cbc:StatusReason>Error processing document</cbc:StatusReason>
			</cac:Status>
			<cac:Status>
				<cbc:StatusReasonCode listID="SCIStatusAction">NIN</cbc:StatusReasonCode>
				<cbc:StatusReason>Request to re-issue a corrected new invoice (or other document) or fix the error and resend the document</cbc:StatusReason>
			</cac:Status>
			<cac:Status>
				<cbc:StatusReasonCode listID="SCIERPStatusCode">401-Document error</cbc:StatusReasonCode>
				<cbc:StatusReason>Error processing document</cbc:StatusReason>
			</cac:Status>
			<cac:Status>
				<cbc:StatusReasonCode listID="SCIInternalValidationStatusCode">401</cbc:StatusReasonCode>
				<cbc:StatusReason>Required properties are missing from object: AssAmt. Path 'ItemList[0]', line 1, position 762.</cbc:StatusReason>
			</cac:Status>
		</cac:Response>

The supplier can use the following Indirect Tax API endpoints to retrieve application responses:

• GET /notifications/IN

• GET /documents/IN/{documentId}/notifications

GET /notifications/IN

The supplier can send a GET request to the /notifications/IN endpoint to retrieve application responses that match the configured search criteria. To make this request, set the following query parameters:

Name	Type	Required	Default	Description
taxId	string	No		Include only notifications related to the specified taxId. This value relates to the CompanyCode set in the SBDH. Note: If a request doesn't include this parameter, it will return all the notifications related to the country and the sourceSystemId parameter.
page	integer	No	1	To specify the page to be returned, enter a value between 1 and 10.
perPage	integer	No	10	To specify the number of results for the returned page, enter a value between 1 and 100. Note: If the attachment file is configured to return the binary content instead of a link, use only values between 1 and 10.
sourceSystemId	string	Yes		Include only notifications related to documents that originate from the given source system. This value is related to the SenderSystemId in the SBDH.
includeAcknowledged	boolean	No	false	Enter "true" to specify whether previously acknowledged notifications, within 24 hours of their acknowledgment, must be included in the result.
processType	string	No		Enter "0" to only include notifications related to outbound documents.

Request sample

curl --location --request GET 'https://api-test.sovos.com/v1/notifications/IN?page=1&perPage=2&includeAcknowledged=true&taxId={taxId}&sourceSystemId={sourceSystemId}&processType=0' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE'

Response sample

{
    "timestamp": 1633685509314,
    "status": 200,
    "success": true,
    "message": "Notifications Listed",
    "data": {
        "pageState": {
            "page": 1,
            "perPage": 50,
            "totalEntries": 1
        },
        "notifications": [
            {
                "createdDate": 1633681296,
                "metadata": {
                    "productId": "in_GSTInvoice__1.1",
                    "documentId": "DOCUMENT-ID",
                    "erpDocumentId": "ERP-DOCUMENT-ID",
                    "erpSystemId": "SystemERP",
                    "processType": "0",
                    "taxId": "YOUR-TAXID",
                    "sciCloudStatusCode": "200",
                    "sciResponseCode": "AP",
                    "sciStatusAction": "NOA",
                    "sciGovtStatusCode": "100"
                },
                "appPrefix": "DLT",
                "notificationId": "a8dc1aa2-...-97a3d5fdb91c",
                "content": "PEF...NlPg=="
            }
        ]
    }
}

GET /documents/IN/{documentId}/notifications

The supplier can send a GET request to the /documents/IN/{documentId}/notifications endpoint to retrieve application responses related to a single document. To make this request, set the following path parameter:

Name	Type	Required	Description
documentId	string	Yes	The ID of the document returned in step 2

Request sample

curl --location --request GET 'https://api-test.sovos.com/v1/documents/IN/{documentId}/notifications' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE'

Response sample

{
    "timestamp": 1633685509314,
    "status": 200,
    "success": true,
    "message": "Notifications Listed",
    "data": {
        "pageState": {
            "page": 1,
            "perPage": 50,
            "totalEntries": 1
        },
        "notifications": [
            {
                "createdDate": 1633681296,
                "metadata": {
                    "productId": "in_GSTInvoice__1.1",
                    "documentId": "DOCUMENT-ID",
                    "erpDocumentId": "ERP-DOCUMENT-ID",
                    "erpSystemId": "SystemERP",
                    "processType": "0",
                    "taxId": "YOUR-TAXID",
                    "sciCloudStatusCode": "200",
                    "sciResponseCode": "AP",
                    "sciStatusAction": "NOA",
                    "sciGovtStatusCode": "100"
                },
                "appPrefix": "DLT",
                "notificationId": "a8dc1aa2-...-97a3d5fdb91c",
                "content": "PEF...NlPg=="
            }
        ]
    }
}

Step 9: Supplier marks the application responses as acknowledged

The supplier must process the retrieved application responses and mark them as acknowledged. This can be done by sending a PUT request to the /notifications/IN endpoint.

To make this request, set the following request body parameters:

Request sample

curl --location --request PUT 'https://api-test.sovos.com/v1/notifications/IN' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--data-raw '[
    {
        "status": "read",
        "notificationId": "51341d39-...-a73d73e0de76"
    }
]'

Response sample

{
    "timestamp": 1601673284,
    "status": 200,
    "success": true,
    "message": "Notifications acknowledged successfully."
}

Step 10: Archiving

You can compliantly archive the XML, the application response, and any graphical representation, such as a PDF, using Sovos' Compliant Archive.

For suppliers integrating with the Sovos solution for India for the first time, we recommend the bundled approach, in which archiving is part of the invoice clearance flow. Archiving can also be done separately through an explicit API call that uses another archive. For more information on standalone archiving, see the eArchiving documentation page.

Step 11: Supplier sends the invoice to the buyer

The supplier must design a solution that accommodates the preferred business processes for delivering the invoice to the buyer because this process is outside the scope of Sovos and the tax authority.

Step 1: Supplier sends a POST request to Sovos

When the supplier wants to cancel an invoice in India, they send a POST request to the /documents/IN/action endpoint. To make this request, set the following request body parameters:

Request sample

curl --location --request POST 'https://api-test.sovos.com/v1/documents/IN/action' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--data '{
    "actionCode": "document.cancellation",
    "documents": [
      {
        "metadata": {
            "reason": "Faulty document data",
            "reasonCode": "1"
        },

        "documentId": "DOCUMENT-ID"
      }
    ]
}'

Response sample

{
    "status": 202,
    "message": "Accepted",
    "success": true,
    "timestamp": 1699440641940,
    "data": [
        {
            "status": 202,
            "documentId": "DOCUMENT-ID"
        }
    ]
}

Step 2: Sovos transmits the request

Sovos transmits the cancellation request to the tax authority.

Step 3: Tax authority processes the request

The tax authority performs the validation and the cancellation action.

Step 4: Tax authority returns the response

The tax authority sends the response to Sovos.

Step 5: Supplier retrieves the application responses

As a response to the initial sending of the document, the client receives a JSON response message with an HTTP status code of 202 (asynchronous transaction). This means that the supplier must retrieve the application responses that become available during the transaction, which provide status information and the cleared XML encoded in Base64 after it's available during the process.

To complete a transaction, the supplier must retrieve application responses until the transaction is finished. If the supplier has subscribed to all notifications, the transaction can generate different application responses. See the table below:

	<cac:DocumentResponse>
		<cac:Response>
			<cbc:ReferenceID/>
			<cbc:ResponseCode listID="SCIResponseCode">IP</cbc:ResponseCode>
			<cac:Status>
				<cbc:StatusReasonCode listID="SCICloudStatusCode">101</cbc:StatusReasonCode>
				<cbc:StatusReason>Document mapped successfully</cbc:StatusReason>
			</cac:Status>
			<cac:Status>
				<cbc:StatusReasonCode listID="SCIStatusAction">NOA</cbc:StatusReasonCode>
				<cbc:StatusReason>No action required</cbc:StatusReason>
			</cac:Status>
			<cac:Status>
				<cbc:StatusReasonCode listID="SCIERPStatusCode">101-Mapped successfully</cbc:StatusReasonCode>
				<cbc:StatusReason>Document mapped successfully</cbc:StatusReason>
			</cac:Status>
		</cac:Response>

	<cac:DocumentResponse>
		<cac:Response>
			<cbc:ReferenceID/>
			<cbc:ResponseCode listID="SCIResponseCode">AP</cbc:ResponseCode>
			<cac:Status>
				<cbc:StatusReasonCode listID="SCICloudStatusCode">201</cbc:StatusReasonCode>
				<cbc:StatusReason>Cancelled</cbc:StatusReason>
			</cac:Status>
			<cac:Status>
				<cbc:StatusReasonCode listID="SCIStatusAction">NOA</cbc:StatusReasonCode>
				<cbc:StatusReason>No action required</cbc:StatusReason>
			</cac:Status>
			<cac:Status>
				<cbc:StatusReasonCode listID="SCIERPStatusCode">201-Cancelled successfully</cbc:StatusReasonCode>
				<cbc:StatusReason>Cancelled</cbc:StatusReason>
			</cac:Status>
		</cac:Response>

	<cac:DocumentResponse>
		<cac:Response>
			<cbc:ReferenceID/>
			<cbc:ResponseCode listID="SCIResponseCode">AP</cbc:ResponseCode>
			<cac:Status>
				<cbc:StatusReasonCode listID="SCICloudStatusCode">209</cbc:StatusReasonCode>
				<cbc:StatusReason>Workflow Successfully Completed</cbc:StatusReason>
			</cac:Status>
			<cac:Status>
				<cbc:StatusReasonCode listID="SCIStatusAction">NOA</cbc:StatusReasonCode>
				<cbc:StatusReason>No action required</cbc:StatusReason>
			</cac:Status>
			<cac:Status>
				<cbc:StatusReasonCode listID="SCIERPStatusCode">209-Completed successfully</cbc:StatusReasonCode>
				<cbc:StatusReason>Workflow Successfully Completed</cbc:StatusReason>
			</cac:Status>
		</cac:Response>

	<cac:DocumentResponse>
		<cac:Response>
			<cbc:ReferenceID/>
			<cbc:ResponseCode listID="SCIResponseCode">RE</cbc:ResponseCode>
			<cac:Status>
				<cbc:StatusReasonCode listID="SCICloudStatusCode">400</cbc:StatusReasonCode>
				<cbc:StatusReason>Rejected by the tax authority or the counter party</cbc:StatusReason>
			</cac:Status>
			<cac:Status>
				<cbc:StatusReasonCode listID="SCIStatusAction">NIN</cbc:StatusReasonCode>
				<cbc:StatusReason>Request to re-issue a corrected new invoice (or other document) or fix the error and resend the document</cbc:StatusReason>
			</cac:Status>
			<cac:Status>
				<cbc:StatusReasonCode listID="SCIERPStatusCode">400-Rejected</cbc:StatusReasonCode>
				<cbc:StatusReason>Rejected by the tax authority or the counter party</cbc:StatusReason>
			</cac:Status>
			<cac:Status>
				<cbc:StatusReasonCode listID="SCIGovtStatusCode">9999</cbc:StatusReasonCode>
				<cbc:StatusReason>Invoice is not active</cbc:StatusReason>
			</cac:Status>
		</cac:Response>

The supplier can use the following Indirect Tax API endpoints to retrieve application responses:

• GET /notifications/IN

• GET /documents/IN/{documentId}/notifications

GET /notifications/IN

The supplier can send a GET request to the /notifications/IN endpoint to retrieve application responses that match the configured search criteria. To make this request, set the following query parameters:

Name	Type	Required	Default	Description
taxId	string	No		Include only notifications related to the specified taxId. This value relates to the CompanyCode set in the SBDH.
page	integer	No	1	To specify the page to be returned, enter a value between 1 and 10.
perPage	integer	No	10	To specify the number of results for the returned page, enter a value between 1 and 100. Note: If the attachment file is configured to return the binary content instead of a link, use only values between 1 and 10.
sourceSystemId	string	Yes		Include only notifications related to documents that originate from the given source system. This value is related to the SenderSystemId in the SBDH.
includeAcknowledged	boolean	No	false	Enter "true" to specify whether previously acknowledged notifications, within 24 hours of their acknowledgment, must be included in the result.
processType	string	No		Enter "0" to only include notifications related to outbound documents.

Request sample

curl --location --request GET 'https://api-test.sovos.com/v1/notifications/IN?page=1&perPage=2&taxId={taxId}&sourceSystemId={sourceSystemId}&processType=0' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' 

Response sample

{
    "status": 200,
    "message": "Notifications Listed",
    "success": true,
    "timestamp": 0,
    "data": {
        "pageState": {
            "page": 1,
            "perPage": 20,
            "totalEntries": 1,
            "totalPages": 1
        },
        "notifications": [
            {
                "notificationId": "6385272d-...-e35e80b3b8e7",
                "correlationId": "rrt-...-1",
                "appPrefix": "DLT",
                "metadata": {
                    "productId": "in_GSTInvoice__1.1",
                    "transactionId": "TRANSACTION-ID",
                    "documentId": "DOCUMENT-ID",
                    "erpDocumentId": "ERP-DOCUMENT-ID",
                    "erpSystemId": "SystemERP",
                    "processType": "0",
                    "taxId": "YOUR-TAXID",
                    "sciCloudStatusCode": "101",
                    "sciResponseCode": "IP",
                    "sciStatusAction": "NOA"
                },
                "content": "PD...2U+",
                "createdDate": 1686579756
            }
        ]
    }
}

GET /documents/IN/{documentId}/notifications

The supplier can send a GET request to the /documents/IN/{documentId}/notifications endpoint to retrieve application responses related to a single document. To make this request, set the following path parameter:

Name	Type	Required	Description
documentId	string	Yes	The ID of the document returned in step 1

Request sample

curl --location --request GET 'https://api-test.sovos.com/v1/documents/IN/{documentId}/notifications' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE'

Response sample

{
    "status": 200,
    "message": "Notifications Listed",
    "success": true,
    "timestamp": 0,
    "data": {
        "pageState": {
            "page": 1,
            "perPage": 20,
            "totalEntries": 1,
            "totalPages": 1
        },
        "notifications": [
            {
                "notificationId": "6385272d-...-e35e80b3b8e7",
                "correlationId": "rrt-...-1",
                "appPrefix": "DLT",
                "metadata": {
                    "productId": "in_GSTInvoice__1.1",
                    "transactionId": "TRANSACTION-ID",
                    "documentId": "DOCUMENT-ID",
                    "erpDocumentId": "ERP-DOCUMENT-ID",
                    "erpSystemId": "SystemERP",
                    "processType": "0",
                    "taxId": "YOUR-TAXID",
                    "sciCloudStatusCode": "101",
                    "sciResponseCode": "IP",
                    "sciStatusAction": "NOA"
                },
                "content": "PD...2U+",
                "createdDate": 1686579756
            }
        ]
    }
}

Step 6: Supplier marks the application responses as acknowledged

The supplier must process the retrieved application responses and mark them as acknowledged. This can be done by sending a PUT request to the /notifications/IN endpoint.

To make this request, set the following request body parameters:

Request sample

curl --location --request PUT 'https://api-test.sovos.com/v1/notifications/IN' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--data-raw '[
    {
        "status": "read",
        "notificationId": "DOCUMENT-ID"
    }
]'

Response sample

{
    "status": 200,
    "message": "OK",
    "success": true,
    "timestamp": 1657019349646,
    "data": {}
}

Step 1: Supplier creates the Standard Business Document

Every invoice sent to Sovos must be part of a Standard Business Document (SBD). This document includes a Standard Business Document Header (SBDH) and a Sovos Document node, which in turn includes a Sovos Canonical Invoice (SCI). To create the SBD, follow the detailed instructions in the SBDH, Sovos Document, and SCI pages.

Here are some key elements that should be included in the SBD:

SBD sample

Below is a sample of the SBD. In addition, there's a full sample of the SBD on the Postman Samples page.

<sbd:StandardBusinessDocument xmlns="http://uri.etsi.org/01903/v1.4.1#" xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" xmlns:sbd="http://www.unece.org/cefact/namespaces/StandardBusinessDocumentHeader" xmlns:xades="http://uri.etsi.org/01903/v1.3.2#" xmlns:ad="http://www.sovos.com/namespaces/additionalData" xmlns:sci="http://www.sovos.com/namespaces/sovosCanonicalInvoice" xmlns:svs="http://www.sovos.com/namespaces/sovosDocument" xmlns:sov="http://www.sovos.com/namespaces/sovosExtensions" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:ext="urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2" xmlns:inv="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2">
	<sbd:StandardBusinessDocumentHeader>
		<sbd:HeaderVersion>1.0</sbd:HeaderVersion>
		<sbd:Sender>
			<sbd:Identifier Authority="IN">08AAACI9260R002</sbd:Identifier>
			<sbd:ContactInformation>
				<sbd:Contact>08AAACI9260R002</sbd:Contact>
				<sbd:EmailAddress/>
				<sbd:FaxNumber/>
				<sbd:TelephoneNumber/>
				<sbd:ContactTypeIdentifier/>
			</sbd:ContactInformation>
		</sbd:Sender>
		<sbd:Receiver>
			<sbd:Identifier Authority="IN"/>
			<sbd:ContactInformation>
				<sbd:Contact/>
				<sbd:EmailAddress/>
				<sbd:FaxNumber/>
				<sbd:TelephoneNumber/>
				<sbd:ContactTypeIdentifier/>
			</sbd:ContactInformation>
		</sbd:Receiver>
		<sbd:DocumentIdentification>
			<sbd:Standard>urn:oasis:names:specification:ubl:schema:xsd:Invoice-2</sbd:Standard>
			<sbd:TypeVersion>2.1</sbd:TypeVersion>
			<sbd:InstanceIdentifier/>
			<sbd:Type>Invoice</sbd:Type>
			<sbd:MultipleType>false</sbd:MultipleType>
			<sbd:CreationDateAndTime>2020-06-16T00:31:52Z</sbd:CreationDateAndTime>
		</sbd:DocumentIdentification>
		<sbd:BusinessScope>
			<sbd:Scope>
				<sbd:Type>SenderDocumentId</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>321412</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>Country</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>IN</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>ProcessType</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>Outbound</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>Mapping.TransformDocument</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>SCI-TO-LEGAL_INVOICE</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>Mapping.OutputSchema</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>GSTInvoice</sbd:Identifier>
			</sbd:Scope>
		 	<sbd:Scope>
                <sbd:Type>BusinessProcess</sbd:Type>
                <sbd:InstanceIdentifier/>
                <sbd:BusinessService>
                    <sbd:BusinessServiceName>Default</sbd:BusinessServiceName>
                </sbd:BusinessService>
            </sbd:Scope>
		</sbd:BusinessScope>
	</sbd:StandardBusinessDocumentHeader>
	<svs:SovosDocument>
		<sci:SovosCanonicalInvoice>
			<inv:Invoice>
			    *UBL Elements*
			</inv:Invoice>
		</sci:SovosCanonicalInvoice>
	</svs:SovosDocument>
</sbd:StandardBusinessDocument>

Step 2: Supplier sends the SBD to Sovos

The supplier sends a POST request to the /documents endpoint.

The request must include the following request body parameters:

Request sample

curl --location --request POST 'https://api-test-tls.sovos.com/v1/documents' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--data-raw '{
	"data": "PD9...d4=",
	"dataEncoding" : "base64"
}'

Response sample

{
    "timestamp": 1610532937756,
    "status": 200,
    "success": true,
    "message": "Process Completed",
    "data": {
        "notification": {
            "createdDate": "2020-06-16T00:31:52Z",
            "metadata": {},
            "appPrefix": "TW",
            "notificationId": "MW242873231610532937726",
            "content": "PEF...ZT4="
        }
    }
}

Step 3: Sovos maps the SCI into JSON

Step 4: Sovos performs the schema validation

Sovos performs a schema validation to determine whether the JSON file conforms to the expected structure by validating the file against the official JSON schema.

Step 5: Sovos transmits the JSON

Sovos transmits the JSON file to the GSP, which in turn sends it to the tax authority.

Step 6: Tax authority processes the JSON

Upon receiving the file, the tax authority generates a hash (which becomes the IRN) and communicates with the GST to check for duplicate invoices. The tax authority also performs a schema validation and several business validations. It signs the JSON with its private key and generates and signs the QR code. If e-waybill details have been provided, an e-waybill is generated. Finally, the signed JSON is sent to the GST, where it is stored in the central registry and can be used for duplication checks.

Step 7: Tax authority Returns the JSON

After providing its services, the tax authority sends the signed JSON file, which includes the IRN and the signed QR code data, to the GSP. The GSP then returns the file to Sovos.

As a response to the initial POST request, because the transaction is synchronous, the supplier receives a JSON response with a status code and the application response encoded in Base-64 in the content field. The application response contains the signed JSON, the signed QR code data, the formal identifiers, IRN, acknowledgment number, and acknowledgment date. In addition, if an e-waybill has been generated, it also contains the e-waybill number, the e-waybill date, the e-waybill valid-till timestamp, and, optionally, remarks.

The signed document is the signed and cleared JSON file. The Base-64 encoded string must be decoded, which results in another Base-64 encoded string. This string is divided into three parts by two dots (.). The dots separate the header, the payload, and the signature. All three parts should be decoded separately. For more information, see the JWS JSON Serialization Overview.

Sample application response with only the part that includes the tax authority response:

<ext:UBLExtensions>
    <ext:UBLExtension>
        <ext:ExtensionContent>
            <ad:AdditionalData>
                <ad:Field name="EwbNo" type="FormalIdentifier">701008701804</ad:Field>
                <ad:Field name="EwbDt" type="FormalIdentifier">2021-02-22 18:43:00</ad:Field>
                <ad:Field name="EwbValidTill" type="FormalIdentifier">2021-02-23 23:59:00</ad:Field>
                <ad:Field name="IRN" type="FormalIdentifier">28641fd7671af1a0250a0c6c6ca1152679c05f5860ade98a9dccf1f1a3706f74</ad:Field>
                <ad:Field name="AckNo" type="FormalIdentifier">172110007896600</ad:Field>
                <ad:Field name="AckDt" type="FormalIdentifier">2021-02-22 18:42:57</ad:Field>
            </ad:AdditionalData>
        </ext:ExtensionContent>
    </ext:UBLExtension>
</ext:UBLExtensions>

Step 8: Archiving

You can compliantly archive the XML, the application response, and any graphical representation, such as a PDF, using Sovos' Compliant Archive.

For more information on standalone archiving, see the eArchiving documentation page.

Step 9: Supplier maps the JSON into PDF

For some use cases, you should generate a PDF document that includes a QR code. Sovos does not provide a mapping service or a QR Code generation service, so it is up to you to establish a business process in that case.

Step 10: Supplier sends the invoice to the buyer

The supplier must design a solution that accommodates the preferred business processes for delivering the invoice to the buyer because this process is outside the scope of Sovos and the tax authority.

GSTIN not active or not present in the invoice system

Suppose a scenario in which the client receives a 400 bad request with the subCode document.documentDataInvalid. The message specifies the error code 3028 or 3029 and informs that the GSTIN is either invalid or not present in the invoice system. Here is a response sample:

{
    "timestamp": 1615903378447,
    "status": 400,
    "success": false,
    "message": "Bad Request",
    "errors": [
        {
            "message": "Error code : 3028\r\nError Message : GSTIN -29AWGPV7107B1Z2 is invalid.",
            "subCode": "document.documentDataInvalid"
        }
    ]
}

While the GSTIN might be actually invalid or missing, this error also occurs if the e-invoicing system and the GST portal are not synchronized. To fix this synchronization error, log in to the e-invoicing portal and use the "Tax Payer / GSTIN" option in the search menu. This way, you can manually check the status and update the e-invoicing system with the information from the GST Portal. After that, you should retry issuing the invoice.

Duplicate invoices

Duplicate invoices are detected based on the identifier fields that you use to generate the IRN, namely the supplier's GSTIN, the Financial Year, the Document Type, and the Document Number. This duplication check is in place since there can only exist one invoice with the unique combination of these four fields.

If you issue a duplicate invoice within the next two days of the first issuance with the identifier fields populated with the exact same values as the first invoice, Sovos returns a 409 status code and a Base64-encoded application response with the exact same signed JSON and QR Code data returned when the invoice was issued. So, the application response indicates that the invoice has been rejected because of the duplication issue. Here is a sample response code:

{
    "timestamp": 637384345673110000,
    "success": false,
    "status": 409,
    "message": "Duplicate Document",
    "data": {
        "notification": {
            "createdDate": 637384345673110000,
            "metadata": {},
            "appPrefix": "TW",
            "notificationId": "7fd14d30491deb178036548e76edde68c05048290dfd5a6e95971cfb25354b15",
            "content": "PEF...ZT4="
        }
    }
}

If you issue a duplicate invoice more than two days after the original issuance, you will not receive the application response containing the signed JSON and the QR code data. Instead, the response will contain a 400 status code and the error message will contain the error code 2283. This particular error code comes from the Indian tax authority and indicates that they cannot provide the IRN details because more than two days have elapsed since the original issuance.

e-Waybill not generated

You should take into account that if the e-waybill information contains errors and the invoice doesn't, the transaction will still pass, but the e-Waybill will not be created. To check whether the e-waybill has been created, see if the application response and the signed JSON returned contain the e-waybill information.

If the e-Waybill information is missing, its data didn't pass the IRP validation, so the application response Sovos returns will contain the IRP error codes and message.

Suppose there's an error in the e-Waybill details so it has not been generated, but the invoice has passed clearance. In that case, you can extract the IRN from the response and use it for the e-waybill generation process to subsequently generate the e-waybill using the Indirect Tax API.

Step 1: Supplier sends a POST request to Sovos

When the supplier wants to cancel an invoice in India, they send a POST request to the /documents/IN/action endpoint. To make this request, set the following request body parameters:

Request sample

curl --location --request POST 'https://api-test.sovos.com/v1/documents/IN/action' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--data-raw '  {
    "actionCode": "document.cancellation",
    "documents": [
      {
        "metadata": {
            "reason": "{reason}",
            "reasonCode": "1",
            "companyId": "{companyId}",
            "branchId": "{branchId}",
            "documentType": "INCDJSON"
        },
        "documentId": "{IRN of the invoice you want to cancel}"
      }
    ]
  }'

Response sample

{
    "timestamp": 1610532937756,
    "status": 200,
    "success": true,
    "message": "Process Completed",
    "data": {
        "notification": {
            "createdDate": "2020-06-16T00:31:52Z",
            "metadata": {},
            "appPrefix": "TW",
            "notificationId": "MW242873231610532937726",
            "content": "PEF...ZT4="
        }
    }
}

Step 2: Sovos transmits the JSON

Sovos transmits the JSON to the GSP, which in turn sends it to the tax authority.

Step 3: Tax authority processes the JSON

The tax authority performs the schema validation, the hash validation, and the cancellation action.

Step 4: Tax authority returns the response

The tax authority sends the response along with the e-Waybill number to the GSP. Then, the GSP returns the response to Sovos.

As a response to the initial POST request, because the transaction is synchronous, the supplier receives a JSON response with a status code and the application response encoded in Base-64 in the content field. The application response contains the IRN of the canceled invoice and a timestamp of the cancellation.

Sample application response with the part that includes the IRP response:

<ext:UBLExtensions>
	<ext:UBLExtension>
		<ext:ExtensionContent>
			<ad:AdditionalData>
				<ad:Field name="IRN" type="FormalIdentifier">0a0f864812bf1cd7894ad53572f5cd8abf1ab4fbcf31eaa09e64c3164ca62b6f</ad:Field>
				<ad:Field name="CancelDate" type="FormalIdentifier">2021-02-18 15:42:00</ad:Field>
			</ad:AdditionalData>
		</ext:ExtensionContent>
	</ext:UBLExtension>
</ext:UBLExtensions>

Step 5: Archiving

You can compliantly archive the application response and the proof of cancellation using Sovos' Compliant Archive.

For more information on standalone archiving, see the eArchiving documentation page.

Step 6: Supplier informs the buyer

The supplier should inform the buyer about the invoice cancellation. This process is outside the scope of Sovos.

Step 1: Supplier creates the Standard Business Document

Every invoice sent to Sovos must be part of a Standard Business Document (SBD). This document includes a Standard Business Document Header (SBDH) and a Sovos Document node, which in turn includes a Sovos Canonical Invoice (SCI). To create the SBD, follow the detailed instructions in the SBDH, Sovos Document, and SCI pages.

Here are some key elements that should be included in the SBD:

SBD sample

Below is a sample of the SBD. In addition, there's a full sample of the SBD on the Postman Samples page.

<?xml version="1.0" encoding="UTF-8"?>
<sbd:StandardBusinessDocument xmlns:sbd="http://www.unece.org/cefact/namespaces/StandardBusinessDocumentHeader" xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" xmlns:inv="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2" xmlns:sci="http://www.sovos.com/namespaces/sovosCanonicalInvoice" xmlns:svs="http://www.sovos.com/namespaces/sovosDocument" xmlns:ad="http://www.sovos.com/namespaces/additionalData" xmlns:sov="http://www.sovos.com/namespaces/sovosExtensions" xmlns:ext="urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2">
	<sbd:StandardBusinessDocumentHeader>
		<sbd:HeaderVersion>1.0</sbd:HeaderVersion>
		<sbd:Sender>
			<sbd:Identifier Authority="IN">08AAACI9260R002</sbd:Identifier>
			<sbd:ContactInformation>
				<sbd:Contact>08AAACI9260R002</sbd:Contact>
				<sbd:EmailAddress/>
				<sbd:FaxNumber/>
				<sbd:TelephoneNumber/>
				<sbd:ContactTypeIdentifier/>
			</sbd:ContactInformation>
		</sbd:Sender>
		<sbd:Receiver>
			<sbd:Identifier Authority="IN"/>
			<sbd:ContactInformation/>
			<sbd:Contact/>
			<sbd:EmailAddress/>
			<sbd:FaxNumber/>
			<sbd:TelephoneNumber/>
			<sbd:ContactTypeIdentifier/>
		</sbd:Receiver>
		<sbd:DocumentIdentification>
			<sbd:Standard>urn:oasis:names:specification:ubl:schema:xsd:Invoice-2</sbd:Standard>
			<sbd:TypeVersion>2.1</sbd:TypeVersion>
			<sbd:InstanceIdentifier/>
			<sbd:Type>Invoice</sbd:Type>
			<sbd:MultipleType>false</sbd:MultipleType>
			<sbd:CreationDateAndTime>2020-05-02T00:31:52Z</sbd:CreationDateAndTime>
		</sbd:DocumentIdentification>
		<sbd:BusinessScope>
			<sbd:Scope>
				<sbd:Type>SenderDocumentId</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>100056</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>Country</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>IN</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>ProcessType</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>Outbound</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>Mapping.TransformDocument</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>SCI-TO-LEGAL_INVOICE</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>Mapping.OutputSchema</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>GSTEWayBill</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>BusinessProcess</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:BusinessService>
					<sbd:BusinessServiceName>Default</sbd:BusinessServiceName>
				</sbd:BusinessService>
			</sbd:Scope>
		</sbd:BusinessScope>
	</sbd:StandardBusinessDocumentHeader>
	<svs:SovosDocument>
		<sci:SovosCanonicalInvoice>
			    <inv:Invoice>
			        *UBL Elements*
			    </inv:Invoice>
		</sci:SovosCanonicalInvoice>
	</svs:SovosDocument>
</sbd:StandardBusinessDocument>

Step 2: Supplier sends the SBD to Sovos

The supplier sends a POST request to the /documents endpoint.

The request must include the following request body parameters:

Request sample

curl --location --request POST 'https://api-test-tls.sovos.com/v1/documents' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--data-raw '{
	"data": "PD9...d4=",
	"dataEncoding" : "base64"
}'

Response sample

{
    "timestamp": 1610532937756,
    "status": 200,
    "success": true,
    "message": "Process Completed",
    "data": {
        "notification": {
            "createdDate": "2020-06-16T00:31:52Z",
            "metadata": {},
            "appPrefix": "TW",
            "notificationId": "MW242873231610532937726",
            "content": "PEF...ZT4="
        }
    }
}

Step 3: Sovos maps the SCI into JSON

Step 4: Sovos transmits the JSON

Sovos transmits the JSON file to the GSP, which in turn sends it to the tax authority.

Step 5: Tax authority processes the JSON

Upon receiving the file, the tax authority will communicate with the GST to check whether an e-Waybill already exists for the IRN. In addition, the tax authority performs a schema validation and several business validations. It issues the e-Waybill and stores it along with the GST for future duplication checks.

Step 7: Tax authority returns the response

After providing its services, the tax authority sends the response including the e-waybill number to the GSP. The GSP then returns the response to Sovos.

As a response to the initial POST request, because the transaction is synchronous, the supplier receives a JSON response with a status code and the application response encoded in Base-64 in the content field. The application response contains the e-waybill number, the e-waybill date (timestamp of creation) and the e-waybill valid-till timestamp.

Sample application response with only the part that includes the tax authority response:

<ext:UBLExtensions>
	<ext:UBLExtension>
		<ext:ExtensionContent>
			<ad:AdditionalData>
				<ad:Field name="EwbNo" type="FormalIdentifier">771008701595</ad:Field>
				<ad:Field name="EwbDt" type="FormalIdentifier">2021-02-16 17:58:00</ad:Field>
				<ad:Field name="EwbValidTill" type="FormalIdentifier">2021-02-17 23:59:00</ad:Field>
			</ad:AdditionalData>
		</ext:ExtensionContent>
	</ext:UBLExtension>
</ext:UBLExtensions>

Step 8: Archiving

You can compliantly archive the application response and the proof of e-waybill generation using Sovos' Compliant Archive.

For more information on standalone archiving, see the eArchiving documentation page.

Step 9: Transportation

The supplier should send the e-Waybill outcome along with the transported goods to the buyer. This process is outside the scope of Sovos.

Duplicate e-Waybills

Only one e-Waybill can be issued per IRN. If you try to issue an e-Waybill based on a previously used IRN, Sovos returns a 409 status code and a Base64-encoded application response containing the exact same e-Waybill number, e-Waybill date, and e-Waybill valid-till timestamp from the first e-waybill generation. So, the application response indicates that the e-waybill has been rejected because of the duplication issue.

Here is a sample response code:

{
    "timestamp": 637384345673110000,
    "success": false,
    "status": 409,
    "message": "Duplicate Document",
    "data": {
        "notification": {
            "createdDate": 637384345673110000,
            "metadata": {},
            "appPrefix": "TW",
            "notificationId": "7fd14d30491deb178036548e76edde68c05048290dfd5a6e95971cfb25354b15",
            "content": "PEF...ZT4="
        }
    }
}

Step 1: Supplier sends a POST request to Sovos

When the supplier wants to cancel an e-Waybill in India, they send a POST request to the /documents/IN/action endpoint. To make this request, set the following request body parameters:

Request sample

curl --location --request POST 'https://api-test-tls.sovos.com/v1/documents/IN/action' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--data-raw '  {
    "actionCode": "document.cancellation",
    "documents": [
      {
        "metadata": {
            "reason": "{reason}",
            "reasonCode": "1",
            "companyId": "{companyId}",
            "branchId": "{branchId}",
            "documentType": "INECDJSON"
        },
        "documentId": "{number of the e-waybill you want to cancel}"
      }
    ]
  }'

Response sample

{
    "timestamp": 1610532937756,
    "status": 200,
    "success": true,
    "message": "Action executed",
    "data": {
        "notification": {
            "createdDate": "2020-06-16T00:31:52Z",
            "metadata": {},
            "appPrefix": "TW",
            "notificationId": "MW242873231610532937726",
            "content": "PEF...ZT4="
        }
    }
}

Step 2: Sovos transmits the JSON

Sovos transmits the JSON to the GSP, which in turn sends it to the tax authority.

Step 3: Tax authority processes the JSON

The tax authority performs the schema validation and the cancellation action.

Step 4: Tax authority returns the response

The tax authority sends the response along with the e-Waybill number to the GSP. Then, the GSP returns the response to Sovos.

As a response to the initial POST request, because the transaction is synchronous, the supplier receives a JSON response with a status code and the application response encoded in Base-64 in the content field. The application response contains the number of the cancelled e-waybill and a timestamp of the cancellation.

Sample application response with the part that includes the tax authority response:

<ext:UBLExtensions>
	<ext:UBLExtension>
		<ext:ExtensionContent>
			<ad:AdditionalData>
				<ad:Field name="EwbNo" type="FormalIdentifier">741008701695</ad:Field>
				<ad:Field name="CancelDate" type="FormalIdentifier">18/02/2021 04:04:00 PM</ad:Field>
			</ad:AdditionalData>
		</ext:ExtensionContent>
	</ext:UBLExtension>
</ext:UBLExtensions>

Step 5: Archiving

You can compliantly archive the application response and the proof of cancellation using Sovos' Compliant Archive.

For more information on standalone archiving, see the eArchiving documentation page.

Step 1: Taxable person sends a tax ID verification request

A taxable person sends a POST request to the /taxid-checks/IN endpoint. To make this request, set the following request body parameters:

Request sample

curl --location --request POST 'https://api-test-tls.sovos.com/v1/taxid-checks/IN' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--data-raw '{
    "taxId": "TAX-ID",
    "requester": {
        "taxId": "REQUESTER-TAX-ID",
        "legalName": "REQUESTER-LEGALNAME"
    }
}   '

Response sample

{
    "timestamp": 1602847390224,
    "success": true,
    "status": 200,
    "message": "TaxId Check Complete",
    "data": {
        "taxId": "TAX-ID",
        "status": "Valid",
        "legalName": "LEGAL-NAME",
        "address": {
            "floor": "2ND FLOOR",
            "streetName": "STREET-NAME",
            "cityName": "CITY-NAME",
            "postalZone": 400025,
            "region": 27,
            "district": "DISTRICT",
            "addressLine": "ADDRESS-LINE",
            "country": "IN"
        },
        "additionalData": {
            "traderValidity": "ACT",
            "traderTaxPayerType": "REG"
        }
    }
}

Step 2: Sovos transmits the request

Sovos transmits the request to the GSP, which in turn sends it to the tax authority.

Step 3: Tax authority verifies the GSTIN

The tax authority verifies the GSTIN against the GSTIN database.

Step 4: Tax authority returns the response

The tax authority sends the result of the verification to the GSP, which forwards it to Sovos. The result contains a Status node and some basic information related to the company to which the GSTIN belongs. The CompanyInfo.TraderValidity node is important and can have the following values:

• ACT = Active

• CNL = Cancelled

• INA = Inactive

• PRO = Provision

The Status node can have the values "Valid" or "Invalid". It should be noted that the value will only be "Valid" if the CompanyInfo.TraderValidity node has the value "ACT". Any other value is considered "Invalid".

In addition, the CompanyInfo.TraderEWBStatus node explains the ability of the taxpayer to issue an e-Waybill. It can have the following values:

U (Unblocked)

The taxpayer can issue an e-Waybill.

B (Blocked)

The taxpayer cannot issue an e-Waybill due to unfiled tax returns from the last two months.

Step 5: Sovos sends the result to the requester

Sovos sends the result to the requester. Because this is a synchronous process, the result is returned as a response to the POST request in step 1.

Step 6: Archiving

Sovos recommends archiving the evidence of using GSTIN checks with Sovos' Compliant Archive.

For more information on standalone archiving, see the eArchiving documentation page.