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:xades="http://uri.etsi.org/01903/v1.3.2#" xmlns="http://uri.etsi.org/01903/v1.4.1#" 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: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:n1="urn:oasis:names:specification:ubl:schema:xsd:CommonSignatureComponents-2" xmlns:crn="urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2" xmlns:dbn="urn:oasis:names:specification:ubl:schema:xsd:DebitNote-2" xmlns:fin="urn:oasis:names:specification:ubl:schema:xsd:FreightInvoice-2" xmlns:inv="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2" xmlns:qdt="urn:oasis:names:specification:ubl:schema:xsd:QualifiedDataTypes-2" xmlns:sac="urn:oasis:names:specification:ubl:schema:xsd:SignatureAggregateComponents-2" xmlns:sbc="urn:oasis:names:specification:ubl:schema:xsd:SignatureBasicComponents-2" xmlns:udt="urn:oasis:names:specification:ubl:schema:xsd:UnqualifiedDataTypes-2" xmlns:cct="urn:un:unece:uncefact:data:specification:CoreComponentTypeSchemaModule:2" xmlns:sbd="http://www.unece.org/cefact/namespaces/StandardBusinessDocumentHeader">
	<sbd:StandardBusinessDocumentHeader>
		<sbd:HeaderVersion>1.0</sbd:HeaderVersion>
		<sbd:Sender>
			<sbd:Identifier Authority="UY">99999999999</sbd:Identifier>
			<sbd:ContactInformation>
				<sbd:Contact/>
				<sbd:EmailAddress/>
				<sbd:FaxNumber/>
				<sbd:TelephoneNumber/>
				<sbd:ContactTypeIdentifier/>
			</sbd:ContactInformation>
		</sbd:Sender>
		<sbd:Receiver>
			<sbd:Identifier Authority="UY"/>
			<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-10-01T00:00:00Z</sbd:CreationDateAndTime>
		</sbd:DocumentIdentification>
		<sbd:BusinessScope>
			<sbd:Scope>
				<sbd:Type>Country</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>UY</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>CFE</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>CompanyCode</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>99999999999</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>SenderDocumentId</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>12345</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>BusinessCategory</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>BusinessToBusiness</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 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": 1605282724079,
    "status": 202,
    "success": true,
    "message": "Document Received",
    "data": {
        "documentId": "3add2b7104dc0049ff0bf410f57e0a19afaf"
    }
}

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 contains all the necessary information.

Step 5: Sovos signs the XML

Sovos signs the XML with the digital certificate or the supplier's cryptographic key.

Step 6: Sovos transmits the XML

Sovos transmits the signed XML file to the tax authority for clearance.

Step 7: Tax authority processes the XML

The tax authority performs a clearance process for the XML, which includes a schema validation, business validations, and a signature validation. In addition, they generate an acceptance or rejection message.

Once the process is complete, the tax authority returns the message to Sovos.

Step 8: Sovos generates the PDF

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

Step 9: Sovos distributes the PDF and the XML

As explained in step 11, the supplier can retrieve the XML including the comprobante and the PDF through a GET API request. But Sovos can also distribute the PDF and the XML. Available options:

• Email

• AS2

• SFTP

• Web Services

Step 10: Storing

Sovos stores the PDF and the XML.

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 XML including the comprobante 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/UY

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

GET /notifications/UY

The supplier can send a GET request to the /notifications/UY 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.
includeBinaryData	boolean	No	false	Enter "true" to include the binary data of the XML and PDF in the application response.
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/UY?page=1&perPage=2&includeAcknowledged=true&taxId={taxId}&sourceSystemId={sourceSystemId}&includeBinaryData=true&processType=0' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE'

Response sample

{
    "timestamp": 1633687728708,
    "status": 200,
    "success": true,
    "message": "Notifications Listed",
    "data": {
        "pageState": {
            "page": 1,
            "perPage": 2,
            "totalPages": 140,
            "totalEntries": 1399
        },
        "notifications": [
            {
                "createdDate": 1629824492,
                "metadata": {
                    "productId": "FE",
                    "documentId": "3428ba6600dfd042a2090390e04471ed16b1",
                    "erpDocumentId": "80257087",
                    "erpSystemId": "uat_test",
                    "processType": "0",
                    "taxId": "URE180429TM6",
                    "sciCloudStatusCode": "101",
                    "sciResponseCode": "IP",
                    "sciStatusAction": "NOA"
                },
                "appPrefix": "INV",
                "notificationId": "da3095da-f974-420c-bce2-e33682692276",
                "content": "PEF...c2U+"
            },
            {
                "createdDate": 1629857132,
                "metadata": {
                    "productId": "FE",
                    "documentId": "3b20cf820153a0407f0b40402482b216cd7b",
                    "erpDocumentId": "321412",
                    "erpSystemId": "uat_test",
                    "processType": "0",
                    "taxId": "URE180429TM6",
                    "sciCloudStatusCode": "102",
                    "sciResponseCode": "IP",
                    "sciStatusAction": "NOA"
                },
                "appPrefix": "INV",
                "notificationId": "6b0e273b-9ba9-43bc-9911-7eea7867786e",
                "content": "PEF...NlPg=="
            }
        ]
    }
}

GET /documents/UY/{documentId}/notifications

The supplier can send a GET request to the /documents/UY/{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.
includeBinaryData	boolean	No	Query	false	Enter "true" to include the binary data of the XML and PDF in the application response.

Request sample

curl --location --request GET 'https://api-test.sovos.com/v1/documents/UY/{documentId}/notifications?includeAcknowledged=true&includeBinaryData=true' \
--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": "FE",
                    "documentId": "0af1d17c-759a-4b93-b6f5-ad11601be390",
                    "erpDocumentId": "76059264",
                    "erpSystemId": "uat_test",
                    "processType": "0",
                    "taxId": "URE180429TM6",
                    "sciCloudStatusCode": "200",
                    "sciResponseCode": "AP",
                    "sciStatusAction": "NOA",
                    "sciGovtStatusCode": "100"
                },
                "appPrefix": "INV",
                "notificationId": "a8dc1aa2-fbe6-45ce-9e4c-97a3d5fdb91c",
                "content": "PEF...NlPg=="
            }
        ]
    }
}

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/UY endpoint.

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

Request sample

curl --location --request PUT 'https://api-test.sovos.com/v1/notifications/UY' \
--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 XML and the PDF to the buyer through an agreed-upon channel.