Step 1: Supplier creates the Standard Business Document

Every transactional document 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="http://uri.etsi.org/01903/v1.4.1#" xmlns:sbd="http://www.unece.org/cefact/namespaces/StandardBusinessDocumentHeader" 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:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" 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="PE">77388600-8</sbd:Identifier>
			<sbd:ContactInformation>
				<sbd:Contact>Sovos Support</sbd:Contact>
				<sbd:EmailAddress>support@sovos.com</sbd:EmailAddress>
				<sbd:FaxNumber>+1-212-555-1213</sbd:FaxNumber>
				<sbd:TelephoneNumber>+1-212-555-2122</sbd:TelephoneNumber>
				<sbd:ContactTypeIdentifier>Support</sbd:ContactTypeIdentifier>
			</sbd:ContactInformation>
		</sbd:Sender>
		<sbd:Receiver>
			<sbd:Identifier Authority="PE">98765432-1</sbd:Identifier>
			<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-02T00:00:00Z</sbd:CreationDateAndTime>
		</sbd:DocumentIdentification>
		<sbd:BusinessScope>
			<sbd:Scope>
				<sbd:Type>Country</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>PE</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>UBLInvoice</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>CompanyCode</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>77388600-8</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>SenderDocumentId</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>F00001795T52</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>SenderSystemId</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>UAT101</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>ProcessType</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>Outbound</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:Scope>
				<sbd:Type>BusinessCategory</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>BusinessToBusiness</sbd:Identifier>
			</sbd:Scope>
		</sbd:BusinessScope>
	</sbd:StandardBusinessDocumentHeader>
	<svs:SovosDocument>
		<sci:SovosCanonicalInvoice>
			<inv:Invoice>
				*UBL Nodes*
			</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.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": 1620128574735,
    "status": 202,
    "success": true,
    "message": "Document Received",
    "data": {
        "documentId": "Q0x8NzYxNTcyMjAtMnwxNjIwMTI4NTc0NjQxfDYxOTYzNDIyOQ=="
    }
}

Step 3: Sovos maps the SCI into XML

Upon receiving the SCI, Sovos maps the file into the required XML format.

Step 4: Sovos performs the schema validation

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

Step 5: Sovos signs the XML

Sovos signs the XML with the configured certificate.

Step 6: Storing

Sovos stores the signed CPE XML.

Step 7: Sovos transmits the XML

Sovos transmits the signed CPE XML file to OSE for clearance.

Step 8: OSE processes and stores the XML

OSE validates the correct issuance of the XML and also saves a copy of the validation along with the XML.

After authentications, the OSE sends a CDR to Sovos and the CDR, along with the XML, to the tax authority.

The CDR or Receipt Certificate holds details for the status of the electronic document. An electronic document can have the following statues:

Accepted

The electronic document meets the standards and validation criteria.

Accepted with observation

The electronic document complies with the established validations but you might need to edit some information.

Step 9: Sovos generates the PDF

Sovos generates a PDF file that includes the content of the CPE XML based on the configured PDF template.

Step 10: Sovos distributes the PDF and the XML

As explained in step 11, the supplier can retrieve the CPE XML and the PDF through a GET API request. But Sovos can also distribute the PDF and the CPE XML by email:

Step 11: 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 a URL to access the cleared CPE XML and the PDF after they're available during the process.

To complete a transaction, the supplier must retrieve application responses until the SCIResponseCode in the response has the value of either "AP" or "RE", which indicates that the transaction is finished.

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

• GET /notifications/PE

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

GET /notifications/PE

The supplier can send a GET request to the /notifications/PE 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 must be included in the result.

Request sample

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

Response sample

{
    "timestamp": 1633690045950,
    "status": 200,
    "success": true,
    "message": "Notifications Listed",
    "data": {
        "pageState": {
            "page": 1,
            "perPage": 2,
            "totalPages": 799226,
            "totalEntries": 1598451
        },
        "notifications": [
            {
                "createdDate": "1604415975006",
                "metadata": {
                    "documentId": "Q0x8NzYxNTcyMjAtMnwxNjA0NDEzNzA4NDQxfDgzOTQxMjU5MA==",
                    "erpDocumentId": "3733770",
                    "taxId": "761572202",
                    "sciCloudStatusCode": 200,
                    "sciResponseCode": "AP",
                    "sciStatusAction": "NOA",
                    "sciGovtStatusCode": ""
                },
                "appPrefix": "PPL",
                "notificationId": "915015",
                "content": "PEF...c2U+"
            },
            {
                "createdDate": "1604415856547",
                "metadata": {
                    "documentId": "Q0x8NzYxNTcyMjAtMnwxNjA0NDEzNzA4NDQxfDgzOTQxMjU5MA==",
                    "erpDocumentId": "3733770",
                    "taxId": "761572202",
                    "sciCloudStatusCode": 101,
                    "sciResponseCode": "IP",
                    "sciStatusAction": "NOA",
                    "sciGovtStatusCode": ""
                },
                "appPrefix": "PPL",
                "notificationId": "915016",
                "content": "PEF...ZT4="
            }
        ]
    }
}

GET /documents/PE/{documentId}/notifications

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

Name	Type	Required	Parameter type	Default	Description
documentId	string	Yes	Path		The ID of the document returned in step 2
includeAcknowledged	boolean	No	Query	false	Enter "true" to specify whether previously acknowledged notifications must be included in the result.

Request sample

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

Response sample

{
    "timestamp": 1633690226316,
    "status": 200,
    "success": true,
    "message": "Notifications Listed",
    "data": {
        "pageState": {
            "page": 1,
            "perPage": 2,
            "totalPages": 2,
            "totalEntries": 4
        },
        "notifications": [
            {
                "createdDate": "1620128575181",
                "metadata": {
                    "documentId": "Q0x8NzYxNTcyMjAtMnwxNjIwMTI4NTc0NjQxfDYxOTYzNDIyOQ==",
                    "erpDocumentId": "1100000111",
                    "taxId": "761572202",
                    "sciCloudStatusCode": 101,
                    "sciResponseCode": "IP",
                    "sciStatusAction": "NOA",
                    "sciGovtStatusCode": "",
                    "sciGovtStatusMessage": ""
                },
                "appPrefix": "PPL",
                "notificationId": "3066477",
                "content": "PEF...c2U+"
            },
            {
                "createdDate": "1620237743251",
                "metadata": {
                    "documentId": "Q0x8NzYxNTcyMjAtMnwxNjIwMTI4NTc0NjQxfDYxOTYzNDIyOQ==",
                    "erpDocumentId": "1100000111",
                    "taxId": "761572202",
                    "sciCloudStatusCode": 202,
                    "sciResponseCode": "RE",
                    "sciStatusAction": "NIN",
                    "sciGovtStatusCode": "",
                    "sciGovtStatusMessage": ""
                },
                "appPrefix": "PPL",
                "notificationId": "3066761",
                "content": "PEF...ZT4="
            }
        ]
    }
}

Step 12: 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/PE endpoint.

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

Request sample

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

Response sample

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

Step 13: Supplier sends the XML and the PDF to the Buyer

As the final step, the supplier should send the CPE XML and optionally the PDF to the buyer via an agreed-upon channel.