Introduction
This API serves as a complete middleware solution for integrating your systems with the Dirección General de Impuestos Internos (DGII) electronic invoicing system (e-CF).
It abstracts away the complexity of:
- XML Construction: Automatically builds valid XML documents adhering to standard UBL layouts.
- Digital Signing: Implements XAdES-BES electronic signatures using your stored P12 certificate.
- Token Management: Handles the secure handshake (Seed -> Signed Seed -> Token) automatically.
Authentication & Security
Auto-Managed Tokens
You don't need to manually fetch tokens. Every request to /send or /status automatically checks for a valid cached token. If expired, it renegotiates a new one instantly.
Certificate Security
Your digital certificate (.p12) is stored securely on the server. The password is kept in environment variables and never exposed in API responses.
Using with Postman
Step-by-step guide to testing the API endpoints.
Configure Headers
Set the following headers for all POST requests.
| Key | Value |
|---|---|
| Content-Type | application/json |
| Accept | application/json |
Create a "Send Invoice" Request
Create a new request in Postman, set method to POST and URL to:
Request Body (Raw JSON):
{
"encf": "E310000000001", // Your e-CF number
"rnc_comprador": "101010101", // Buyer RNC
"fecha_vencimiento_secuencia": "31-12-2025",
"total": 1180.00, // Total Amount
"items": [
{
"name": "Consultoría de Software",
"qty": 10,
"price": 100.00,
"amount": 1000.00
},
{
"name": "Soporte Técnico",
"qty": 1,
"price": 180.00,
"amount": 180.00
}
]
}Interpret the Response
A successful 200 OK response means DGII received the request.
{
"status": "success",
"dgii_response": {
"trackId": "3459045-8025-4303-9975-345345345",
"codigo": "1",
"estado": "Recibido",
"mensaje": "La factura fue recibida correctamente"
}
}/api/ecf/emit
This endpoint generates the XML and signs it digitally, but does not send it to DGII. Use this for testing XML structure, verifying signatures locally, or debugging.
{
"status": "success",
"signed_xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<ECF...>...<SignatureValue>MII...</SignatureValue>...</ECF>",
"encoded_xml": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iV..."
}/api/ecf/send
The primary endpoint for operations. It performs the full lifecycle: XML Generation → Signing → Token Auth → Sending to DGII.
| encf | Required | The Electronic NCF (e.g., E3100000001). |
| rnc_comprador | Required | RNC or Cedula of the buyer. |
| items | Required | Array of objects containing name, qty, price, amount. |
/api/ecf/status/{trackId}
After sending an invoice, you receive a trackId. Use this endpoint to poll DGII for the final approval status of that invoice.
Common Statuses
- In Process: The invoice is being analyzed.
- Accepted: Valid invoice, stored in DGII.
- Rejected: Contains errors (check message for details).