API de facturación electrónica para la DGII

Cómo funciona la API

1. Validar (opcional). POST /{ambiente}/documentos-ecf?validate=true revisa el comprobante sin emitirlo ni gastar el e-NCF. Si algo no cuadra, responde 422 con el campo y el motivo.
2. Emitir. POST /{ambiente}/documentos-ecf responde 202 al instante con el documentId. La firma y el envío a la DGII corren por nuestra cuenta.
3. Consultar. POST /{ambiente}/documentos-ecf/status/batch devuelve, hasta 100 documentos por llamada, el estado en la DGII, el TrackID, el código de seguridad, el QR y los mensajes de la DGII.

El JSON usa la misma estructura y los mismos nombres de campo que el XML de la DGII (ECF → Encabezado → IdDoc, Emisor, Comprador, Totales, y DetallesItems), así que la documentación técnica de la DGII se aplica tal cual.

Ambientes

Entre ambientes solo cambian la URL base y la API key: el resto de tu código es igual.

Ejemplo: de la factura al e-CF aceptado

ZF=https://api.zarelafact.com/TesteCF

# 1. Validar sin emitir
curl "$ZF/documentos-ecf?validate=true" \
  -H "X-API-KEY: $ZARELA_API_KEY" \
  -H "Content-Type: application/json" \
  -d @factura.json

# 2. Emitir
curl "$ZF/documentos-ecf" \
  -H "X-API-KEY: $ZARELA_API_KEY" \
  -H "Content-Type: application/json" \
  -d @factura.json

# 3. Consultar el estado
curl "$ZF/documentos-ecf/status/batch" \
  -H "X-API-KEY: $ZARELA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "encfs": ["E310000000010"] }'

La emisión responde 202: el documento está en cola y lo identificas con su documentId.

{
  "ok": true,
  "mode": "queued",
  "result": {
    "documentId": "548fbebf-56bd-41b7-a612-917f3a72cac7",
    "encf": "E310000000010",
    "status": "queued_for_signing"
  }
}

El JSON completo de cada tipo de e-CF está en Ejemplos JSON por tipo.

Lo que la API resuelve por ti

• Validación contra el XSD de cada tipo y de los totales, antes de firmar.
• Conversión a XML y firma digital XMLDSig con tu certificado.
• Envío a la DGII: documento completo o resumen RFCE para las facturas de consumo menores de RD$250,000, según el monto.
• Reintentos seguros: el mismo JSON con el mismo e-NCF devuelve el documento original, nunca un duplicado.
• Contingencia automática cuando la DGII no responde.
• Recepción de los e-CF de tus proveedores, con acuse de recibo y aprobación comercial.
• Anulación de secuencias de e-NCF que no usaste.
• PDF tamaño carta y los datos para imprimir en tu propio formato, como un ticket de 80 mm.
• Custodia del XML firmado y de las respuestas de la DGII durante 10 años.

Estado y avisos

Consulta el estado por lote o recibe webhooks firmados cuando un e-CF cambia de estado o te llega uno de un proveedor. Los webhooks son opcionales: la consulta por lote siempre funciona. En el portal tienes además los logs DGII de cada documento: lo que se envió y lo que respondió la DGII.

Para ERP, POS y SaaS: la API Partner

• Una sola clave X-PARTNER-KEY para todos tus clientes.
• Una cuenta fiscal aislada por cada RNC.
• Tus clientes suben su certificado y se certifican ante la DGII desde tu producto.
• Portal Partner con las claves, el consumo y el estado de cada cliente.
• 30 % menos que una cuenta directa, con el volumen sumado de todos tus clientes.

Empieza por la guía de Partners.

Seguridad

• API keys por ambiente, enviadas en el header X-API-KEY, con permisos por perfil.
• Usuarios con roles y verificación en dos pasos en el portal.
• Cada documento queda con su XML firmado y las respuestas de la DGII.

Precios

Probar en TesteCF y certificarte en CerteCF es gratis. En producción, una empresa emite 50 e-CF al mes gratis y los planes van desde RD$595 al mes (100 e-CF) hasta RD$19,500 (10,000 e-CF), sin cobro por documento. Ver todos los planes.

Preguntas frecuentes

Sigue leyendo

• Facturación electrónica en RDQué es un e-CF, plazos de la Ley 32-23 y cómo elegir un sistema.
• Cómo certificarse ante la DGIIRequisitos, los 12 pasos de CerteCF y los errores más comunes.