Storing invoices

Learn the process for storing invoices using the Standard Business Document (SBD) format, including mandatory nodes and archiving recommendations.

The following diagram gives a detailed overview of the process for storing invoices based on the Archiving business process: A diagram showing interactions between the client and Sovos 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. To create the SBD, follow the detailed instructions in the SBDH and Sovos Document pages. In addition, we'll now take a closer look at some key elements within the SBD for archiving:

Note:

An invoice in the SCI format should not be archived as the main document, as it's not a legally valid document. Instead, Sovos recommends archiving it as an attachment to the legal invoice.

Table 1. 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 registered during the configuration. 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 registered during the configuration. 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.Manifest.NumberOfItems	Yes if there are attachments that must be stored along with the invoice		The number of attachments that must be stored along with the invoice, ranging from 1 to 7.
StandardBusinessDocumentHeader.Manifest.ManifestItem (with child nodes)	Yes for every attachment that must be stored along with the invoice (up to 7)		Child node `MimeTypeQualifierCode`: Set it to the mime type of the Base64-encoded file, as specified by the Internet Assigned Numbers Authority (IANA). Child node `UniformResourceIdentifier`: Always set it to "#Attachment{number}". For example, the first attachment will have the value "#Attachment1". Child node `Description`: Set it to a description of the item. For example, "Attachment".
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes (in most cases)		Child node `Type`: BusinessProcess Child node `Identifier`: None. Instead, this scope type must be grouped along with the BusinessService node, which must be set to "Archiving".
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes (in most cases)		Child node `Type`: SenderDocumentId Child node `Identifier`: The unique document ID for the sender used to identify the document. While the value content is not constrained, Sovos recommends using the unique ERP document identification.
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 Definitions and Concepts for the possible values.
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes (in most cases)		Child node `Type`: Archiving.SignatureType Child node `Identifier`: Must be set to Implicit, Explicit or Audit. See Definitions and Concepts for more information. Note: This element may be omitted if the invoice is unsigned.
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes (in most cases)		Child node `Type`: Archiving.Explicit.DetachedSignature Child node `Identifier`: This scope information must be present if Archiving.SignatureType is set to "Explicit". This is the detached signature encoded in Base-64.
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes (in most cases)		Child node `Type`: Archiving.Audit.AuditData Child node `Identifier`: This scope information may only be present if Archiving.SignatureType is set to "Audit". This is the detached audit data encoded in Base-64. If this element is omitted, no audit data exists.
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes (in most cases)		Child node `Type`: Archiving.SignatureFormat Child node `Identifier`: This element specifies the signature format. Examples: PDF, XMLSIG, and PKCS7. See Definitions and Concepts for the possible values. Note: This element may be omitted if the invoice is unsigned.
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes (in most cases)		Child node `Type`: Archiving.AuditCategory Child node `Identifier`: This element specifies the audit category. Examples: XADESA, PADESEPES, and EVIDENCE. See Definitions and Concepts for the possible values. Note: This element can be omitted if no audit data exists.
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes (in most cases)		Child node `Type`: Archiving.StoreFor Child node `Identifier`: Must be set to "Supplier" or "Buyer". This element specifies if the invoice should be stored for this invoicing party. Note: If the invoice must be stored for both parties, this element should be included once for the supplier and once for the buyer.
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes for additional features		Child node `Type`: Archiving.CustomProperty Child node `Identifier`: Any metadata can be used here. Note: The child node Scope.InstanceIdentifier must be set to a category when this element is used. Each invoice can have up to seven custom properties. Thus, this element may be present up to seven times.
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes for additional features		Child node `Type`: Archiving.CustomNumericProperty Child node `Identifier`: Any numeric metadata can be used here. Note: The child node Scope.InstanceIdentifier must be set to a category when this element is used. Each invoice can have up to seven custom numeric properties. Thus, this element may be present up to seven times.
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes for additional features		Child node `Type`: Archiving.OriginalInvoiceNumber Child node `Identifier`: Can be set to the invoice number of the original invoice referred to by the invoice being stored. This can, for example, be used when storing credit notes and corrective invoices.
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes for additional features		Child node `Type`: Archiving.PurchaseOrderNumber Child node `Identifier`: The purchase order numbers associated with the invoice. This element can be present up to 5 times.
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes for additional features		Child node `Type`: Archiving.InitialContentEncoding Child node `Identifier`: This element specifies if the initial document has any additional encoding. Initial document refers to the document before Sovos has applied any signature. Currently, MIME is the only supported value, and it can be used with unsigned documents to indicate that the provided content is encoded in MIME. If the value MIME is used with an S/MIME-signed document, this means that the content was already encoded in MIME before Sovos signed it. For any other document structure, this element must be omitted.
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes for additional features		Child node `Type`: Archiving.AdditionalOutput Child node `Identifier`: Specifies what additional outputs the response should include. The only supported value is DepositInfo, which is a requirement in Italy.
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes for additional features		Child node `Type`: Archiving.StoragePeriodOverride Child node `Identifier`: The storage period end date. The date has to be set at least 3 days into the future. Warning: setting an incorrect storage period end date may cause the document to be deleted before its legally regulated life-time. Use this feature carefully and at your own risk.

Note:

It's important to include all the mandatory nodes as specified in the SBDH schema. If information cannot be provided and the respective mandatory node hasn't 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.

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

<sbd:StandardBusinessDocumentHeader>
	<sbd:HeaderVersion>1.0</sbd:HeaderVersion>
	<sbd:Sender>
		<sbd:Identifier Authority="IN">123456789</sbd:Identifier>
		<sbd:ContactInformation>
			<sbd:Contact>CompanyXYZ</sbd:Contact>
			<sbd:EmailAddress/>
			<sbd:FaxNumber/>
			<sbd:TelephoneNumber/>
			<sbd:ContactTypeIdentifier/>
		</sbd:ContactInformation>
	</sbd:Sender>
	<sbd:Receiver>
		<sbd:Identifier Authority="IN">987654321</sbd:Identifier>
		<sbd:ContactInformation>
			<sbd:Contact>CompanyABC</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:CommonAggregateComponents-2</sbd:Standard>
		<sbd:TypeVersion>2.1</sbd:TypeVersion>
		<sbd:InstanceIdentifier>12345X</sbd:InstanceIdentifier>
		<sbd:Type>Attachment</sbd:Type>
		<sbd:MultipleType>false</sbd:MultipleType>
		<sbd:CreationDateAndTime>2020-06-12T12:00:00Z</sbd:CreationDateAndTime>
	</sbd:DocumentIdentification>
	<sbd:Manifest>
		<sbd:NumberOfItems>2</sbd:NumberOfItems>
		<sbd:ManifestItem>
			<sbd:MimeTypeQualifierCode>application/pdf</sbd:MimeTypeQualifierCode>
			<sbd:UniformResourceIdentifier>#Attachment1</sbd:UniformResourceIdentifier>
			<sbd:Description>Attachment</sbd:Description>
		</sbd:ManifestItem>
		<sbd:ManifestItem>
			<sbd:MimeTypeQualifierCode>application/xml</sbd:MimeTypeQualifierCode>
			<sbd:UniformResourceIdentifier>#Attachment2</sbd:UniformResourceIdentifier>
			<sbd:Description>Attachment</sbd:Description>
		</sbd:ManifestItem>
	</sbd:Manifest>
	<sbd:BusinessScope>
		<sbd:Scope>
			<sbd:Type>SenderDocumentId</sbd:Type>
			<sbd:InstanceIdentifier/>
			<sbd:Identifier>123456789</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>Archiving.DocumentFormat</sbd:Type>
			<sbd:InstanceIdentifier/>
			<sbd:Identifier>PDF</sbd:Identifier>
		</sbd:Scope>
		<sbd:Scope>
			<sbd:Type>Archiving.SignatureType</sbd:Type>
			<sbd:InstanceIdentifier/>
			<sbd:Identifier>Implicit</sbd:Identifier>
		</sbd:Scope>
		<sbd:Scope>
			<sbd:Type>Archiving.SignatureFormat</sbd:Type>
			<sbd:InstanceIdentifier/>
			<sbd:Identifier>PDF</sbd:Identifier>
		</sbd:Scope>
		<sbd:Scope>
			<sbd:Type>Archiving.AuditCategory</sbd:Type>
			<sbd:InstanceIdentifier/>
			<sbd:Identifier>PADESEPES</sbd:Identifier>
		</sbd:Scope>
		<sbd:Scope>
			<sbd:Type>Archiving.StoreFor</sbd:Type>
			<sbd:InstanceIdentifier/>
			<sbd:Identifier>Supplier</sbd:Identifier>
		</sbd:Scope>
		<sbd:Scope>
			<sbd:Type>Archiving.CustomProperty</sbd:Type>
			<sbd:InstanceIdentifier>TestCategory</sbd:InstanceIdentifier>
			<sbd:Identifier>Test23</sbd:Identifier>
		</sbd:Scope>
		<sbd:Scope>
			<sbd:Type>Archiving.CustomNumericProperty</sbd:Type>
			<sbd:InstanceIdentifier>CategoryX</sbd:InstanceIdentifier>
			<sbd:Identifier>1234</sbd:Identifier>
		</sbd:Scope>
	</sbd:BusinessScope>
</sbd:StandardBusinessDocumentHeader>

Table 2. 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".

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

<svs:SovosDocument>
	<svs:SovosLegalDocument>
		<enc:Base64Document>
			<enc:EmbeddedDocument id="1" filename="invoice.pdf" mimeCode="application/pdf">JVB...0YK</enc:EmbeddedDocument>
		</enc:Base64Document>
		<cac:Attachment>
			<cbc:EmbeddedDocumentBinaryObject filename="attachment1.pdf" mimeCode="application/pdf">JVB...PRg==</cbc:EmbeddedDocumentBinaryObject>
			<cac:ExternalReference>
				<cbc:Description>Attachment1</cbc:Description>
			</cac:ExternalReference>
		</cac:Attachment>
		<cac:Attachment>
			<cbc:EmbeddedDocumentBinaryObject filename="attachment2.xml" mimeCode="application/xml">PHN...BlPg==</cbc:EmbeddedDocumentBinaryObject>
			<cac:ExternalReference>
				<cbc:Description>Attachment2</cbc:Description>
			</cac:ExternalReference>
		</cac:Attachment>
	</svs:SovosLegalDocument>
</svs:SovosDocument>

Attachments: As explained before, an invoice is stored via the Base64Document node. In addition, it's possible to store attachments related to the invoice. Attachments are documents associated with the invoice and can be, for example, purchase orders, delivery notes, agreements, invoice hash value, and tax authority response. As explained before, to store attachments, one should include the Manifest node as part of the SBDH and the Attachment node as part of the Sovos Document container. Up to 7 attachments can be stored with the invoice.
Custom Storage Period End Date: By default, Sovos applies a storage period to every invoice which is compliant with the applicable law. If you prefer to apply a customized storage end date for a particular invoice, a custom end date can be set via the Archiving.StoragePeriodOverride scope information. The earliest date that can be set is 3 days in the future.
Note:
Using this element overrides the default storage period and is an explicit request for Sovos eArchive to delete the invoice on that specific date. Hence, setting an incorrect date may cause the document to be deleted before its legally regulated lifetime, so this feature should be used carefully.

Step 2: Supplier Sends the SBD to Sovos

The supplier sends a POST request to the /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".

Note:

See API Specifications for more information about the request. In addition, there's a full sample request and response on the Postman Samples page.

Request sample

curl --location --request POST 'https://api-test-tls.sovos.com/v1/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

{
    "success": true,
    "status": 200,
    "message": "Document Stored",
    "timestamp": 1648827072703,
    "data": {
        "supplierReference": "dfcafdc20a27427ca88675426cc7c6a4"
        "depositInfo": {
            "documentHash":"sKkPmBdneBmYi7F53YkoFg6TrOp9uDuYn8kqSo8=",
            "documentHashAlgorithm": "Sha256",
            "documentDate": "2022-04-01T15:31:12:557104Z"
        }
    }
}

Step 3: Sovos Stores the Invoice

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

Step 4: Sovos Returns the Invoice Reference

As part of the response, the client application will receive an invoice reference related to the specific file that has been stored. If the operation is performed for both parties, i.e., Archiving.StoreFor has been set for both the supplier and the buyer, two invoice references (one for the supplier and one for the buyer) will be returned within the same response. Finally, if Archiving.AdditionalOutput was specified, the response will also contain those details. See also step 2 for a sample response.

Error Handling

Adhere to the error handling principles outlined on the responses page.

In general, all error codes in the 400 range are client errors, so analyze them individually. After fixing the error, it's possible to resend the request. Error codes 408 and 429 are exceptions: in these cases, you should wait at least 60 seconds before retrying. The error codes in the 500 range are server errors. In that case, you need to resend the request, according to the instructions given on the responses page, which also includes a full list of error codes the COAPI can return.

Sovos Docs

Storing invoices

Step 1: Supplier Creates the Standard Business Document

Step 2: Supplier Sends the SBD to Sovos

Step 3: Sovos Stores the Invoice

Step 4: Sovos Returns the Invoice Reference

Error Handling

sovos-footer