Updating invoices
Learn how to follow the process for updating invoices.
The updating invoices functionality can be used to add attachments and metadata or adjust the storage period. The following diagram gives a detailed overview of the process for updating invoices based on the Archiving business process:
Step 1: Supplier Creates Standard Business Document
Every invoice sent to Sovos for archiving 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 updating an invoice:
| Node | Required | Attributes | Value |
|---|---|---|---|
| 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 invoice reference, as returned by Sovos upon initial storage of the invoice. | |
| 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 Child node Child node | |
| StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes (in most cases) | Child node Child node | |
| StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes (in most cases) | Child node Child node | |
| StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes to add searchable metadata or change the storage period | Child node Child node | |
| StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes to add searchable metadata or change the storage period | Child node Child node | |
| StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes to add searchable metadata or change the storage period | Child node Child node |
It is important to include all the mandatory nodes as specified in the SBDH schema. In case the information cannot be provided, and the respective mandatory node has not 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.
<sbd:StandardBusinessDocumentHeader>
<sbd:HeaderVersion>1.0</sbd:HeaderVersion>
<sbd:Sender>
<sbd:Identifier/>
<sbd:ContactInformation>
<sbd:Contact/>
<sbd:EmailAddress/>
<sbd:FaxNumber/>
<sbd:TelephoneNumber/>
<sbd:ContactTypeIdentifier/>
</sbd:ContactInformation>
</sbd:Sender>
<sbd:Receiver>
<sbd:Identifier/>
<sbd:ContactInformation>
<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>8971234435</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>Attachment1</sbd:Description>
</sbd:ManifestItem>
<sbd:ManifestItem>
<sbd:MimeTypeQualifierCode>text/xml</sbd:MimeTypeQualifierCode>
<sbd:UniformResourceIdentifier>#Attachment2</sbd:UniformResourceIdentifier>
<sbd:Description>Attachment2</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.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>Category1</sbd:InstanceIdentifier>
<sbd:Identifier>1234</sbd:Identifier>
</sbd:Scope>
</sbd:BusinessScope>
</sbd:StandardBusinessDocumentHeader>In case of adding attachments, the following nodes must be present:
| Node | Required | Value | Attributes |
|---|---|---|---|
| SovosDocument.SovosLegalDocument.Attachment (with child nodes) | Yes for each attachment (up to 7) | Child node Child node | Required attributes for EmbeddedDocumentBinaryObject:
|
When adding attachments, the nodes listed above must be present.
<svs:SovosDocument>
<svs:SovosLegalDocument>
<cac:Attachment>
<cbc:EmbeddedDocumentBinaryObject filename="attachment1.pdf" mimeCode="application/pdf">Asc..Pdj</cbc:EmbeddedDocumentBinaryObject>
<cac:ExternalReference>
<cbc:Description>Attachment1</cbc:Description>
</cac:ExternalReference>
</cac:Attachment>
<cac:Attachment>
<cbc:EmbeddedDocumentBinaryObject filename="attachment2.xml" mimeCode="application/xml">Asc..Pdj</cbc:EmbeddedDocumentBinaryObject>
<cac:ExternalReference>
<cbc:Description>Attachment2</cbc:Description>
</cac:ExternalReference>
</cac:Attachment>
</svs:SovosLegalDocument>
</svs:SovosDocument>Step 2: Supplier Sends the SBD to Sovos
The supplier sends a PUT request to the /archived-documents/{referenceId} endpoint.
| Name | Type | Required | Description | |
|---|---|---|---|---|
| referenceId | string | Yes | Path | The archived invoice's referenceId |
| data | string | Yes | Request body | Set it to the SBD encoded in Base64, as created in step 1. |
| dataEncoding | string | Yes | Request body | Always set it to "base64". |
See API Specifications for more information about the request. In addition, there are full samples on the Postman Samples page.
curl --location --request PUT 'https://api-test-tls.sovos.com/v1/archived-documents/{referenceId}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--data-raw '{
"data": "PD9...dD4=",
"dataEncoding": "base64"
}'{
"success": true,
"status": 200,
"message": "Document Stored",
"timestamp": 1605702778709,
"data": {
"supplierReference": "dfcafdc20a27427ca88675426cc7c6a4"
}
}Step 3: Sovos Updates the Invoices
Sovos updates the invoice with the new attachments and metadata. The reference ID of the invoice remains the same.
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.