Dominican Republic
Enabling support for the Dominican Republic involves confirming prerequisites and product IDs, registering with the DGII (Dirección General de Impuestos) tax authority, and setting up credentials.
Prerequisites
-
A valid RNC (Registro Nacional de Contribuyentes), username, and password obtained from the DGII tax authority
-
A valid digital certificate or cryptographic key to electronically sign documents
-
Registered in the RNC as an electronic issuer-receiver of electronic documents
Buyer acceptance or rejection
If the buyer or recipient of the invoice is an issuer or authorized recipient of electronic invoices, they must accept, or (partially) reject the invoice by sending a message in XML format to the DGI.
Available products
- do_fe__1.0
- Tax Credit Invoice
- do_fce__1.0
- Electronic consumer invoice
- do_nde__1.0
- Debit Note
- do_nce__1.0
- Credit Note
- do_ce__1.0
- Electronic purchase receipt
- do_gme__1.0
- Electronic receipt for minor expenses
- do_ree__1.0
- Electronic receipt for special regimes
- do_ge__1.0
- Government electronic receipt
- do_fex__1.0
- Export Invoice
- do_fpex__1.0
- Electronic receipt for payments abroad
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.
Issue invoice
Issuing an invoice in the Dominican Republic is based on the Default business process, which follows this order: Mapping, Signing, and Transmission. The following diagram provides a detailed overview:
You can choose to do the PDF rendering before transmission.
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:
| Node | Required | Attributes | Value |
|---|---|---|---|
| StandardBusinessDocumentHeader.Sender.Identifier | Yes | Authority="DO" | Supplier's tax ID |
| StandardBusinessDocumentHeader.Receiver.Identifier | Yes | Authority="DO" | |
| 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) | No |
Child node Child node | |
| StandardBusinessDocumentHeader.BusinessScope.Scope.BusinessService.BusinessServiceName | Yes | Default | |
| SovosDocument.SovosCanonicalInvoice.Invoice | Yes | SCI |
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"?> <sbd:StandardBusinessDocument xmlns:sbc="urn:oasis:names:specification:ubl:schema:xsd:SignatureBasicComponents-2" xmlns:sbd="http://www.unece.org/cefact/namespaces/StandardBusinessDocumentHeader" xmlns:udt="urn:oasis:names:specification:ubl:schema:xsd:UnqualifiedDataTypes-2" xmlns:ad="http://www.sovos.com/namespaces/additionalData" xmlns:n1="urn:oasis:names:specification:ubl:schema:xsd:CommonSignatureComponents-2" xmlns:qdt="urn:oasis:names:specification:ubl:schema:xsd:QualifiedDataTypes-2" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:enc="http://www.sovos.com/namespaces/base64Document" xmlns:inj="http://www.sovos.com/namespaces/injections" xmlns:leg="http://www.sovos.com/namespaces/sovosExtensions/LegalExtension" xmlns:sac="urn:oasis:names:specification:ubl:schema:xsd:SignatureAggregateComponents-2" xmlns:sov="http://www.sovos.com/namespaces/sovosExtensions" xmlns="http://uri.etsi.org/01903/v1.4.1#" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" xmlns:dea="urn:oasis:names:specification:ubl:schema:xsd:DespatchAdvice-2" xmlns:ccts-cct="urn:un:unece:uncefact:data:specification:CoreComponentTypeSchemaModule:2" xmlns:crn="urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2" xmlns:inv="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2" xmlns:svs="http://www.sovos.com/namespaces/sovosDocument" xmlns:sci="http://www.sovos.com/namespaces/sovosCanonicalInvoice" xmlns:xades="http://uri.etsi.org/01903/v1.3.2#" xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" xmlns:ext="urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2" xmlns:dbn="urn:oasis:names:specification:ubl:schema:xsd:DebitNote-2" xmlns:mex="MexicoExtension.xsd"> <sbd:StandardBusinessDocumentHeader> <sbd:HeaderVersion>1.0</sbd:HeaderVersion> <sbd:Sender> <sbd:Identifier Authority="DO">123456789</sbd:Identifier> <sbd:ContactInformation> <sbd:Contact>123456789</sbd:Contact> <sbd:EmailAddress/> <sbd:FaxNumber/> <sbd:TelephoneNumber/> <sbd:ContactTypeIdentifier/> </sbd:ContactInformation> </sbd:Sender> <sbd:Receiver> <sbd:Identifier Authority="DO">444555666</sbd:Identifier> <sbd:ContactInformation> <sbd:Contact>444555666</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>2024-08-06T11:20:31Z</sbd:CreationDateAndTime> </sbd:DocumentIdentification> <sbd:BusinessScope> <sbd:Scope> <sbd:Type>Country</sbd:Type> <sbd:InstanceIdentifier/> <sbd:Identifier>DO</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>FCE</sbd:Identifier> </sbd:Scope> <sbd:Scope> <sbd:Type>CompanyCode</sbd:Type> <sbd:InstanceIdentifier/> <sbd:Identifier>444555666</sbd:Identifier> </sbd:Scope> <sbd:Scope> <sbd:Type>SenderDocumentId</sbd:Type> <sbd:InstanceIdentifier/> <sbd:Identifier>321412</sbd:Identifier> </sbd:Scope> <sbd:Scope> <sbd:Type>SenderSystemId</sbd:Type> <sbd:InstanceIdentifier/> <sbd:Identifier>SystemERP</sbd:Identifier> </sbd:Scope> <sbd:Scope> <sbd:Type>ProcessType</sbd:Type> <sbd:InstanceIdentifier/> <sbd:Identifier>Outbound</sbd:Identifier> </sbd:Scope> <sbd:Scope> <sbd:Type>BusinessProcess</sbd:Type> <sbd:InstanceIdentifier/> <sbd:BusinessService> <sbd:BusinessServiceName>Default</sbd:BusinessServiceName> </sbd:BusinessService> </sbd:Scope> <sbd:Scope> <sbd:Type>BusinessCategory</sbd:Type> <sbd:InstanceIdentifier/> <sbd:Identifier>BusinessToConsumer</sbd:Identifier> </sbd:Scope> <sbd:Scope> <sbd:Type>Version</sbd:Type> <sbd:InstanceIdentifier/> <sbd:Identifier>1.0</sbd:Identifier> </sbd:Scope> </sbd:BusinessScope> </sbd:StandardBusinessDocumentHeader> <svs:SovosDocument> <sci:SovosCanonicalInvoice> <inv:Invoice> *UBL Elements* </inv:Invoice> </sci:SovosCanonicalInvoice> </svs:SovosDocument> </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". |
After receiving the document, Sovos performs a structure/schema validation of both the SCI and the SBD parts.
- 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": "Accepted", "data": { "transactionId": "813d91ef-...-f98c09aa1157", "documentId": "3add2b7104dc0049ff0bf410f57e0a19afaf" } }
Step 3: Sovos maps the SCI into XML
Upon receiving the SCI, Sovos maps the file into the required XML format.
Step 4: Sovos performs the schema validation
Sovos performs a schema validation before preparing the document for transmission.
Step 5: Sovos signs the XML
Sovos signs the XML with the qualified seal certificate.
Step 6: Sovos transmits the XML
Sovos transmits the signed XML file to the tax authority e-invoicing system.
Step 7: Tax authority processes the XML
The tax authority performs a schema validation and several business validations. An approval or rejection response message is then generated along with an error message, where applicable.
Step 8: Tax authority sends the response to Sovos
The tax authority sends a response to Sovos for the transmitted document.
Step 9: Sovos generates the PDF
Sovos generates a PDF file that includes the content of the invoice XML in a human-readable format.
Step 10: 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 signed XML encoded in Base64 after they're 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. 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.
Fields that must be unique inside each invoice payload:
-
Invoice Number
-
Document Type
-
Supplier Identification
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.
When these fields are not unique, ApplicationResponse includes the following error in the subsequent invoices: "Processing of another operation with identical identifier(s) has already been initiated."
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 |
|
SCICloudStatusCode with a value in the 5xx range still remains an option, as 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/DO
-
GET /documents/DO/{documentId}/notifications
- GET /notifications/DO
- The supplier can send a GET request to the /notifications/DO 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/DO?page=1&perPage=2&includeAcknowledged=true&taxId={taxId}&sourceSystemId={sourceSystemId}&includeBinaryData=true&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": 1724846485495, "data": { "pageState": { "page": 1, "perPage": 10, "totalEntries": 248, "totalPages": 25 }, "notifications": [ { "notificationId": "aebd1d2e-a694-4312-ae6f-fc6251f2d163", "correlationId": "e2e_Pablo.Caun_UAT_c54f83f7-af8c-4d1a-ad81-5973140f9e2a", "appPrefix": "DLT", "metadata": { "productId": "do_fpex__1.0", "transactionId": "c95e2e60-3974-4ee3-9d6e-aa0b94414669", "documentId": "7d9bffcbec9099ed05868f0d12b2d57d", "erpDocumentId": "130873011|FPEX|0000729005", "erpSystemId": "qa_dom_e2e", "processType": "0", "taxId": "130873011", "sciCloudStatusCode": "200", "sciResponseCode": "AP", "sciStatusAction": "NOA", "sciGovtStatusCode": "1" }, "content": "PD94...zZT4=", "createdDate": 1724843081309 } ] } }
- GET /documents/DO/{documentId}/notifications
- The supplier can send a GET request to the /documents/DO/{documentId}/notifications endpoint to retrieve application responses related to a single document. To make this request, set the following parameters:
Name Type Required Parameter type Default Description documentId string Yes Path The ID of the document returned in step 2 includeAcknowledged boolean No Query false Enter "true" to specify whether previously acknowledged notifications must be included in the result. 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/DO/{documentId}/notifications?includeAcknowledged=true&includeBinaryData=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": 1724774743519, "data": { "pageState": { "page": 1, "perPage": 20, "totalEntries": 9, "totalPages": 1 }, "notifications": [ { "notificationId": "70fec913-bea2-4d3e-ae6e-fe3f79b8c686", "correlationId": "rrt-9108161019709423297-a-geu3-5414-179039850-3", "appPrefix": "DLT", "metadata": { "productId": "do_nce__1.0", "transactionId": "6e2178d1-0c96-414f-824a-e4d3e70c1552", "documentId": "f28a5a1c115414d6a18fd9b703014e0b", "erpDocumentId": "130873011|NCE|0000782260", "erpSystemId": "qa_dom_e2e", "processType": "0", "taxId": "130873011", "sciCloudStatusCode": "209", "sciResponseCode": "AP", "sciStatusAction": "NOA", "sciGovtStatusCode": "1" }, "content": "PD94...uc2U+", "createdDate": 1724767247566 } ] } }
Step 11: Supplier marks the application responses as acknowledged
The supplier must process the retrieved application responses and mark them as acknowledged. This can be done by sending a PUT request to the /notifications/DO 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/DO' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer TOKEN' \ --header 'x-correlationId: SET-TO-UNIQUE-VALUE' \ --data-raw '[ { "status": "read", "notificationId": "51341d39-fd3e-4dcf-aea3-a73d73e0de76" } ]' - Response sample
-
{ "status": 200, "message": "OK", "success": true, "timestamp": 1724847565969, "data": {} }
Step 12: Supplier sends the XML and the PDF to the Buyer
As the final step, the supplier should send the cleared invoice to the buyer through an agreed-upon channel.
This process is outside the scope of Sovos.
In case the buyer is an electronic issuer or an authorized recipient of electronic invoices, they must accept or partially reject the invoice by sending a message to the tax authority. Sovos does not support the issuance or reception of acceptance and rejection messages.