Step 1: Sovos receives the document

Sovos receives the document from the supplier's PEPPOL access point.

Step 2: Validation

Sovos performs the necessary semantic, syntactic, and legal validations.

Step 3: Send the response

Sovos sends the status response to the supplier's PEPPOL access point.

Step 4: Mapping

When the document passes Sovos' validations, we map the document from the Business Interoperability Specifications (BIS) 3 or PEPPOL International Invoice (PINT) PEPPOL formats to the buyer's format.

Step 5: Sovos makes the document available

Sovos stores the retrieved documents and makes them available to buyers for retrieval.

Step 6: Buyer retrieves the application responses

To complete a transaction, the buyer must retrieve the application responses until the transaction has finished. If the buyer has subscribed to all notifications, the transaction can generate different application responses.

The buyer can use the following Indirect Tax API endpoint to retrieve application responses that match the set search criteria: GET /notifications/{countryCode}.

This endpoint allows setting the following query parameters:

Request sample

curl --location 'https://api-test.sovos.com/v1/notifications/{countryCode}?processType=1&sourceSystemId=SystemERP&taxId=YOUR-TAXID&orgId=0000000-0000-0000-0000000000001&senderDocumentId=0000000AB' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE'

Step 7: Buyer acknowledges the retrieved documents

After retrieving the documents, the buyer must process them and mark them as read. This can be done by sending a PUT request to the /notifications/{countryCode} endpoint.

To make this request, use the following parameters:

Request sample

curl --location --request PUT 'https://api-test.sovos.com/v1/notifications/{countryCode}' \
--header 'Content-Type: application/json' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--data '[
    {
        "status": "read",
        "notificationId": "55f26671-...-d42925946ebf"
    }
]'

Response sample

{
    "status": 200,
    "message": "OK",
    "success": true,
    "timestamp": 1653424820578,
    "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:

Here is an SBD sample:

<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:leg="http://www.sovos.com/namespaces/sovosExtensions/LegalExtension" xmlns:inv="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.unece.org/cefact/namespaces/StandardBusinessDocumentHeader file:///C:\Users\helder.barbosa\OneDrive - Sovos Compliance\Sovos\Sovos XSDs\Sovos Document/StandardBusinessDocumentHeader.xsd">
<sbd:StandardBusinessDocumentHeader>
	<sbd:HeaderVersion>1.0</sbd:HeaderVersion>
	<sbd:Sender>
		<sbd:Identifier Authority="{countryCode}">SENDER-TAXID</sbd:Identifier>
	</sbd:Sender>
	<sbd:Receiver>
		<sbd:Identifier Authority="{countryCode}">RECEIVER-TAXID</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>100002</sbd:InstanceIdentifier>
		<sbd:Type>Invoice</sbd:Type>
		<sbd:MultipleType>false</sbd:MultipleType>
		<sbd:CreationDateAndTime>2023-10-31T00:00:00Z</sbd:CreationDateAndTime>
	</sbd:DocumentIdentification>
	<sbd:BusinessScope>
		<sbd:Scope>
			<sbd:Type>Country</sbd:Type>
			<sbd:InstanceIdentifier/>
			<sbd:Identifier>{countryCode}</sbd:Identifier>
		</sbd:Scope>
		<sbd:Scope>
			<sbd:Type>CompanyCode</sbd:Type>
			<sbd:InstanceIdentifier/>
			<sbd:Identifier>SENDER-TAXID</sbd:Identifier>
		</sbd:Scope>
		<sbd:Scope>
			<sbd:Type>SenderDocumentId</sbd:Type>
			<sbd:InstanceIdentifier/>
			<sbd:Identifier>SENDER-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>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>eDelivery</sbd:BusinessServiceName>
			</sbd:BusinessService>
		</sbd:Scope>
		<sbd:Scope>
			<sbd:Type>BusinessCategory</sbd:Type>
			<sbd:InstanceIdentifier/>
			<sbd:Identifier>B2B</sbd:Identifier>
		</sbd:Scope>
		<sbd:Scope>
			<sbd:Type>Version</sbd:Type>
			<sbd:InstanceIdentifier/>
			<sbd:Identifier>3.0</sbd:Identifier>
		</sbd:Scope>
	</sbd:BusinessScope>
</sbd:StandardBusinessDocumentHeader>

Step 2: Supplier sends the SBD to Sovos

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

To make this request, set 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...de4=",
	"dataEncoding" : "base64"
}'

Response sample:

{
    "timestamp": 1605282724079,
    "status": 202,
    "success": true,
    "message": "Document Received",
    "data": {
        "documentId": "3add2b7104dc0049ff0bf410f57e0a19afaf"
    }
}

Step 3: Validation

Sovos performs the necessary semantic, syntactic, and legal validations. In addition, Sovos performs a schema validation to ensure the XML file conforms to the expected legal validations. Additionally, Sovos performs a schema validation to ensure the XML file conforms to the expected structure by comparing it with the official schema.

If the validation fails, you'll see an error when you retrieve application responses.

Step 4: Mapping

When the XML passes Sovos' validations, we map the document to the appropriate PEPPOL format: Business Interoperability Specifications (BIS) 3 or PEPPOL International Invoice (PINT). If the mapping fails, you'll see an error when you retrieve application responses.

Step 5: Sovos generates and transmits the document

Sovos generates the document and sends it to the buyer's PEPPOL access point (AP). If the buyer doesn't have a registered PEPPOL access point, you'll see an error when retrieving application responses.

Step 6: Buyer's PEPPOL AP processes the document

After receiving the document, the buyer's PEPPOL AP will process (validate) it, make it available for the buyer to retrieve, and send a response back to Sovos.

Step 7: Buyer's PEPPOL AP sends the response

Sovos receives the response from the buyer's PEPPOL access point and then generates notifications for the supplier to retrieve, so they can understand the flow's state.

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. These responses provide status information and also include a URL to access the documents once these have become 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", "CA", "PD", or "RE", which indicates that the transaction has finished.

Sample application responses:

<cac:DocumentResponse>
<cac:Response>
<cbc:ResponseCode listID="SCIResponseCode">AP</cbc:ResponseCode>
<cac:Status>
<cbc:StatusReasonCode listID="SCICloudStatusCode">102</cbc:StatusReasonCode>
<cbc:StatusReason>Document validated successfully.</cbc:StatusReason>
</cac:Status>
</cac:Response>

<cac:DocumentResponse>
<cac:Response>
<cbc:ResponseCode listID="SCIResponseCode">UQ</cbc:ResponseCode>
<cac:Status>
<cbc:StatusReasonCode listID="SCICloudStatusCode">108</cbc:StatusReasonCode>
<cbc:StatusReason>Document being processed by the recipient</cbc:StatusReason>
</cac:Status>
<cac:Status>
<cbc:StatusReasonCode listID="OPStatusReason">REF</cbc:StatusReasonCode>
</cac:Status>
</cac:Response>

<cac:DocumentResponse>
<cac:Response>
<cbc:ResponseCode listID="SCIResponseCode">IP</cbc:ResponseCode>
<cac:Status>
<cbc:StatusReasonCode listID="SCICloudStatusCode">108</cbc:StatusReasonCode>
<cbc:StatusReason>Document being processed by the recipient</cbc:StatusReason>
</cac:Status>
</cac:Response>

<cac:DocumentResponse>
<cac:Response>
<cbc:ResponseCode listID="SCIResponseCode">IP</cbc:ResponseCode>
<cbc:EffectiveDate>2017-12-15</cbc:EffectiveDate>
<cac:Status>
<cbc:StatusReasonCode listID="SCICloudStatusCode">108</cbc:StatusReasonCode>
<cbc:StatusReason>Document being processed by the recipient</cbc:StatusReason>
</cac:Status>
<cac:Status>
<cbc:StatusReason>Shipment has not yet been received. Invoice processing will be attempted later.</cbc:StatusReason>
</cac:Status>

<cac:DocumentResponse>
<cac:Response>
<cbc:ResponseCode listID="SCIResponseCode">AP</cbc:ResponseCode>
<cac:Status>
<cbc:StatusReasonCode listID="SCICloudStatusCode">203</cbc:StatusReasonCode>
<cbc:StatusReason>Document accepted/acknowledged by the counterparty.</cbc:StatusReason>
</cac:Status>
</cac:Response>

<cac:DocumentResponse>
<cac:Response>
<cbc:ResponseCode listID="SCIResponseCode">CA</cbc:ResponseCode>
<cac:Status>
<cbc:StatusReasonCode listID="SCICloudStatusCode">210</cbc:StatusReasonCode>
<cbc:StatusReason>Document conditionally accepted by the recipient</cbc:StatusReason>
</cac:Status>
<cac:Status>
<cbc:StatusReasonCode listID="OPStatusReason">PAY</cbc:StatusReasonCode>
</cac:Status>
</cac:Response>

<cac:DocumentResponse>
<cac:Response>
<cbc:ResponseCode listID="SCIResponseCode">PD</cbc:ResponseCode>
<cbc:EffectiveDate>2017-12-30</cbc:EffectiveDate>
<cac:Status>
<cbc:StatusReasonCode listID="SCICloudStatusCode">211</cbc:StatusReasonCode>
<cbc:StatusReason>Document payment sent by the recipient</cbc:StatusReason>
</cac:Status>
</cac:Response>

<cac:DocumentResponse>
<cac:Response>
<cbc:ResponseCode listID="SCIResponseCode">RE</cbc:ResponseCode>
<cac:Status>
<cbc:StatusReasonCode listID="NetworkErrorCode">BTZ0016</cbc:StatusReasonCode>
<cbc:StatusReason>DocumentValidationError: 12801654</cbc:StatusReason>
</cac:Status>
<cac:Status>
<cbc:StatusReasonCode listID="NetworkErrorCode">B4_2000046</cbc:StatusReasonCode>
<cbc:StatusReason>Goods service available date must be smaller or equal than the document date.</cbc:StatusReason>
</cac:Status>
<cac:Status>
<cbc:StatusReasonCode listID="NetworkErrorCode">BTZ_036</cbc:StatusReasonCode>
<cbc:StatusReason>For the invoices with amounts subject and no exempt, the type is mandatory.</cbc:StatusReason>
</cac:Status>
<cac:Status>
<cbc:StatusReasonCode listID="NetworkErrorCode">BTZ_037</cbc:StatusReasonCode>
<cbc:StatusReason>For the invoices with amounts subject and no exempt, the type must be one of these values S1 (Without reversal of the taxable subject) or S2 (With reversal of the taxable subject).</cbc:StatusReason>
</cac:Status>
<cac:Status>
<cbc:StatusReasonCode listID="SCICloudStatusCode">401</cbc:StatusReasonCode>
<cbc:StatusReason>Error processing document.</cbc:StatusReason>
</cac:Status>

<cac:DocumentResponse>
<cac:Response>
<cbc:ResponseCode listID="SCIResponseCode">RE</cbc:ResponseCode>
<cac:Status>
<cbc:StatusReasonCode listID="SCICloudStatusCode">405</cbc:StatusReasonCode>
<cbc:StatusReason>Document rejected by the counterparty.</cbc:StatusReason>
</cac:Status>
<cac:Status>
<cbc:StatusReasonCode listID="OPStatusReason">REF</cbc:StatusReasonCode>
<cbc:StatusReason>A textual explanation for why the invoice is being rejected. E.g. PO reference is missing.</cbc:StatusReason>
</cac:Status>
</cac:Response>

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

• GET /notifications/{countryCode}

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

GET /notifications/{countryCode}

The supplier can send a GET request to the /notifications/{countryCode} endpoint to retrieve application responses that match the set search criteria. This endpoint allows using the following query parameters:

Name	Type	Required	Default	Description
taxId	string	No		Include only notifications related to the specified taxId. This value is related to the CompanyCode from the SBDH.
page	integer	No	1	To specify the page to be returned, use a value between 1 and 10.
perPage	integer	No	10	To specify the number of results for the returned page, use a value between 1 and 100. Important: 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	Use "true" to include previously acknowledged notifications in the result.
orgId	string	No		Restricts the notifications listed to documents associated with the given organization ID (only applicable for Worskspace tenants).
senderDocumentId	string	No		Restricts the notifications listed to the given sender document ID if you used the SenderDocumentId scope in the POST /v1/documents endpoint.

Request sample

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

Response sample

{
    "status": 200,
    "message": "Notifications Listed",
    "success": true,
    "timestamp": 1708537586642,
    "data": {
        "pageState": {
            "page": 1,
            "perPage": 2,
            "totalEntries": 1,
            "totalPages": 1
        },
            {
                "notificationId": "b0a9c81a-...9b29-e7a693da0ecd",
                "correlationId": "rrt-...-21916838-1",
                "appPrefix": "sph",
                "metadata": {
                    "productId": "aa_edelivery__1.0",
                    "documentId": "DOCUMENT-ID",
                    "erpDocumentId": "ERP-DOCUMENT-ID",
                    "erpSystemId": "SystemERP",
                    "processType": "0",
                    "taxId": "999999999",
                    "sciCloudStatusCode": "209",
                    "sciResponseCode": "AP",
                    "sciStatusAction": "NOA"
                },
                "content": "PD..g==",
                "createdDate": 1708008887925
            }
        ]
    }
}

GET /documents/{countryCode}/{documentId}/notifications

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

Name	Type	Required	Parameter type	Default	Description
documentId	string	Yes	Path		The document ID returned in step 2
includeAcknowledged	boolean	No	Query	false	Use "true" to include previously acknowledged notifications in the result

Request sample

curl --location --request GET 'https://api-test.sovos.com/v1/documents/{countryCode}/{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": 1633687728708,
    "status": 200,
    "success": true,
    "message": "Notifications Listed",
    "data": {
        "pageState": {
            "page": 1,
            "perPage": 2,
            "totalPages": 1,
            "totalEntries": 1
        },
        "notifications": [
            {
                "createdDate": 1629824492,
                "metadata": {
                    "productId": "aa_edelivery__1.0",
                    "documentId": "3add2b7104dc0049ff0bf410f57e0a19afaf",
                    "erpDocumentId": "80257087",
                    "erpSystemId": "SystemERP",
                    "processType": "0",
                    "taxId": "999999999",
                    "sciCloudStatusCode": "200",
                    "sciResponseCode": "AP",
                    "sciStatusAction": "NOA"
                },
                "appPrefix": "SPH",
                "notificationId": "da3095da-f974-420c-bce2-e33682692276",
                "content": "PEF...c2U+"
            }
        ]
    }
}

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/{countryCode} endpoint.

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

Request sample

curl --location --request PUT 'https://api-test.sovos.com/v1/notifications/{countryCode}' \
--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."
}