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 Standard Business Document Header (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, whereby the ERP document ID is recommended.
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 PUT ' 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: Generate and transmit document

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

Step 6: PEPPOL processes 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

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/{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. 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. 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	It determines if previously acknowledged notifications, within 24 hours of acknowledgment, will be included in the response. Can be set to true or false.
perPage	integer	No		It can be set to specify how many results to return for this page. Only values from 1 to 100 can be used.
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 (Standard Business Document Header).
processType	string	No		Can be set to 0 to include only notifications related to outbound documents.

Request sample

curl --location --request GET ' https://api-test.sovos.com/v1/notifications/FR ?page=PAGE&PERPAGE=2&taxId=YOUR-TAXID}&sourceSystemId=SYSTEMID&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/{countryCode}/{documentId}/notifications

The supplier can send a GET request to the /documents/{countryCode}/{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	Set to the id of the document as returned in step 2.

Request sample

curl --location --request GET ' https://api-test.sovos.com/v1/notifications/FR/DOCUMENT-ID/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/{countryCode} 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 document

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

Step 3: Sovos sends response to supplier

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

Step 4: Sovos sends response to the buyer

Once 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 documents and makes them available to buyers for retrieval.

Step 6: Buyer retrieves application response

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

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. The following query parameters can be set:

Name	Type	Required	Default	Description
taxId	string	No		Set to include only notifications related to the specified taxId. This value relates to the CompanyCode set in the SBDH. It's important to note that once a request doesn't include this parameter it will return all of the notifications related to the country and sourceSystemId.
page	integer	No		To specify the page to be returned, set the value between 1 and 10.
includeAcknowledged	boolean	No	false	Set it to "true" to specify whether previously acknowledged notifications must be included in the result.
perPage	integer	No		To specify the number of results for the returned page, set its value between 1 and 100.
sourceSystemId	string	Yes		Set to include notifications related to documents originating from the given source system. This value relates to the ERP System ID configured on the company endpoint.
processType	string	No		Set it to "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/{CountryCode} 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 
}