About application responses
The Indirect Tax API uses application responses to send notifications.
Notifications play a crucial role in the Indirect Tax API. They are delivered as application responses, which are formatted in UBL 2.1 (UBL 2.1 Application Response XSD) and carry status updates and documents that are part of the transaction. Examples of these documents include cleared invoices, generated PDFs, and messages from the tax authority.
Indirect Tax API returns application responses as Base64-encoded strings in the content field of the response in these specific cases:
| Method | Endpoint | Description |
|---|---|---|
| POST | /documents | Document creation — only returns an application response when the customer specifies one business scope (e.g. mapping) in the new document (synchronous transaction). |
| GET | /documents/{countryCode}/{documentId}/notifications | Retrieves all notifications for a given document. |
| GET | /notifications/{countryCode} | Retrieves notifications based on the applied filters. |
| GET | /notifications/{countryCode}/{notificationId} | Retrieves a specific notification. |
Sovos response codes and status reason codes
Each application response comprises one Sovos response code and several status reason codes. These codes provide the status of the issued document and help determine when further action is required. The following response code and status reason codes can appear in the application response:
| Code | Code type | Display frequency | Description |
|---|---|---|---|
SCIResponseCode | Response code | Always | Shows the overall compliance status of the document. |
SCICloudStatusCode | Status reason code | At least once | Gives more specific information regarding the status of the document and helps understand why the document received a particular SCIResponseCode. |
SCIGovtStatusCode | Status reason code | In some cases | Comes from the tax authority of the relevant market. |
SCIStatusAction | Status reason code | At least once | Informs when additional action is required. |
SCIInternalValidation | Status reason code | In some cases | Part of the application response when there are market-specific schema validation errors in the document, as detected by Sovos' schema validation service. It shows the fields in the document that need to be fixed. |
Schema validation is performed sequentially, from top to bottom, according to the structure of the schema (xsd) for the applicable market. The system stops the validation and returns an error as soon as it finds a mandatory field, so no further validation is performed on the remaining fields.
SCI response code
SCIResponseCode is a two-letter response code, which is always included in the application response. It provides the overall compliance status of a document, the primary processing logic for implementers, and indicates whether a document has been processed successfully.
This code can have the following values:
| Response Code | Name | Description | Final |
|---|---|---|---|
AB | Message acknowledgment | An acknowledgment is required in relation to the receipt of a message or a transaction. | No |
IP | In Process | The referenced message or transaction is being processed. | No |
CA | Conditionally accepted | The referenced offer or transaction has been accepted under the conditions indicated in this message. | Yes |
RE | Rejected | The referenced offer or transaction hasn't been accepted. | Yes |
AP | Accepted | The referenced offer or transaction has been accepted. | Yes |
The SCI response codes of AB and IP are not final responses. They provide the implementer visibility of the ongoing governmental process. Eventually, all documents settle into" Accepted", "Conditionally Accepted", or "Rejected".
SCI cloud status code
SCICloudStatusCode provides additional status information for the SCIResponseCode. This unique three-digit status code appears one or more times in the application response.
SCICloudStatusCode can include two elements: - StatusReason
- This code explains what the status code means.
- Text
- This element may be included to offer more in-depth details.
The SCI cloud status codes are categorized as follows:
- 100 Series codes
- Indicate work in process steps completed.
- 200 Series codes
- Indicate successful process completions.
- 400 Series codes
- Indicate document-related rejections or errors.
- 500 Series codes
- Indicate system-related issues or errors, such as network, credential issue, or API endpoint down.
Possible SCI cloud status codes:
| Status reason code | Event code | Description |
|---|---|---|
| 100 | document.received | Document received successfully |
| 101 | document.mapped | Document mapped successfully |
| 102 | document.validated | Document validated successfully |
| 103 | document.signed | Document signed successfully |
| 104 | document.transmitted | Document transmitted to the tax authority |
| 105 | document.processing | Document being processed by the tax authority (polling status) |
| 106 | document.processingInternally | Document being processed by Sovos |
| 107 | action.received | Action received successfully |
| 200 | document.authorized | Document authorized by the tax authority |
| 201 | document.cancelled | Document canceled |
| 202 | document.denied | Use denied by the tax authority |
| 203 | document.acceptedByCounterparty | Document accepted/acknowledged by the counterparty |
| 204 | document.distributed | Document distributed successfully |
| 205 | document.printed | Document printed successfully |
| 206 | document.finalized | Document finalized successfully |
| 207 | document.pdf.created | PDF created successfully |
| 208 | document.archived | Document archived successfully |
| 209 | workflow completed | Workflow completed successfully |
| 212 | document.commerciallyRejected | Rejection request accepted/acknowledged by the tax authority |
| 213 | document.continue | Document continued successfully |
| 214 | document.hearingRequest | Document hearing requested successfully |
| 400 | document.rejected | Document rejected by the tax authority |
| 401 | document.error | Error processing document |
| 402 | document.notFound | Document not found |
| 403 | document.cancellationRejected | Cancellation rejected by the tax authority or the counterparty |
| 404 | document.authorizedPreviously | Document already authorized by the tax authority |
| 405 | document.rejectedByCounterparty | Document rejected by the counterparty |
| 406 | document.alreadyInProgress | Document already in progress |
| 500 | system.error | Internal system error |
| 501 | taxAuthority.unavailable | Tax authority down or unavailable |
| 502 | request.invalidParameters | Invalid or missing input parameters |
| 503 | request.invalidCredentials | Expired token or invalid user credentials |
| 504 | process.Timeout | Tax authority not responding, and the current process will be stopped |
SCI government status code
The SCIGovtStatusCode comes directly from the tax authority of certain countries. Sovos collects the tax authority response in these cases and passes along the raw error message to the calling application or user.
This code offers similar information to the Sovos generated SCIResponseCode and SCICloudStatusCode. However, it is usually accompanied by a local language rationale for the error, such as "Address field format is invalid" or "Tax ID length is incorrect".
SCIGovtStatusCode can contain two elements:
-
StatusReason, which explains what the status code means. -
SequenceId, which may be included to represent the legal tracking ID provided by the tax authority.
For a comprehensive list of government status codes, visit the corresponding tax authority's website.
SCI status action
SCIStatusAction is a three-letter status code based on SCIResponseCode. It identifies any additional required action and is included at least once in every application response.
Possible codes for the SCI status action:
| Status Reason Code | Name | Description |
|---|---|---|
NOA | No action required | Typical response for a successful transmission. |
NIN | Issue new document or fix the error | Request to reissue a corrected new invoice (or other document) or fix the error and resend the document. Typical response for unsuccessful transmission due to a 400 series error. |
OTH | Other | The requested action is not defined by code. |
SCI internal validation
SCIInternalValidation is a code that identifies country-specific schema validation errors. This code highlights the specific field or node that is causing validation errors so that you can review and correct the errors.
Document status handling
The most important status element within the application response is the SCIResponseCode. A transaction can only be marked as completed when an application response has been retrieved that has one of the final SCI response codes (AP, RE, or CA). In some cases, there may be multiple SCI response codes per document, so the SCICloudStatusCode must be used to determine the status of the document.
To determine the status of a document, the client application must process responses in the following order of importance:
- SCIResponseCode "AP" with SCICloudStatusCode "201"
- This is relevant if the country supports cancellations, and the customer is using the cancellation functionality. If there is a cancellation, there will be two application responses with
SCIResponseCodeAP: One for the authorization, and one for the cancellation. In this case, the cancellation has priority over the authorization because it happened last. - SCIResponseCode "AP" with SCICloudStatusCode "200"
- The tax authority approved a document.
- SCIResponseCode "RE"
- A document was rejected.
SCIGovtStatusCodedisplays the error code and the description returned by the state agent. Sovos recommends analyzing the error and taking the appropriate action. - SCIResponseCode "IP"
- The transaction is still in progress. No action is needed, but the client must keep retrieving application responses until the transaction can be marked as completed when retrieving one of the final SCI response codes.
Application response sample
This sample application response illustrates the structure and content of a response authorized by the tax authority:
<ApplicationResponse xmlns="urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2" xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ext="urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2" xmlns:ad="http://www.sovos.com/namespaces/additionalData">
<ext:UBLExtensions>
<ext:UBLExtension>
<ext:ExtensionContent>
<ad:AdditionalData>
<ad:Field name="InscricaoMunicipal" type="LegalNumber">FAKEF04D</ad:Field>
<ad:Field name="NFeNumber" type="LegalNumber">278754</ad:Field>
<ad:Field name="VerificationCode" type="LegalNumber">17626b16cd46</ad:Field>
</ad:AdditionalData>
</ext:ExtensionContent>
</ext:UBLExtension>
</ext:UBLExtensions>
<cbc:UBLVersionID>2.1</cbc:UBLVersionID>
<cbc:CustomizationID>urn:sovos:names:specification:sci:schema:xsd:Transaction-3</cbc:CustomizationID>
<cbc:ProfileID>urn:sovos:names:specification:sci:schema:xsd:Transaction-3</cbc:ProfileID>
<cbc:ID>1cdbf2a2-6698-4a82-8aaa-17626b16cd46</cbc:ID>
<cbc:IssueDate>2020-11-27</cbc:IssueDate>
<cac:SenderParty>
<cac:PartyName>
<cbc:Name>Sovos Compliance</cbc:Name>
</cac:PartyName>
<cac:Contact>
<cbc:Name>Sovos Support</cbc:Name>
<cbc:Telephone>+44(0) 203 868 4126</cbc:Telephone>
<cbc:ElectronicMail>support@sovos.com</cbc:ElectronicMail>
</cac:Contact>
</cac:SenderParty>
<cac:ReceiverParty>
<cac:PartyIdentification>
<cbc:ID>22129014</cbc:ID>
</cac:PartyIdentification>
</cac:ReceiverParty>
<cac:DocumentResponse>
<cac:Response>
<cbc:ResponseCode listID="SCIResponseCode">AP</cbc:ResponseCode>
<cac:Status>
<cbc:StatusReasonCode listID="SCICloudStatusCode">200</cbc:StatusReasonCode>
<cbc:StatusReason>Authorized by the tax authority</cbc:StatusReason>
</cac:Status>
<cac:Status>
<cbc:StatusReasonCode listID="SCIGovtStatusCode">S100</cbc:StatusReasonCode>
<cbc:StatusReason>NFSe autorizada pela prefeitura. Numero:278754, Codigo de Autorizacao:FAKEF04D</cbc:StatusReason>
<cbc:SequenceID>278754</cbc:SequenceID>
<cbc:Text>NFSe autorizada pela prefeitura. Numero:278754, Codigo de Autorizacao:FAKEF04D</cbc:Text>
</cac:Status>
<cac:Status>
<cbc:StatusReasonCode listID="SCIStatusAction">NOA</cbc:StatusReasonCode>
<cbc:StatusReason>No action required</cbc:StatusReason>
</cac:Status>
</cac:Response>
<cac:DocumentReference>
<cac:Attachment>
<cac:ExternalReference>
<cbc:URI schemeID="SCIStorage">http://uat-einv-br.sovos.com/TF.Portal/ws/DownloadDocument.aspx?id=4d10ff3f-29f5-4362-b397-887910a268ee&format=attach&attach=NFSe</cbc:URI>
<cbc:MimeCode>text/xml</cbc:MimeCode>
</cac:ExternalReference>
</cac:Attachment>
</cac:DocumentReference>
<cac:DocumentReference>
<cac:Attachment>
<cac:ExternalReference>
<cbc:URI schemeID="SCIStorage">http://uat-einv-br.sovos.com/TF.Portal/ws/DownloadDocument.aspx?id=4d10ff3f-29f5-4362-b397-887910a268ee&format=attach&attach=NFSeBRDefault</cbc:URI>
<cbc:MimeCode>application/pdf</cbc:MimeCode>
</cac:ExternalReference>
</cac:Attachment>
</cac:DocumentReference>
</cac:DocumentResponse>
</ApplicationResponse>