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 also be of Croatian 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="HR"	Supplier's tax ID
StandardBusinessDocumentHeader.Receiver.Identifier	Yes	Authority="HR"
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: HR
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 assume 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 - for Invoice submissions SCI-TO-LEGAL_CREDIT_NOTE - for Credit Note (CN) submissions
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">
				PD94bWwgdmVyc2lvbj...NlPg==
				</enc:EmbeddedDocument>
			</enc:Base64Document>
		</svs:SovosLegalDocument>
	</svs:SovosDocument>
</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, the node can be left empty but must still be included in the SBDH.

SBD Sample

Below is a sample of the SBD:

<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="HR">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="HR">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-10-15T21:06:48.277Z</sbd:CreationDateAndTime>
		</sbd:DocumentIdentification>
		<sbd:BusinessScope>
			<sbd:Scope>
				<sbd:Type>Country</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>HR</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>Mapping.TransformDocument</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>LEGAL-TO-SCI_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>test-legal-inbound</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>SenderSystemId</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>ERPSystemRita</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>B2B</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>

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",
 		"transactionId": "TRANSACTION-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 schema 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 Unimaze, which handles both the e-invoicing process (sending the document to the Buyer AP) and the fiscalization process (submitting the document to the tax authority) according to requirements.

Step 6: Unimaze processes the XML and sends the response 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.

Step 9: 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 Croatia 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.

When bundled archiving is set, the XML document is archived for seven years.

Step 10: 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

The ERP system configuration is available through our Professional Services team.

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.

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

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

• GET /notifications/HR

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

We'll discuss these endpoints in the following subsections.

GET /notifications/HR

The supplier can send a GET request to the /notifications/HR 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 in the SBDH. Note: If a request doesn't 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, it's recommended to use 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/HR?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": "hr_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/HR/{documentId}/notifications

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

To make this request, set the following parameter:

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

Request sample

curl --location --request GET 'https://api-test.sovos.com/v1/documents/HR/{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": "hr_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 11: 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/HR endpoint.

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

Classification codes

You need to map your internal product and service codes to Croatia's KPD classification codes before submitting invoices. Use this guide to implement the mapping between your internal codes and the required KPD product codes.

The KPD classification system is available through the KLASUS website. You can download the complete code list in either TXT or XLS format directly from the KLASUS website.

Map your products and services to the appropriate KPD codes within your ERP system. This mapping makes sure your invoices have the correct classification codes required by the Croatian Tax Administration.

Step 1: Sovos Retrieves the documents from the Unimaze system

Sovos uses the buyer's credentials to authenticate with the Unimaze 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. Sovos also provides the PDF version of the documents.

Similar to the outbound process, Unimaze returns two different messages, one for each requirement. Sovos also returns two notifications for each process.

E-invoicing process

SCICloudStatusCode:

• Success: 216 (document.acknowledgeByRecipient)

  • SCIGovtStatusCode: eInvoicing

    • Reason: <Description from Unimaze>

Fiscalization process

• Received: 100 (document.received)

  • SCICloudStatusCode: Fiscalization

    • Reason:

      Fiscalized

      The document was sent to the tax authority with the possible e-invoicing process.

      TaxableDelivery

      The document was sent to the tax authority but the e-invoicing process was not possible.

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, if applicable.

Step 5: Archiving

Archiving can be done as a bundle (for example, within the Clearance flow), which is recommended for suppliers integrating with the Sovos solution for Croatia for the first time. It can be done separately through an explicit API call. For 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.

When bundled archiving is set, the XML document is archived for seven years.

Step 6: 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

The buyer can use the GET /notifications/HR endpoint to retrieve application responses.

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

GET /notifications/HR

The buyer can send a GET request to the /notifications/HR endpoint to retrieve application responses that match the set search criteria. You can set 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.
includeAcknowledged	boolean	No	false	Use "true" to include previously acknowledged notifications in the result.
processType	string	No		Use "1" to include only notifications related to inbound documents.

Request Sample

curl --location --request GET 'https://api-test.sovos.com/v1/notifications/HR?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": "hr_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 7: Buyer acknowledges the retrieved documents

After retrieving the documents, the buyer must process them and mark them as acknowledged. To do this, send a PUT request to the /notifications/HR endpoint.

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

Request Sample

curl --location --request PUT 'https://api-test.sovos.com/v1/notifications/HR' \
--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/HR/action endpoint. Set the following request body parameters:

Request sample for rejection

curl --location 'https://api-test.sovos.com/v1/documents/HR/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"
		"rejectionType": "MismatchNotAffectingTax"
      },
      "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 Unimaze

Sovos finds the corresponding document in the system and transmits the rejection request to Unimaze .

Step 3: Unimaze processes the request

Unimaze sends the rejection to the tax authority, which validates that the rejection report is within the timeframe (up until the 20th of the next month).

Step 4: Unimaze returns the response

Unimaze returns either a success message or an error message if the rejection fails.

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 taxpayer must retrieve the application responses that become available during the transaction, which provide status information.

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

Fetch everything in one single response (notification)

When polling for responses, Sovos returns one final notification with SCICloudStatusCode 209 that contains all the relevant attachments and data. Detailed description follows.

Fetch multiple responses (notifications) containing different information

When polling for responses, Sovos returns multiple notifications with different SCICloudStatusCode values that contain different attachments and 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 and 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:

If there is a server error, you review a notification that contains an SCICloudStatusCode with a value in the 5xx range. In this case, the workflow would not be considered complete because it would not return a notification with SCICloudStatusCode of 209.

SCICloudStatusCode	SCIResponseCode	Sample
209	AP	Workflow successfully completed
209	RE	Workflow successfully 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:

If you receive a notification that contains SCICloudStatusCode with a value in the 5xx range, there is a server error. This means that the workflow has not completed, and you must retry the transaction.

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

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

We'll discuss these endpoints in the following subsections.

GET /notifications/HR

The buyer can send a GET request to the /notifications/HR 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 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&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": "hr_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/HR/{documentId}/notifications

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

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": "hr_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. To do this, send a PUT request to the /notifications/HR endpoint.

Set the following request body parameters:

Request sample

curl --location --request PUT 'https://api-test.sovos.com/v1/notifications/HR' \
--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": {}
}