Step 1: Supplier creates Standard Business Document

Each invoice sent to Sovos must be part of a Standard Business Document . 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 the SBDH, Sovos Document, and SCI pages. The following section explains some of the most important elements that you should include in the SBD and the invoice.

SBDH - Invoice / Lifecycle

The SBDH must be created using the following values:

Note:

Include all the required nodes as specified in the SBDH schema. If the information cannot be provided, and the respective required node has not been mentioned on the current page, for example, the receiver.identifier, the node can be left empty but must still be included in the SBDH.

Node	Required	Attributes	Value
StandardBusinessDocumentHeader.Sender.Identifier	Yes	Authority="BE"	Supplier's VAT Number
StandardBusinessDocumentHeader.Receiver.Identifier	Yes	Authority="BE"	Buyer's VAT Number
StandardBusinessDocumentHeader.DocumentIdentification.Standard	Yes		urn:oasis:names:specification:ubl:schema:xsd:Invoice-2
StandardBusinessDocumentHeader.DocumentIdentification.TypeVersion	Yes		2.1
StandardBusinessDocumentHeader.DocumentIdentification.Type	Yes		Invoice
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes		Child node Type: Country Child node Identifier: BE
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes		Child node Type: ProcessType Child node Identifier: Outbound
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes		Child node Type: CompanyCode Child node Identifier: Supplier's VAT Number
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes		Child node Type: SenderDocumentId Child node Identifier: A unique document ID. We recommend the ERP document ID.
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes		Child node Type: SenderSystemId Child node Identifier: The definition of formats, protocols, and integration rules with our system is now incorporated into ERP System Communications through the setup of these configurations on top of a predefined ERP System ID. The value must be defined by you and configured by SOVOS support.
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes		Child node Type: BusinessCategory Child node Identifier: B2B
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes		Child node Type: Mapping.InputSchema Child node Identifier: One of: ALL-PEPPOLBISUBL-3.0-INVOICE-1.0 ALL-PEPPOLSCI-1.0-INVOICE-1.0
StandardBusinessDocumentHeader.BusinessScope.Scope BusinessService.BusinessServiceName	Yes		Default
SovosDocument.SovosCanonicalInvoice.Invoice	*Yes (only if document type is ALL-PEPPOLSCI-1.0-INVOICE-1.0)		SCI
SovosDocument.SovosLegalDocument.Base64Document	*Yes (for document types: ALL-PEPPOLBISUBL-3.0-INVOICE-1.0)		Other supported formats

Step 2: Supplier sends 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 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--data-raw ' {
   "data": "base64_invoice_data",
   " dataEncoding": "base64",
}'

Response sample

{
	"status": 202,
	"message": "Accepted",
	"success": true,
	"timestamp": 1672405631469,
	"data": {
		"documentId": "DOCUMENT-ID",
         "transactionId": "TRANSACTION-ID"
	}
}

Response sample - failure

{
  "success": false,
  "status": 400,
  "message": "Bad Request",
  "timestamp": 1601666692,
  "errors": [
    {
      "subCode": " XSD_SYNTAX_ERROR",
      "message": " An XML comment cannot contain '--', and '-' cannot be the last character. Line 276, position 11. "
    }
  ]
}

Step 3: Sovos validates the document

Sovos performs the necessary semantic, syntactic, and legal validations. In addition, Sovos validates the schema to make sure the XML file conforms to the expected structure, comparing it with the official schema.

If validation fails, an error is returned in the application response.

Step 4: Mapping

After the XML passes Sovos validations, Sovos maps the document to the appropriate PEPPOL format (BIS3 / PINT).

The format to generate depends on the capabilities published by the recipient in the PEPPOL SMP.

In case mapping fails, an error is returned in the application response.

Step 5: Sovos generates and transmits the document

Sovos then generates the document and sends it to the buyer's PEPPOL AP. If the buyer does not have a registered PEPPOL AP, an error is returned in the application response

Step 6: PEPPOL AP processes the document

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

Step 7: PEPPOL sends response

Sovos receives the response from the buyer's PEPPOL, and then generates notifications for the supplier to retrieve in order to understand the state of the flow. This step is optional and depends on whether the PEPPOL SMP is set to receive PEPPOL invoice responses.

Step 8: Supplier retrieves the application responses

Attachments configuration

There are three ways you can access your attachments:

• As binary data, so the file is embedded in the Base64-encoded application response.

• As open download links, in which the response contains a public URL to download the file.

• As secure download links, in which you need to use the Indirect Tax API's bearer token to download the attachment.

By default, Sovos configures your attachments as open download links to avoid potential size limitations when retrieving responses. To improve security, you should configure them as secure links. Then, make a GET call to the secure link returned by the Indirect Tax API, and include the API token. Sample request:

curl --location 'https://einvoicing-api.sovos.com/download/api/v1/download/JqYyqliXiJFKhXshnBQZfW3qpfwATVGE5Q73T41JUynNLJD8zHy5VH__9qzL9No-Kia9olSw3_lNX3KmaA9Je89Xx--vk5pQjyKx0iT_4CwPSABD0Yg7uxXZ8SNiliEhFY-4TOX7m1TV5FwwfqntehbGaiGMI2JVYu18VBDiC_0/plain%27 \
--header 'Authorization: Bearer TOKEN'Y

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.

To retrieve the application responses, the supplier can use the following API methods:

• GET /notifications/BE

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

GET /notifications/BE

The supplier can send a GET request to the /notifications/BE endpoint to retrieve application responses that match the set 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 is related to the CompanyCode in the SBDH. It's important to note that once a request doesn't include this parameter it will return all notifications related to the country and sourceSystemId.
page	integer	No		To specify the page to be returned, enter a value between 1 and 10.
includeAcknowledged	boolean	No	false	Use "true" to include previously acknowledged notifications, within 24 hours of acknowledgment, in the response.
perPage	integer	No		To specify the number of results for the returned page, use a value between 1 and 100.
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. Note: Document routing configuration The system determines document routing based on the following priority: With configured endpoint: Use the ERP System ID value configured on the endpoint Without a configured endpoint: Use the ERP System ID value from the document's SBDH.
processType	string	No		Use "0" to only include notifications related to outbound documents.

Request sample

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

Response sample

{
 "status": 200,
"message": "Notifications Listed",
"success": true,
"timestamp": 1724063214026,
"data": {
    "pageState": {
        "page": 1,
        "perPage": 10,
        "totalEntries": 2,
        "totalPages": 1
    },
    "notifications": [
        {
            "notificationId": "8e807567-..-e1f9524a76b7",
            "correlationId": "6dc9ef7c-..-3b9c6b413fd9",
            "appPrefix": "CN",
            "metadata": {
                "productId": "be_invoice_outbound_1.0",
                "documentId": "f6bba4ff-..-e2f9524a76b7",
                "erpSystemId": "Outbound_ERPSystemID",
                "processType": "0",
                "taxId": "123456789",
                "sciCloudStatusCode": "214"
            },
            "content": "PD94..jYXRpb25SZXNwb25zZT4=",
            "createdDate": 1724059702440

      }
    ]
  }

GET /documents/BE/{documentId}/notifications

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

Name	Type	Required	Description
documentId	string	Yes	The document ID from step 2

Request sample

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

Response sample

{
	"status": 200,
	"message": " Notifications Listed",
	"success": true,
	"timestamp": 1672405631469,
	"data": {
		"pageState": { … },
		"notifications":[{ … }],
	}
}

Step 9: Supplier marks application response as acknowledged

After retrieving application responses, the supplier must process them and mark them as acknowledged. To do this, send a PUT request to the /notifications/BE endpoint.

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

Request sample

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

Response sample

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

Step 1: Sovos receives the documents

Sovos receives documents from the supplier's PEPPOL Access Point.

Step 2: Sovos validates the document

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

Step 3: Sovos sends the response to supplier

Sovos sends the status response to the supplier's PEPPOL Access Point.

Step 4: Sovos sends the response to the buyer

After the document passes Sovos' validations, Sovos maps the document from the PEPPOL format (BIS3 / PINT) to the buyer's integration format.

Step 5: Sovos makes the document available

Sovos stores the retrieved document and makes it available for buyers to retrieve.

Step 6: Buyer retrieves the application responses

To retrieve the application responses, use the following API endpoint:

GET /notifications/BE

The supplier can send a GET request to the /notifications/BE endpoint to retrieve application responses that match the set 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 is related to the CompanyCode in the SBDH. Note: If a request does not include this parameter, it returns all of the notifications related to the country and sourceSystemId.
page	integer	No		To specify the page to be returned, use a value between 1 and 10.
perPage	integer	No		To specify the number of results for the returned page, use a value between 1 and 100.
sourceSystemId	string	Yes		Include only notifications related to documents that originate from the given source system. This value is related to the ERP System ID configured on the company endpoint.
includeAcknowledged	boolean	No	false	Use "true" to include previously acknowledged notifications in the result.
processType	string	No		Use "1" to only include notifications related to inbound documents.

Request sample

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

Response sample

{
 "status": 200,
"message": "Notifications Listed",
"success": true,
"timestamp": 1724063214026,
"data": {
    "pageState": {
        "page": 1,
        "perPage": 10,
        "totalEntries": 2,
        "totalPages": 1
    },
    "notifications": [
        {
            "notificationId": "8e807567-..-e1f9524a76b7",
            "correlationId": "6dc9ef7c-..-3b9c6b413fd9",
            "appPrefix": "CN",
            "metadata": {
                "productId": "aa_peppol_inbound_1.0",
                "documentId": "f6bba4ff-..-e2f9524a76b7",
                "erpSystemId": "Inbound_ERPSystemID ",
                "processType": "1",
                "taxId": "123456789",
                "sciCloudStatusCode": "215"
            },
            "content": "PD94..jYXRpb25SZXNwb25zZT4=",
            "createdDate": 1724059702440

      }
    ]
  }
}

Step 7: Supplier marks application response as acknowledged

After retrieving application responses, the supplier must process them and mark them as acknowledged. Send a PUT request to the /notifications/BE endpoint.

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

Request sample

curl --location --request PUT 'https://api-test.sovos.com/v1/notifications/BE' \
--header ' x-correlationId: developer-guide' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '[
	"status": "read",
	"notificationId": "NOTIFICATION-ID",
]'

Response sample

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