Retrieving invoices
This guide details the process for retrieving invoices using a GET request to the Sovos API, including handling responses and errors.
The following diagram gives a detailed overview of the process for retrieving invoices:
Step 1: Client Sends GET Request
A client application can retrieve a stored invoice by sending a GET request to the /archived-documents/{referenceId} endpoint.
| Name | Type | Required | Description |
|---|---|---|---|
| referenceId | string | Yes | The reference ID of the invoice as returned by Sovos after it's stored. |
See the API Specifications page for more information about the request. In addition, there are full samples on the Postman Samples page.
curl --location --request GET 'https://api-test-tls.sovos.com/v1/archived-documents/{referenceId}' \
--header 'Authorization: Bearer oroMYMXxuyqmRAzzUDKRnOn2FaNc' \
--header 'Content-Type: application/json' \
--header 'x-correlationId: 2063583a-f0e0-4f85-9a6b-2d4616bc7424'{
"success": true,
"status": 200,
"message": "Document",
"timestamp": 1605712004725,
"data": "PD9...dD4="
}Step 2: Sovos Returns the Invoice (+ Attachments and Metadata)
As a response, Sovos returns the Base64-encoded Standard Business Document (SBD) that was initially sent to Sovos. This SBD includes the invoices, any attachments, and metadata. See also step 1 for a response sample.
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.