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:

After receiving the document, Sovos performs a structure/schema validation of both the SCI and the SBD parts.

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 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 8: Supplier Retrieves the Application Responses

It is highly recommended that clients configure their Application Response attachments as download links instead of base64 encoded data to avoid potential size limitations when retrieving responses. The default option is "download links".

• When using "download links" the response contains a URL from where the file can be downloaded.

• When using "binary data", the file itself is embedded in the response encoded in base64.

This configuration is available through our Professional Services team.

As a response to the initial sending of the document, the client will receive 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 — once it's available during the process. Additionally, the following details included in the response must be considered:

Transmission Message: It maps to the SCIGovtStatusCode and StatusReason elements in the response message, as described in the Application Responses section, which details any warnings or additional notes to consider. The Italian tax authority doesn't define any specific set of rules about what action to take on each error. Depending on the type of message, the user 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:

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 COAPI endpoints to retrieve application responses:

• GET /notifications/IT

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

We'll discuss these endpoints in the following subsections.

Clients need to make sure they receive all these attachments (via notifications) to be compliant:

• OutcomeNotice

• DeadlinePassedNotice

• FailedDeliveryAttestation

• DeliveryReceipt

• FailedDeliveryNotice

• RejectionNotice

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

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		Set it to include only notifications related to the specified taxId. This value relates to the CompanyCode set in the SBDH. Note: If a request doesn't 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, set the value between 1 and 10.
perPage	integer	No	10	To specify the number of results for the returned page, set its value between 1 and 100. Important: If the attachment file is configured to return the binary content, instead of a link, it's recommended to use only values between 1 and 10.
sourceSystemId	string	Yes		Set it to 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	Set it to "true" to specify whether previously acknowledged notifications, within 24 hours of their acknowledgment, must be included in the result.
processType	string	No		Set it to "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/IT/{documentId}/notifications

To make this request, set the following parameter:

Name	Type	Required	Parameter Type	Description
documentId	string	Yes	Path	Set it to the ID of the document 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

After retrieving application responses, the supplier must process them 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:

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 Available Documents

It is highly recommended that clients configure their Application Response attachments as download links instead of base64 encoded data to avoid potential size limitations when retrieving responses. The default option is download links.

• When using download links the response contains a URL from where the file can be downloaded.

• When using binary data, the file itself is embedded in the response encoded in base64.

This configuration is available through our Professional Services team.

The buyer can use the following COAPI endpoint to retrieve the application responses:

GET /v1/notifications/IT

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, as shown in the following table:

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

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