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 in turn includes a Sovos Canonical Invoice (SCI). To create the SBD, follow the detailed instructions in the SBDH, Sovos Document, and SCI pages. Here are some key elements that should be included in the SBD:

SBD sample

Below is a sample of the SBD, which shows only the part of the application response that includes the response of the IRP. In addition, there's a full sample of the SBD on the Postman Samples page.

<?xml version="1.0" encoding="UTF-8"?>
<sbd:StandardBusinessDocument xmlns:sbd="http://www.unece.org/cefact/namespaces/StandardBusinessDocumentHeader" xmlns:col="ColombiaExtension.xsd" xmlns:dom="DominicanRepublicExtension.xsd" xmlns:spa="SpainExtension.xsd" xmlns:xades="http://uri.etsi.org/01903/v1.3.2#" xmlns:ad="http://www.sovos.com/namespaces/additionalData" xmlns:sci="http://www.sovos.com/namespaces/sovosCanonicalInvoice" xmlns:svs="http://www.sovos.com/namespaces/sovosDocument" xmlns:sov="http://www.sovos.com/namespaces/sovosExtensions" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" xmlns:ext="urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2" xmlns:n1="urn:oasis:names:specification:ubl:schema:xsd:CommonSignatureComponents-2" xmlns:crn="urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2" xmlns:dbn="urn:oasis:names:specification:ubl:schema:xsd:DebitNote-2" xmlns:fin="urn:oasis:names:specification:ubl:schema:xsd:FreightInvoice-2" xmlns:inv="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2" 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:udt="urn:oasis:names:specification:ubl:schema:xsd:UnqualifiedDataTypes-2" xmlns:ccts-cct="urn:un:unece:uncefact:data:specification:CoreComponentTypeSchemaModule:2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<sbd:StandardBusinessDocumentHeader>
		<sbd:HeaderVersion>1.0</sbd:HeaderVersion>
		<sbd:Sender>
			<sbd:Identifier Authority="BR">11111111111111</sbd:Identifier>
			<sbd:ContactInformation>
<sbd:Identifier Authority="BR">22222222222</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>2020-01-01T12:00:00Z</sbd:CreationDateAndTime>
		</sbd:DocumentIdentification>
		<sbd:BusinessScope>
		    <sbd:Scope>
				<sbd:Type>Version</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>4.0</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>Country</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>BR</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>SenderSystemId</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>ABC200</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>
				<InstanceIdentifier/>
				<sbd:Identifier>NFe</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>CompanyCode</sbd:Type>
<sbd:InstanceIdentifier/>
				<sbd:Identifier>ABC134</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>SenderDocumentId</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>XYZ1234</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>ProcessType</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>Outbound</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>BusinessCategory</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>BusinessToBusiness</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:BusinessScope>
	</sbd:StandardBusinessDocumentHeader>
	<svs:SovosDocument>
		<sci:SovosCanonicalInvoice>
			<inv:Invoice>
				*UBL Nodes*
			</inv:Invoice>
		</sci:SovosCanonicalInvoice>
	</svs:SovosDocument>
</sbd: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:

Step 3: Sovos maps the SCI into the NF-e

Upon receiving the SCI, Sovos maps the file into the required NF-e format.

Step 4: Sovos performs the schema validation

Sovos performs a schema validation to determine whether the NF-e XML file conforms to the expected structure by validating the file against the official schema.

Step 5: Sovos signs the NF-e

Step 6: Sovos transmits the NF-e

Sovos transmits the signed NF-e file to the SEFAZ of the respective state.

Step 7: SEFAZ processes the NF-e

SEFAZ performs the clearance process, which involves schema validation and several content validations, including the supplier's signature. Once finished, SEFAZ returns the cleared NF-e to Sovos. In addition, SEFAZ generates a PDF and sends it to the buyer.

Step 8: Sovos generates the PDF (Danfe)

Sovos generates a PDF with the content of the NF-e based on the configured PDF template.

Step 9: Supplier retrieves the application responses

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

• GET /notifications/BR

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

GET /notifications/BR

The supplier can send a GET request to the /notifications/BR endpoint to retrieve application responses that match the configured search criteria. To make this request, set the following query parameters:

Name	Type	Required	Default	Description
taxId	string	No		Include only notifications related to the specified taxId. This value relates to the CompanyCode set in the SBDH.
page	integer	No	1	To specify the page to be returned, enter a value between 1 and 10.
perPage	integer	No	10	To specify the number of results for the returned page, enter a value between 1 and 100. Note: 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	Enter "true" to specify whether previously acknowledged notifications must be included in the result.

Request sample

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

Response sample

{
    "timestamp": 1639056915485,
    "status": 200,
    "success": true,
    "message": "Notifications Listed",
    "data": {
        "pageState": {
            "page": 1,
            "perPage": 100,
            "totalPages": 1,
            "totalEntries": 2
        },
        "notifications": [
            {
                "createdDate": "1638473970231",
                "metadata": {
                    "productId": "NFe",
                    "documentId": "LXNvdm9zfDk5OTl8NTV8MTMxNXwxMTQ0MDM0MQ==",
                    "erpDocumentId": "11111",
                    "erpSystemId": "UAT800",
                    "processType": "0",
                    "taxId": "06158643000144",
                    "sciCloudStatusCode": "200",
                    "sciResponseCode": "AP",
                    "sciStatusAction": "NOA"
                },
                "appPrefix": "Smart DF-e",
                "notificationId": 13248873,
                "content": "PEF...c2U+"
            },
            {
                "createdDate": "1638475005999",
                "metadata": {
                    "productId": "NFe",
                    "documentId": "LXNvdm9zfDk5OTl8NTV8MTMxNnwxMTg2OTgyOQ==",
                    "erpDocumentId": "00001",
                    "erpSystemId": "UAT800",
                    "processType": "0",
                    "taxId": "06158643000144",
                    "sciCloudStatusCode": "200",
                    "sciResponseCode": "AP",
                    "sciStatusAction": "NOA"
                },
                "appPrefix": "Smart DF-e",
                "notificationId": 13250178,
                "content": "PEF...c2U+"
            }
        ]
    }
}

GET /documents/BR/{documentId}/notifications

The supplier can send a GET request to the /documents/BR/{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 ID of the document returned in step 2
includeAcknowledged	boolean	No	Query	false	Enter "true" to specify whether previously acknowledged notifications must be included in the result.

Request sample

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

Response sample

{
    "timestamp": 1639056627347,
    "status": 200,
    "success": true,
    "message": "Notifications Listed",
    "data": {
        "pageState": {
            "page": 1,
            "perPage": 1,
            "totalPages": 1,
            "totalEntries": 1
        },
        "notifications": [
            {
                "createdDate": "1639043097008",
                "metadata": {
                    "productId": "NFe",
                    "documentId": "LXNvdm9zfDk5OTl8NTV8MTM1M3wyODUwMjQ0NQ==",
                    "erpDocumentId": "5a645bd6-772f-4009-b2cd-7ad4c4d338ff",
                    "erpSystemId": "UAT800",
                    "processType": "0",
                    "taxId": "06158643000144",
                    "sciCloudStatusCode": "400",
                    "sciResponseCode": "RE",
                    "sciStatusAction": "NIN"
                },
                "appPrefix": "Smart DF-e",
                "notificationId": 13403535,
                "content": "PEF...ZT4="
            }
        ]
    }
}

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/BR endpoint.

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

Request sample

curl --location --request PUT 'https://api-test.sovos.com/v1/notifications/BR' \
--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 11: Supplier Sends the NF-e and the DANFE to the Buyer

As the final step, the supplier should send the NF-e to the buyer through an agreed-upon channel. Additionally, the DANFE should be included during the transportation of the goods. These processes are outside the scope of Sovos.

Step 1: Supplier sends the POST request to Sovos

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

Request sample

curl --location --request POST 'https://api-test.sovos.com/v1/documents/BR/action' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--data-raw '  {
    "actionCode": "document.cancellation",
    "documents": [
      {
        "metadata": {
            "reason": "{reason}"
            "index": "{index number, only used for corrections}"
        },
        "documentId": "{documentId}"
      }
    ]
  }'

Response sample

{
    "timestamp": 1605632952347,
    "status": 202,
    "success": true,
    "message": "Action Received",
    "data": [
        {
            "documentId": "62b6c12e08264046960a35e00b5ed9d11d97"
        }
    ]
}

Step 2: Sovos generates the XML

Upon receiving the request, Sovos generates the required correction or cancellation XML.

Step 3: Sovos signs the XML

Sovos signs the XML with the supplier's certificate.

Step 4: Sovos transmits the XML

Sovos transmits the signed XML to SEFAZ.

Step 5: Supplier retrieves the application responses

The application responses provide status information of the transaction and will also include the acceptance or rejection message.

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 will also include the acceptance or rejection message.

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.

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

• GET /notifications/BR

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

GET /notifications/BR

The supplier can send a GET request to the /notifications/BR endpoint to retrieve application responses that match the configured search criteria. To make this request, set the following query parameters:

Name	Type	Required	Default	Description
taxId	string	No		Include only notifications related to the specified taxId. This value relates to the CompanyCode set in the SBDH.
page	integer	No	1	To specify the page to be returned, enter a value between 1 and 10.
perPage	integer	No	10	To specify the number of results for the returned page, enter a value between 1 and 100. Note: 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	Enter "true" to specify whether previously acknowledged notifications must be included in the result.

Request sample

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

Response sample

{
    "timestamp": 1633687728708,
    "status": 200,
    "success": true,
    "message": "Notifications Listed",
    "data": {
        "pageState": {
            "page": 1,
            "perPage": 2,
            "totalPages": 140,
            "totalEntries": 1399
        },
        "notifications": [
            {
                "createdDate": 1629824492,
                "metadata": {
                    "productId": "NFE",
                    "documentId": "3428ba6600dfd042a2090390e04471ed16b1",
                    "erpDocumentId": "80257087",
                    "erpSystemId": "uat_test",
                    "processType": "0",
                    "taxId": "URE180429TM6",
                    "sciCloudStatusCode": "101",
                    "sciResponseCode": "IP",
                    "sciStatusAction": "NOA"
                },
                "appPrefix": "INV",
                "notificationId": "da3095da-f974-420c-bce2-e33682692276",
                "content": "PEF...c2U+"
            },
            {
                "createdDate": 1629857132,
                "metadata": {
                    "productId": "NFE",
                    "documentId": "3b20cf820153a0407f0b40402482b216cd7b",
                    "erpDocumentId": "321412",
                    "erpSystemId": "uat_test",
                    "processType": "0",
                    "taxId": "URE180429TM6",
                    "sciCloudStatusCode": "102",
                    "sciResponseCode": "IP",
                    "sciStatusAction": "NOA"
                },
                "appPrefix": "INV",
                "notificationId": "6b0e273b-9ba9-43bc-9911-7eea7867786e",
                "content": "PEF...NlPg=="
            }
        ]
    }
}

GET /documents/BR/{documentId}/notifications

The supplier can send a GET request to the /documents/BR/{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 ID of the document returned in step 1
includeAcknowledged	boolean	No	Query	false	Enter "true" to specify whether previously acknowledged notifications must be included in the result.

Request sample

curl --location --request GET 'https://api-test.sovos.com/v1/documents/BR/{documentId}/notifications?includeAcknowledged=true' \
--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": "NFSE",
                    "documentId": "0af1d17c-759a-4b93-b6f5-ad11601be390",
                    "erpDocumentId": "76059264",
                    "erpSystemId": "uat_test",
                    "processType": "0",
                    "taxId": "URE180429TM6",
                    "sciCloudStatusCode": "201",
                    "sciResponseCode": "AP",
                    "sciStatusAction": "NOA",
                    "sciGovtStatusCode": "100"
                },
                "appPrefix": "INV",
                "notificationId": "a8dc1aa2-fbe6-45ce-9e4c-97a3d5fdb91c",
                "content": "PEF...NlPg=="
            }
        ]
    }
}

Step 6: Supplier marks the application responses as acknowledged

The supplier must process the retrieved application responses and mark them as acknowledged. To do that, make a PUT request to the /notifications/BR endpoint.

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

Request sample

curl --location --request PUT 'https://api-test.sovos.com/v1/notifications/BR' \
--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: 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 in turn includes a Sovos Canonical Invoice (SCI). To create the SBD, follow the detailed instructions in the SBDH, Sovos Document, and SCI pages. Here are some key elements that you should include in the SBD:

SBD sample

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

<?xml version="1.0" encoding="UTF-8"?>
<sbd:StandardBusinessDocument xmlns:sbd="http://www.unece.org/cefact/namespaces/StandardBusinessDocumentHeader" xmlns:col="ColombiaExtension.xsd" xmlns:dom="DominicanRepublicExtension.xsd" xmlns:spa="SpainExtension.xsd" xmlns:xades="http://uri.etsi.org/01903/v1.3.2#" xmlns:ad="http://www.sovos.com/namespaces/additionalData" xmlns:sci="http://www.sovos.com/namespaces/sovosCanonicalInvoice" xmlns:svs="http://www.sovos.com/namespaces/sovosDocument" xmlns:sov="http://www.sovos.com/namespaces/sovosExtensions" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" xmlns:ext="urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2" xmlns:n1="urn:oasis:names:specification:ubl:schema:xsd:CommonSignatureComponents-2" xmlns:crn="urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2" xmlns:dbn="urn:oasis:names:specification:ubl:schema:xsd:DebitNote-2" xmlns:fin="urn:oasis:names:specification:ubl:schema:xsd:FreightInvoice-2" xmlns:inv="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2" 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:udt="urn:oasis:names:specification:ubl:schema:xsd:UnqualifiedDataTypes-2" xmlns:ccts-cct="urn:un:unece:uncefact:data:specification:CoreComponentTypeSchemaModule:2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<sbd:StandardBusinessDocumentHeader>
		<sbd:HeaderVersion>1.0</sbd:HeaderVersion>
		<sbd:Sender>
			<sbd:Identifier Authority="BR">11111111111111</sbd:Identifier>
			<sbd:ContactInformation>
				<sbd:Contact/>
				<sbd:EmailAddress/>
				<sbd:FaxNumber/>
				<sbd:TelephoneNumber/>
				<sbd:ContactTypeIdentifier/>
			</sbd:ContactInformation>
		</sbd:Sender>
		<sbd:Receiver>
			<sbd:Identifier Authority="BR">22222222222</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>2020-01-01T12:00:00Z</sbd:CreationDateAndTime>
		</sbd:DocumentIdentification>
		<sbd:BusinessScope>
			<sbd:Scope>
				<sbd:Type>Country</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>BR</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>SenderSystemId</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>ABC200</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>
				<InstanceIdentifier/>
				<sbd:Identifier>NFSe</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>CompanyCode</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>ABC134</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>SenderDocumentId</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>XYZ1234</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>ProcessType</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>Outbound</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>BusinessCategory</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>BusinessToBusiness</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:BusinessScope>
	</sbd:StandardBusinessDocumentHeader>
	<svs:SovosDocument>
		<sci:SovosCanonicalInvoice>
			<inv:Invoice>
				*UBL Nodes*
			</inv:Invoice>
		</sci:SovosCanonicalInvoice>
	</svs:SovosDocument>
</sbd: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:

Step 3: Sovos maps the SCI into the NFS-e

Upon receiving the SCI, Sovos maps the file into the required NFS-e format.

Step 4: Sovos performs the schema validation

Sovos performs a schema validation to determine whether the NFS-e XML file conforms to the expected structure by validating the file against the official schema.

Step 5: Sovos signs the NFS-e

Step 6: Sovos transmits the NFS-e

Sovos transmits the signed NFS-e file to the relevant municipality for clearance.

Step 7: Municipality processes the NFS-e

The municipality performs the clearance process, which involves schema validation and several content validations, including the supplier's signature. Once finished, the municipality returns the cleared NFS-e to Sovos . In addition, the municipality generates a PDF and sends it to the buyer.

Step 8: Sovos generates the PDF

Sovos generates a PDF with the content of the NFS-e based on the configured PDF template.

Step 9: Sovos distributes the PDF and the NFS-e

As explained in step 11, the supplier can retrieve the NFS-e and the PDF via a GET API request. But Sovos can also distribute the PDF and the NFS-e to the supplier using one of the following options:

• Email

• AS2

• SFTP

• Web services

Step 10: Sovos stores the document

Sovos stores the PDF and NFS-e.

Step 11: Supplier retrieves the application responses

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. These responses provide status information and also include a URL to access the cleared NFS-e and the PDF, once these have become available during the process.

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.

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

• GET /notifications/BR

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

GET /notifications/BR

The supplier can send a GET request to the /notifications/BR endpoint to retrieve application responses that match the configured search criteria. To make this request, set the following query parameters:

Name	Type	Required	Default	Description
taxId	string	No		Include only notifications related to the specified taxId. This value relates to the CompanyCode set in the SBDH.
page	integer	No	1	To specify the page to be returned, enter a value between 1 and 10.
perPage	integer	No	10	To specify the number of results for the returned page, enter a value between 1 and 100. Note: 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	Enter "true" to specify whether previously acknowledged notifications must be included in the result.

Request sample

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

Response sample

{
    "timestamp": 1633687728708,
    "status": 200,
    "success": true,
    "message": "Notifications Listed",
    "data": {
        "pageState": {
            "page": 1,
            "perPage": 2,
            "totalPages": 140,
            "totalEntries": 1399
        },
        "notifications": [
            {
                "createdDate": 1629824492,
                "metadata": {
                    "productId": "NFSE",
                    "documentId": "3428ba6600dfd042a2090390e04471ed16b1",
                    "erpDocumentId": "80257087",
                    "erpSystemId": "uat_test",
                    "processType": "0",
                    "taxId": "URE180429TM6",
                    "sciCloudStatusCode": "101",
                    "sciResponseCode": "IP",
                    "sciStatusAction": "NOA"
                },
                "appPrefix": "INV",
                "notificationId": "da3095da-f974-420c-bce2-e33682692276",
                "content": "PEF...c2U+"
            },
            {
                "createdDate": 1629857132,
                "metadata": {
                    "productId": "NFSE",
                    "documentId": "3b20cf820153a0407f0b40402482b216cd7b",
                    "erpDocumentId": "321412",
                    "erpSystemId": "uat_test",
                    "processType": "0",
                    "taxId": "URE180429TM6",
                    "sciCloudStatusCode": "102",
                    "sciResponseCode": "IP",
                    "sciStatusAction": "NOA"
                },
                "appPrefix": "INV",
                "notificationId": "6b0e273b-9ba9-43bc-9911-7eea7867786e",
                "content": "PEF...NlPg=="
            }
        ]
    }
}

GET /documents/BR/{documentId}/notifications

The supplier can send a GET request to the /documents/BR/{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 ID of the document returned in step 2
includeAcknowledged	boolean	No	Query	false	Enter "true" to specify whether previously acknowledged notifications must be included in the result.

Request sample

curl --location --request GET 'https://api-test.sovos.com/v1/documents/BR/{documentId}/notifications?includeAcknowledged=true' \
--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": "NFSE",
                    "documentId": "0af1d17c-759a-4b93-b6f5-ad11601be390",
                    "erpDocumentId": "76059264",
                    "erpSystemId": "uat_test",
                    "processType": "0",
                    "taxId": "URE180429TM6",
                    "sciCloudStatusCode": "200",
                    "sciResponseCode": "AP",
                    "sciStatusAction": "NOA",
                    "sciGovtStatusCode": "100"
                },
                "appPrefix": "INV",
                "notificationId": "a8dc1aa2-fbe6-45ce-9e4c-97a3d5fdb91c",
                "content": "PEF...NlPg=="
            }
        ]
    }
}

Step 12: 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/BR endpoint.

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

Request sample

curl --location --request PUT 'https://api-test.sovos.com/v1/notifications/BR' \
--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 13: Supplier sends the NFS-e and the PDF to the buyer

As the final step, the supplier should send the NFS-e and optionally the PDF to the buyer through an agreed-upon channel. This process is outside the scope of Sovos.

Step 1: Supplier sends a POST request to Sovos

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

Request sample

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

Response sample

{
    "timestamp": 1605632952347,
    "status": 202,
    "success": true,
    "message": "Action Received",
    "data": [
        {
            "documentId": "62b6c12e08264046960a35e00b5ed9d11d97"
        }
    ]
}

Step 2: Sovos generates the cancellation XML

Upon receiving the request, Sovos generates the required cancellation XML.

Step 3: Sovos signs the cancellation XML

Sovos signs the XML with the supplier's certificate.

Step 4: Sovos transmits the cancellation XML

Sovos transmits the signed XML to the municipality.

Step 5: Municipality processes the cancellation

The municipality performs the cancellation and generates the acceptance or rejection message in XML format.

Step 6: Municipality returns the response

The municipality returns the acceptance or rejection message to Sovos.

Step 7: Supplier retrieves the application responses

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 will also include the acceptance or rejection message.

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.

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

• GET /notifications/BR

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

GET /notifications/BR

The supplier can send a GET request to the /notifications/BR endpoint to retrieve application responses that match the configured search criteria. To make this request, set the following query parameters:

Name	Type	Required	Default	Description
taxId	string	No		Include only notifications related to the specified taxId. This value relates to the CompanyCode set in the SBDH.
page	integer	No	1	To specify the page to be returned, enter a value between 1 and 10.
perPage	integer	No	10	To specify the number of results for the returned page, enter a value between 1 and 100. Note: 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	Enter "true" to specify whether previously acknowledged notifications must be included in the result.

Request sample

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

Response sample

{
    "timestamp": 1633687728708,
    "status": 200,
    "success": true,
    "message": "Notifications Listed",
    "data": {
        "pageState": {
            "page": 1,
            "perPage": 2,
            "totalPages": 140,
            "totalEntries": 1399
        },
        "notifications": [
            {
                "createdDate": 1629824492,
                "metadata": {
                    "productId": "NFSE",
                    "documentId": "3428ba6600dfd042a2090390e04471ed16b1",
                    "erpDocumentId": "80257087",
                    "erpSystemId": "uat_test",
                    "processType": "0",
                    "taxId": "URE180429TM6",
                    "sciCloudStatusCode": "101",
                    "sciResponseCode": "IP",
                    "sciStatusAction": "NOA"
                },
                "appPrefix": "INV",
                "notificationId": "da3095da-f974-420c-bce2-e33682692276",
                "content": "PEF...c2U+"
            },
            {
                "createdDate": 1629857132,
                "metadata": {
                    "productId": "NFSE",
                    "documentId": "3b20cf820153a0407f0b40402482b216cd7b",
                    "erpDocumentId": "321412",
                    "erpSystemId": "uat_test",
                    "processType": "0",
                    "taxId": "URE180429TM6",
                    "sciCloudStatusCode": "102",
                    "sciResponseCode": "IP",
                    "sciStatusAction": "NOA"
                },
                "appPrefix": "INV",
                "notificationId": "6b0e273b-9ba9-43bc-9911-7eea7867786e",
                "content": "PEF...NlPg=="
            }
        ]
    }
}

GET /documents/BR/{documentId}/notifications

The supplier can send a GET request to the /documents/BR/{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 ID of the document returned in step 1
includeAcknowledged	boolean	No	Query	false	Enter "true" to specify whether previously acknowledged notifications must be included in the result.

Request sample

curl --location --request GET 'https://api-test.sovos.com/v1/documents/BR/{documentId}/notifications?includeAcknowledged=true' \
--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": "NFSE",
                    "documentId": "0af1d17c-759a-4b93-b6f5-ad11601be390",
                    "erpDocumentId": "76059264",
                    "erpSystemId": "uat_test",
                    "processType": "0",
                    "taxId": "URE180429TM6",
                    "sciCloudStatusCode": "201",
                    "sciResponseCode": "AP",
                    "sciStatusAction": "NOA",
                    "sciGovtStatusCode": "100"
                },
                "appPrefix": "INV",
                "notificationId": "a8dc1aa2-fbe6-45ce-9e4c-97a3d5fdb91c",
                "content": "PEF...NlPg=="
            }
        ]
    }
}

Step 8: Supplier marks the application responses as acknowledged

The supplier must process the retrieved application responses and mark them as acknowledged. To do that, make a PUT request to the /notifications/BR endpoint.

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

Request sample

curl --location --request PUT 'https://api-test.sovos.com/v1/notifications/BR' \
--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: 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 in turn includes a Sovos Canonical Invoice (SCI). To create the SBD, follow the detailed instructions in the SBDH, Sovos Document, and SCI pages. Here are some key elements that you should include in the SBD:

SBD sample

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

<?xml version="1.0" encoding="UTF-8"?>
<sbd:StandardBusinessDocument xmlns:sbd="http://www.unece.org/cefact/namespaces/StandardBusinessDocumentHeader" xmlns:col="ColombiaExtension.xsd" xmlns:dom="DominicanRepublicExtension.xsd" xmlns:spa="SpainExtension.xsd" xmlns:xades="http://uri.etsi.org/01903/v1.3.2#" xmlns:ad="http://www.sovos.com/namespaces/additionalData" xmlns:sci="http://www.sovos.com/namespaces/sovosCanonicalInvoice" xmlns:svs="http://www.sovos.com/namespaces/sovosDocument" xmlns:sov="http://www.sovos.com/namespaces/sovosExtensions" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" xmlns:ext="urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2" xmlns:n1="urn:oasis:names:specification:ubl:schema:xsd:CommonSignatureComponents-2" xmlns:crn="urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2" xmlns:dbn="urn:oasis:names:specification:ubl:schema:xsd:DebitNote-2" xmlns:fin="urn:oasis:names:specification:ubl:schema:xsd:FreightInvoice-2" xmlns:inv="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2" 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:udt="urn:oasis:names:specification:ubl:schema:xsd:UnqualifiedDataTypes-2" xmlns:ccts-cct="urn:un:unece:uncefact:data:specification:CoreComponentTypeSchemaModule:2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<sbd:StandardBusinessDocumentHeader>
		<sbd:HeaderVersion>1.0</sbd:HeaderVersion>
		<sbd:Sender>
			<sbd:Identifier Authority="BR">11111111111111</sbd:Identifier>
			<sbd:ContactInformation>
        <sbd:Identifier Authority="BR">22222222222</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>2020-01-01T12:00:00Z</sbd:CreationDateAndTime>
		</sbd:DocumentIdentification>
		<sbd:BusinessScope>
			<sbd:Scope>
				<sbd:Type>Country</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>BR</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>SenderSystemId</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>ABC200</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>
				<InstanceIdentifier/>
				<sbd:Identifier>NFCom</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>CompanyCode</sbd:Type>
            <sbd:InstanceIdentifier/>
				<sbd:Identifier>ABC134</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>SenderDocumentId</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>XYZ1234</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>ProcessType</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>Outbound</sbd:Identifier>
			</sbd:Scope>
			<sbd:Scope>
				<sbd:Type>BusinessCategory</sbd:Type>
				<sbd:InstanceIdentifier/>
				<sbd:Identifier>BusinessToBusiness</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:BusinessScope>
	</sbd:StandardBusinessDocumentHeader>
	<svs:SovosDocument>
		<sci:SovosCanonicalInvoice>
			<inv:Invoice>
				*UBL Nodes*
			</inv:Invoice>
		</sci:SovosCanonicalInvoice>
	</svs:SovosDocument>
</sbd: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:

Step 3: Sovos maps the SCI into the NFCom

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

Step 4: Sovos performs the schema validation

Sovos performs a schema validation to determine whether the NFCom XML file conforms to the expected structure by validating the file against the official schema. In addition, an extended set of offline validations was added according to the NFCom tax payer manual, and it can be activated in configurations.

Step 5: Sovos signs the NFCom

Sovos signs the document using the configured e-NFCom certificate.

Step 6: Sovos transmits the NFCom

Sovos transmits the signed NFCom file to the relevant SEFAZ of the respective state.

Step 7: SEFAZ processes the NFCom

The jurisdiction performs the clearance process, which involves schema validation and several content validations, including the supplier's signature. Once finished, the jurisdiction returns the cleared NFCom to Sovos.

Step 8: Sovos Generates the PDF (Danfe COM)

Sovos generates a PDF with the content of the NFCom based on the configured PDF template.

Step 9: Sovos Distributes the PDF and the NFCom

As explained in step 11, the supplier can retrieve the NFCom and the PDF via a GET API request. But Sovos can also distribute the PDF and the NFCom to the supplier by email.

Step 10: Sovos stores the document

Upon request,Sovos can store the NFCom XML for auditing purposes.

Step 11: Supplier retrieves the application responses

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. These responses provide status information and also include a URL to access the cleared NFCom and the PDF after they become available during the process.

For each transaction, the supplier must retrieve application responses until getting one that indicates that the transaction has been finished.

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

• GET /notifications/BR

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

GET /notifications/BR

The supplier can send a GET request to the /notifications/BR endpoint to retrieve application responses that match the configured search criteria. To make this request, set the following query parameters:

Name	Type	Required	Default	Description
taxId	string	No		Include only notifications related to the specified taxId. This value relates to the CompanyCode set in the SBDH.
page	integer	No	1	To specify the page to be returned, enter a value between 1 and 10.
perPage	integer	No	10	To specify the number of results for the returned page, enter a value between 1 and 100. Note: 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	Enter "true" to specify whether previously acknowledged notifications must be included in the result.

Request sample

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

Response sample

{
        "timestamp": 1633687728708,
    "status": 200,
    "success": true,
    "message": "Notifications Listed",
    "data": {
        "pageState": {
            "page": 1,
            "perPage": 2,
            "totalPages": 140,
            "totalEntries": 1399
        },
        "notifications": [
            {
                "appPrefix": "DLT",
                "content": "PD94bWwgdmVyc2lv...W9uUmVzcG9uc2U+",
                "correlationId": "00801e8c-1782-4e88-909a-8721d55593cd",
                "createdDate": 1710523851824,
                "metadata": {
                    "documentId": "de2a40f2c4aae819205ce706a906d1ab",
                    "erpDocumentId": "NFCOM-24-03-15-143014275",
                    "erpSystemId": "ERPSystem",
                    "processType": "0",
                    "productId": "BR_NFCOM__1.0",
                    "sciCloudStatusCode": "209",
                    "sciGovtStatusCode": "100",
                    "sciResponseCode": "AP",
                    "sciStatusAction": "NOA",
                    "taxId": "CNPJouCPF",
                    "transactionId": "d083b662-8fc9-46d2-a4ab-4a3f1ce3728b"
                },
                "notificationId": "713f2d6b-9078-4ffb-9f65-5edd747254ce"
            },
            {
                "appPrefix": "DLT",
                "content": ""PD94bWwgdmVyc2lv...W9uUmVzcG9uc2U+"",
                "correlationId": "00801e8c-1782-4e88-909a-8721d55593cd",
                "createdDate": 1710523851785,
                "metadata": {
                    "documentId": "de2a40f2c4aae819205ce706a906d1ab",
                    "erpDocumentId": "NFCOM-24-03-15-143014275",
                    "erpSystemId": "ERPSystem",
                    "processType": "0",
                    "productId": "BR_NFCOM__1.0",
                    "sciCloudStatusCode": "208",
                    "sciResponseCode": "AB",
                    "sciStatusAction": "NOA",
                    "taxId": "CNPJouCPF",
                    "transactionId": "d083b662-8fc9-46d2-a4ab-4a3f1ce3728b"
                },
                "notificationId": "72c91e44-62ec-4e12-82be-432fecbf2a65"
            }
        ]
    }
}

GET /documents/BR/{documentId}/notifications

The supplier can send a GET request to the /documents/BR/{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 ID of the document returned in step 2.
includeAcknowledged	boolean	No	Query	false	Enter "true" to specify whether previously acknowledged notifications must be included in the result.

Request sample

curl --location --request GET 'https://api-test.sovos.com/v1/documents/BR/{documentId}/notifications?includeAcknowledged=true' \
--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": [
           {
                "appPrefix": "DLT",
                "content": "PD94bWwgdmVyc2lv...W9uUmVzcG9uc2U+",
                "correlationId": "00801e8c-1782-4e88-909a-8721d55593cd",
                "createdDate": 1710523851824,
                "metadata": {
                    "documentId": "de2a40f2c4aae819205ce706a906d1ab",
                    "erpDocumentId": "NFCOM-24-03-15-143014275",
                    "erpSystemId": "ERPSystem",
                    "processType": "0",
                    "productId": "BR_NFCOM__1.0",
                    "sciCloudStatusCode": "209",
                    "sciGovtStatusCode": "100",
                    "sciResponseCode": "AP",
                    "sciStatusAction": "NOA",
                    "taxId": "CNPJouCPF",
                    "transactionId": "d083b662-8fc9-46d2-a4ab-4a3f1ce3728b"
                },
                "notificationId": "713f2d6b-9078-4ffb-9f65-5edd747254ce"
            }
        ]
    }
}

Step 12: 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/BR endpoint.

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

Request sample

curl --location --request PUT 'https://api-test.sovos.com/v1/notifications/BR' \
--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 13: Supplier sends the NFCom and the PDF to the buyer

As the final step, the supplier should send the NFCom and optionally the PDF to the buyer through an agreed-upon channel. Sovos supports this if it is by email.

Step 1: Supplier sends a POST request to Sovos

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

Request sample

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

Response sample

{
    "timestamp": 1610532937756,
    "status": 200,
    "success": true,
    "message": "Process Completed",
    "data": {
        "notification": {
            "createdDate": "2020-06-16T00:31:52Z",
            "metadata": {},
            "appPrefix": "dlt",
            "notificationId": "MW242873231610532937726",
            "content": "PEF...ZT4="
        }
    }
}

Step 2: Sovos transmits the XML

Sovos transmits the cancellation XML to SEFAZ.

Step 3: SEFAZ returns the response and the notification is created

Step 4: Archiving

Optionally, you can store the application response and the proof of cancellation in a compliant way using Sovos Compliant Archive. See the eArchiving section for more information.

Step 5: Supplier informs buyer

The supplier should inform the buyer about the invoice cancellation. Unless the buyer has the Inbound solution, this process is out of scope of Sovos.

Step 1a: Sovos retrieves the NFS-e

Step 1b: Buyer sends the NFS-e to Sovos

The buyer sends the NFS-e to Sovos via email.

Step 2: Sovos validates the signature

Step 3: Sovos transmits the NFS-e

In scenario 1b, Sovos transmits the received NFS-e to the municipality for validation. The buyer's certificate is used to contact the Municipality's web services for authentication and authorization purposes.

Step 4: Municipality validates the NFS-e

In scenario 1b, the municipality validates the NFS-e by comparing the clearance information provided with the one they have in store and returns a validation report.

Step 5: Sovos generates the PDF

Sovos generates a PDF that contains the content of the NFS-e, based on the configured PDF template.

Step 6: Sovos distributes the NFS-e, the PDF, and the validation report

As explained in step 8, the buyer can retrieve the NFS-e, the PDF and, optionally, the validation report via a GET API request. But Sovos can also distribute the NFS-e, the PDF, and the validation report to the buyer via one of the following options:

Step 7: Storing

Sovos stores the NFS-e, the PDF, and the validation report.

Step 8: Buyer retrieves the application responses

The NFS-e, the PDF, and optionally the validation report are included in the application responses that the buyer can retrieve. This means that the buyer must retrieve all the application responses that become available. The application responses provide status information and also include the NFS-e, the PDF and, optionally, the validation report.

The buyer can use the following endpoint to retrieve application responses:

Step 9: 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/BR endpoint.

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

Request sample

curl --location --request PUT 'https://api-test.sovos.com/v1/notifications/BR' \
--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 1a: Sovos retrieves the NF-e

Step 1b: Buyer sends the NF-e to Sovos

The buyer sends the NF-e to Sovos via email.

Step 2: Sovos validates the signature

In scenario 1b, Sovos validates the NF-e schema and verifies the integrity and authenticity of the supplier's signature.

Step 3: Sovos transmits the NF-e

In scenario 1b, Sovos transmits the received NF-e to the SEFAZ for validation. The buyer's certificate is used to contact the SEFAZ web services for authentication and authorization purposes.

Step 4: SEFAZ validates the NF-e

In scenario 1b,SEFAZ validates the NF-e by comparing the clearance information provided with the one they have in store and returns a validation report.

Step 5: Sovos generates the PDF

Sovos generates a PDF that contains the content of the NF-e, based on the configured PDF template.

Step 6: Sovos distributes the NF-e, the PDF, and the validation report

As explained in step 8, the buyer can retrieve the NF-e, the PDF, and, optionally, the validation report via a GET API request. But Sovos can also distribute the NF-e, the PDF, and the validation report to the buyer via one of the following options:

• Email

• AS2

• SFTP

• Web services

Step 7: Storing

Sovos stores the NF-e, the PDF, and the validation report.

Step 8: Buyer retrieves the application responses

The NF-e, the PDF, and optionally the validation report are included in the application responses that the buyer can retrieve. This means that the buyer must retrieve all the application responses that become available. The application responses provide status information and also include the NF-e, the PDF and, optionally, the validation report.

The buyer can use the following endpoint to retrieve application responses:

Step 9: 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/BR endpoint.

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

Request sample

curl --location --request PUT 'https://api-test.sovos.com/v1/notifications/BR' \
--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 1a: Sovos retrieves the CT-e

Step 1b: Buyer sends the CT-e to Sovos

The buyer sends the CT-e to Sovos via email.

Step 2: Sovos validates the signature

In scenario 1b, Sovos validates the CT-e schema and verifies the integrity and authenticity of the supplier's signature.

Step 3: Sovos transmits the CT-e

In scenario 1b, Sovos transmits the received CT-e to the SEFAZ for validation. The buyer's certificate is used to contact the SEFAZ web services for authentication and authorization purposes.

Step 4: SEFAZ validates the CT-e

In scenario 1b, SEFAZ validates the CT-e by comparing the clearance information provided with the one they have in store and returns a validation report.

Step 5: Sovos generates the PDF

Sovos generates a PDF that contains the content of the CT-e, based on the configured PDF template.

Step 6: Sovos distributes the CT-e, the PDF, and the validation report

As explained in step 8, the buyer can retrieve the CT-e, the PDF, and, optionally, the validation report via a GET API request. But Sovos can also distribute the CT-e, the PDF, and the validation report to the buyer via one of the following options:

• Email

• AS2

• SFTP

• Web services

Step 7: Storing

Sovos stores the CT-e, the PDF, and the validation report.

Step 8: Buyer retrieves the application responses

The CT-e, the PDF, and optionally the validation report are included in the application responses that the buyer can retrieve. This means that the buyer must retrieve all the application responses that become available. The application responses provide status information and also include the CT-e, the PDF and, optionally, the validation report.

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

Step 9: 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/BR endpoint.

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

Request sample

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