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="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:ext="urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2" xmlns:inv="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2" xmlns:sbd="http://www.unece.org/cefact/namespaces/StandardBusinessDocumentHeader" xmlns:col="ColombiaExtension.xsd" 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">
	<sbd:StandardBusinessDocumentHeader>
		<sbd:HeaderVersion>1.0</sbd:HeaderVersion>
		<sbd:Sender>
			<sbd:Identifier Authority="CO">123456789-4</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="CO"/>
			<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>2019-06-20T00:00:00Z</sbd:CreationDateAndTime>
		</sbd:DocumentIdentification>
		<sbd:BusinessScope>
			<sbd:Scope>
				<sbd:Type>Country</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>CO</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>123456789-4</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>SenderSystemId</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>UAT101</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>SenderDocumentId</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>112345</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>BusinessToConsumer</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: Sovos transmits the XML

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

Step 7: Tax authority processes the XML

After the invoice, debit note, or credit note is transmitted, the Special Administrative Unit of the tax authority generates an electronic document, which has verification and validation rules, in compliance with the legal and technical requirements. The possible responses will be either "Documento validado por la DIAN" (Spanish: Document validated by DIAN) or "Documento Rechazado por la DIAN" (Spanish: Document Rejected by DIAN), in which case the reasons for rejection are also specified.

Step 8: Sovos generates the PDF

Sovos generates a PDF file that includes the content of the 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 and the PDF through a GET API request. But Sovos can also distribute the PDF and the XML by email:

Step 9: Storing

Sovos stores the PDF and the XML.

Step 10: 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 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/CO

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

GET /notifications/CO

The supplier can send a GET request to the /notifications/CO 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.
orgId	string	No		Unique identifier for the organization. When provided, restricts the notifications listed to documents associated with this organization ID (only applicable for Worskspace tenants).
senderDocumentId	string	No		Unique identifier for the sender's document. When provided, restricts the notifications listed to this sender document ID (only applicable if the scope SenderDocumentId has been provided in the POST /v1/documents endpoint).

Request sample

curl --location --request GET 'https://api-test.sovos.com/v1/notifications/CO?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/CO/{documentId}/notifications

The supplier can send a GET request to the /documents/CO/{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/CO/{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": 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 11: 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/CO endpoint.

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

Request sample

curl --location --request PUT 'https://api-test.sovos.com/v1/notifications/CO' \
--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 12: Supplier sends the XML and the PDF to the Buyer

As the final step, the supplier should send the cleared invoice to the buyer. Here are the prescribed methods:

Buyers registered as electronic invoice issuers

The supplier can send the electronic invoice to the buyer, along with the electronic validation document containing the «Document validated by DIAN» value. This can be sent by email or electronically through servers, depending on the agreed-upon plan.

Buyers not registered as electronic invoice issuers

The supplier can send the invoice by:

• Sending an email to the buyer's electronic address, in digital graphic representation format.

• Sending an email to the buyer's electronic address, in the electronic generation format, along with the electronic validation document containing the «Document validated by DIAN» value.

• Sending the printed graphic representation of the electronic invoice.

• Using their own server to deliver the invoice electronically — if there is an agreement in place between the parties.

Note:

If there is no exchange method in place, the supplier sends the printed graphic representation of the electronic invoice.

This process is outside the scope of Sovos.