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 includes a Sovos Canonical Invoice (SCI). To create the SBD, follow the detailed instructions in the SBDH, Sovos Document, and SCI pages.

Besides the SCI format the payload can be also of Serbian UBL 2.1 format.

SCI - Invoice

Use the following values in the SBDH for documents that use the SCI format:

Node	Required	Attributes	Value
StandardBusinessDocumentHeader.Sender.Identifier	Yes	Authority="RS"	Supplier's tax ID
StandardBusinessDocumentHeader.Receiver.Identifier	Yes	Authority="RS"
StandardBusinessDocumentHeader.DocumentIdentification.Standard	Yes		urn:oasis:names:specification:ubl:schema:xsd:Invoice-2
StandardBusinessDocumentHeader.DocumentIdentification.TypeVersion	Yes		2.1
StandardBusinessDocumentHeader.DocumentIdentification.Type	Yes		Invoice
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes		Child node Type: Country Child node Identifier: RS
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes		Child node Type: ProcessType Child node Identifier: Outbound
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes		Child node Type: CompanyCode Child node Identifier: Supplier's tax ID
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes		Child node Type: SenderDocumentId Child node Identifier: A unique document ID. We recommend the ERP document ID.
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes		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. If SenderSystemId is not configured on the client side, it'll use the default value of "DefaultSystemERP". For more information, see this topic.
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes		Child node Type: Mapping.OutputSchema Child node Identifier: UBLInvoice
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes		Child node Type: Mapping.TransformDocument Child node Identifier: SCI-TO-LEGAL_INVOICE
StandardBusinessDocumentHeader.BusinessScope.Scope.BusinessService.BusinessServiceName	Yes		Default
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes		Child node Type: BusinessCategory Child node Identifier: "B2B" or "B2G"
SovosDocument.SovosCanonicalInvoice.Invoice	Yes		SCI
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes		Child node Type: Version Child node Identifier: 1.0

Local format - invoice

Alternatively, the supplier can use the local format (XML) instead of SCI. Use the following values in the SBDH for documents that use the local format:

Node	Required	Value
StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes)	Yes	Child node Type: Mapping.TransformDocument Child node Identifier: LEGAL-TO-SCI_INVOICE
SovosDocument.SovosLegalDocument.Base64Document	Yes	A local format document encoded in Base64

Note:

The Local Format (XML) document must be Base64-encoded before it can be added as part of the SBD.

</sbd:StandardBusinessDocumentHeader>
<svs:SovosDocument>
	<svs:SovosLegalDocument>
		<enc:Base64Document>
			<enc:EmbeddedDocument id="1" filename="invoice.xml" mimeCode="application/xml">PD94bWwgdmVyc...FRdHVyYT4NCg==<enc:EmbeddedDocument>
		</enc:Base64Document>
	</svs:SovosLegalDocument>
</svs:SovosDocument>
</sbd:StandardBusinessDocument>

Note:

Include all the required nodes as specified in the SBDH schema. If the information cannot be provided, and the respective required node has not been mentioned on the current page, for example the receiver.identifier, you can leave the node empty but you must still include it in the SBDH.

SBD Sample

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

<?xml version="1.0" encoding="UTF-8"?>
<StandardBusinessDocument xmlns="http://www.unece.org/cefact/namespaces/StandardBusinessDocumentHeader" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ad="http://www.sovos.com/namespaces/additionalData" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:n0="urn:oasis:names:specification:ubl:schema:xsd:CommonSignatureComponents-2" xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" xmlns:cct="urn:un:unece:uncefact:data:specification:CoreComponentTypeSchemaModule:2" xmlns:crn="urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2" xmlns:dbn="urn:oasis:names:specification:ubl:schema:xsd:DebitNote-2" xmlns:enc="http://www.sovos.com/namespaces/base64Document" xmlns:ext="urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2" xmlns:inv="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2" xmlns:leg="http://www.sovos.com/namespaces/sovosExtensions/LegalExtension" xmlns:qdt="urn:oasis:names:specification:ubl:schema:xsd:QualifiedDataTypes-2" xmlns:sac="urn:oasis:names:specification:ubl:schema:xsd:SignatureAggregateComponents-2" xmlns:sbc="urn:oasis:names:specification:ubl:schema:xsd:SignatureBasicComponents-2" xmlns:sbd="http://www.unece.org/cefact/namespaces/StandardBusinessDocumentHeader" xmlns:sci="http://www.sovos.com/namespaces/sovosCanonicalInvoice" xmlns:sov="http://www.sovos.com/namespaces/sovosExtensions" xmlns:svs="http://www.sovos.com/namespaces/sovosDocument" xmlns:udt="urn:oasis:names:specification:ubl:schema:xsd:UnqualifiedDataTypes-2" xmlns:xades="http://uri.etsi.org/01903/v1.3.2#" xsi:schemaLocation="http://www.unece.org/cefact/namespaces/StandardBusinessDocumentHeader">
<sbd:StandardBusinessDocumentHeader>
<sbd:HeaderVersion>1.0</sbd:HeaderVersion>
<sbd:Sender>
<sbd:Identifier Authority="RS">SUPPLIER_TAX_ID</sbd:Identifier>
<sbd:ContactInformation>
<sbd:Contact/>
<sbd:EmailAddress/>
<sbd:FaxNumber/>
<sbd:TelephoneNumber/>
<sbd:ContactTypeIdentifier/>
</sbd:ContactInformation>
</sbd:Sender>
<sbd:Receiver>
<sbd:Identifier Authority="RS">BUYER_TAX_ID</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:Invoice-2</sbd:Standard>
<sbd:TypeVersion>2.1</sbd:TypeVersion>
<sbd:InstanceIdentifier/>
<sbd:Type>Invoice</sbd:Type>
<sbd:MultipleType>false</sbd:MultipleType>
<sbd:CreationDateAndTime>2025-07-04T00:00:00Z</sbd:CreationDateAndTime>
</sbd:DocumentIdentification>
<sbd:BusinessScope>
<sbd:Scope>
<sbd:Type>Country</sbd:Type>
<sbd:InstanceIdentifier/>
<sbd:Identifier>RS</sbd:Identifier>
</sbd:Scope>
<sbd:Scope>
<sbd:Type>Mapping.TransformDocument</sbd:Type>
<sbd:InstanceIdentifier/>
<sbd:Identifier>SCI-TO-LEGAL_INVOICE</sbd:Identifier>
</sbd:Scope>
<sbd:Scope>
<sbd:Type>Mapping.OutputSchema</sbd:Type>
<sbd:InstanceIdentifier/>
<sbd:Identifier>UBLInvoice</sbd:Identifier>
</sbd:Scope>
<sbd:Scope>
<sbd:Type>CompanyCode</sbd:Type>
<sbd:InstanceIdentifier/>
<sbd:Identifier>SUPPLIER_TAX_ID</sbd:Identifier>
</sbd:Scope>
<sbd:Scope>
<sbd:Type>SenderDocumentId</sbd:Type>
<sbd:InstanceIdentifier/>
<sbd:Identifier>RS2025/7/00000007</sbd:Identifier>
</sbd:Scope>
<sbd:Scope>
<sbd:Type>SenderSystemId</sbd:Type>
<sbd:InstanceIdentifier/>
<sbd:Identifier>ERPSystem</sbd:Identifier>
</sbd:Scope>
<sbd:Scope>
<sbd:Type>ProcessType</sbd:Type>
<sbd:InstanceIdentifier/>
<sbd:Identifier>Outbound</sbd:Identifier>
</sbd:Scope>
<sbd:Scope>
<sbd:Type>BusinessProcess</sbd:Type>
<sbd:InstanceIdentifier/>
<sbd:BusinessService>
<sbd:BusinessServiceName>Default</sbd:BusinessServiceName>
</sbd:BusinessService>
</sbd:Scope>
<sbd:Scope>
<sbd:Type>BusinessCategory</sbd:Type>
<sbd:InstanceIdentifier/>
<sbd:Identifier>B2G</sbd:Identifier>
</sbd:Scope>
<sbd:Scope>
<sbd:Type>SubSchema</sbd:Type>
<sbd:InstanceIdentifier/>
<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>
<sci:SovosCanonicalInvoice>
<inv:Invoice>
				*UBL Elements*
</inv:Invoice>
</sci:SovosCanonicalInvoice>
</svs:SovosDocument>
</StandardBusinessDocument>

Step 2: Supplier sends the SBD to Sovos

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

The request must include the following request body parameters:

Request sample

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

Response sample

{
    "timestamp": 1605282724079,
    "status": 202,
    "success": true,
    "message": "Document Received",
    "data": {
        "documentId": "DOCUMENT-ID"
    }
}

Step 3: Sovos maps the SCI into XML

Upon receiving the SCI file, Sovos maps it into the required XML format.

Step 4: Sovos validates the XML

Sovos validates the schema based on the information provided by the Tax Authority. If the client's document has errors, Sovos detects them instead of waiting for the Tax Authority's response. This allows Sovos to return errors in a clear and concise manner, which is often not the case when they come from the Tax Authority.

Step 5: Sovos transmits the XML

Sovos transmits the document to the tax authority's e-Invoice system (SEF).

Step 6: SEF processes the XML and sends the response to Sovos

SEF validates the schema and verifies that business logic, taxpayer information and duplicates are checked. After performing its services, the SEF system sends a success or a rejection message to Sovos.

Step 7: Sovos generates the PDF

Sovos generates a PDF that contains the content of the invoice XML in a human-readable format.

Step 8: Distribution

Either Sovos or the taxpayer can communicate the invoice to the Counterparty.

Sovos shares the invoice with the Counterparty

For Sovos to be able to distribute the invoice to the Counterparty, the Taxpayer must have configured an email distribution channel. For more information contact Sovos Professional Services.

Once a distribution channel has been configured, the Taxpayer should no longer send the invoice to the Counterparty.

Taxpayer shares the invoice with their Counterparty

If a distribution channel has not been configured, the Taxpayer is responsible for distributing the invoice to the Counterparty.

When communicating the invoice, it's important to ensure the invoice's authenticity and integrity.

Step 9: Retrieve the Counterparty's response

The XML is made available for the Counterparty to retrieve, and potentially accept or reject within 20 days. To make sure the document is correctly categorized, the Scope BusinessCategory in the SBDH is required and should be set, by the client, to either B2B or B2G.

In a B2B flow, if the Counterparty does not respond within 20 days, the document will be deemed rejected (per law).

For B2G flows, when 20 days are due, the document is deemed authorized (also per law).

Taxpayer retrieves the application responses

Attachments configuration

There are three ways you can access your attachments:

• As binary data, so the file is embedded in the Base64-encoded application response.

• As open download links, in which the response contains a public URL to download the file.

• As secure download links, in which you need to use the Indirect Tax API's bearer token to download the attachment.

By default, Sovos configures your attachments as open download links to avoid potential size limitations when retrieving responses. To improve security, you should configure them as secure links. Then, make a GET call to the secure link returned by the Indirect Tax API, and include the API token. Sample request:

curl --location 'https://einvoicing-api.sovos.com/download/api/v1/download/JqYyqliXiJFKhXshnBQZfW3qpfwATVGE5Q73T41JUynNLJD8zHy5VH__9qzL9No-Kia9olSw3_lNX3KmaA9Je89Xx--vk5pQjyKx0iT_4CwPSABD0Yg7uxXZ8SNiliEhFY-4TOX7m1TV5FwwfqntehbGaiGMI2JVYu18VBDiC_0/plain%27 \
--header 'Authorization: Bearer TOKEN'Y

As a response to the initial sending of the document, the client receives a JSON response message with an HTTP status code of 202 (asynchronous transaction). This means that the supplier must retrieve the application responses that become available during the transaction, which provide status information and also contain the signed XML encoded in Base64.

There are two ways you can retrieve application responses (notifications):

Fetch everything in one single response (notification)

This means, when polling for responses, Sovos will only return one final notification with SCICloudStatusCode 209 that contains all the relevant attachments/data. Detailed description follows.

Fetch multiple responses (notifications) containing different information

In this case, when polling for responses, Sovos will return multiple notifications with different SCICloudStatusCode values containing different attachments/data until the final one (with status 209) is returned. Detailed description follows.

Single response

To complete a transaction, the supplier retrieves only one notification, the complete workflow one, with SCICloudStatusCode of 209 and all the necessary attachments/data. Afterwards, the notification needs to be parsed for SCIResponseCode value. Possible values for SCIResponseCode:

• "AP", meaning the document's compliance status has been accepted with all the necessary attachments/data present.

• "RE", meaning the document's compliance status has been rejected, and more parsing is needed:

  • if SCIGovtStatusCode is present, the error can be found by reading StatusReason

  • if SCIInternalValidationCode is present, the error can be found by reading StatusReason

Note:

Receiving a notification containing SCICloudStatusCode with a value in the 5xx range, still remains an option as it indicates a server error. In this case, the workflow would not be considered complete since it would not return a notification with SCICloudStatusCode of 209.

SCICloudStatusCode	SCIResponseCode	Sample
209	AP UBLExtensions in the ApplicationResponse will contain: salesInvoiceId - SEF ID for the current invoice. uniqueId - unique UUID generated by SEF. invoiceId - an echo of the invoice ID that is sent in the document.	Workflow successfully completed
209	RE	Workflow successfully completed

Multiple response

To complete a transaction, the supplier must retrieve the application responses until the transaction has finished. If the supplier has subscribed to multiple notifications, the transaction can generate different application responses, as shown in the table below. The transaction finishes when a notification containing SCICloudStatusCode with value of 209 has been received.

Note:

Receiving a notification containing SCICloudStatusCode with a value in the 5xx range, still remains an option as it indicates a server error. In this case the workflow would not complete in a sense that it will not return a notification with SCICloudStatusCode of 209.

SCICloudStatusCode	SCIResponseCode	Sample
100	IP	Document received successfully
101	IP	Document mapped successfully
200	Initially "IP" is sent and when the workflow finishes (after 72h) "AP" is sent. UBLExtensions in the ApplicationResponse will contain: salesInvoiceId - SEF ID for the current invoice. uniqueId - unique UUID generated by SEF. invoiceId - an echo of the invoice ID that is sent in the document.	Authorized by the Tax Authority
203	AP	Document accepted or acknowledged by the counterparty
207	AP	PDF created successfully
209	AP	Workflow successfully completed
400	RE	Rejected by the Tax Authority or the counterparty - automatically terminated
401	RE	Document error
405	AP	Document rejected by the counterparty

The taxpayer can use the following Indirect Tax API endpoints to retrieve application responses:

• GET /notifications/RS

• GET /documents/RS/{documentId}/notifications

GET /notifications/RS

The supplier can send a GET request to the /notifications/RS endpoint to retrieve application responses that match the set search criteria. This endpoint allows setting the following query parameters:

Name	Type	Required	Default	Description
taxId	string	No		Include only notifications related to the specified taxId. This value is related to the CompanyCode set in the SBDH. Note: If a request does not include this parameter, it will return all the notifications related to the country and the sourceSystemId parameter.
page	integer	No	1	To specify the page to be returned, use a value between 1 and 10.
perPage	integer	No	10	To specify the number of results for the returned page, use a value between 1 and 100. Important: If the attachment file is configured to return the binary content instead of a link, use only values between 1 and 10.
sourceSystemId	string	Yes		Include only notifications related to documents that originate from the given source system. This value is related to the SenderSystemId in the SBDH.
includeAckwnowledged	boolean	No	false	Use "true" to include previously acknowledged notifications, within 24 hours of their acknowledgment, in the result.
processType	string	No		Use "0" to only include notifications related to outbound documents.

Request Sample

curl --location --request GET 'https://api-test.sovos.com/v1/notifications/RS?page=1&perPage=2&includeAcknowledged=true&taxId={taxId}&sourceSystemId={sourceSystemId}&processType=0' \\
--header 'Content-Type: application/json' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--header 'Authorization: Bearer TOKEN'

Response Sample

{
    "timestamp": 1633685509314,
    "status": 200,
    "success": true,
    "message": "Notifications Listed",
    "data": {
        "pageState": {
            "page": 1,
            "perPage": 50,
            "totalEntries": 1
        },
        "notifications": [
            {
                "createdDate": 1633681296,
                "metadata": {
                    "productId": "rs_UBLInvoice__1.0",
                    "documentId": "DOCUMENT-ID",
                    "erpDocumentId": "321412",
                    "erpSystemId": "UAT101",
                    "processType": "0",
                    "taxId": "YOUR-TAXID",
                    "sciCloudStatusCode": "200",
                    "sciResponseCode": "AP",
                    "sciStatusAction": "NOA",
                    "sciGovtStatusCode": "100"
                },
                "appPrefix": "DLT",
                "notificationId": "a8dc1aa2-fbe6-45ce-9e4c-97a3d5fdb91c",
                "content": "PEF...NlPg=="
            }
        ]
    }
}

GET /documents/RS/{documentId}/notifications

The supplier can send a GET request to the /documents/RS/{documentId}/notifications endpoint to retrieve application responses related to a single document.

To make this request, use the following path parameter:

Name	Type	Required	Description
documentId	string	Yes	The document ID returned in step 2

Request sample

curl --location --request GET 'https://api-test.sovos.com/v1/documents/RS/{documentId}/notifications?' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE'

Response sample

{
    "timestamp": 1633685509314,
    "status": 200,
    "success": true,
    "message": "Notifications Listed",
    "data": {
        "pageState": {
            "page": 1,
            "perPage": 50,
            "totalEntries": 1
        },
        "notifications": [
            {
                "createdDate": 1633681296,
                "metadata": {
                    "productId": "rs_UBLInvoice__1.0",
                    "documentId": "DOCUMENT-ID",
                    "erpDocumentId": "321412",
                    "erpSystemId": "UAT101",
                    "processType": "0",
                    "taxId": "YOUR-TAXID",
                    "sciCloudStatusCode": "200",
                    "sciResponseCode": "AP",
                    "sciStatusAction": "NOA",
                    "sciGovtStatusCode": "100"
                },
                "appPrefix": "DLT",
                "notificationId": "a8dc1aa2-fbe6-45ce-9e4c-97a3d5fdb91c",
                "content": "PEF...NlPg=="
            }
        ]
    }
}

Step 10: Supplier marks the application responses as acknowledged

The supplier must process the retrieved application responses and mark them as acknowledged. This can be done by sending a PUT request to the /notifications/RS endpoint.

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

Request sample

curl --location --request PUT 'https://api-test.sovos.com/v1/notifications/RS' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--data-raw '[
    {
        "status": "read",
        "notificationId": "51341d39-fd3e-4dcf-aea3-a73d73e0de76"
    }
]'

Response sample

{
    "timestamp": 1601673284,
    "status": 200,
    "success": true,
    "message": "Notifications acknowledged successfully."
}

Archiving

Archiving can be done as a bundle, for example as part of the Clearance flow, and is recommended for suppliers integrating with the Sovos solution for Serbia for the first time. It can also be done separately, through an explicit API call, which uses another archive. For more information on standalone archiving, see the e-Archiving documentation page.

Bundled e-invoice archiving on the new platform is optional. Existing customers can choose to use their current solution and include e-Archiving.

Step 1: Supplier sends a POST Request to Sovos

The supplier sends a POST request to the /documents/RS/action endpoint. To make this request, use the following request body parameters:

Request sample

curl --location 'https://api-test.sovos.com/v1/documents/RS/action' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--data '{
    "actionCode": "document.cancellation",
    "documents": [
      {
        "metadata": {
            "reason": "Wrong total submitted"
        },
        "documentId": "DOCUMENT-ID"
      }
    ]
  }'

Response sample

{
    "status": 202,
    "message": "Accepted",
    "success": true,
    "timestamp": 1708018192828,
    "data": [
        {
            "status": 202,
            "documentId": "DOCUMENT-ID"
        }
    ]
}

Step 2: Sovos transmits the request to SEF

Sovos finds the corresponding document in the system and transmits the cancellation request to SEF.

Step 3: SEF processes the request

SEF validates the request and verifies business logic before returning a success or error message.

Step 4: SEF returns the response

SEF returns the success message, or the error message if the cancellation could not be performed.

Step 5: Taxpayer retrieves the application responses

Attachments configuration

There are three ways you can access your attachments:

• As binary data, so the file is embedded in the Base64-encoded application response.

• As open download links, in which the response contains a public URL to download the file.

• As secure download links, in which you need to use the Indirect Tax API's bearer token to download the attachment.

By default, Sovos configures your attachments as open download links to avoid potential size limitations when retrieving responses. To improve security, you should configure them as secure links. Then, make a GET call to the secure link returned by the Indirect Tax API, and include the API token. Sample request:

curl --location 'https://einvoicing-api.sovos.com/download/api/v1/download/JqYyqliXiJFKhXshnBQZfW3qpfwATVGE5Q73T41JUynNLJD8zHy5VH__9qzL9No-Kia9olSw3_lNX3KmaA9Je89Xx--vk5pQjyKx0iT_4CwPSABD0Yg7uxXZ8SNiliEhFY-4TOX7m1TV5FwwfqntehbGaiGMI2JVYu18VBDiC_0/plain%27 \
--header 'Authorization: Bearer TOKEN'Y

As a response to the initial sending of the document, the client receives a JSON response message with an HTTP status code of 202 (asynchronous transaction). This means that the supplier must retrieve the application responses that become available during the transaction, which provide status information.

You have the option to retrieve application responses (notifications) in one of two ways:

Fetch everything in one single response (notification)

This means, when polling for responses, Sovoswill only return one final notification with SCICloudStatusCode 209 that contains all the relevant attachments/data. Detailed description follows.

Fetch multiple responses (notifications) containing different information

In this case, when polling for responses, Sovoswill return multiple notifications with different SCICloudStatusCode values containing different attachments/data until the final one (with status 209) is returned. Detailed description follows.

Single response

To complete a transaction, the buyer retrieves only one notification, the complete workflow one, with SCICloudStatusCode of 209 and all the necessary attachments/data. Afterwards, the notification needs to be parsed for SCIResponseCode value. Possible values for SCIResponseCode:

• "AP", meaning the document's compliance status has been accepted with all the necessary attachments/data present.

• "RE", meaning the document's compliance status has been rejected, and more parsing is needed:

  • if SCIGovtStatusCode is present, the error can be found by reading StatusReason

  • if SCIInternalValidationCode is present, the error can be found by reading StatusReason

Note:

Receiving a notification containing SCICloudStatusCode with a value in the 5xx range, still remains an option as it indicates a server error. In this case, the workflow would not be considered complete since it would not return a notification with SCICloudStatusCode of 209.

SCICloudStatusCode	SCIResponseCode	Sample
209	AP	Workflow successfully completed
209	RE	Workflow succesfully completed

Multiple responses

To complete a transaction, the buyer retrieves only one notification, the complete workflow one, with SCICloudStatusCode of 209 and all the necessary attachments/data. Afterwards, the notification needs to be parsed for SCIResponseCode value. Possible values for SCIResponseCode:

• "AP", meaning the document's compliance status has been accepted with all the necessary attachments/data present.

• "RE", meaning the document's compliance status has been rejected, and more parsing is needed:

  • if SCIGovtStatusCode is present, the error can be found by reading StatusReason

  • if SCIInternalValidationCode is present, the error can be found by reading StatusReason

Note:

Receiving a notification containing SCICloudStatusCode with a value in the 5xx range, still remains an option as it indicates a server error. In this case the workflow would not be considered complete since it would not return a notification with SCICloudStatusCode of 209.

SCICloudStatusCode	SCIResponseCode	Sample
101	IP	Document mapped successfully
201	AP	Canceled
209	AP	Workflow successfully completed

The buyer can use the following Indirect Tax API endpoints to retrieve application responses:

• GET /notifications/RS

• GET /documents/RS/{documentId}/notifications

GET /notifications/RS

The buyer can send a GET request to the /notifications/RS endpoint to retrieve application responses that match the set search criteria. This endpoint allows setting the following query parameters:

Name	Type	Required	Default	Description
taxId	string	No		Include only notifications related to the specified tax ID. This value is related to the CompanyCode in the SBDH. Note: If a request does not include this parameter, it will return all the notifications related to the country and the sourceSystemId parameter.
page	integer	No	1	To specify the page to be returned, use a value between 1 and 10.
perPage	integer	No	10	To specify the number of results for the returned page, use a value between 1 and 100. Important: If the attachment file is configured to return the binary content instead of a link, use only values between 1 and 10.
sourceSystemId	string	Yes		Include only notifications related to documents that originate from the given source system. This value is related to the SenderSystemId in the SBDH.
includeAcknowledged	boolean	No	false	Use "true" to include previously acknowledged notifications in the result.
processType	string	No		Use "0" to only include notifications related to outbound documents.

Request sample

curl --location --request GET 'https://api-test.sovos.com/v1/notifications/RS?page=1&perPage=2&includeAcknowledged=true&taxId={taxId}&sourceSystemId={sourceSystemId}&processType=0' \
--header 'Content-Type: application/json' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--header 'Authorization: Bearer TOKEN' \

Response sample

"status": 200,
"message": "Notifications Listed",
"success": true,
"timestamp": 1708533734893,
"data": {
    "pageState": {
        "page": 1,
        "perPage": 20,
        "totalEntries": 52,
        "totalPages": 3
    },
    "notifications": [
        {
            "notificationId": "40e2ef57-...-8e1c9e8de016",
            "correlationId": "SET-TO-UNIQUE-VALUE",
            "appPrefix": "DLT",
            "metadata": {
                "productId": "rs_UBLInvoice__1.0",
                "transactionId": "78...5f0",
                "documentId": "DOCUMENT-ID",
                "erpDocumentId": "172012265",
                "erpSystemId": "ERPSystem",
                "processType": "0",
                "taxId": SUPPLIER_TAX_ID,
                "sciCloudStatusCode": "209",
                "sciResponseCode": "AP",
                "sciStatusAction": "NOA",
                "sciGovtStatusCode": "Success"
            },
            "content": "PD...2U+",
            "createdDate": 1708533707255

GET /documents/RS/{documentId}/notifications

The buyer can send a GET request to the /documents/RS/{documentId}/notifications endpoint to retrieve application responses related to a single document.

To make this request, set the following parameters:

Name	Type	Required	Parameter type	Default	Description
documentId	string	Yes	Path		The document ID returned in step 1
includeAcknowledged	boolean	No	Query	false	Use "true" to include previously acknowledged notifications in the result

Request sample

curl --location --request GET 'https://api-test.sovos.com/v1/documents/RS/DOCUMENT-ID/notifications?includeAcknowledged=false' \
--header 'Content-Type: application/json' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--header 'Authorization: Bearer TOKEN'

Response sample

"status": 200,
"message": "Notifications Listed",
"success": true,
"timestamp": 1708533734893,
"data": {
    "pageState": {
        "page": 1,
        "perPage": 20,
        "totalEntries": 52,
        "totalPages": 3
    },
    "notifications": [
        {
            "notificationId": "40e2ef57-...-8e1c9e8de016",
            "correlationId": "SET-TO-UNIQUE-VALUE",
            "appPrefix": "DLT",
            "metadata": {
                "productId": "rs_UBLInvoice__1.0",
                "transactionId": "78...5f0",
                "documentId": "DOCUMENT-ID",
                "erpDocumentId": "172012265",
                "erpSystemId": "ERPSystem",
                "processType": "0",
                "taxId": SUPPLIER_TAX_ID,
                "sciCloudStatusCode": "209",
                "sciResponseCode": "AP",
                "sciStatusAction": "NOA",
                "sciGovtStatusCode": "Success"
            },
            "content": "PD...2U+",
            "createdDate": 1708533707255

Step 6: Taxpayer marks the application responses as acknowledged

After retrieving application responses, the supplier must process them and mark them as acknowledged. This can be done by sending a PUT request to the /notifications/RS endpoint.

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

Request sample

curl --location --request PUT 'https://api-test.sovos.com/v1/notifications/RS' \
--header 'Content-Type: application/json' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--header 'Authorization: Bearer TOKEN' \
--data '[
    {
        "status": "read",
        "notificationId": "e7b32eda-cb67-43b9-91de-f6d9c90f60d9"
    }
]'

Response sample

{
    "status": 200,
    "message": "OK",
    "success": true,
    "timestamp": 1708509282198,
    "data": {}
}

Step 1: Sovos Retrieves the documents from the SEF System

Sovos uses the buyer's credentials to authenticate with the SEF system to collect the documents that have been made available (either in JSON or XML formats).

Step 2: Sovos maps the retrieved documents into SCI and makes them available

Sovos stores the retrieved documents, maps them to SCI, and makes them available for buyers to get. The PDF version of the documents is also made available.

Step 3: Sovos generates the PDF

Sovos generates a PDF for this document.

Step 4: Sovos distributes the PDF

Sovos can distribute the PDF by email to a configurable email address.

Step 5: Buyer retrieves the application responses

Attachments configuration

There are three ways you can access your attachments:

• As binary data, so the file is embedded in the Base64-encoded application response.

• As open download links, in which the response contains a public URL to download the file.

• As secure download links, in which you need to use the Indirect Tax API's bearer token to download the attachment.

By default, Sovos configures your attachments as open download links to avoid potential size limitations when retrieving responses. To improve security, you should configure them as secure links. Then, make a GET call to the secure link returned by the Indirect Tax API, and include the API token. Sample request:

curl --location 'https://einvoicing-api.sovos.com/download/api/v1/download/JqYyqliXiJFKhXshnBQZfW3qpfwATVGE5Q73T41JUynNLJD8zHy5VH__9qzL9No-Kia9olSw3_lNX3KmaA9Je89Xx--vk5pQjyKx0iT_4CwPSABD0Yg7uxXZ8SNiliEhFY-4TOX7m1TV5FwwfqntehbGaiGMI2JVYu18VBDiC_0/plain%27 \
--header 'Authorization: Bearer TOKEN'Y

To complete a transaction, the buyer must retrieve the application responses until the transaction has finished using the /notifications/RS endpoint. If the buyer has subscribed to all notifications, the transaction can generate different application responses, as shown in the table below:

GET /notifications/RS

The buyer can send a GET request to the /notifications/RS endpoint to retrieve application responses that match the set search criteria. This endpoint allows setting the following query parameters:

Name	Type	Required	Default	Description
taxId	string	No		Include only notifications related to the specified taxId.
page	integer	No	1	To specify the page to be returned, use a value between 1 and 10.
perPage	integer	No	10	To specify the number of results for the returned page, use a value between 1 and 100. Important: If the attachment file is configured to return the binary content instead of a link, use only values between 1 and 10.
sourceSystemId	string	Yes		Include only notifications related to documents that originate from the given source system.
includeAckwnowledged	boolean	No	false	Use "true" to include previously acknowledged notifications in the result.
processType	string	No		Use "1" to only include notifications related to inbound documents.

Request Sample

curl --location --request GET 'https://api-test.sovos.com/v1/notifications/RS?page=1&perPage=2&taxId={taxId}&sourceSystemId={sourceSystemId}&processType=1' \
--header 'Content-Type: application/json' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--header 'Authorization: Bearer TOKEN'

Response Sample

{
    "timestamp": 1633685509314,
    "status": 200,
    "success": true,
    "message": "Notifications Listed",
    "data": {
        "pageState": {
            "page": 1,
            "perPage": 50,
            "totalEntries": 1
        },
        "notifications": [
            {
                "createdDate": 1633681296,
                "metadata": {
                    "productId": "rs_UBLInvoice_Polling_1.0",
                    "documentId": "DOCUMENT-ID",
                    "erpDocumentId": "321412",
                    "erpSystemId": "UAT101",
                    "processType": "0",
                    "taxId": "YOUR-TAXID",
                    "sciCloudStatusCode": "200",
                    "sciResponseCode": "AP",
                    "sciStatusAction": "NOA",
                    "sciGovtStatusCode": "100"
                },
                "appPrefix": "DLT",
                "notificationId": "a8dc1aa2-fbe6-45ce-9e4c-97a3d5fdb91c",
                "content": "PEF...NlPg=="
            }
        ]
    }
}

Step 6: Buyer acknowledges the retrieved documents

After retrieving the documents, the buyer must process them and mark them as acknowledged. This can be done by sending a PUT request to the /notifications/RS endpoint

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

Request Sample

curl --location --request PUT 'https://api-test.sovos.com/v1/notifications/RS' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--data-raw '[
    {
        "status": "read",
        "notificationId": "51341d39-fd3e-4dcf-aea3-a73d73e0de76"
    }
]'

Response Sample

{
    "timestamp": 1601673284,
    "status": 200,
    "success": true,
    "message": "Notifications acknowledged successfully."
}

Step 1: Buyer sends a POST request to Sovos

The buyer sends a POST request to the /documents/RS/action endpoint. To make this request, set the following request body parameters:

Request sample for acceptance

curl --location 'https://api-test.sovos.com/v1/documents/RS/action' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--data '{
    "actionCode": "document.accept",
    "documents": [
      {
        "documentId": "DOCUMENT_ID"
      }
    ]
  }'

Request sample for rejection

curl --location 'https://api-test.sovos.com/v1/documents/RS/action' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--data '{
  "actionCode": "document.reject",
  "documents": [
    {
      "metadata": {
        "reason": "reject action test"
      },
      "documentId": DOCUMENT_ID
    }
  ]
}

Response sample

{
	"status": 202,
	"message": "Accepted",
	"success": true,
	"timestamp": 1724404345626
	"data":[
		{
			"status": 202,
			"transactionId": TRANSACTION_ID,
			"documentId": DOCUMENT_ID
		}
	]
}

Step 2: Sovos transmits the request to SEF

Sovos finds the corresponding document in the system and transmits the acceptance or rejection request to SEF.

Step 3: SEF processes the request

SEF verifies that the 20 days window has not passed since the original document was issued, and that the document can be rejected/accepted successfully.

Step 4: SEF returns the response

SEF returns the success message, or the error message if the rejection or acceptance could not be performed.

Step 5: Buyer retrieves the application responses

Attachments configuration

There are three ways you can access your attachments:

• As binary data, so the file is embedded in the Base64-encoded application response.

• As open download links, in which the response contains a public URL to download the file.

• As secure download links, in which you need to use the Indirect Tax API's bearer token to download the attachment.

By default, Sovos configures your attachments as open download links to avoid potential size limitations when retrieving responses. To improve security, you should configure them as secure links. Then, make a GET call to the secure link returned by the Indirect Tax API, and include the API token. Sample request:

curl --location 'https://einvoicing-api.sovos.com/download/api/v1/download/JqYyqliXiJFKhXshnBQZfW3qpfwATVGE5Q73T41JUynNLJD8zHy5VH__9qzL9No-Kia9olSw3_lNX3KmaA9Je89Xx--vk5pQjyKx0iT_4CwPSABD0Yg7uxXZ8SNiliEhFY-4TOX7m1TV5FwwfqntehbGaiGMI2JVYu18VBDiC_0/plain%27 \
--header 'Authorization: Bearer TOKEN'Y

As a response to the initial sending of the document, the client receives a JSON response message with an HTTP status code of 202 (asynchronous transaction). This means that the supplier must retrieve the application responses that become available during the transaction, which provide status information.

To complete a transaction, the supplier must retrieve application responses until the SCIResponseCode in the response has the value of either "AP" or "RE", which indicates that the transaction is finished.

You have two options to retrieve application responses (notifications):

Fetch everything in one single response (notification)

This means, when polling for responses, Sovos will only return one final notification with SCICloudStatusCode 209 that contains all the relevant attachments/data. Detailed description follows.

Fetch multiple responses (notifications) containing different information

In this case, when polling for responses, Sovos will return multiple notifications with different SCICloudStatusCode values containing different attachments/data until the final one (with status 209) is returned. Detailed description follows.

Single response

To complete a transaction, the buyer retrieves only one notification, the complete workflow one, with SCICloudStatusCode of 209 and all the necessary attachments/data. Afterwards, the notification needs to be parsed for SCIResponseCode value. Possible values for SCIResponseCode:

• "AP", meaning the document's compliance status has been accepted with all the necessary attachments/data present.

• "RE", meaning the document's compliance status has been rejected, and more parsing is needed:

  • if SCIGovtStatusCode is present, the error can be found by reading StatusReason

  • if SCIInternalValidationCode is present, the error can be found by reading StatusReason

Note:

Receiving a notification containing SCICloudStatusCode with a value in the 5xx range, still remains an option as it indicates a server error. In this case, the workflow would not be considered complete since it would not return a notification with SCICloudStatusCode of 209.

SCICloudStatusCode	SCIResponseCode	Sample
209	AP	Workflow successfully completed
209	RE	Workflow succesfully completed

Multiple responses

To complete a transaction, the buyer retrieves only one notification, the complete workflow one, with SCICloudStatusCode of 209 and all the necessary attachments/data. Afterwards, the notification needs to be parsed for SCIResponseCode value. Possible values for SCIResponseCode:

• "AP", meaning the document's compliance status has been accepted with all the necessary attachments/data present.

• "RE", meaning the document's compliance status has been rejected, and more parsing is needed:

  • if SCIGovtStatusCode is present, the error can be found by reading StatusReason

  • if SCIInternalValidationCode is present, the error can be found by reading StatusReason

Note:

Receiving a notification containing SCICloudStatusCode with a value in the 5xx range, still remains an option as it indicates a server error. In this case the workflow would not be considered complete since it would not return a notification with SCICloudStatusCode of 209.

SCICloudStatusCode	SCIResponseCode	Sample
101	IP	Document mapped successfully
212	AP	Rejection Request Accepted
209	AP	Workflow successfully completed

The buyer can use the following Indirect Tax API endpoints to retrieve application responses:

• GET /notifications/RS

• GET /documents/RS/{documentId}/notifications

We'll discuss these endpoints in the following subsections.

GET /notifications/RS

The buyer can send a GET request to the /notifications/RS endpoint to retrieve application responses that match the set search criteria. This endpoint allows using the following query parameters:

Name	Type	Required	Default	Description
taxId	string	No		Include only notifications related to the specified taxId. This value is related to the CompanyCode in the SBDH. Note: If a request does not include this parameter, it will return all the notifications related to the country and the sourceSystemId parameter.
page	integer	No	1	To specify the page to be returned, use a value between 1 and 10.
perPage	integer	No	10	To specify the number of results for the returned page, set its value between 1 and 100. Important: If the attachment file is configured to return the binary content instead of a link, use only values between 1 and 10.
sourceSystemId	string	Yes		Include only notifications related to documents that originate from the given source system. This value is related to the SenderSystemId in the SBDH.
includeAcknowledged	boolean	No	false	Use "true" to include previously acknowledged notifications in the result.
processType	string	No		Use "0" to only include notifications related to outbound documents.

Request sample

curl --location --request GET 'https://api-test.sovos.com/v1/notifications/RS?page=1&perPage=2&taxId={taxId}&sourceSystemId={sourceSystemId}&processType=0' \
--header 'Content-Type: application/json' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--header 'Authorization: Bearer TOKEN' \

Response sample

"status": 200,
"message": "Notifications Listed",
"success": true,
"timestamp": 1708533734893,
"data": {
    "pageState": {
        "page": 1,
        "perPage": 20,
        "totalEntries": 52,
        "totalPages": 3
    },
    "notifications": [
        {
            "notificationId": "78bd5a18-...-73bfbdb3bf21",
            "correlationId": "SET-TO-UNIQUE-VALUE",
            "appPrefix": "DLT",
            "metadata": {
                "productId": "rs_UBLInvoice_Polling_1.0",
                "transactionId": "43...d94",
                "documentId": "DOCUMENT-ID",
                "erpDocumentId": "192714478",
                "erpSystemId": "ERPSystem",
                "processType": "1",
                "taxId": "C873686030",
                "sciCloudStatusCode": "209",
                "sciResponseCode": "AP",
                "sciStatusAction": "NOA",
                "sciGovtStatusCode": "Success"
            },
            "content": "PD...2U+",
            "createdDate": 1708533707255

GET /documents/RS/{documentId}/notifications

The buyer can send a GET request to the /documents/RS/{documentId}/notifications endpoint to retrieve application responses related to a single document.

To make this request, set the following parameters:

Name	Type	Required	Parameter type	Default	Description
documentId	string	Yes	Path		The document ID returned in step 1
includeAcknowledged	boolean	No	Query	false	Use "true" to include previously acknowledged notifications in the result

Request sample

curl --location  --request GET 'https://api-test.sovos.com/v1/documents/RS/DOCUMENT-ID/notifications?includeAcknowledged=false' \
--header 'Content-Type: application/json' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--header 'Authorization: Bearer TOKEN'

Response sample

"status": 200,
"message": "Notifications Listed",
"success": true,
"timestamp": 1708533734893,
"data": {
    "pageState": {
        "page": 1,
        "perPage": 20,
        "totalEntries": 52,
        "totalPages": 3
    },
    "notifications": [
        {
            "notificationId": "78bd5a18-...-73bfbdb3bf21",
            "correlationId": "SET-TO-UNIQUE-VALUE",
            "appPrefix": "DLT",
            "metadata": {
                "productId": "rs_UBLInvoice_Polling_1.0",
                "transactionId": "43...d94",
                "documentId": "DOCUMENT-ID",
                "erpDocumentId": "192714478",
                "erpSystemId": "ERPSystem",
                "processType": "1",
                "taxId": "C873686030",
                "sciCloudStatusCode": "209",
                "sciResponseCode": "AP",
                "sciStatusAction": "NOA",
                "sciGovtStatusCode": "Success"
            },
            "content": "PD...2U+",
            "createdDate": 1708533707255

Step 6: Buyer marks the application responses as acknowledged

The buyer must process the retrieved application responses and mark them as acknowledged. This can be done by sending a PUT request to the /notifications/RS endpoint.

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

Request sample

curl --location --request PUT 'https://api-test.sovos.com/v1/notifications/RS' \
--header 'Content-Type: application/json' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--header 'Authorization: Bearer TOKEN' \
--data '[
    {
        "status": "read",
        "notificationId": "e7b32eda-cb67-43b9-91de-f6d9c90f60d9"
    }
]'

Response sample

{
    "status": 200,
    "message": "OK",
    "success": true,
    "timestamp": 1708509282198,
    "data": {}
}