API e-CF — VENTHOUSE TECHNOLOGY SRL

Emisión y consulta de Comprobantes Fiscales Electrónicos (e-CF) ante la DGII, República Dominicana. Un endpoint por empresa, identificada por su API Key.

Autenticación

Todas las rutas bajo /api/ecf/* requieren el header X-API-Key con la key entregada al aprobar el onboarding de tu empresa. Cada key identifica una empresa y aísla sus datos (secuencias NCF, e-CFs emitidos) — nunca se comparten entre empresas.

Header requerido

X-API-Key: tu_api_key_aqui
Content-Type: application/json

Si el header falta o la key no corresponde a una empresa activa, todas las rutas responden 401 con {"success": false, "error": "..."}.

POST/api/ecf/emitir

Construye, firma y envía un e-CF a la DGII. Soporta los 10 tipos de comprobante (31, 32, 33, 34, 41, 43, 44, 45, 46, 47). Si el eNCF no se envía, se asigna automáticamente de la secuencia de tu empresa. Para tipo 32 con monto < RD$250,000 se procesa como RFCE (resumen) según lo exige la DGII.

Campo	Tipo	Notas
`tipoeCF`	int	requerido — 31, 32, 33, 34, 41, 43, 44, 45, 46 o 47
`fecha_emision`	string	requerido
`items`	array	requerido — al menos 1 ítem
`rnc_comprador`	string	requerido para tipo 31, 34, 41, 45
`encf_referenciado`	string	requerido para tipo 33, 34 (nota que referencia otro e-CF)
`encf`	string	opcional — si no se envía, se asigna de la secuencia

Request

curl -X POST https://tu-dominio/api/ecf/emitir \
  -H "X-API-Key: tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "tipoeCF": 32,
    "fecha_emision": "2026-07-19",
    "items": [
      { "descripcion": "Lenovo P16 (RZ2B72XP)", "cantidad": 1, "precio_unitario": 1440.68, "itbis": 18 }
    ]
  }'

Response 202 Aceptado

{
  "success": true,
  "encf": "E320000025002",
  "tipoEcf": 32,
  "estado": "aceptado",
  "trackId": "abc123-track-id",
  "codigoSeguridad": "e7uml7",
  "xmlFirmado": "PD94bWwgdmVyc2lvbj0i...",
  "respuestaDGII": { "...": "..." },
  "timestamp": "2026-07-19T13:04:08.128-04:00"
}

GET/api/ecf/detalle/{encf}

Ficha de un e-CF ya emitido — NCF, monto, código de seguridad y el link/QR oficial de DGII para verificar el timbre, pensado para que tu propio POS lo muestre a un cajero o cliente (igual que la pantalla de "Detalle de venta" de cualquier POS con e-CF).

Response

{
  "success": true,
  "ecf": {
    "encf": "E320000025002",
    "tipo": 32,
    "tipo_descripcion": "Factura de Consumo Electrónica",
    "rnc_emisor": "132028414",
    "razon_social_emisor": "Mi Tienda SRL",
    "rnc_comprador": null,
    "monto_total": 1700.00,
    "total_itbis": 259.32,
    "track_id": "abc123-track-id",
    "estado": "aceptado",
    "codigo_seguridad": "e7uml7",
    "registrado_en": "2026-07-19 13:04:08",
    "ambiente": "testecf",
    "consulta_url": "https://fc.dgii.gov.do/testecf/ConsultaTimbreFC?RncEmisor=132028414&ENCF=E320000025002&MontoTotal=1700.00&CodigoSeguridad=e7uml7",
    "qr_url": "https://fc.dgii.gov.do/testecf/ConsultaTimbreFC?RncEmisor=132028414&ENCF=E320000025002&MontoTotal=1700.00&CodigoSeguridad=e7uml7"
  }
}

qr_url es el link — si prefieres la imagen ya generada, usa el endpoint de abajo en vez de generarla tú mismo.

GET/api/ecf/detalle/{encf}/qr.png

Devuelve la imagen PNG del QR ya generada (300×300, mismo contenido que qr_url) — úsalo directo en un <img src="...">, no hace falta que tu POS genere el QR.

Request

<img src="https://tu-dominio/api/ecf/detalle/E320000025002/qr.png">
<!-- el navegador no manda headers custom en <img>, asi que en produccion
     esta ruta normalmente se sirve detras de tu propio backend, que agrega
     el X-API-Key server-side antes de reenviar la imagen al cliente -->

Respuesta: image/png binario (no JSON). Si el eNCF no existe para tu empresa, responde 404 JSON normal.

GET/api/ecf/detalle/{encf}/pdf

Comprobante en PDF (encabezado, totales, QR) — pensado para "descargar factura" en tu POS.

Es un resumen, no una factura itemizada — no incluye la lista de productos/servicios (esa parte vive solo en el XML firmado que tu POS ya recibió al emitir). Respuesta: application/pdf.

POST/api/ecf/detalle/{encf}/reenviar-whatsapp

Envía el mismo PDF por WhatsApp (Evolution API) al número indicado — para el caso típico de "el cliente no se llevó el comprobante impreso".

Request

curl -X POST https://tu-dominio/api/ecf/detalle/E320000025002/reenviar-whatsapp \
  -H "X-API-Key: tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "numero": "18091234567" }'

Response

{ "success": true, "enviado_a": "18091234567" }

Reenvío por correo llega más adelante (falta configurar SMTP) — por ahora todo el reenvío es por WhatsApp.

GET/api/ecf/resultado/{trackId}

Consulta en vivo contra DGII el estado de validación de un envío. Si DGII responde "en proceso", reintenta automáticamente hasta 3 veces antes de devolver la respuesta.

Response

{
  "success": true,
  "resultado": { "codigo": 1, "eNCF": "E320000025002", "trackId": "abc123-track-id" },
  "estado_legible": "Aceptado"
}

GET/api/ecf/estado?encf=E320000025002

Consulta el estado de un e-CF por sus datos directamente (sin necesitar el trackId).

Query param	Notas
`encf`	requerido
`rnc_emisor`	opcional — por defecto el RNC de tu empresa
`rnc_comprador`	opcional
`codigo_seguridad`	opcional

GET/api/ecf/trackids?encf=E320000025002

Lista todos los trackId asociados a un eNCF (útil si un mismo comprobante se reenvió más de una vez).

GET/api/ecf/local/{encf}

Busca un e-CF en la base local de tu empresa (sin llamar a DGII) — más rápido para verificar que algo se emitió sin gastar una consulta contra DGII.

GET/api/ecf/secuencias

Estado de tus secuencias de eNCF por tipo — cuántos llevas emitidos y cuánto te queda antes de necesitar un nuevo lote autorizado por DGII.

Response

{
  "success": true,
  "ambiente": "testecf",
  "rnc_emisor": "132028414",
  "secuencias": {
    "31": { "descripcion": "Factura de Crédito Fiscal Electrónica", "actual": 12, "maximo": 10000000 },
    "32": { "descripcion": "Factura de Consumo Electrónica", "actual": 5002, "maximo": 50000000 }
  }
}

GET/api/ecf/directorio?rnc=101234567

Directorio de contribuyentes electrónicos de DGII. Sin rnc, devuelve el directorio completo — úsalo con moderación, es una lista grande.

GET/api/ecf/servicios

Health check de los servicios de DGII (autenticación, recepción, consulta). Útil para saber si un error viene de tu integración o de DGII.