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. The following sections identify key elements that you should include in the SBD and in the invoice:

SBDH

Node	Required	Attributes	Value
StandardBusinessDocumentHeader.Sender.Identifier	Yes	Authority=Supplier's ISO 3166-1 alpha-2 country code, which should reflect the country of the applicable law for the invoice.	Supplier's tax ID
StandardBusinessDocumentHeader.Sender.ContactInformation.Contact	Yes		Supplier's company ID. If the invoice is not stored for the supplier, use the supplier's name.
StandardBusinessDocumentHeader.Receiver.Identifier	Yes	Authority=Buyer's ISO 3166-1 alpha-2 country code, which should reflect the country of the applicable law for the invoice.	Buyer's tax ID
StandardBusinessDocumentHeader.Receiver.ContactInformation.Contact	Yes		Buyer's company ID. If the invoice is not stored for the buyer, use the buyer's name.
StandardBusinessDocumentHeader.DocumentIdentification.Standard	Yes		urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2
StandardBusinessDocumentHeader.DocumentIdentification.TypeVersion	Yes		2.1
StandardBusinessDocumentHeader.DocumentIdentification.Type	Yes		Attachment
StandardBusinessDocumentHeader.DocumentIdentification.InstanceIdentifier	Yes		The legal invoice number
StandardBusinessDocumentHeader.DocumentIdentification.CreationDateAndTime	Yes		The invoice date
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes (in most cases)		Child node Type: CompanyCode Child node Identifier: Supplier's tax ID
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes (in most cases)		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 (in most cases)		Child node Type: SenderSystemId Child node Identifier: The system ID configured in the backend. This parameter is used to determine which notifications are returned to the client and what attachments they include, so as to meet different needs. If SenderSystemId is not configured on the client side, it'll assume the default value of "DefaultSystemERP". For more information, see this topic.
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes (in most cases)		Child node Type: ProcessType Child node Identifier: Outbound or Inbound
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes (in most cases)		Child node Type: Country Child node Identifier: The required country code.
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes (in most cases)		Child node Type: Archiving.DocumentFormat Child node Identifier: This element specifies the format of the document to be stored. Examples: PDF, XML and CXML. See Applicable countries and document formats for the possible values.
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes (in most cases)		Child node Type: Version Child node Identifier: The correct number for the required country.

Note:

Include all the mandatory nodes as specified in the SBDH schema. If you can't provide the information for a mandatory node, include the empty node in the SBDH. For example, see the InstanceIdentifier nodes in the following sample.

In most cases, the information from the StandardBusinessDocumentHeader.BusinessScope.Scope nodes must be included in the SBDH when storing an invoice (exceptions are explained in the following section).

Sample

<sbd:StandardBusinessDocumentHeader>
		<sbd:HeaderVersion>1.0</sbd:HeaderVersion>
		<sbd:Sender>
			<sbd:Identifier Authority="PL">123456789</sbd:Identifier>
		</sbd:Sender>
		<sbd:Receiver>
			<sbd:Identifier Authority="PL">123456789</sbd:Identifier>
		</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>123</sbd:InstanceIdentifier>
			<sbd:Type>Invoice</sbd:Type>
			<sbd:MultipleType>false</sbd:MultipleType>
			<sbd:CreationDateAndTime>2024-02-22T22:09:26.822Z</sbd:CreationDateAndTime>
		</sbd:DocumentIdentification>
		<sbd:BusinessScope>
			<sbd:Scope>
				<sbd:Type>CompanyCode</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>2220008199</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>SenderDocumentId</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>123456789</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>Inbound</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>BusinessProcess</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:BusinessService>
					<sbd:BusinessServiceName>Archiving</sbd:BusinessServiceName>
				</sbd:BusinessService>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>Country</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>PL</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>Archiving.DocumentFormat</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>Faktura</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>Version</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>1.0</sbd:Identifier>
			</sbd:Scope>
		</sbd:BusinessScope>
	</sbd:StandardBusinessDocumentHeader>
	<svs:SovosDocument>
		<svs:SovosLegalDocument>
			<enc:Base64Document>
				<enc:EmbeddedDocument id="1" fileName="invoice" mimeCode="application/xml">PD9...cmE+</enc:EmbeddedDocument>
			</enc:Base64Document>
			<cac:Attachment>
				<cbc:EmbeddedDocumentBinaryObject format="AttachmentType1" filename="invoice" mimeCode="application/pdf">JVB...Rg0K</cbc:EmbeddedDocumentBinaryObject>
			</cac:Attachment>
		</svs:SovosLegalDocument>
		<ad:AdditionalData>
			<ad:Field name="p1" item="CustomProperty">Property1</ad:Field>
			<ad:Field name="p2" item="CustomProperty">Property2</ad:Field>
		</ad:AdditionalData>
	</svs:SovosDocument>
</sbd:StandardBusinessDocument>

Note:

You can find a full sample of the SBD in the Postman Samples.

Sovos Document

Node	Required	Attributes	Value
SovosDocument.SovosLegalDocument.Base64Document.EmbeddedDocument (with child nodes)	Yes	id: Must always be set to "1". filename: Must be set to the name of the file. mimeCode: Must be set to the mime type of the Base64-encoded invoice, as specified by the Internet Assigned Numbers Authority (IANA).	The string of the Base64-encoded invoice.
SovosDocument.SovosLegalDocument.Attachment (with child nodes)	Yes for each attachment (up to 7)	Required attributes for EmbeddedDocumentBinaryObject: filename: Set it to the file name. mimecode: Set it to the mimetype of the Base64-encoded file, as specified by IANA.	Child node EmbeddedDocumentBinaryObject: Use the Base64-encoded string of the attachment. Child node ExternalReference: A block with the child node Description that must contain the file's description. For example, Attachment1.

Note:

Do not archive an invoice in SCI format as the main document because it is not a legally-valid document. Instead, archive it as an attachment to the legal invoice.

Attachments

The invoice is stored through the Base64Document node. You can also store attachments that are related to the invoice. Attachments may include purchase orders, delivery notes, agreements, invoice hash value, and tax authority response.

Custom Properties

Custom properties need to be put inside the SBD in the Field element, under the AdditionalData node:

Node	Required	Attributes
SovosDocument.AdditionalData.Field	No	name: The name of the custom property. item: Use CustomProperty.

Sample

<svs:SovosDocument>
	<svs:SovosLegalDocument>
		<enc:Base64Document>
			<enc:EmbeddedDocument id="1" filename="invoice" mimeCode="application/xml">JVB...0YK</enc:EmbeddedDocument>
		</enc:Base64Document>
		<cac:Attachment>
			<cbc:EmbeddedDocumentBinaryObject format="AttachmentType1" filename="attachment1" mimeCode="application/pdf">JVB...PRg==</cbc:EmbeddedDocumentBinaryObject>
		</cac:Attachment>
		<cac:Attachment>
			<cbc:EmbeddedDocumentBinaryObject format="AttachmentType2" filename="attachment2" mimeCode="application/xml">PHN...BlPg==</cbc:EmbeddedDocumentBinaryObject>
		</cac:Attachment>
	</svs:SovosLegalDocument>
	    <ad:AdditionalData>
			<ad:Field name="property1" item="CustomProperty">value1</ad:Field>
			<ad:Field name="property2" item="CustomProperty">value2</ad:Field>
		</ad:AdditionalData>
</svs:SovosDocument>

Step 2: Client sends SBD to Sovos

The supplier sends a POST request to the/v2/archived-documents endpoint.

The request must include the following request body parameters:

Request Sample

curl --location --request POST 'https://api-test.sovos.com/v2/archived-documents' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--data-raw '{
    "data": "PD9...dD4=",
    "dataEncoding": "base64"
}'

Response Sample

{
    "status": 202,
    "message": "Accepted",
    "success": true,
    "timestamp": 1708645408342,
    "data": {
        "transactionId": "fa173412-f768-4b3a-adc5-1b3c0140e84d",
        "documentId": "4bd8300288b10538e51954ff1ea43eea"
    }
}

Step 3: Sovos stores invoice

Sovos stores the invoice together with the metadata and any attachments in the specified company.

Step 4: Sovos returns invoice reference

As part of the response, the client receives an invoice reference (documentId) related to the specific file that has been stored. Based on the documentId, the client can do further operations, such as updating or retrieving invoices.

Step 5: Sovos returns application response

The client retrieves the archiving status using GET /v1/documents with the documentId reference received in step 4. This response confirms if the document was successfully archived after the system completes its archiving process, which takes up to ten minutes from the initial submission. If the archiving process failed, the response provides error details.

Error handling

When handling errors, the client application must follow the Indirect Tax API's error handling principles, as specified in the error handling documentation.

In general, all error codes in the 400 range are client errors, which you need to analyze. After fixing the error, you can resend the request. Error codes 408 and 429 are exceptions: In these cases, you should wait at least 60 seconds before retrying. Error codes in the 500 range are server errors. In that case, resend the request according to the instructions given on the error handling documentation, which also includes a full list of error codes Indirect Tax API can return.