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 and in the invoice.

<svs:SovosDocument>
	<svs:SovosLegalDocument>
		<enc:Base64Document>
			<enc:EmbeddedDocument id="1" filename="invoice.xml" mimeCode="application/xml">
			PD94bWwgdmVyc21...DOog

SBD sample

Below is a sample of the SBD. In addition, there's a full sample of the SBD in the Postman Samples page.

<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:sbd="http://www.unece.org/cefact/namespaces/StandardBusinessDocumentHeader" xmlns:xades="http://uri.etsi.org/01903/v1.3.2#" 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:ext="urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2" xmlns:inv="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2">
	<sbd:StandardBusinessDocumentHeader>
		<sbd:HeaderVersion>1.0</sbd:HeaderVersion>
		<sbd:Sender>
			<sbd:Identifier Authority="IT">123456789</sbd:Identifier>
			<sbd:ContactInformation>
				<sbd:Contact>123456789</sbd:Contact>
				<sbd:EmailAddress/>
				<sbd:FaxNumber/>
				<sbd:TelephoneNumber/>
				<sbd:ContactTypeIdentifier/>
			</sbd:ContactInformation>
		</sbd:Sender>
		<sbd:Receiver>
			<sbd:Identifier Authority="IT">444555666</sbd:Identifier>
			<sbd:ContactInformation>
				<sbd:Contact>444555666</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>2022-06-16T00:31:52Z</sbd:CreationDateAndTime>
		</sbd:DocumentIdentification>
		<sbd:BusinessScope>
			<sbd:Scope>
				<sbd:Type>Version</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>1.2.2</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>SenderDocumentId</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>321412</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>SenderSystemId</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>SystemERP</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
                <sbd:Type>CompanyCode</sbd:Type>
                <sbd:InstanceIdentifier/>
                <sbd:Identifier>444555666</sbd:Identifier>
            </sbd:Scope>
			<sbd:Scope>
				<sbd:Type>Country</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>IT</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>ProcessType</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>Outbound</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>FatturaPA</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>SubSchema</sbd:Type>
				<sbd:InstanceIdentifier/>
				<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 Elements*
			</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 'x-correlationId: 057b5a5e-...-9d583b4d121c' \
--data-raw '{
	"data": "PD9...d4=",
	"dataEncoding" : "base64"
}'

Response sample

{
    "status": 202,
    "message": "Accepted",
    "success": true,
    "timestamp": 1684270247645,
    "data": {
        "transactionId": "813d91ef-...-f98c09aa1157",
        "documentId": "350...550"
    }
}

Step 3: Sovos maps the SCI into FatturaPA

Upon receiving the SCI, Sovos maps the file into the required FatturaPA format.

Step 4: Sovos signs the document

Once the document is ready, it is signed with the qualified seal certificate.

Step 5: Sovos transmits the document

After signing the FatturaPA file, Sovos transmits it to the tax authority's e-Invoice system (SDI).

Step 6: SDI processes the document

SDI validates the schema and several business requirements. Then, SDI generates an approval or rejection response message that includes an error message, when applicable.

Step 7: SDI sends the response to Sovos

This step varies depending on the type of transaction: B2B or B2G.

Step 7a: B2B Step 7b: B2G

After performing its services, the SDI sends the response to Sovos. The system then returns multiple status messages while processing the document. Here is a diagram of this step:

Note:

The customer must continue polling until a "final" status notification is received. In cases where the SDI cannot reach the buyer, it may take up to five days to receive a non-reachable notification.

In a B2G transaction, the supplier must continuously poll for notifications until an acceptance or rejection is received from the buyer. If the buyer does not respond within 15 days, the SDI will send a message stating that the deadline has passed, which can be considered an implicit acceptance. Here is a diagram of this step:

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, which provide status information and also contain the signed XML encoded in Base64 when it's available during the process.

Additionally, you must consider the following details included in the response:

Transmission message

It maps to the SCIGovtStatusCode and StatusReason elements in the response message, as described in the application responses documentation, which details any warnings or additional notes to consider. The tax authority doesn't define any specific set of rules about what action to take on each error. Depending on the type of message, you may have to modify the invoice, take some additional action, or simply make a note for the future.

For each invoice, the following fields must be unique inside the invoice payload:

• Invoice Date

• Invoice Number

• Document Type

• Supplier Identification

Clients have the option to retrieve application responses (notifications) in one of two ways:

Fetch everything in one single response (notification)

This means, when polling for responses, Sovos will only return one final notification with SCICloudStatusCode 209 that contains all the relevant attachments/data. Detailed description follows.

Fetch multiple responses (notifications) containing different information

In this case, when polling for responses, Sovos will return multiple notifications with different SCICloudStatusCode values containing different attachments/data until the final one (with status 209) is returned. Detailed description follows.

In case these fields are not unique, the ApplicationResponse will contain the following error for the subsequent invoices: "Processing of another operation with identical identifier(s) has already been initiated."

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

• GET /notifications/IT

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

We'll discuss these endpoints in the following subsections.

To be compliant, make sure you receive all these attachments (via notifications):

• OutcomeNotice

• DeadlinePassedNotice

• FailedDeliveryAttestation

• DeliveryReceipt

• FailedDeliveryNotice

• RejectionNotice

In addition, here is a workflow diagram explaining when certain attachments (as part of the notifications) become available:

B2B B2G

In the B2B case, there is one response that comes from the tax authority.

In the B2G case, there are usually multiple responses that come from the tax authority:

GET/Notifications/IT

The supplier can send a GET request to the /notifications/IT endpoint to retrieve application responses that match the set search criteria. This endpoint allows setting 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 will return all the notifications related to the country and the sourceSystemId parameter.
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.
includeAckwnowledged	boolean	No	false	Use "true" to include previously acknowledged notifications, within 24 hours of their acknowledgment, in the result.
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/IT?page=1&perPage=2&taxId={taxId}&sourceSystemId={sourceSystemId}&processType=0' \
--header 'Content-Type: application/json' \
--header 'x-correlationId: 057b5a5e-...-9d583b4d121c'

Response sample

{
    "timestamp": 1633685509314,
    "status": 200,
    "success": true,
    "message": "Notifications Listed",
    "data": {
        "pageState": {
            "page": 1,
            "perPage": 50,
            "totalEntries": 1
        },
        "notifications": [
            {
                "createdDate": 1633681296,
                "metadata": {
                    "productId": "it_FatturaPA__1.2.2",
                    "documentId": "DOCUMENT-ID",
                    "erpDocumentId": "ERP-DOCUMENT-ID",
                    "erpSystemId": "SystemERP",
                    "processType": "0",
                    "taxId": "YOUR-TAXID",
                    "sciCloudStatusCode": "200",
                    "sciResponseCode": "AP",
                    "sciStatusAction": "NOA",
                    "sciGovtStatusCode": "100"
                },
                "appPrefix": "DLT",
                "notificationId": "a8dc1aa2-...-97a3d5fdb91c",
                "content": "PEF...NlPg=="
            }
        ]
    }
}

GET /documents/IT/{documentId}/notifications

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

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

Request sample

curl --location --request GET 'https://api-test.sovos.com/v1/documents/IT/{documentId}/notifications?' \
--header 'Content-Type: application/json' \
--header 'x-correlationId: 6d49dcfe-...-44f4e720d70b'

Response sample

{
    "timestamp": 1633685509314,
    "status": 200,
    "success": true,
    "message": "Notifications Listed",
    "data": {
        "pageState": {
            "page": 1,
            "perPage": 50,
            "totalEntries": 1
        },
        "notifications": [
            {
                "createdDate": 1633681296,
                "metadata": {
                    "productId": "it_FatturaPA__1.2.2",
                    "documentId": "DOCUMENT-ID",
                    "erpDocumentId": "ERP-DOCUMENT-ID",
                    "erpSystemId": "SystemERP",
                    "processType": "0",
                    "taxId": "YOUR-TAXID",
                    "sciCloudStatusCode": "200",
                    "sciResponseCode": "AP",
                    "sciStatusAction": "NOA",
                    "sciGovtStatusCode": "100"
                },
                "appPrefix": "DLT",
                "notificationId": "a8dc1aa2-...-97a3d5fdb91c",
                "content": "PEF...NlPg=="
            }
        ]
    }
}

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

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

Request sample

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

Response sample

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

Sovos generates the PDF

Sovos generates a PDF that presents the content of the invoice XML in a human-readable format that follows the official SDI stylesheet.

Archiving

It's possible to compliantly archive the XML, the application response, and any graphical representation (i.e., PDF) using Sovos' Compliant Archive. However, this will not be done automatically as part of the clearance process. Instead, customers need to perform their own archiving using our Archiving resource (see also our eArchiving integration guide).

SDI sends the invoice to the buyer

Sovos does not handle the delivery of the invoice to the buyer. Once the document is processed, the SDI sends it directly to the buyer.

Step 1: Sovos retrieves documents from the SDI

Sovos receives the inbound FatturaPA documents from SDI for any destination code generated by Sovos.

If you are a Sovos partner, you can have your dedicated destination code. Otherwise, the destination code value for UAT environment is "DELTADI", whereas for Production it is "1BM91M1".

Step 2: Sovos maps the FatturaPA into SCI

Upon receiving the FatturaPA, Sovos maps the file into the SCI format.

Step 3: Sovos makes the documents available

Sovos stores the retrieved documents and makes them available for the buyers to fetch them. The PDF version of these documents is also made available, which follows the official SDI stylesheet.

Step 4: Buyer 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

To complete a transaction, the buyer must retrieve the application responses until the transaction has finished using the GET/v1/notifications/IT endpoint. If the buyer has subscribed to all notifications, the transaction can generate different application responses, as shown in the following table:

GET /notifications/IT

The buyer can send a GET request to the /notifications/IT endpoint to retrieve application responses that match the set search criteria. This endpoint allows setting the following query parameters:

Name	Type	Required	Default	Description
taxId	string	Yes for customers, no for hub partners		Include only notifications related to the specified taxId.
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.
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/IT?processType=1&sourceSystemId=YOUR-SYSTEM&taxId=YOUR-TAXID' \
--header 'x-correlationId: developer-guide'

Response sample

{
    "status": 200,
    "message": "Notifications Listed",
    "success": true,
    "timestamp": 0,
    "data": {
        "pageState": {
            "page": 1,
            "perPage": 10,
            "totalEntries": 1,
            "totalPages": 1
        },
        "notifications": [
            {
                "notificationId": "ba056226-...-a111e24acd51",
                "correlationId": "49a75544-...-5f672c2a814d",
                "appPrefix": "DLT",
                "metadata": {
                    "productId": "TBD",
                    "transactionId": "47514154-...-77a72ab75731",
                    "documentId": "04c...151",
                    "erpDocumentId": "YOUR-DOCUMENT-ID",
                    "erpSystemId": "YOUR-SYSTEMERP",
                    "processType": "1",
                    "taxId": "YOUR-TAXID",
                    "sciCloudStatusCode": "209",
                    "sciResponseCode": "AP",
                    "sciStatusAction": "NOA"
                },
                "content": "PD...T4=",
                "createdDate": 1674572920
            }
        ]
    }
}

Step 5: Buyer acknowledges the retrieved documents

After retrieving the documents, the buyer must process them and mark them as acknowledged. This can be done by sending a PUT request to the /v1/notifications/IT endpoint.

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

Request sample

curl --location --request PUT 'https://api-test.sovos.com/v1/notifications/IT' \
--header 'Content-Type: application/json' \
--header 'x-correlationId: developer-guide' \
--data-raw '[
    {
        "status": "read",
        "notificationId": "51341d39-...-a73d73e0de76"
    }
]'

Response sample

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

Archiving

You can compliantly archive the XML, the application response, and any graphical representation (i.e., PDF) using Sovos' Compliant Archive. However, this is not done automatically as part of the clearance process. Instead, you need to perform your own archiving using our Archiving resource (see also our eArchiving integration guide).