API e-CF (DGII) — Guía para integradores#

Esta guía explica cómo emitir comprobantes fiscales electrónicos (e-CF) de la DGII a través de nuestro API: cómo autenticarse, qué ambiente usar, cómo armar el JSON, cómo se calculan los totales, qué pasa después del envío y cómo consultar el resultado.

Todo lo que aparece aquí sale del código del API y de los XSD oficiales de la DGII. Los ejemplos (uno por tipo de comprobante) se validan automáticamente contra las mismas reglas del endpoint y el XSD de la DGII: puedes enviarlos tal cual, cambiando solo el encf.

Inicio rápido#

1. Pide una API Key de testecf al administrador de tu empresa (portal → API Keys). Cada key es de un RNC y un ambiente.

2. Envía el ejemplo E31-credito-fiscal.json, cambiando el encf por uno de tu secuencia:

   curl -X POST https://ecf.paciolird.com/api/testecf/factura/enviar-directo \
     -H "Authorization: Bearer $API_KEY" \
     -H "Content-Type: application/json" \
     -d @E31-credito-fiscal.json
   

3. Guarda la respuesta 201: codigo_seguridad, url_dgii y qr_image son lo que va en la factura impresa, y ecf_queue_id sirve para consultar después.

4. Consulta el resultado unos minutos después (el envío a la DGII es en segundo plano):

   curl "https://ecf.paciolird.com/api/testecf/ecf/estado?encf=E310000000001" \
     -H "Authorization: Bearer $API_KEY"
   

   Repite hasta que data.dgii.estado sea final (Aceptado, Aceptado Condicional, Rechazado, resumido, duplicado o fallido). Si no es Aceptado, el motivo está en data.dgii.mensaje.

Cuando funcione en testecf, pide la key de produccion y cambia testecf por produccion en la URL.

Contenido#

1. Ambientes y autenticación
2. Flujo completo
3. Endpoint principal: POST /{ambiente}/factura/enviar-directo
4. Campos del request
5. Cálculo de totales, redondeo y cuadre
6. Respuestas y errores
7. Estados del comprobante
8. Endpoints de consulta
9. Tablas de códigos
10. Resumen por tipo de comprobante
11. Recetas: casos frecuentes

Documentación por tipo: E31 · E32 · E33 · E34 · E41 · E43 · E44 · E45 · E46 · E47

1. Ambientes y autenticación#

URL base#

https://ecf.paciolird.com/api/{ambiente}/...

Cada ambiente lleva su propia secuencia de e-NCF en la DGII: el mismo e-NCF puede usarse en testecf y luego en produccion sin conflicto.

API Key#

Cada request lleva el header:

Authorization: Bearer <api_key>

• Una API Key por ambiente. La key está registrada para un RNC y un ambiente. Si llamas /produccion/... con una key de testecf, la respuesta es 401 {"message": "Token inválido o entorno no coincide"}.
• El RNC emisor y la razón social se toman de la key. No hace falta enviarlos en el JSON (ver rnc_emisor).
• Las keys las crea el administrador de la empresa en el portal (sección API Keys).

Errores de autenticación (todos HTTP 401):

Los endpoints de comprobantes recibidos (/api/ecf/recibidos...) no llevan ambiente en la URL: aceptan una key activa de cualquier ambiente y devuelven los comprobantes recibidos por su RNC.

2. Flujo completo#

Tu sistema                         API                                   DGII
    │  POST /{ambiente}/factura/enviar-directo                             │
    │──────────────────────────────▶│ 1. valida el JSON                     │
    │                               │ 2. arma el XML del e-CF               │
    │                               │ 3. lo firma con el certificado        │
    │                               │ 4. lo valida contra el XSD de DGII    │
    │                               │ 5. guarda y encola (estado pendiente) │
    │◀──────────────────────────────│ 201: código de seguridad, URL, QR     │
    │                               │                                       │
    │   (imprimes / entregas el comprobante con el QR)                      │
    │                               │ worker (cada minuto)                  │
    │                               │──────────────────────────────────────▶│ envío
    │                               │◀──────────────────────────────────────│ trackId / estado
    │  GET /{ambiente}/ecf/estado   │                                       │
    │──────────────────────────────▶│ estado local (Aceptado, Rechazado…)   │

1. Envías el comprobante a POST /{ambiente}/factura/enviar-directo.
2. En la misma respuesta (201) recibes el código de seguridad, la URL de consulta del timbre DGII, la imagen QR (PNG en base64) y el XML firmado. Con eso ya puedes imprimir la representación impresa. Todo el paso 1–5 es atómico: si algo falla (validación, firma, XSD), no se guarda nada y puedes reintentar con el mismo e-NCF.
3. El envío a la DGII es asíncrono. Un proceso corre cada minuto y envía los comprobantes en estado pendiente. Las Facturas de Consumo (E32) menores de RD$250,000 no se envían una por una: van en un Resumen de Factura de Consumo (RFCE) y quedan en estado resumido (ver E32).
4. Consultas el resultado con GET /{ambiente}/ecf/estado?encf=... (o por ecf_queue_id / track_id) hasta que llegue a un estado final (Aceptado, Aceptado Condicional, Rechazado, resumido, fallido). Ver estados.

3. Endpoint principal#

POST https://ecf.paciolird.com/api/{ambiente}/factura/enviar-directo
Authorization: Bearer <api_key>
Content-Type: application/json

Cuerpo: un objeto con dos claves.

{
  "factura": { "...": "encabezado: tipo, e-NCF, fechas, emisor, comprador, totales" },
  "detalle": [ { "...": "una entrada por línea" } ]
}

Ejemplo mínimo completo (Factura de Crédito Fiscal): ejemplos/E31-credito-fiscal.json. Hay un ejemplo validado por cada tipo en ejemplos/.

Solo se aceptan los campos listados en la sección 4. Cualquier otra clave (por ejemplo nombre_comercial, telefono_emisor, descripcion_item, identificador_extranjero) se descarta en silencio y no llega al XML.

4. Campos del request#

Columna "XML": el elemento del e-CF que se genera. Las restricciones de largo/formato son las del XSD de la DGII; si no se cumplen, la respuesta es 422 Comprobante inválido según el esquema de DGII.

Fechas: envíalas como YYYY-MM-DD. El API las convierte al formato DGII (dd-mm-aaaa).

Tipos JSON. Estos campos se validan como texto y deben ir como string JSON (entre comillas); un número ("tipo_ecf": 31) se rechaza con 422 Error de validación ("must be a string"): tipo_ecf, encf, tipo_ingresos, termino_pago, rnc_emisor, razon_social_emisor, direccion_emisor, municipio_emisor, provincia_emisor, correo_emisor, website_emisor, codigo_vendedor, numero_factura_interna, numero_pedido_interno, zona_venta, rnc_comprador, razon_social_comprador, direccion_comprador, municipio_comprador, provincia_comprador, correo_comprador, numero_orden_compra, codigo_interno_comprador, ncf_modificado, codigo_modificacion, razon_modificacion y, en el detalle, nombre_item y unidad_medida. tipo_pago y formas_pago[].forma_pago aceptan "1" o 1 (se recomienda string). Los montos y los indicadores (indicador_monto_gravado, indicador_facturacion, indicador_bien_servicio, indicador_nota_credito, indicador_agente_retencion_percepcion, numero_linea) van como número.

Identificación del comprobante#

Emisor#

El NombreComercial del XML se toma de la empresa registrada (o su razón social); en 34 no se emite.

Comprador#

La sección comprador se emite si viene rnc_comprador o razon_social_comprador. En 43 nunca se emite. En 32 se emite vacía si no hay datos (consumidor final). Para 47 ver E47. Qué es obligatorio en cada tipo está en la página del tipo.

Totales#

Montos en 0 no se emiten. En 43, 44, 46 y 47 el API no emite montos gravados ni ITBIS (ver cada tipo).

Se aceptan pero no se usan: monto_propina_legal, total_descuento, monto_no_facturable, subtotal_sin_impuesto.

Referencia (solo 33 y 34)#

Si falta ncf_modificado, fecha_ncf_modificado o codigo_modificacion en un 33/34, la respuesta es 500 con el mensaje El campo ... es obligatorio para Notas de Crédito (tipo 34) (también en 33).

Detalle (cada línea)#

En 41 y 47 cada línea lleva siempre el bloque Retencion (lo exige el XSD). En 31, 33 y 34 no se emite el bloque por línea, pero monto_itbis_retenido / monto_isr_retenido del detalle se suman para TotalITBISRetenido / TotalISRRetencion si no envías esos totales.

5. Cálculo de totales, redondeo y cuadre#

El API no calcula los totales del encabezado: usa los que envías. La DGII sí los verifica contra el detalle; si no cuadran, el comprobante vuelve como Aceptado Condicional o Rechazado. Calcula así:

5.1 MontoItem#

monto_item = round(cantidad × precio_unitario − descuento, 2)

El API siempre envía a la DGII el MontoItem calculado con esa fórmula (la DGII valida la misma igualdad), aunque el monto_item que mandes sea otro. Excepción: si cantidad o precio_unitario son 0 se respeta el monto_item enviado. En E43 el descuento no se resta (E43 no admite descuentos).

CantidadItem viaja con 2 decimales: si usas cantidades con más decimales, redondéalas tú antes de calcular, para que cantidad × precio cuadre con lo que ve la DGII.

5.2 Totales por tasa (indicador_monto_gravado = 0)#

monto_gravado_i1   = Σ monto_item de las líneas con indicador_facturacion = 1
monto_gravado_i2   = Σ monto_item con indicador_facturacion = 2
monto_gravado_i3   = Σ monto_item con indicador_facturacion = 3
monto_exento       = Σ monto_item con indicador_facturacion = 4
monto_gravado_total = i1 + i2 + i3

total_itbis1 = round(monto_gravado_i1 × 0.18, 2)
total_itbis2 = round(monto_gravado_i2 × 0.16, 2)
total_itbis3 = 0
total_itbis  = total_itbis1 + total_itbis2 + total_itbis3

monto_total  = monto_gravado_total + monto_exento + total_itbis
valor_pagar  = monto_total

Ejemplo (E31 con descuento y exento):

MontoGravadoI1 66,500.00 · MontoGravadoI2 850.00 · MontoGravadoTotal 67,350.00 · MontoExento 3,600.00 · TotalITBIS1 11,970.00 · TotalITBIS2 136.00 · TotalITBIS 12,106.00 · MontoTotal 83,056.00.

5.3 Retenciones no se restan#

valor_pagar no es el neto después de retenciones. La DGII valida ValorPagar = MontoTotal + SaldoAnterior − MontoAvancePago; el API no maneja saldo anterior ni avances, así que ValorPagar = MontoTotal siempre que valor_pagar sea mayor que 0 (si mandas el neto, el API lo corrige). Las retenciones viajan aparte, en cada línea (monto_itbis_retenido, monto_isr_retenido) y en el encabezado (total_itbis_retenido, total_isr_retencion). Ver E41 y E47.

5.4 indicador_monto_gravado#

Usa 0. Todos los ejemplos de esta guía usan 0. El API revisa los totales y, si una de las dos igualdades cuadra y la otra no, envía el indicador que cuadra aunque hayas mandado el otro.

5.5 Redondeo#

• Montos del encabezado y MontoItem: 2 decimales. PrecioUnitarioItem: 4 decimales.
• Calcula el ITBIS sobre la base total de cada tasa (no línea por línea) para que TotalITBIS1 = MontoGravadoI1 × 18 % cuadre exactamente.
• formas_pago debe sumar exactamente monto_total.

6. Respuestas y errores#

201 — Comprobante emitido#

{
  "mensaje": "Factura procesada exitosamente",
  "factura_id": 1234,
  "encf": "E310000000001",
  "codigo_seguridad": "a1B2c3",
  "url_dgii": "https://ecf.dgii.gov.do/TesteCF/consultatimbre?rncemisor=101000001&encf=E310000000001&FechaEmision=01-10-2026&montototal=19706.00&FechaFirma=01-10-2026+10%3A15%3A30&codigoseguridad=a1B2c3&rnccomprador=131000001",
  "qr_image": "data:image/png;base64,iVBORw0KGgo...",
  "xml_firmado": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><ECF>...</ECF>",
  "estado": "pendiente",
  "ecf_queue_id": 5678
}

(Valores ilustrativos.)

Prefijo de url_dgii según ambiente:

Parámetros: rncemisor, encf, FechaEmision (dd-mm-aaaa), montototal, FechaFirma, codigoseguridad y, si hay comprador con RNC, rnccomprador.

Errores de enviar-directo#

En cualquier 422 o 500 no se guarda nada: puedes reenviar con el mismo e-NCF.

Ejemplo de 422 por validación:

{
  "error": "Error de validación",
  "mensajes": {
    "factura.encf": ["The factura.encf field is required."]
  }
}

409 — e-NCF duplicado y cómo recuperar la respuesta#

El 409 protege contra la doble emisión. Si el comprobante existente ya tiene código de seguridad, el 409 trae sus datos para que puedas recuperarlos (por ejemplo, si tu request anterior hizo timeout y no recibiste el 201):

{
  "error": "eNCF duplicado",
  "mensaje": "Ya existe una factura con eNCF E310000000001 para este emisor",
  "factura_id": 1234,
  "encf": "E310000000001",
  "codigo_seguridad": "a1B2c3",
  "url_dgii": "https://ecf.dgii.gov.do/TesteCF/consultatimbre?...",
  "qr_image": "data:image/png;base64,...",
  "estado": "Aceptado",
  "track_id": "a2b9c1d4-...",
  "ecf_queue_id": 5678
}

Regla práctica ante un timeout: reenvía exactamente el mismo request. Si el primero se procesó, recibes 409 con los datos; si no, se procesa ahora. Antes de usar los datos del 409, verifica que corresponden a la misma venta (el 409 también aparece si reutilizaste por error un e-NCF de otra venta). El 409 no incluye xml_firmado; puedes obtenerlo con GET /{ambiente}/ecf-queue/{ecf_queue_id}/xml.

7. Estados del comprobante#

Es el valor de data.dgii.estado en GET /{ambiente}/ecf/estado (y de estado en las demás consultas).

Reintentos automáticos (valores por defecto): una falla de conexión con la DGII se reintenta hasta 12 veces; cualquier otra falla, hasta 3. Entre intentos se espera intentos × 5 minutos. Si un intento anterior llegó a la DGII aunque la respuesta se perdiera, el sistema lo detecta y no reenvía.

Cuando la DGII recibe el comprobante (enviado, Aceptado, Aceptado Condicional, resumido…), si tiene rnc_comprador el sistema intenta entregarlo al comprador (si este es receptor electrónico). El resultado aparece en data.comprador de ecf/estado.

8. Endpoints de consulta#

Todos con Authorization: Bearer <api_key> y el prefijo de ambiente, salvo que se indique. Solo devuelven comprobantes del RNC de la key.

Errores de ecf/estado:

{ "error": true, "mensaje": "Comprobante no encontrado." }

(404). Sin track_id, encf ni ecf_queue_id: 422 con { "error": true, "mensaje": "Debe proveer al menos uno de: track_id, encf, ecf_queue_id." }.

Los endpoints /api/ecf/recibidos* y /api/pdf/{id} usan otra validación de key: una key inexistente o inactiva responde 401 {"message": "Token inválido"} (sin header: 401 {"message": "Token requerido"}).

Respuesta de ecf/estado:

{
  "status": true,
  "data": {
    "ecf_queue_id": 5678,
    "track_id": "a2b9c1d4-...",
    "encf": "E310000000001",
    "tipo_ecf": "31",
    "fecha_emision": "2026-10-01",
    "monto_total": "19706.00",
    "dgii": {
      "estado": "Aceptado",
      "codigo_respuesta": "1",
      "mensaje": null,
      "fecha_procesado": "2026-10-01T10:16:02-04:00",
      "intentos": 0
    },
    "comprador": {
      "rnc": "131000001",
      "estado": "entregado",
      "url": "...",
      "fecha": "...",
      "error": null,
      "arecf": "..."
    }
  }
}

(Valores ilustrativos.) dgii.mensaje trae los mensajes de la DGII (lista {codigo, valor}) o el texto del sistema que explica un fallido o una espera. comprador es null si no hay rnc_comprador.

Por qué la DGII rechazó un comprobante#

enviar-directo no puede decirte si la DGII va a rechazar el comprobante: responde antes de enviarlo (estado: pendiente). El motivo aparece después, cuando consultas el estado:

GET /{ambiente}/ecf/estado?encf=E310000000001

{
  "status": true,
  "data": {
    "ecf_queue_id": 5679,
    "track_id": "80ef4915-...",
    "encf": "E310000000001",
    "dgii": {
      "estado": "Rechazado",
      "codigo_respuesta": "2",
      "mensaje": [
        { "codigo": 145, "valor": "texto del motivo, tal como lo devuelve la DGII" }
      ],
      "fecha_procesado": "2026-10-25T12:20:11-04:00",
      "intentos": 0
    }
  }
}

(Valores ilustrativos.)

• dgii.mensaje es una lista {codigo, valor} con lo que respondió la DGII. Puede traer varios motivos; muéstralos todos. Si la DGII solo devolvió el mensaje vacío ({"codigo": 0, "valor": ""}), llega null.
• Es un texto en vez de lista cuando el mensaje lo pone el sistema: un fallido (por ejemplo, la DGII no aceptó la recepción) o el resultado de una verificación posterior que cambió el estado.
• codigo_respuesta es el código de la DGII: 1 Aceptado, 2 Rechazado, 3 En Proceso, 4 Aceptado Condicional.
• Lo mismo aplica a Aceptado Condicional: mensaje explica las observaciones.

GET /{ambiente}/factura/{factura_id}/estado también trae el motivo, en mensaje y en respuesta_dgii, pero ahí mensaje llega como texto JSON sin interpretar ("[{\"codigo\":145,...}]"). Para leer el motivo usa ecf/estado.

Un rechazado no se corrige reenviando el mismo e-NCF: enviar-directo responde 409 porque el comprobante ya existe en el sistema. Corrige lo que indica el mensaje y emite un comprobante nuevo.

9. Tablas de códigos#

Fuente: enumeraciones de los XSD oficiales de la DGII.

TipoeCF#

TipoIngresos#

TipoPago#

FormaPago#

tipo_pago (contado/crédito/gratuito) y forma_pago (cómo se pagó) son catálogos distintos: no pongas un código de forma de pago en tipo_pago.

IndicadorFacturacion#

IndicadorBienoServicio#

IndicadorMontoGravado#

CodigoModificacion#

Para notas de débito (33) y crédito (34).

IndicadorNotaCredito (34)#

IndicadorAgenteRetencionoPercepcion (41 y 47)#

UnidadMedida#

Catálogo completo en el XSD (UnidadMedidaType, códigos 1–62). Los más usados:

10. Resumen por tipo de comprobante#

Advertencia E46 y E47: la salida actual tiene limitaciones conocidas: el E46 no emite ningún MontoGravado*, ITBIS* ni TotalITBIS* (sus totales solo llevan MontoTotal y ValorPagar) y el E47 sale sin datos del comprador. No se ha verificado que la DGII los acepte; coordina con soporte antes de usarlos en produccion.

Qué emite el API por tipo (según el XSD y el constructor del XML):

11. Recetas: casos frecuentes#

Mi request a enviar-directo dio timeout#

No sabes si se procesó. Reenvía exactamente el mismo request: si el primero se procesó recibes 409 con el código de seguridad, la URL y el QR; si no, se procesa ahora. Ver 409.

La DGII rechazó el comprobante#

Consulta GET /{ambiente}/ecf/estado?encf=... y lee data.dgii.mensaje: es la lista {codigo, valor} que devolvió la DGII (detalle). Corrige y emite un comprobante nuevo; reenviar el mismo e-NCF devuelve 409.

Quedó Aceptado Condicional#

Tiene validez fiscal, no hay que reemitir. data.dgii.mensaje dice qué observó la DGII (por ejemplo, totales que no cuadran con el detalle). Revisa tu cálculo con la sección 5 para los próximos comprobantes.

Quedó fallido#

El comprobante no llegó a la DGII o la DGII no aceptó recibirlo. data.dgii.mensaje trae el texto del error. Corrige y emite de nuevo.

Sigue en pendiente o enviado después de varios minutos#

Es normal si la DGII está lenta: el sistema reintenta solo (ver estados). data.dgii.intentos dice cuántas veces lo intentó y data.dgii.mensaje qué está esperando.

Necesito el XML firmado otra vez#

GET /{ambiente}/ecf-queue/{ecf_queue_id}/xml (JSON con el campo xml) o GET /{ambiente}/ecf-queue/{ecf_queue_id}/descargar-xml (archivo {rnc}{encf}.xml).

Necesito el PDF#

GET /api/pdf/{ecf_queue_id} con tu API Key (header Authorization). Para mostrárselo a un cliente, descárgalo desde tu sistema y entrégale el archivo: el enlace no abre sin la key.

Tengo que anular o corregir una factura ya aceptada#

No se anula: se emite una nota de crédito (E34) que referencia la factura original, o una nota de débito (E33) para aumentar el monto. Ver E34 y E33.