Spain
Enabling support for Spain has requirements such as an electronic certificate and other requirements for SII, TicketBAI, and LROE.
Prerequisites
- Electronic certificate
- Send an electronic certificate obtained from AEAT or other approved agencies to Sovos using Indirect Tax API. This certificate is associated with the taxpayer's NIF and works with both the AEAT's test and production environments.Note:
Because Sovos is a "social collaborator" (colaborador social, in Spanish) in Spain, you can use the Sovos certificate instead. This also requires a Power of Attorney that must be signed and kept in the internal records. Therefore, it doesn't need to be submitted to AEAT. If you had another provider before Sovos, your old provider needs to revoke their Power of Attorney before you can join Sovos (Revocacion de apoderamientos, in Spanish).
Check this AEAT web page to learn more about the SII Electronic Certificate.
- Developer accounts
- Create two developer accounts with different email addresses to use the Configuration v2 resource — one of them specifically indicated for TicketBAI integration. You also need (for now) to contact the Sovos' Professional Services team to obtain special authorization to use this resource and to obtain your organization ID.Note:
Organization IDs differ between sandbox and production.
- Required forms
- For both sandbox (UAT) and production in SII and Biscay, you need to fill out the following forms and share them with the Sovos Professional Services team:
- Specific to BATUZ TicketBAI
-
-
You must live in Spain or own a stable establishment in Spain
-
You must have a valid tax ID that does not begin with "N"
-
In the case of self invoicing, whether you are an issuer in invoices or buyer in self-invoices, you must have a valid signing certificate.
-
- Specific to BATUZ LROE
-
The LROE service requires an electronic certificate to authenticate the validity of the request. This can be done by the taxpayers themselves or by their representatives (acting on their behalf). Types of certificates that are accepted:
-
Certificate of a physical or natural person
-
Certificate of a legal entity
-
Company seal
-
Non-qualified self-employed certificate
-
Device certificate registered for the taxpayer in DFB or BFA
-
Available products
- SII products
- Available categories and product IDs:
- Sales (ES_SALES category)
-
-
es_SuministroLRFacturasEmitidas_Gipuzkoa_1.0
-
es_SuministroLRFacturasEmitidas_CanaryIslands_1.0
-
es_SuministroLRFacturasEmitidas_Bizkaia_1.0
-
es_SuministroLRFacturasEmitidas_Mainland_1.0
-
- Purchases (ES_INB category)
-
-
es_SuministroLRFacturasRecibidas_Gipuzkoa_1.0
-
es_SuministroLRFacturasRecibidas_CanaryIslands_1.0
-
es_SuministroLRFacturasRecibidas_Bizkaia_1.0
-
es_SuministroLRFacturasRecibidas_Mainland_1.0
-
- Intracommunity supply (ES_OIC category)
-
-
es_SuministroLRDetOperacionesIntracomunitaria_Mainland_1.0
-
- Consignment sales (ES_VC category)
-
-
es_SuministroLRVentaConsigna_Mainland_1.0
-
- TicketBAI
- The only available product ID is es_temp_Ticketbai_1.0.Note:
The product ID for TicketBAI is only relevant for creating a company, including self-billing cases. You can't upload credentials for TicketBAI using the API at this time, so the Professional Services team handles this process during the implementation phase.
- LROE
- Available categories and product IDs:
- ES_LROES category
- Sales with TicketBAI (Chapter 1.1)
- es_LROEPJ240FacturasEmitidasConSGAltaPeticion_Batuz_1.0
- Sales without TicketBAI (Chapter 1.2)
- es_LROEPJ240FacturasEmitidasSinSGAltaModifPeticion_Batuz_1.0
- ES_LROEP category
- Purchase (Chapter 2) includes only the es_LROEPJ240FacturasRecibidasAltaModifPeticion_Batuz_1.0 product
- ES_LROEGA category
- Intracommunity Transfers (Chapter 4.1) includes only the es_LROEPJ240TransferenciasPericialesOtrosAltaModifPeticion_Batuz_1.0 product
- ES_LROEIO category
- Insurance operations (Chapter 6.2) includes only the es_LROEPJ240OperacionesSegurosAltaModifPeticion_Batuz_1.0 product
Error handling
When handling errors, the client application must follow the Indirect Tax API's error handling principles, as specified in the error handling documentation.
In general, all error codes in the 400 range are client errors, which you need to analyze. After fixing the error, you can resend the request. Error codes 408 and 429 are exceptions: In these cases, you should wait at least 60 seconds before retrying. Error codes in the 500 range are server errors. In that case, resend the request according to the instructions given on the error handling documentation, which also includes a full list of error codes Indirect Tax API can return.
Errors coming from the tax authority are shown in the application response. This means that if the tax authority rejects the request, SCIResponseCode is set to "RE" and any error codes will be located in the SCIGovtStatusCode element.
You need to take action after receiving an error code and a message from the tax authority.
The same applies to when errors come from the LROE.
For additional help on error handling for SII invoices, the Validaciones y Errores SII document from the Agencia Tributaria website includes all the error codes and messages the tax authority can return for invoice cancellation in the Spanish Tax Authority.
Configure transmission credentials for Spain
-
Configure a company and a product.
-
Obtain the required certificate.
Upon successful creation, the API will return a JSON object containing the uploaded transmission credentials and their assigned SETTING-ID.
Samples for uploading transmission credentials for Spain
Request sample
Request sample for uploading new credentials:
curl --location --request POST 'https://api-test.sovos.com/v2/configurations/organizations/{organizationId}/settings' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--header 'x-correlationId: SET-TO-UNIQUE-VALUE' \
--data-raw '[
{
"context": "transmission",
"configurations": [
{
"name": "partner_credentials_es",
"value": {
"certificate": "CERT-IN-BASE64",
"password": "CERT-PASS"
},
"scope": {
"category": "ES_SALES",
"productId": "es_SuministroLRFacturasEmitidas_Mainland_1.0",
"orgId": "YOUR-ORG-ID",
"taxId": "YOUR-COMPANY-TAXID"
}
}
]
}
]'Response sample
Response sample for uploading new credentials:
{
"status": 201,
"message": "Created",
"success": true,
"timestamp": 1663415078266,
"data": [
{
"message": "Configurations are created",
"statusCode": 201,
"configurationContextResponse": {
"context": "Transmission",
"configurations": [
{
"id": "SETTING-ID",
"name": "partner_credentials_es",
"value": {
"certificate": "*******",
"password": "*******"
},
"scope": {
"category": "ES_SALES",
"productId": "es_SuministroLRFacturasEmitidas_Mainland_1.0",
"orgId": "YOUR-ORG-ID",
"taxId": "YOUR-COMPANY-TAXID"
},
"auditData": {
"createdAt": 1663415078,
"createdBy": "user@company.com",
"isDeleted": false,
"version": 1
}
}
]
}
}
]
}Report invoice (SII)
Reporting sales invoices in Spain (SII) is based on the Default business process, which follows this order: Mapping and Transmission. The following diagram provides a detailed overview:
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 and in the invoice:
Use the following values in the SBDH for documents that use the SCI format:
| Node | Required | Attributes | Value |
|---|---|---|---|
| StandardBusinessDocumentHeader.Sender.Identifier | Yes | Authority="ES" | Supplier's NIF |
| StandardBusinessDocumentHeader.Receiver.Identifier | Yes | Authority="ES" | |
| 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 Child node | |
| StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes |
Child node Child node | |
| StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes |
Child node Child node | |
| StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes |
Child node Child node | |
| StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes |
Child node Child node | |
| StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes |
Child node Child node | |
| StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes |
Child node Child node | |
| StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes |
Child node Child node | |
| StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes |
Child node Child node | |
| StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes |
Child node Child node | |
| StandardBusinessDocumentHeader.BusinessScope.Scope.BusinessService.BusinessServiceName | Yes | Default | |
| SovosDocument.SovosCanonicalInvoice.Invoice | Yes | SCI |
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 Child node |
| SovosDocument.SovosLegalDocument.Base64Document | Yes | A local format |
You need to encode the local format (XML) document in Base64 before you can add it as part of the SBD. Here is a sample:
</sbd:StandardBusinessDocumentHeader>
<svs:SovosDocument>
<svs:SovosLegalDocument>
<enc:Base64Document>
<enc:EmbeddedDocument id="1" fileName="invoice.xml" mimeCode="application/xml">PD94bWwgdmVyc...FrdHVyYT4NCg==</enc:EmbeddedDocument>
</enc:Base64Document>
</svs:SovosLegalDocument>
</svs:SovosDocument>
</svs:StandardBusinessDocument>
Supported document types for the local format (XML) document:
- Sales (TipoFactura)
-
-
F1 - Invoice (art. 6, 7.2, and 7.3 of RD 1619/2012)
-
F2 - Simplified invoice and invoices without identification of the recipient (art. 6.1.d of RD 1619/2012)
-
F3 - Invoice issued to replace simplified invoices issued and filed
-
F4 - Invoice summary entry
-
R1 - Corrected Invoice (error based on law and art. 80 One, Two, and Six LIVA)
-
R2 - Corrected invoice (art. 80.3)
-
R3 - Corrected invoice (art. 80.4)
-
R4 - Corrected invoice (other)
-
R5 - Corrected invoice in simplified invoices
-
AJ - Profit margin adjustment
Note:If
TipoComunicacionis "A5" or "A6", theTipoFacturafield must be "F1".
-
- Purchases (TipoFactura)
-
-
F1 - Invoice (art. 6, 7.2, and 7.3 of RD 1619/2012)
-
F2 - Simplified invoice and invoices without identification of the recipient (art. 6.1.d of RD 1619/2012)
-
F3 - Invoice issued to replace simplified invoices issued and filed
-
F4 - Invoice summary entry
-
F5 - Imports (DUA)
-
F6 - Accounting support material
-
R1 - Corrected invoice (error based on law and art. 80 One, Two, and Six LIVA)
-
R2 - Corrected invoice (art. 80.3)
-
R3 - Corrected invoice (art. 80.4)
-
R4 - Corrected invoice (other)
-
R5 - Corrected invoice in simplified invoices
-
LC - Customs - complementary settlement
-
- Intracommunity Supply, Consignment Sales (TipoOperacion)
-
-
-
01 - Issuance
-
02 - Replacement of the initial addressee
-
03 - Delivery to the initial recipient or substitute
-
04 - Delivery different recip. Initial or substitute
-
05 - Issue to another country
-
06 - Destruction, loss, theft
-
07 - Return to TAI
-
08 - 12-month period elapses without acquisition by the initial or substitute consignee
-
09 - Receipt
-
10 - Acquisition
-
11 - Withdrawal of goods by the seller
-
12 - Destruction or disappearance
-
-
Include all the mandatory nodes, as specified in the SBDH schema. If the information cannot be provided, and the respective mandatory 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. In addition, there's a full sample of the SBD on the Postman Samples page.
<sbd:StandardBusinessDocument xmlns="http://uri.etsi.org/01903/v1.4.1#" xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" xmlns:sbd="http://www.unece.org/cefact/namespaces/StandardBusinessDocumentHeader" 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:ext="urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2" xmlns:inv="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"> <sbd:StandardBusinessDocumentHeader> <sbd:HeaderVersion>1.0</sbd:HeaderVersion> <sbd:Sender> <sbd:Identifier Authority="ES">YOUR-TAXID</sbd:Identifier> <sbd:ContactInformation> <sbd:Contact>YOUR-TAXID</sbd:Contact> <sbd:EmailAddress/> <sbd:FaxNumber/> <sbd:TelephoneNumber/> <sbd:ContactTypeIdentifier/> </sbd:ContactInformation> </sbd:Sender> <sbd:Receiver> <sbd:Identifier Authority="ES"/> <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>2022-06-16T00:31:52Z</sbd:CreationDateAndTime> </sbd:DocumentIdentification> <sbd:BusinessScope> <sbd:Scope> <sbd:Type>Version</sbd:Type> <sbd:InstanceIdentifier/> <sbd:Identifier>1.0</sbd:Identifier> </sbd:Scope> <sbd:Scope> <sbd:Type>SenderDocumentId</sbd:Type> <sbd:InstanceIdentifier/> <sbd:Identifier>DOCUMENT-ID</sbd:Identifier> </sbd:Scope> <sbd:Scope> <sbd:Type>SenderSystemId</sbd:Type> <sbd:InstanceIdentifier/> <sbd:Identifier>SENDER-SYSTEM-ID</sbd:Identifier> </sbd:Scope> <sbd:Scope> <sbd:Type>CompanyCode</sbd:Type> <sbd:InstanceIdentifier/> <sbd:Identifier>YOUR-TAXID</sbd:Identifier> </sbd:Scope> <sbd:Scope> <sbd:Type>Country</sbd:Type> <sbd:InstanceIdentifier/> <sbd:Identifier>ES</sbd:Identifier> </sbd:Scope> <sbd:Scope> <sbd:Type>ProcessType</sbd:Type> <sbd:InstanceIdentifier/> <sbd:Identifier>Outbound</sbd:Identifier> </sbd:Scope> <sbd:Scope> <sbd:Type>Mapping.TransformDocument</sbd:Type> <sbd:InstanceIdentifier/> <sbd:Identifier>SCI-TO-LEGAL_INVOICE</sbd:Identifier> </sbd:Scope> <sbd:Scope> <sbd:Type>Mapping.OutputSchema</sbd:Type> <sbd:InstanceIdentifier/> <sbd:Identifier>SuministroLRFacturasEmitidas</sbd:Identifier> </sbd:Scope> <sbd:Scope> <sbd:Type>SubSchema</sbd:Type> <sbd:InstanceIdentifier/> <sbd:Identifier>Mainland / Bizkaia / Gipuzkoa</sbd:Identifier> </sbd:Scope> <sbd:Scope> <sbd:Type>BusinessCategory</sbd:Type> <sbd:InstanceIdentifier/> <sbd:Identifier>B2B</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 Elements* </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:
| Name | Type | Required | Description |
|---|---|---|---|
| data | string | Yes | The SBD encoded in Base64, as created in step 1. |
| dataEncoding | string | Yes | Enter "base64". |
- 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
-
{ "status": 202, "message": "Accepted", "success": true, "timestamp": 1686579755320, "data": { "transactionId": "d799d405-...-43f2d9cf4e67", "documentId": "3de...26c" } }
Step 3: Sovos maps the SCI into XML
This step will be skipped if the SBD contains the invoice in the local format (XML).
Step 4: Sovos performs the schema validation
Sovos performs a schema validation based on the information provided by the tax authority. If there are errors in the document, Sovos detects them instead of waiting for the tax authority's response.
Step 5: Sovos transmits the XML
Sovos transmits the XML file to the tax authority.
Requests are sent in batches over time. The batch service waits for either 10000 (1000 for LROE TBAI chapter 1.1) documents to be uploaded or one hour to pass before sending everything. In UAT, the batch service timeout is one minute.
Step 6: Tax authority processes the XML
The tax authority performs a schema validation and several business validations. Then it generates an approval or rejection response message along with an error message, where applicable.
Step 7: Tax authority sends the response to Sovos
After performing its services, the tax authority sends the response to Sovos.
Step 8: Supplier retrieves the application responses
- Attachments configuration
- Sovos highly recommends configuring your application response attachments as download links instead of base64-encoded data to avoid potential size limitations when retrieving responses. The default option is "download links".Note:
When you use "download links", the response contains a URL to download the file. When you use "binary data", the file is embedded in the base64-encoded response. This configuration is available through the 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 the cleared XML encoded in Base64 after it's available during the process.
Additionally, you must consider the following details included in the response:
- Transmission message
- It maps to the
SCIGovtStatusCodeandStatusReasonelements in the response message, as described in the application responses documentation, which details any warnings or additional notes to consider. The tax authority doesn't define any specific set of rules about what action to take on each error. Depending on the type of message, the user may have to modify the invoice, take some additional action, or simply make a note for the future.
Options for retrieving application responses (notifications):
- Fetch everything in one single response (notification)
- When polling for responses, Sovos only returns one final notification with
SCICloudStatusCodeof 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
SCICloudStatusCodevalues containing different attachments and data until the final one (with status 209) is returned. Detailed description follows.
To configure notifications for your company or update your current configuration, contact the Professional Services team.
To complete a transaction, the supplier 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 the SCIResponseCode value. Possible values for SCIResponseCode:
- AP
- The document's compliance status has been accepted with all the necessary attachments and data included.
- RE
- The document's compliance status has been rejected, and more parsing is needed:
-
If
SCIGovtStatusCodeis present, the error can be found by readingStatusReason. -
if
SCIInternalValidationCodeis present, the error can be found by readingStatusReason.
-
| # | SCICloudStatusCode | SCIResponseCode | Sample |
|---|---|---|---|
| 1 | 209 | AP |
|
| 2 | 209 | RE |
|
To complete a transaction, the supplier must retrieve the application responses until the transaction has finished. If the supplier has subscribed to all notifications, the transaction can generate different application responses. See the table below:
| # | SCICloudStatusCode | SCIResponseCode | Sample |
|---|---|---|---|
| 1 | 100 | IP |
|
| 2 | 101 | IP |
|
| 3 | 200 | AP |
|
| 4 | 209 | AP |
|
| 5 | 400 | RE |
|
| 6 | 401 | RE |
|
The transaction finishes when you receive a notification containing SCICloudStatusCode with the value of 209.
SCICloudStatusCode with a value in the 5xx range still remains an option because it indicates a server error. In this case, the workflow doesn't finish in the sense that it doesn't return a notification with SCICloudStatusCode of 209.The supplier can use the following Indirect Tax API endpoints to retrieve application responses:
-
GET /notifications/ES
-
GET /documents/ES/{documentId}/notifications
- GET /notifications/ES
- The supplier can send a GET request to the /notifications/ES 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 theCompanyCodeset 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 SenderSystemIdin the SBDH.includeAcknowledged boolean No false Enter "true" to specify whether previously acknowledged notifications, within 24 hours of their acknowledgment, must be included in the result. processType string No Enter "0" to only include notifications related to outbound documents. - Request sample
-
curl --location --request GET 'https://api-test.sovos.com/v1/notifications/ES?page=1&perPage=2&taxId={taxId}&sourceSystemId={sourceSystemId}&processType=0' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer TOKEN' --header 'x-correlationId: SET-TO-UNIQUE-VALUE' \ - Response sample
-
{ "status": 200, "message": "Notifications Listed", "success": true, "timestamp": 0, "data": { "pageState": { "page": 1, "perPage": 20, "totalEntries": 1, "totalPages": 1 }, "notifications": [ { "notificationId": "6385272d-...-e35e80b3b8e7", "correlationId": "rrt-...-1", "appPrefix": "DLT", "metadata": { "productId": "es_SuministroLRFacturasEmitidas_Mainland_1.0", "transactionId": "25c40e96-...-b67f8c5e215b", "documentId": "DOCUMENT-ID", "erpDocumentId": "ERP-DOCUMENT-ID", "erpSystemId": "SystemERP", "processType": "0", "taxId": "YOUR-TAXID", "sciCloudStatusCode": "101", "sciResponseCode": "IP", "sciStatusAction": "NOA" }, "content": "PD...2U+", "createdDate": 1686579756 } ] } }
- GET /documents/ES/{documentId}/notifications
- The supplier can send a GET request to the /documents/ES/{documentId}/notifications endpoint to retrieve application responses related to a single document. To make this request, set the following path parameter:
Name Type Required Default Description documentId string Yes The ID of the document returned in step 2 - Request sample
-
curl --location --request GET 'https://api-test.sovos.com/v1/documents/ES/{documentId}/notifications' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer TOKEN' \ --header 'x-correlationId: SET-TO-UNIQUE-VALUE' - Response sample
-
{ "status": 200, "message": "Notifications Listed", "success": true, "timestamp": 0, "data": { "pageState": { "page": 1, "perPage": 20, "totalEntries": 1, "totalPages": 1 }, "notifications": [ { "notificationId": "6385272d-...-e35e80b3b8e7", "correlationId": "rrt-...-1", "appPrefix": "DLT", "metadata": { "productId": "es_SuministroLRFacturasEmitidas_Mainland_1.0", "transactionId": "25c40e96-...-b67f8c5e215b", "documentId": "DOCUMENT-ID", "erpDocumentId": "ERP-DOCUMENT-ID", "erpSystemId": "SystemERP", "processType": "0", "taxId": "YOUR-TAXID", "sciCloudStatusCode": "101", "sciResponseCode": "IP", "sciStatusAction": "NOA" }, "content": "PD...2U+", "createdDate": 1686579756 } ] } }
Step 9: 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/ES endpoint.
To make this request, set the following request body parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| status | string | Yes | Enter "read". |
| notificationId | string | Yes | The ID of the notification that must be marked as acknowledged. |
notificationId values can be acknowledged in one Indirect Tax API call by including them in a single request.- Request sample
-
curl --location --request PUT 'https://api-test.sovos.com/v1/notifications/ES' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer TOKEN' \ --header 'x-correlationId: SET-TO-UNIQUE-VALUE' \ --data-raw '[ { "status": "read", "notificationId": "51341d39-...-a73d73e0de76" } ]' - Response sample
-
{ "status": 200, "message": "OK", "success": true, "timestamp": 1657019349646, "data": {} }
Step 10: Supplier sends the invoice to the buyer
The supplier must design a solution that caters to the preferred business processes for delivering the invoice to the buyer, as this is outside the scope of Sovos.
Cancel invoice (SII)
The following diagram provides a detailed overview of the invoice cancellation process in Spain (SII):
Step 1: Supplier sends a POST request to Sovos
When the supplier wants to cancel an invoice in Spain, they send a POST request to the /documents/ES/action endpoint. To make this request, set the following request body parameters:
| Name | Type | Required | Description | ||
|---|---|---|---|---|---|
| actionCode | string | Yes | Enter "document.cancellation". | ||
| documents | array of objects | Yes | An array of objects to include the metadata and the document ID. | ||
| metadata | object | No | An object that includes the required metadata. | ||
| reason | string | No | The reason for canceling the invoice. The max length is 100 characters. | ||
| documentId | string | Yes | The documentId retrieved when the document was originally submitted. | ||
- Request sample
-
curl --location --request POST 'https://api-test.sovos.com/v1/documents/ES/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 transmits the request
Sovos transmits the cancellation request to the tax authority.
Step 3: Tax authority processes the cancellation
The tax authority processes the cancellation and generates an acceptance or rejection message.
Step 4: Tax authority returns the response
The tax authority returns a success or error message to Sovos.
Step 5: Supplier retrieves the application responses
- Attachments configuration
- Sovos highly recommends configuring your application response attachments as download links instead of base64-encoded data to avoid potential size limitations when retrieving responses. The default option is "download links".Note:
When you use "download links", the response contains a URL to download the file. When you use "binary data", the file is embedded in the base64-encoded response. This configuration is available through the Professional Services team.
As a response to the initial request, 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 include an 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. If the supplier has subscribed to all notifications, the transaction can generate different application responses. See the table below:
| # | SCICloudStatusCode | SCIResponseCode | Sample |
|---|---|---|---|
| 1 | 101 | IP |
|
| 2 | 201 | AP |
|
| 3 | 209 | AP |
|
| 4 | 400 | RE |
|
The supplier can use the following Indirect Tax API endpoints to retrieve application responses:
-
GET /notifications/ES
-
GET /documents/ES/{documentId}/notifications
- GET /notifications/ES
- The supplier can send a GET request to the /notifications/ES 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 theCompanyCodeset 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 SenderSystemIdin the SBDH.includeAcknowledged boolean No false Enter "true" to specify whether previously acknowledged notifications must be included in the result. processType string No Enter "0" to only include notifications related to outbound documents. - Request sample
-
curl --location --request GET 'https://api-test.sovos.com/v1/notifications/ES?page=1&perPage=2&taxId={taxId}&sourceSystemId={sourceSystemId}&processType=0' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer TOKEN' \ --header 'x-correlationId: SET-TO-UNIQUE-VALUE' - Response sample
-
{ "status": 200, "message": "Notifications Listed", "success": true, "timestamp": 0, "data": { "pageState": { "page": 1, "perPage": 20, "totalEntries": 1, "totalPages": 1 }, "notifications": [ { "notificationId": "4f68d990-...-0bfb0a7f28af", "correlationId": "rrt-...-2547795-1", "appPrefix": "DLT", "metadata": { "productId": "es_SuministroLRFacturasEmitidas_Mainland_1.0", "transactionId": "725b6612-...-1183fde4c4b0", "documentId": "DOCUMENT-ID", "erpDocumentId": "ERP-DOCUMENT-ID", "erpSystemId": "SystemERP", "processType": "0", "taxId": "YOUR-TAXID", "sciCloudStatusCode": "200", "sciResponseCode": "AP", "sciStatusAction": "NOA", "sciGovtStatusCode": "Success" }, "content": "PD...T4=", "createdDate": 1686579784 } ] } }
- GET /documents/ES/{documentId}/notifications
- The supplier can send a GET request to the /documents/ES/{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/ES/{documentId}/notifications?includeAcknowledged=false' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer TOKEN' \ --header 'x-correlationId: SET-TO-UNIQUE-VALUE' - Response sample
-
{ "status": 200, "message": "Notifications Listed", "success": true, "timestamp": 0, "data": { "pageState": { "page": 1, "perPage": 20, "totalEntries": 1, "totalPages": 1 }, "notifications": [ { "notificationId": "4f68d990-...-0bfb0a7f28af", "correlationId": "rrt-...-2547795-1", "appPrefix": "DLT", "metadata": { "productId": "es_SuministroLRFacturasEmitidas_Mainland_1.0", "transactionId": "725b6612-...-1183fde4c4b0", "documentId": "DOCUMENT-ID", "erpDocumentId": "ERP-DOCUMENT-ID", "erpSystemId": "SystemERP", "processType": "0", "taxId": "YOUR-TAXID", "sciCloudStatusCode": "200", "sciResponseCode": "AP", "sciStatusAction": "NOA", "sciGovtStatusCode": "Success" }, "content": "PD...T4=", "createdDate": 1686579784 } ] } }
Step 6: 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/ES endpoint.
To make this request, set the following request body parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| status | string | Yes | Enter "read". |
| notificationId | string | Yes | The ID of the notification that must be marked as acknowledged. |
notificationId values can be acknowledged in one Indirect Tax API call by including them in a single request.- Request sample
-
curl --location --request PUT 'https://api-test.sovos.com/v1/notifications/ES' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer TOKEN' \ --header 'x-correlationId: SET-TO-UNIQUE-VALUE' \ --data-raw '[ { "status": "read", "notificationId": "51341d39-...-a73d73e0de76" } ]' - Response sample
-
{ "status": 200, "message": "OK", "success": true, "timestamp": 1657019349646, "data": {} }
Issue certified eInvoice (TicketBAI)
The process for issuing a certified eInvoice in the province of Biscay (Spain) is based on the Default business process. The following diagram provides a detailed overview:
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 the SovosLegalDocument node that must include the FacturaE. To create the SBD, follow the detailed instructions in the SBDH and Sovos Document pages.
The most important elements within the SBD in which the supplier can use the local format (XML):
| Node | Required | Attributes | Value |
|---|---|---|---|
| StandardBusinessDocumentHeader.Sender.Identifier | Yes | Authority="ES" | Supplier's tax ID |
| StandardBusinessDocumentHeader.Receiver.Identifier | Yes | Authority="ES" | Buyer's tax ID |
| StandardBusinessDocumentHeader.DocumentIdentification.Standard | Yes | Ticketbai | |
| StandardBusinessDocumentHeader.DocumentIdentification.TypeVersion | Yes | 1.0 | |
| StandardBusinessDocumentHeader.DocumentIdentification.Type | Yes | Invoice | |
| StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes |
Child node Child node | |
| StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes |
Child node Child node | |
| StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes |
Child node Child node | |
| StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes |
Child node Child node | |
| StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes |
Child node Child node | |
| StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes |
Child node Child node | |
| StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes |
Child node Child node | |
| StandardBusinessDocumentHeader.BusinessScope.Scope.BusinessService.BusinessServiceName | Yes | Default | |
| SovosDocument.SovosLegalDocument | Yes | FacturaE |
Include all the mandatory nodes, as specified in the SBDH schema. If the information cannot be provided, and the respective mandatory 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. In addition, there's a full sample of the SBD on the Postman Samples page.
<?xml version="1.0" encoding="UTF-8"?> <StandardBusinessDocument xmlns="http://www.unece.org/cefact/namespaces/StandardBusinessDocumentHeader" xmlns:ad="http://www.sovos.com/namespaces/additionalData" xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" xmlns:enc="http://www.sovos.com/namespaces/base64Document" xmlns:ext="urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2" xmlns:sci="http://www.sovos.com/namespaces/sovosCanonicalInvoice" xmlns:sov="http://www.sovos.com/namespaces/sovosExtensions" xmlns:svs="http://www.sovos.com/namespaces/sovosDocument"> <StandardBusinessDocumentHeader> <HeaderVersion>1.0</HeaderVersion> <Sender> <Identifier Authority="ES">MY_TAXID</Identifier> <ContactInformation> <Contact>MY_COMPANY</Contact> </ContactInformation> </Sender> <Receiver> <Identifier Authority="ES">MY_TAX_ID</Identifier> <ContactInformation> <Contact>MY_ADMINISTRATOR</Contact> </ContactInformation> </Receiver> <DocumentIdentification> <Standard>Ticketbai</Standard> <TypeVersion>1.0</TypeVersion> <InstanceIdentifier /> <Type>Invoice</Type> <MultipleType>false</MultipleType> <CreationDateAndTime>2023-10-27T14:15:11Z</CreationDateAndTime> </DocumentIdentification> <BusinessScope> <Scope> <Type>Country</Type> <InstanceIdentifier /> <Identifier>ES</Identifier> </Scope> <Scope> <Type>Mapping.OutputSchema</Type> <InstanceIdentifier /> <Identifier>Ticketbai</Identifier> </Scope> <Scope> <Type>CompanyCode</Type> <InstanceIdentifier /> <Identifier>N0107861G</Identifier> </Scope> <Scope> <Type>SenderDocumentId</Type> <InstanceIdentifier /> <Identifier>BATUZ|20231027141511</Identifier> </Scope> <Scope> <Type>ProcessType</Type> <InstanceIdentifier /> <Identifier>Outbound</Identifier> </Scope> <Scope> <Type>SenderSystemId</Type> <InstanceIdentifier /> <Identifier>SystemERP</Identifier> </Scope> <Scope> <Type>Version</Type> <InstanceIdentifier /> <Identifier>1.0</Identifier> </Scope> <Scope> <Type>BusinessCategory</Type> <InstanceIdentifier /> <Identifier>B2B</Identifier> </Scope> <Scope> <Type>BusinessProcess</Type> <InstanceIdentifier /> <BusinessService> <BusinessServiceName>Default</BusinessServiceName> </BusinessService> </Scope> </BusinessScope> </StandardBusinessDocumentHeader> <svs:SovosDocument> <svs:SovosLegalDocument> <enc:Base64Document> *FacturaE Base64 encoded* </enc:Base64Document> </svs:SovosLegalDocument> </svs:SovosDocument> </StandardBusinessDocument>
Step 2: Supplier sends the SBD to Sovos
The supplier sends a POST request to the /documents endpoint.
The request must include the following request body parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| data | string | Yes | The SBD encoded in Base64, as created in step 1 |
| dataEncoding | string | Yes | Enter "base64" |
- 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": "3add2b7104dc0049ff0bf410f57e0a19afaf" } }
Step 3: Sovos performs validations
Sovos performs the necessary semantic, syntactic, and legal validations. In addition, we perform a schema validation to ensure the XML file conforms to the expected structure, comparing it with the official schema.
If we find any errors, we don't issue the invoices or generate the TicketBai files. We generate a negative response with the list of triggered validations.
Step 4: Mapping
Sovos implements the necessary mapping of the invoice values into the fields of the TicketBAI XML file.
Step 5: TicketBAI file Generation (Chaining, Signing)
Sovos transmits the XML file to the tax authority.
When the XML passes Sovos' validation, we create a TicketBAI XML file, which receives the TicketBAI signature policy with the proper digital certificate. A TicketBAI identifier along with a QR code is also generated to identify the resulting eInvoice FacturaE or PDF file. A chaining process is created on the TicketBAI XML file, where it identifies the last-issued invoice and that invoice is included in the file.
Step 6: FacturaE
Sovos generates an eInvoice called FacturaE in a structured format for visualization. Following Biscay's regulations, it includes the TicketBAI ID.
Step 7: PDF generation
Sovos generates an eInvoice in a readable format (PDF). Following Biscay's regulations, it includes a QR-code and the TicketBAI ID.
Step 8: Supplier retrieves the application responses
- Attachments configuration
- Sovos highly recommends configuring your application response attachments as download links instead of base64-encoded data to avoid potential size limitations when retrieving responses. The default option is "download links".Note:
When you use "download links", the response contains a URL to download the file. When you use "binary data", the file is embedded in the base64-encoded response. This configuration is available through the 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 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. A successful transaction will generate five application responses, as shown in the table below:
| # | SCICloudStatusCode | SCIResponseCode | Sample |
|---|---|---|---|
| 1 | 200 | AP |
|
| 2 | 201 | RE |
|
| 3 | 400 | RE |
|
The supplier can use the following Indirect Tax API endpoints to retrieve application responses:
-
GET /notifications/ES
-
GET /documents/ES/{documentId}/notifications
- GET /notifications/ES
- The supplier can send a GET request to the /notifications/ES 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 theCompanyCodeset 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 SenderSystemIdin the SBDH.includeAcknowledged boolean No false Enter "true" to specify whether previously acknowledged notifications must be included in the result. includeBinaryData boolean No false Enter "true" to include the binary data of the XML and PDF in the application response. processType string No Enter "0" to only include notifications related to outbound documents. - Request sample
-
curl --location --request GET 'https://api-test.sovos.com/v1/notifications/ES?page=1&perPage=2&taxId={taxId}&sourceSystemId={sourceSystemId}&processType=0' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer TOKEN' \ --header 'x-correlationId: SET-TO-UNIQUE-VALUE' - Response sample
-
{ "status": 200, "message": "Notifications Listed", "success": true, "timestamp": 1698772220010, "data": { "pageState": { "page": 1, "perPage": 20, "totalEntries": 1, "totalPages": 1 }, "notifications": [ { "notificationId": "6385272d-...-e35e80b3b8e7", "correlationId": "rrt-...-1", "appPrefix": "sph", "metadata": { "productId": "es_temp_ticketbai_1.0", "documentId": "DOCUMENT-ID", "erpDocumentId": "ERP-DOCUMENT-ID", "erpSystemId": "SystemERP", "processType": "0", "taxId": "YOUR-TAXID", "sciCloudStatusCode": "200", "sciResponseCode": "AP", "sciStatusAction": "NOA" }, "content": "PD...2U+", "createdDate": 1698763380865 } ] } }
- GET /documents/ES/{documentId}/notifications
- The supplier can send a GET request to the /documents/ES/{documentId}/notifications endpoint to retrieve application responses related to a single document. To make this request, set the following path parameter:
Name Type Required Parameter type Default Description documentId string Yes Path The document ID returned in step 2 includeAcknowledged boolean No Query false Enter "true" to specify whether previously acknowledged notifications must be included in the result. includeBinaryData boolean No Query false Enter "true" to include the binary data of the XML and PDF in the application response. - Request sample
-
curl --location --request GET 'https://api-test.sovos.com/v1/documents/ES/{documentId}/notifications?includeAcknowledged=true' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer TOKEN' \ --header 'x-correlationId: SET-TO-UNIQUE-VALUE' - Response sample
-
{ "status": 200, "message": "Notifications Listed", "success": true, "timestamp": 1698772220010, "data": { "pageState": { "page": 1, "perPage": 20, "totalEntries": 1, "totalPages": 1 }, "notifications": [ { "notificationId": "6385272d-...-e35e80b3b8e7", "correlationId": "rrt-...-1", "appPrefix": "sph", "metadata": { "productId": "es_temp_ticketbai_1.0", "documentId": "DOCUMENT-ID", "erpDocumentId": "ERP-DOCUMENT-ID", "erpSystemId": "SystemERP", "processType": "0", "taxId": "YOUR-TAXID", "sciCloudStatusCode": "200", "sciResponseCode": "AP", "sciStatusAction": "NOA" }, "content": "PD...2U+", "createdDate": 1698763380865 } ] } }
Step 9: 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/ES endpoint.
To make this request, set the following request body parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| status | string | Yes | Enter "read". |
| notificationId | string | Yes | The ID of the notification that must be marked as acknowledged. |
notificationId values can be acknowledged in one Indirect Tax API call by including them in a single request.- Request sample
-
curl --location --request PUT 'https://api-test.sovos.com/v1/notifications/ES' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer TOKEN' \ --header 'x-correlationId: SET-TO-UNIQUE-VALUE' \ --data-raw '[ { "status": "read", "notificationId": "51341d39-...-a73d73e0de76" } ]' - Response sample
-
{ "timestamp": 1601673284, "status": 200, "success": true, "message": "Notifications acknowledged successfully." }
Step 10: Supplier sends the invoice to the buyer
As the final step, the supplier should send the TicketBAI invoice (FacturaE or PDF) to the buyer using an agreed-upon channel. This process is outside the scope of Sovos.
Cancel invoice (TicketBAI)
Canceling an invoice in the province of Biscay (Spain) is based on the Default business process. The following diagram provides a detailed overview:
Step 1: Supplier sends a POST request to Sovos
When the supplier wants to cancel an invoice in Biscay, they send a POST request to the /documents/ES/action endpoint. To make this request, set the following request body parameters:
| Name | Type | Required | Description | ||
|---|---|---|---|---|---|
| actionCode | string | Yes | Enter "document.cancellation". | ||
| documents | array of objects | Yes | An array of objects to include the metadata and the document ID. | ||
| metadata | object | No | An object that includes the required metadata. | ||
| reason | string | No | The reason for canceling the invoice. The max length is 100 characters. | ||
| reasonCode | string | No | The reason code for the cancellation. | ||
| companyId | string | No | The customer's tax ID. | ||
| documentType | string | No | Enter "MESSAGE_STATUS". | ||
| documentNumber | string | No | The number of the document/invoice. | ||
| documentPrefix | string | No | The prefix of the document. | ||
| documentDate | string | No | The date of the document. | ||
| documentId | string | Yes | The documentId retrieved when the document was originally submitted. | ||
- Request sample
-
curl --location --request POST 'https://api-test.sovos.com/v1/documents/ES/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": "Faulty document data", "reasonCode": "1", "companyId": "TAX_ID", "documentType": "MESSAGE_STATUS", "documentNumber": "DOCUMENT_NUMBER", "documentPrefix": "SVS", "documentDate": "01-01-2022" }, "documentId": "b91...f3" } ] }' - Response sample
-
{ "status": 202, "message": "Document Received", "success": true, "timestamp": 1686579755320, "data": { "documentId": "3de...26c" } }
Step 2: Validation
Sovos performs the necessary semantic, syntactic, and legal validations. In addition, we perform a schema validation to make sure that the XML file conforms to the expected structure, comparing it with the official schema.
In case Sovos finds errors, we don't issue the invoices or generate the TicketBai files. We generate a negative response including a list of all failed validations.
Step 3: Mapping
Sovos implements the necessary mapping of the invoice values into the fields of the TicketBAI XML cancellation file.
Step 4: Anula TicketBAI file generation
The Sovos TicketBAI cancellation process generates an Anula TicketBAI XML file containing the cancellation action. Then we sign this file digitally, according to the Batuz TicketBAI requirements.
Step 5: Supplier retrieves the application responses
- Attachments configuration
- Sovos highly recommends configuring your application response attachments as download links instead of base64-encoded data to avoid potential size limitations when retrieving responses. The default option is "download links".Note:
When you use "download links", the response contains a URL to download the file. When you use "binary data", the file is embedded in the base64-encoded response. This configuration is available through the Professional Services team.
As a response to the initial request, 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 include an 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. A successful transaction will generate five application responses, as shown in the table below:
| # | SCICloudStatusCode | SCIResponseCode | Sample |
|---|---|---|---|
| 1 | 200 | AP |
|
| 2 | 201 | RE |
|
| 3 | 400 | RE |
|
The supplier can use the following Indirect Tax API endpoints to retrieve application responses:
-
GET /notifications/ES
-
GET /documents/ES/{documentId}/notifications
- GET /notifications/ES
- The supplier can send a GET request to the /notifications/ES 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 theCompanyCodeset 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 SenderSystemIdin the SBDH.includeAcknowledged boolean No false Enter "true" to specify whether previously acknowledged notifications must be included in the result. includeBinaryData boolean No false Enter "true" to include the binary data of the XML and PDF in the application response. processType string No Enter "0" to only include notifications related to outbound documents. - Request sample
-
curl --location --request GET 'https://api-test.sovos.com/v1/notifications/ES?page=1&perPage=2&taxId={taxId}&sourceSystemId={sourceSystemId}&processType=0' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer TOKEN' \ --header 'x-correlationId: SET-TO-UNIQUE-VALUE' - Response sample
-
{ "status": 200, "message": "Notifications Listed", "success": true, "timestamp": 1698772220010, "data": { "pageState": { "page": 1, "perPage": 20, "totalEntries": 1, "totalPages": 1 }, "notifications": [ { "notificationId": "6385272d-...-e35e80b3b8e7", "correlationId": "rrt-...-1", "appPrefix": "sph", "metadata": { "productId": "es_temp_ticketbai_1.0", "documentId": "DOCUMENT-ID", "erpDocumentId": "ERP-DOCUMENT-ID", "erpSystemId": "SystemERP", "processType": "0", "taxId": "YOUR-TAXID", "sciCloudStatusCode": "201", "sciResponseCode": "RE", "sciStatusAction": "NOA" }, "content": "PD...2U+", "createdDate": 1698763380865 } ] } }
- GET /documents/ES/{documentId}/notifications
- The supplier can send a GET request to the /documents/ES/{documentId}/notifications endpoint to retrieve application responses related to a single document. To make this request, set the following parameters:
Name Type Required Parameter type Default Description documentId string Yes Path The document ID returned in step 1 includeAcknowledged boolean No Query false Enter "true" to specify whether previously acknowledged notifications must be included in the result. includeBinaryData boolean No Query false Enter "true" to include the binary data of the XML and PDF in the application response. - Request sample
-
curl --location --request GET 'https://api-test.sovos.com/v1/documents/ES/{documentId}/notifications?includeAcknowledged=true' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer TOKEN' \ --header 'x-correlationId: SET-TO-UNIQUE-VALUE' - Response sample
-
{ "status": 200, "message": "Notifications Listed", "success": true, "timestamp": 1698772220010, "data": { "pageState": { "page": 1, "perPage": 20, "totalEntries": 1, "totalPages": 1 }, "notifications": [ { "notificationId": "6385272d-...-e35e80b3b8e7", "correlationId": "rrt-...-1", "appPrefix": "sph", "metadata": { "productId": "es_temp_ticketbai_1.0", "documentId": "DOCUMENT-ID", "erpDocumentId": "ERP-DOCUMENT-ID", "erpSystemId": "SystemERP", "processType": "0", "taxId": "YOUR-TAXID", "sciCloudStatusCode": "201", "sciResponseCode": "RE", "sciStatusAction": "NOA" }, "content": "PD...2U+", "createdDate": 1698763380865 } ] } }
Step 6: 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/ES endpoint.
To make this request, set the following request body parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| status | string | Yes | Enter "read". |
| notificationId | string | Yes | The ID of the notification that must be marked as acknowledged. |
notificationId values can be acknowledged in one Indirect Tax API call by including them in a single request.- Request sample
-
curl --location --request PUT 'https://api-test.sovos.com/v1/notifications/ES' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer TOKEN' \ --header 'x-correlationId: SET-TO-UNIQUE-VALUE' \ --data-raw '[ { "status": "read", "notificationId": "51341d39-...-a73d73e0de76" } ]' - Response sample
-
{ "timestamp": 1601673284, "status": 200, "success": true, "message": "Notifications acknowledged successfully." }
Report invoice (LROE)
Reporting invoices in Spain for the province of Biscay is based on the Default business process, which follows this order: Mapping and Transmission. This process involves reporting data on income, expenses, and other fiscally relevant information to LROE in a structured format.
The following diagram provides a detailed overview:
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.
The SBDH must be created using the following common values when issuing a document in the local format:
| Node | Required | Attributes | Value |
|---|---|---|---|
| StandardBusinessDocumentHeader.Sender.Identifier | Yes | Authority="ES" | Supplier's NIF |
| StandardBusinessDocumentHeader.Receiver.Identifier | Yes | Authority="ES" | |
| StandardBusinessDocumentHeader.DocumentIdentification.Standard | Yes | See the scenarios table below | |
| StandardBusinessDocumentHeader.DocumentIdentification.TypeVersion | Yes | See the scenarios table below | |
| StandardBusinessDocumentHeader.DocumentIdentification.Type | Yes | See the scenarios table below | |
| StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes |
Child node Child node | |
| StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes |
Child node Child node | |
| StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes |
Child node Child node | |
| StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes |
Child node Child node | |
| StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes |
Child node Child node | |
| StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes |
Child node Child node | |
| StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes |
Child node Child node | |
| StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes |
Child node Child node | |
| StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes |
Child node Child node | |
| StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes |
Child node Child node | |
| StandardBusinessDocumentHeader.BusinessScope.Scope.BusinessService.BusinessServiceName | Yes | Default | |
| SovosDocument.SovosLegalDocument.Base64Document | Yes | A local format |
You need to encode the local format (XML) document in Base64 before you can add it as part of the SBD. Here is a sample:
</sbd:StandardBusinessDocumentHeader>
<svs:SovosDocument>
<svs:SovosLegalDocument>
<enc:Base64Document>
<enc:EmbeddedDocument id="1" fileName="invoice.xml" mimeCode="application/xml">PD94bWwgdmVyc...FrdHVyYT4NCg==</enc:EmbeddedDocument>
</enc:Base64Document>
</svs:SovosLegalDocument>
</svs:SovosDocument>
</svs:StandardBusinessDocument>
To configure the SBDH for each supported scenario, look for the corresponding fields in this table:
| Node | Required | Value |
|---|---|---|
| StandardBusinessDocumentHeader.DocumentIdentification.Standard | Yes for LROE Invoices issued with the guarantor software | https://www.batuz.eus/fitxategiak/batuz/LROE/esquemas/LROE_PJ_240_1_1_FacturasEmitidas_ConSG_AltaPeticion_V1_0_2.xsd |
| StandardBusinessDocumentHeader.DocumentIdentification.Standard | Yes for LROE Invoices issued without the guarantor software | https://www.batuz.eus/fitxategiak/batuz/LROE/esquemas/LROE_PJ_240_1_2_FacturasEmitidas_SinSG_AltaModifPeticion_V1_0_1.xsd |
| StandardBusinessDocumentHeader.DocumentIdentification.Standard | Yes for LROE Received Invoices | https://www.batuz.eus/fitxategiak/batuz/LROE/esquemas/LROE_PJ_240_2_FacturasRecibidas_AltaModifPeticion_V1_0_1.xsd |
| StandardBusinessDocumentHeader.DocumentIdentification.Standard | Yes for LROE Operaciones Intracomunitarias - Export and Transfers | https://www.batuz.eus/fitxategiak/batuz/LROE/esquemas/LROE_PJ_240_4_1_DeterminadasOpIntracomunitarias_TransfPericialesOtros_AltaModifPeticion_V1_0_2.xsd |
| StandardBusinessDocumentHeader.DocumentIdentification.Standard | Yes for LROE Otra Información - Operaciones de seguros | https://www.batuz.eus/fitxategiak/batuz/LROE/esquemas/LROE_PJ_240_6_2_OtraInfoTrascTributaria_OperacionesSeguros_AltaModifPeticion_V1_0_0.xsd |
| StandardBusinessDocumentHeader.DocumentIdentification.TypeVersion | Yes for LROE Invoices issued with the guarantor software | 1.0.2 |
| StandardBusinessDocumentHeader.DocumentIdentification.TypeVersion | Yes for LROE Operaciones Intracomunitarias - Export and Transfers | 1.0.2 |
| StandardBusinessDocumentHeader.DocumentIdentification.TypeVersion | Yes for LROE Invoices issued without the guarantor software | 1.0.1 |
| StandardBusinessDocumentHeader.DocumentIdentification.TypeVersion | Yes for LROE Received Invoices | 1.0.1 |
| StandardBusinessDocumentHeader.DocumentIdentification.TypeVersion | Yes for LROE Otra Información - Operaciones de seguros | 1.0 |
| StandardBusinessDocumentHeader.DocumentIdentification.Type | Yes for LROE Invoices issued with the guarantor software | LROEPJ240FacturasEmitidasConSGAltaPeticion |
| StandardBusinessDocumentHeader.DocumentIdentification.Type | Yes for LROE Invoices issued without the guarantor software | LROEPJ240FacturasEmitidasSinSGAltaModifPeticion |
| StandardBusinessDocumentHeader.DocumentIdentification.Type | Yes for LROE Received Invoices | LROEPJ240FacturasRecibidasAltaModifPeticion |
| StandardBusinessDocumentHeader.DocumentIdentification.Type | Yes for LROE Operaciones Intracomunitarias - Export and Transfers | LROEPJ240TransferenciasPericialesOtrosAltaModifPeticion |
| StandardBusinessDocumentHeader.DocumentIdentification.Type | Yes for LROE Otra Información - Operaciones de seguros | LROEPJ240OperacionesSegurosAltaModifPeticion |
| StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes for LROE Invoices issued with the guarantor software |
Child node Child node |
| StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes for LROE Invoices issued without the guarantor software |
Child node Child node |
| StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes for LROE Received Invoices |
Child node Child node |
| StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes for LROE Operaciones Intracomunitarias - Export and Transfers |
Child node Child node |
| AdditionalData (with fields) | Yes for LROE Invoices issued with the guarantor software | The AdditionalData node with the following fields: |
Unsupported scenarios:
-
LROE Investment Goods
-
LROE Operaciones Intracomunitarias - consignment goods
-
LROE Otra Información - greater amounts of 6000
-
LROE Otra Información - travel agencies
Supported document types for the local format (XML) document:
- Invoices issued (TipoFactura)
-
-
F1 - Invoice (art. 6, 7.2, and 7.3 of RD 1619/2012)
-
F2 - Simplified invoice and invoices without identification of the recipient (art. 6.1.d of RD 1619/2012)
-
F3 - Invoice issued to replace simplified invoices issued and filed
-
F4 - Invoice summary entry
-
R1 - Corrected invoice (error based on law and art. 80 One, Two, and Six LIVA)
-
R2 - Corrected invoice (art. 80.3)
-
R3 - Corrected invoice (art. 80.4)
-
R4 - Corrected invoice (other)
-
R5 - Corrected invoice in simplified invoices
-
AJ - Profit margin adjustment
Note:If
TipoComunicacionis "A5" or "A6", theTipoFacturafield must be "F1".
-
- Invoices received (TipoFactura)
-
-
F1 - Invoice (art. 6, 7.2, and 7.3 of RD 1619/2012)
-
F2 - Simplified invoice and invoices without identification of the recipient (art. 6.1.d of RD 1619/2012)
-
F3 - Invoice issued to replace simplified invoices issued and filed
-
F4 - Invoice summary entry
-
F5 - Imports (DUA)
-
F6 - Accounting support material
-
R1 - Corrected invoice (error based on law and art. 80 One, Two, and Six LIVA)
-
R2 - Corrected invoice (art. 80.3)
-
R3 - Corrected invoice (art. 80.4)
-
R4 - Corrected invoice (other)
-
R5 - Corrected invoice in simplified invoices
-
LC - Customs - complementary settlement
-
Include all the mandatory nodes, as specified in the SBDH schema. If the information cannot be provided, and the respective mandatory 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. In addition, there's a full sample of the SBD on the Postman Samples page.
<sbd:StandardBusinessDocument xmlns="http://uri.etsi.org/01903/v1.4.1#" xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" xmlns:sbd="http://www.unece.org/cefact/namespaces/StandardBusinessDocumentHeader" 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:ext="urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2" xmlns:inv="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"> <sbd:StandardBusinessDocumentHeader> <sbd:HeaderVersion>1.0</sbd:HeaderVersion> <sbd:Sender> <sbd:Identifier Authority="ES">YOUR-TAXID</sbd:Identifier> <sbd:ContactInformation> <sbd:Contact>YOUR-TAXID</sbd:Contact> <sbd:EmailAddress/> <sbd:FaxNumber/> <sbd:TelephoneNumber/> <sbd:ContactTypeIdentifier/> </sbd:ContactInformation> </sbd:Sender> <sbd:Receiver> <sbd:Identifier Authority="ES"/> <sbd:ContactInformation> <sbd:Contact/> <sbd:EmailAddress/> <sbd:FaxNumber/> <sbd:TelephoneNumber/> <sbd:ContactTypeIdentifier/> </sbd:ContactInformation> </sbd:Receiver> <sbd:DocumentIdentification> <sbd:Standard>[DEPENDS ON SCENARIO]</sbd:Standard> <sbd:TypeVersion>[DEPENDS ON SCENARIO]</sbd:TypeVersion> <sbd:InstanceIdentifier/> <sbd:Type>[DEPENDS ON SCENARIO]</sbd:Type> <sbd:MultipleType>false</sbd:MultipleType> <sbd:CreationDateAndTime>2022-06-16T00:31:52Z</sbd:CreationDateAndTime> </sbd:DocumentIdentification> <sbd:BusinessScope> <sbd:Scope> <sbd:Type>Version</sbd:Type> <sbd:InstanceIdentifier/> <sbd:Identifier>1.0</sbd:Identifier> </sbd:Scope> <sbd:Scope> <sbd:Type>SenderDocumentId</sbd:Type> <sbd:InstanceIdentifier/> <sbd:Identifier>DOCUMENT-ID</sbd:Identifier> </sbd:Scope> <sbd:Scope> <sbd:Type>SenderSystemId</sbd:Type> <sbd:InstanceIdentifier/> <sbd:Identifier>SENDER-SYSTEM-ID</sbd:Identifier> </sbd:Scope> <sbd:Scope> <sbd:Type>CompanyCode</sbd:Type> <sbd:InstanceIdentifier/> <sbd:Identifier>YOUR-TAXID</sbd:Identifier> </sbd:Scope> <sbd:Scope> <sbd:Type>Country</sbd:Type> <sbd:InstanceIdentifier/> <sbd:Identifier>ES</sbd:Identifier> </sbd:Scope> <sbd:Scope> <sbd:Type>ProcessType</sbd:Type> <sbd:InstanceIdentifier/> <sbd:Identifier>Outbound</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>[DEPENDS ON SCENARIO]</sbd:Identifier> </sbd:Scope> <sbd:Scope> <sbd:Type>SubSchema</sbd:Type> <sbd:InstanceIdentifier/> <sbd:Identifier>Batuz</sbd:Identifier> </sbd:Scope> <sbd:Scope> <sbd:Type>BusinessCategory</sbd:Type> <sbd:InstanceIdentifier/> <sbd:Identifier>B2B</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> <!--LEGAL FORMAT--> <svs:SovosLegalDocument> <enc:Base64Document> <enc:EmbeddedDocument id="1" fileName="name.xml" mimeCode="application/xml"> *Base64Document* </enc:EmbeddedDocument> </enc:Base64Document> </svs:SovosLegalDocument> <!--LEGAL FORMAT--> </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:
| Name | Type | Required | Description |
|---|---|---|---|
| data | string | Yes | The SBD encoded in Base64, as created in step 1. |
| dataEncoding | string | Yes | Enter "base64". |
- 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
-
{ "status": 202, "message": "Accepted", "success": true, "timestamp": 1686579755320, "data": { "transactionId": "d799d405-...-43f2d9cf4e67", "documentId": "3de...26c" } }
Step 3: Sovos maps the SCI into XML
This step will be skipped if the SBD contains the invoice in the local format (XML).
Step 4: Sovos performs the schema validation
Sovos performs a schema validation based on the information provided by the tax authority. If there are errors in the document, Sovos detects them instead of waiting for the tax authority's response.
Step 5: Sovos transmits the XML
Sovos transmits the XML file to the LROE.
Requests are sent in batches over time. The batch service waits for either 10000 (1000 for LROE TBAI chapter 1.1) documents to be uploaded or one hour to pass before sending everything. In UAT, the batch service timeout is one minute.
Step 6: LROE processes the XML
LROE performs a schema validation and several business validations. Then it generates an approval or rejection response message along with an error message, where applicable.
Step 7: LROE sends the response to Sovos
After performing its services, the LROE sends the response to Sovos.
Step 8: Supplier retrieves the application responses
- Attachments configuration
- Sovos highly recommends configuring your application response attachments as download links instead of base64-encoded data to avoid potential size limitations when retrieving responses. The default option is "download links".Note:
When you use "download links", the response contains a URL to download the file. When you use "binary data", the file is embedded in the base64-encoded response. This configuration is available through the 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 the cleared XML encoded in Base64 after it's available during the process.
Additionally, you must consider the following details included in the response:
- Transmission message
- It maps to the
SCIGovtStatusCodeandStatusReasonelements in the response message, as described in the application responses documentation, which details any warnings or additional notes to consider. The tax authority doesn't define any specific set of rules about what action to take on each error. Depending on the type of message, the user may have to modify the invoice, take some additional action, or simply make a note for the future.
To complete a transaction, the supplier must retrieve the application responses until the transaction has finished. If the supplier has subscribed to all notifications, the transaction can generate different application responses. See the table below:
| # | SCICloudStatusCode | SCIResponseCode | Sample |
|---|---|---|---|
| 1 | 100 | IP |
|
| 2 | 200 | AP |
|
| 3 | 209 | AP |
|
| 4 | 400 | RE |
|
| 5 | 401 | RE |
|
| 6 | 500 | RE | |
The supplier can use the following Indirect Tax API endpoints to retrieve application responses:
-
GET /notifications/ES
-
GET /documents/ES/{documentId}/notifications
- GET /notifications/ES
- The supplier can send a GET request to the /notifications/ES 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 theCompanyCodeset 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 SenderSystemIdin the SBDH.includeAcknowledged boolean No false Enter "true" to specify whether previously acknowledged notifications, within 24 hours of their acknowledgment, must be included in the result. processType string No Enter "0" to only include notifications related to outbound documents. - Request sample
-
curl --location --request GET 'https://api-test.sovos.com/v1/notifications/ES?page=1&perPage=2&taxId={taxId}&sourceSystemId={sourceSystemId}&processType=0' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer TOKEN' --header 'x-correlationId: SET-TO-UNIQUE-VALUE' \ - Response sample
-
{ "status": 200, "message": "Notifications Listed", "success": true, "timestamp": 0, "data": { "pageState": { "page": 1, "perPage": 20, "totalEntries": 1, "totalPages": 1 }, "notifications": [ { "notificationId": "6385272d-...-e35e80b3b8e7", "correlationId": "rrt-...-1", "appPrefix": "DLT", "metadata": { "productId": "es_LROEPJ240OperacionesSegurosAltaModifPeticion_Batuz_1.0", "transactionId": "25c40e96-...-b67f8c5e215b", "documentId": "DOCUMENT-ID", "erpDocumentId": "ERP-DOCUMENT-ID", "erpSystemId": "SystemERP", "processType": "0", "taxId": "YOUR-TAXID", "sciCloudStatusCode": "100", "sciResponseCode": "IP", "sciStatusAction": "NOA" }, "content": "PD...2U+", "createdDate": 1686579756 } ] } }
- GET /documents/ES/{documentId}/notifications
- The supplier can send a GET request to the /documents/ES/{documentId}/notifications endpoint to retrieve application responses related to a single document. To make this request, set the following path parameter:
Name Type Required Default Description documentId string Yes The document ID returned in step 2 - Request sample
-
curl --location --request GET 'https://api-test.sovos.com/v1/documents/ES/{documentId}/notifications' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer TOKEN' \ --header 'x-correlationId: SET-TO-UNIQUE-VALUE' - Response sample
-
{ "status": 200, "message": "Notifications Listed", "success": true, "timestamp": 0, "data": { "pageState": { "page": 1, "perPage": 20, "totalEntries": 1, "totalPages": 1 }, "notifications": [ { "notificationId": "6385272d-...-e35e80b3b8e7", "correlationId": "rrt-...-1", "appPrefix": "DLT", "metadata": { "productId": "es_LROEPJ240OperacionesSegurosAltaModifPeticion_Batuz_1.0", "transactionId": "25c40e96-...-b67f8c5e215b", "documentId": "DOCUMENT-ID", "erpDocumentId": "ERP-DOCUMENT-ID", "erpSystemId": "SystemERP", "processType": "0", "taxId": "YOUR-TAXID", "sciCloudStatusCode": "100", "sciResponseCode": "IP", "sciStatusAction": "NOA" }, "content": "PD...2U+", "createdDate": 1686579756 } ] } }{ "status": 200, "message": "Notifications Listed", "success": true, "timestamp": 0, "data": { "pageState": { "page": 1, "perPage": 20, "totalEntries": 1, "totalPages": 1 }, "notifications": [ { "notificationId": "6385272d-...-e35e80b3b8e7", "correlationId": "rrt-...-1", "appPrefix": "DLT", "metadata": { "productId": "es_LROEPJ240OperacionesSegurosAltaModifPeticion_Batuz_1.0", "transactionId": "25c40e96-...-b67f8c5e215b", "documentId": "DOCUMENT-ID", "erpDocumentId": "ERP-DOCUMENT-ID", "erpSystemId": "SystemERP", "processType": "0", "taxId": "YOUR-TAXID", "sciCloudStatusCode": "100", "sciResponseCode": "IP", "sciStatusAction": "NOA" }, "content": "PD...2U+", "createdDate": 1686579756 } ] } }
Step 9: 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/ES endpoint.
To make this request, set the following request body parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| status | string | Yes | Enter "read". |
| notificationId | string | Yes | The ID of the notification that must be marked as acknowledged. |
notificationId values can be acknowledged in one Indirect Tax API call by including them in a single request.- Request sample
-
curl --location --request PUT 'https://api-test.sovos.com/v1/notifications/ES' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer TOKEN' \ --header 'x-correlationId: SET-TO-UNIQUE-VALUE' \ --data-raw '[ { "status": "read", "notificationId": "51341d39-...-a73d73e0de76" } ]' - Response sample
-
{ "status": 200, "message": "OK", "success": true, "timestamp": 1657019349646, "data": {} }
Cancel LROE invoice
Canceling an LROE invoice in the province of Biscay (Spain) is based on the Default business process. This process involves the cancellation of reported data on income, expenses, and other information that is fiscally relevant to the tax authority using the POST /documents/ES/action endpoint.
Document types that can use this cancellation process:
-
LROE invoices issued without the guarantor software
-
LROE received invoices
-
LROE Operaciones Intracomunitarias - Export and Transfers
-
LROE Otra Información - Operaciones de seguros
Unsupported document types:
-
LROE Investment Goods
-
LROE Operaciones Intracomunitarias - Consignment Goods
-
LROE Otra Información - Greater amounts of 6000
-
LROE Otra Información - Travel agencies
For LROE Invoices issued with the guarantor software, see Cancel LROE invoice from guarantor software.
The following diagram provides a detailed overview:
Step 1: Supplier sends a POST request to Sovos
When the supplier wants to cancel an invoice in Biscay, they send a POST request to the /documents/ES/action endpoint. To make this request, set the following request body parameters:
| Name | Type | Required | Description | ||
|---|---|---|---|---|---|
| actionCode | string | Yes | Enter "document.cancellation". | ||
| documents | array of objects | Yes | An array of objects to include the metadata and the document ID. | ||
| metadata | object | No | An object that includes the required metadata. | ||
| reason | string | No | The reason for canceling the invoice. The max length is 100 characters. | ||
| reasonCode | string | No | The reason code for the cancellation. | ||
| documentId | string | Yes | The transactionId retrieved when the document was originally submitted. | ||
Although the parameter name is documentId, you must enter the transactionId.
- Request sample
-
curl --location --request POST 'https://api-test.sovos.com/v1/documents/ES/action' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer TOKEN' \ --header 'x-correlationId: SET-TO-UNIQUE-VALUE' \ --data '{ "actionCode": "document.cancellation", "documents": [ { "metadata": { "reason": "Faulty document data", "reasonCode": "1" }, "documentId": "TRANSACTION-ID" } ] }' - Response sample
-
{ "status": 202, "message": "Accepted", "success": true, "timestamp": 1699440641940, "data": [ { "status": 202, "documentId": "TRANSACTION-ID" } ] }
Step 2: Sovos transmits the request
Sovos transmits the cancellation request to LROE.
Requests are sent in batches over time. The batch service waits for either 10000 documents to be uploaded or four hours to pass before sending everything. These values are different between the production and the UAT environments.
Step 3: LROE processes the request
LROE performs the validation and the cancellation action.
Step 4: LROE returns the response
LROE sends the response to Sovos.
Step 5: Supplier retrieves the application responses
- Attachments configuration
- Sovos highly recommends configuring your application response attachments as download links instead of base64-encoded data to avoid potential size limitations when retrieving responses. The default option is "download links".Note:
When you use "download links", the response contains a URL to download the file. When you use "binary data", the file is embedded in the base64-encoded response. This configuration is available through the 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 the cleared XML encoded in Base64 after it's available during the process.
To complete a transaction, the supplier must retrieve application responses until the transaction is finished. If the supplier has subscribed to all notifications, the transaction can generate different application responses. See the table below:
| # | SCICloudStatusCode | SCIResponseCode | Sample |
|---|---|---|---|
| 1 | 101 | IP |
|
| 2 | 201 | AP |
|
| 3 | 209 | AP |
|
The supplier can use the following Indirect Tax API endpoints to retrieve application responses:
-
GET /notifications/ES
-
GET /documents/ES/{documentId}/notifications
- GET /notifications/ES
- The supplier can send a GET request to the /notifications/ES 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 theCompanyCodeset 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 SenderSystemIdin the SBDH.includeAcknowledged boolean No false Enter "true" to specify whether previously acknowledged notifications, within 24 hours of their acknowledgment, must be included in the result. processType string No Enter "0" to only include notifications related to outbound documents. - Request sample
-
curl --location --request GET 'https://api-test.sovos.com/v1/notifications/ES?page=1&perPage=2&taxId={taxId}&sourceSystemId={sourceSystemId}&processType=0' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer TOKEN' \ --header 'x-correlationId: SET-TO-UNIQUE-VALUE' - Response sample
-
{ "status": 200, "message": "Notifications Listed", "success": true, "timestamp": 0, "data": { "pageState": { "page": 1, "perPage": 10, "totalEntries": 1, "totalPages": 1 }, "notifications": [ { "notificationId": "6385272d-...-e35e80b3b8e7", "correlationId": "rrt-...-1", "appPrefix": "DLT", "metadata": { "productId": "es_LROEPJ240OperacionesSegurosAltaModifPeticion_Batuz_1.0", "transactionId": "25c40e96-...-b67f8c5e215b", "documentId": "DOCUMENT-ID", "erpDocumentId": "ERP-DOCUMENT-ID", "erpSystemId": "SystemERP", "processType": "0", "taxId": "YOUR-TAXID", "sciCloudStatusCode": "101", "sciResponseCode": "IP", "sciStatusAction": "NOA" }, "content": "PD...2U+", "createdDate": 1686579756 } ] } }
- GET /documents/ES/{documentId}/notifications
- The supplier can send a GET request to the /documents/ES/{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 Default Description documentId string Yes Path The ID of the document returned in step 1 - Request sample
-
curl --location --request GET 'https://api-test.sovos.com/v1/documents/ES/{documentId}/notifications' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer TOKEN' \ --header 'x-correlationId: SET-TO-UNIQUE-VALUE' - Response sample
-
{ "status": 200, "message": "Notifications Listed", "success": true, "timestamp": 0, "data": { "pageState": { "page": 1, "perPage": 20, "totalEntries": 1, "totalPages": 1 }, "notifications": [ { "notificationId": "6385272d-...-e35e80b3b8e7", "correlationId": "rrt-...-1", "appPrefix": "DLT", "metadata": { "productId": "es_LROEPJ240OperacionesSegurosAltaModifPeticion_Batuz_1.0", "transactionId": "25c40e96-...-b67f8c5e215b", "documentId": "DOCUMENT-ID", "erpDocumentId": "ERP-DOCUMENT-ID", "erpSystemId": "SystemERP", "processType": "0", "taxId": "YOUR-TAXID", "sciCloudStatusCode": "101", "sciResponseCode": "IP", "sciStatusAction": "NOA" }, "content": "PD...2U+", "createdDate": 1686579756 } ] } }
Step 6: 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/ES endpoint.
To make this request, set the following request body parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| status | string | Yes | Enter "read". |
| notificationId | string | Yes | The ID of the notification that must be marked as acknowledged. |
notificationId values can be acknowledged in one Indirect Tax API call by including them in a single request.- Request sample
-
curl --location --request PUT 'https://api-test.sovos.com/v1/notifications/ES' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer TOKEN' \ --header 'x-correlationId: SET-TO-UNIQUE-VALUE' \ --data-raw '[ { "status": "read", "notificationId": "51341d39-...-a73d73e0de76" } ]' - Response sample
-
{ "status": 200, "message": "OK", "success": true, "timestamp": 1657019349646, "data": {} }
Cancel LROE invoice from guarantor software
Reporting invoices in Spain for the province of Biscay is based on the Default business process, which follows this order: Mapping and Transmission. This process involves reporting data on income, expenses, and other fiscally relevant information to LROE in a structured format and is specific to invoices issued with the guarantor software.
Unsupported document types:
-
LROE Investment Goods
-
LROE Operaciones Intracomunitarias - Consignment Goods
-
LROE Otra Información - Greater amounts of 6000
-
LROE Otra Información - Travel agencies
For document types not listed here, see Cancel LROE invoice.
The following diagram provides a detailed overview of the cancellation process:
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.
The SBDH must be created using the following common values when issuing a document in the local format:
| Node | Required | Attributes | Value |
|---|---|---|---|
| StandardBusinessDocumentHeader.Sender.Identifier | Yes | Authority="ES" | Supplier's NIF |
| StandardBusinessDocumentHeader.Receiver.Identifier | Yes | Authority="ES" | |
| StandardBusinessDocumentHeader.DocumentIdentification.Standard | Yes | https://www.batuz.eus/fitxategiak/batuz/LROE/ esquemas/LROE_PJ_240_1_1_FacturasEmitidas_ConSG_AltaPeticion_V1_0_2.xsd | |
| StandardBusinessDocumentHeader.DocumentIdentification.TypeVersion | Yes | 1.0 | |
| StandardBusinessDocumentHeader.DocumentIdentification.Type | Yes | LROEPJ240FacturasEmitidasConSGAnulacionPeticion
| |
| StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes |
Child node Child node | |
| StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes |
Child node Child node | |
| StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes |
Child node Child node | |
| StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes |
Child node Child node | |
| StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes |
Child node Child node | |
| StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes |
Child node Child node | |
| StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes |
Child node Child node | |
| StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes |
Child node Child node | |
| StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes |
Child node Child node | |
| StandardBusinessDocumentHeader.BusinessScope.Scope (with child nodes) | Yes |
Child node Child node | |
| StandardBusinessDocumentHeader.BusinessScope.Scope.BusinessService.BusinessServiceName | Yes | Default | |
| SovosDocument.SovosLegalDocument.Base64Document | Yes | A local format |
You need to encode the local format (XML) document in Base64 before you can add it as part of the SBD. Here is a sample:
</sbd:StandardBusinessDocumentHeader>
<svs:SovosDocument>
<svs:SovosLegalDocument>
<enc:Base64Document>
<enc:EmbeddedDocument id="1" fileName="invoice.xml" mimeCode="application/xml">PD94bWwgdmVyc...FrdHVyYT4NCg==</enc:EmbeddedDocument>
</enc:Base64Document>
</svs:SovosLegalDocument>
</svs:SovosDocument>
</svs:StandardBusinessDocument>
Include all the mandatory nodes, as specified in the SBDH schema. If the information cannot be provided, and the respective mandatory 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. In addition, there's a full sample of the SBD on the Postman Samples page.
<sbd:StandardBusinessDocument xmlns="http://uri.etsi.org/01903/v1.4.1#" xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" xmlns:sbd="http://www.unece.org/cefact/namespaces/StandardBusinessDocumentHeader" 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:ext="urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2" xmlns:inv="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"> <sbd:StandardBusinessDocumentHeader> <sbd:HeaderVersion>1.0</sbd:HeaderVersion> <sbd:Sender> <sbd:Identifier Authority="ES">YOUR-TAXID</sbd:Identifier> <sbd:ContactInformation> <sbd:Contact>YOUR-TAXID</sbd:Contact> <sbd:EmailAddress/> <sbd:FaxNumber/> <sbd:TelephoneNumber/> <sbd:ContactTypeIdentifier/> </sbd:ContactInformation> </sbd:Sender> <sbd:Receiver> <sbd:Identifier Authority="ES"/> <sbd:ContactInformation> <sbd:Contact/> <sbd:EmailAddress/> <sbd:FaxNumber/> <sbd:TelephoneNumber/> <sbd:ContactTypeIdentifier/> </sbd:ContactInformation> </sbd:Receiver> <sbd:DocumentIdentification> <sbd:Standard>https://www.batuz.eus/fitxategiak/batuz/LROE/ esquemas/LROE_PJ_240_1_1_FacturasEmitidas_ConSG_AltaPeticion_V1_0_2.xsd</sbd:Standard> <sbd:TypeVersion>1.0</sbd:TypeVersion> <sbd:InstanceIdentifier/> <sbd:Type>LROEPJ240FacturasEmitidasConSGAnulacionPeticion</sbd:Type> <sbd:MultipleType>false</sbd:MultipleType> <sbd:CreationDateAndTime>2022-06-16T00:31:52Z</sbd:CreationDateAndTime> </sbd:DocumentIdentification> <sbd:BusinessScope> <sbd:Scope> <sbd:Type>Version</sbd:Type> <sbd:InstanceIdentifier/> <sbd:Identifier>1.0</sbd:Identifier> </sbd:Scope> <sbd:Scope> <sbd:Type>SenderDocumentId</sbd:Type> <sbd:InstanceIdentifier/> <sbd:Identifier>DOCUMENT-ID</sbd:Identifier> </sbd:Scope> <sbd:Scope> <sbd:Type>SenderSystemId</sbd:Type> <sbd:InstanceIdentifier/> <sbd:Identifier>SENDER-SYSTEM-ID</sbd:Identifier> </sbd:Scope> <sbd:Scope> <sbd:Type>CompanyCode</sbd:Type> <sbd:InstanceIdentifier/> <sbd:Identifier>YOUR-TAXID</sbd:Identifier> </sbd:Scope> <sbd:Scope> <sbd:Type>Country</sbd:Type> <sbd:InstanceIdentifier/> <sbd:Identifier>ES</sbd:Identifier> </sbd:Scope> <sbd:Scope> <sbd:Type>ProcessType</sbd:Type> <sbd:InstanceIdentifier/> <sbd:Identifier>Outbound</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>LROEPJ240FacturasEmitidasConSGAnulacionPeticion</sbd:Identifier> </sbd:Scope> <sbd:Scope> <sbd:Type>SubSchema</sbd:Type> <sbd:InstanceIdentifier/> <sbd:Identifier>Batuz</sbd:Identifier> </sbd:Scope> <sbd:Scope> <sbd:Type>BusinessCategory</sbd:Type> <sbd:InstanceIdentifier/> <sbd:Identifier>B2B</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> <!--LEGAL FORMAT--> <svs:SovosLegalDocument> <enc:Base64Document> <enc:EmbeddedDocument id="1" fileName="name.xml" mimeCode="application/xml"> *Base64Document* </enc:EmbeddedDocument> </enc:Base64Document> </svs:SovosLegalDocument> <!--LEGAL FORMAT--> </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:
| Name | Type | Required | Description |
|---|---|---|---|
| data | string | Yes | The SBD encoded in Base64, as created in step 1. |
| dataEncoding | string | Yes | Enter "base64". |
- 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
-
{ "status": 202, "message": "Accepted", "success": true, "timestamp": 1686579755320, "data": { "transactionId": "d799d405-...-43f2d9cf4e67", "documentId": "3de...26c" } }
Step 3: Sovos maps the SCI into XML
This step will be skipped if the SBD contains the invoice in the local format (XML).
Step 4: Sovos transmits the XML
Sovos transmits the XML file to the LROE.
Requests are sent in batches over time. The batch service waits for either 10000 documents to be uploaded or four hours to pass before sending everything. These values are different between the production and the UAT environments.
Step 5: LROE processes the XML
LROE performs a schema validation and several business validations. Then it generates an approval or rejection response message along with an error message, where applicable.
Step 6: LROE sends the response to Sovos
After performing its services, LROE sends the response to Sovos.
Step 7: Supplier retrieves the application responses
- Attachments configuration
- Sovos highly recommends configuring your application response attachments as download links instead of base64-encoded data to avoid potential size limitations when retrieving responses. The default option is "download links".Note:
When you use "download links", the response contains a URL to download the file. When you use "binary data", the file is embedded in the base64-encoded response. This configuration is available through the 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 the cleared XML encoded in Base64 after it's available during the process.
Additionally, you must consider the following details included in the response:
- Transmission message
- It maps to the
SCIGovtStatusCodeandStatusReasonelements in the response message, as described in the application responses documentation, which details any warnings or additional notes to consider. The tax authority doesn't define any specific set of rules about what action to take on each error. Depending on the type of message, the user may have to modify the invoice, take some additional action, or simply make a note for the future.
To complete a transaction, the supplier must retrieve the application responses until the transaction has finished. If the supplier has subscribed to all notifications, the transaction can generate different application responses. See the table below:
| # | SCICloudStatusCode | SCIResponseCode | Sample |
|---|---|---|---|
| 1 | 101 | IP |
|
| 2 | 201 | AP |
|
| 3 | 209 | AP |
|
The supplier can use the following Indirect Tax API endpoints to retrieve application responses:
-
GET /notifications/ES
-
GET /documents/ES/{documentId}/notifications
- GET /notifications/ES
- The supplier can send a GET request to the /notifications/ES 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 theCompanyCodeset 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 SenderSystemIdin the SBDH.includeAcknowledged boolean No false Enter "true" to specify whether previously acknowledged notifications, within 24 hours of their acknowledgment, must be included in the result. processType string No Enter "0" to only include notifications related to outbound documents. - Request sample
-
curl --location --request GET 'https://api-test.sovos.com/v1/notifications/ES?page=1&perPage=2&taxId={taxId}&sourceSystemId={sourceSystemId}&processType=0' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer TOKEN' --header 'x-correlationId: SET-TO-UNIQUE-VALUE' \ - Response sample
-
{ "status": 200, "message": "Notifications Listed", "success": true, "timestamp": 0, "data": { "pageState": { "page": 1, "perPage": 20, "totalEntries": 1, "totalPages": 1 }, "notifications": [ { "notificationId": "6385272d-...-e35e80b3b8e7", "correlationId": "rrt-...-1", "appPrefix": "DLT", "metadata": { "productId": "es_SuministroLRFacturasEmitidas_Mainland_1.0", "transactionId": "25c40e96-...-b67f8c5e215b", "documentId": "DOCUMENT-ID", "erpDocumentId": "ERP-DOCUMENT-ID", "erpSystemId": "SystemERP", "processType": "0", "taxId": "YOUR-TAXID", "sciCloudStatusCode": "101", "sciResponseCode": "IP", "sciStatusAction": "NOA" }, "content": "PD...2U+", "createdDate": 1686579756 } ] } }
- GET /documents/ES/{documentId}/notifications
- The supplier can send a GET request to the /documents/ES/{documentId}/notifications endpoint to retrieve application responses related to a single document. To make this request, set the following path parameter:
Name Type Required Default Description documentId string Yes The document ID returned in step 2 - Request sample
-
curl --location --request GET 'https://api-test.sovos.com/v1/documents/ES/{documentId}/notifications' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer TOKEN' \ --header 'x-correlationId: SET-TO-UNIQUE-VALUE' - Response sample
-
{ "status": 200, "message": "Notifications Listed", "success": true, "timestamp": 0, "data": { "pageState": { "page": 1, "perPage": 20, "totalEntries": 1, "totalPages": 1 }, "notifications": [ { "notificationId": "6385272d-...-e35e80b3b8e7", "correlationId": "rrt-...-1", "appPrefix": "DLT", "metadata": { "productId": "es_SuministroLRFacturasEmitidas_Mainland_1.0", "transactionId": "25c40e96-...-b67f8c5e215b", "documentId": "DOCUMENT-ID", "erpDocumentId": "ERP-DOCUMENT-ID", "erpSystemId": "SystemERP", "processType": "0", "taxId": "YOUR-TAXID", "sciCloudStatusCode": "101", "sciResponseCode": "IP", "sciStatusAction": "NOA" }, "content": "PD...2U+", "createdDate": 1686579756 } ] } }
Step 8: 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/ES endpoint.
To make this request, set the following request body parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| status | string | Yes | Enter "read". |
| notificationId | string | Yes | The ID of the notification that must be marked as acknowledged. |
notificationId values can be acknowledged in one Indirect Tax API call by including them in a single request.- Request sample
-
curl --location --request PUT 'https://api-test.sovos.com/v1/notifications/ES' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer TOKEN' \ --header 'x-correlationId: SET-TO-UNIQUE-VALUE' \ --data-raw '[ { "status": "read", "notificationId": "51341d39-...-a73d73e0de76" } ]' - Response sample
-
{ "status": 200, "message": "OK", "success": true, "timestamp": 1657019349646, "data": {} }