Storing invoices

The following figure gives a detailed overview of the process for storing invoices based on the Archiving business process.

Overview process for storing invoices.

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 will not be stored for the supplier, set it to 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 will not be stored for the buyer, set it to 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

Note:

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

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

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: Set it to the Base64-encoded string of the attachment. Child node ExternalReference: A block with the child node Description that must be set to 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 Base42Document 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: Set the name of the custom property. item: Set it as `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.

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


Name	Type	Required	Description
data	string	Yes	Set it to the SBD encoded in Base64, as created in step 1.
dataEncoding	string	Yes	Always set it to "base64".

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

The client must apply the error handling principles that are outlined on the responses page. The responses page also includes a full list of error codes that the API might return.

In general, all error codes in the 400 range are client errors that the client must analyze. After fixing the errors, the client can resend the request. For 408 and 429 errors, the client must wait 60 seconds before resending the request.

Error codes in the 500 range are server errors. The client should resend the request according to the instructions on the responses page.

Sovos Docs

Storing invoices

Step 1: Supplier creates the Standard Business Document

Step 2: Client sends SBD to Sovos

Step 3: Sovos stores invoice

Step 4: Sovos returns invoice reference

Step 5: Sovos returns application response

Error Handling

sovos-footer