API e-CF de CLIFACTUR

Emitimos, firmamos y enviamos tus Comprobantes Fiscales Electrónicos (e-CF) a la DGII, República Dominicana. Un endpoint por empresa, identificada por su propia API Key — tu sistema (POS, ERP, e-commerce) llama a nuestra API, nosotros nos encargamos de la firma XML, el envío, y de que cumpla el formato exigido por DGII.

Si tu empresa todavía no está certificada como emisor electrónico ante DGII, empieza por la guía de certificación paso a paso — nosotros construimos y firmamos el set de pruebas por ti, no tienes que hacerlo a mano.

Cómo obtener tu API Key

No hay registro público ni self-signup — CLIFACTUR opera bajo un modelo de onboarding asistido: tu contacto en VENTHOUSE (o el socio/revendedor que te atiende) te crea una solicitud y te manda un link único.

  1. Recibes un link de onboarding

    Válido por 14 días, sin necesidad de crear una cuenta ni contraseña.

  2. Llenas tus datos y subes tu certificado

    El certificado digital .p12 (el mismo que usas para firmar ante DGII) y su contraseña. Lo validamos ahí mismo — si algo está mal, te enteras al momento, no después.

  3. Te activan y recibes tu API Key

    Se muestra una única vez al aprobarse — cópiala de inmediato. Si la pierdes, se rota (no se recupera).

Si tu empresa todavía no está certificada como emisor electrónico ante DGII (es la primera vez que vas a facturar electrónicamente), ese es un paso previo — ver Certificación DGII — paso a paso.

Autenticación

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

Header requerido en cada request
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 en un solo llamado. Soporta los 10 tipos de comprobante. Si encf no se envía, se asigna automáticamente de tu secuencia. Para tipo 32 con monto < RD$250,000, se procesa como RFCE (resumen) — así lo exige DGII, no tienes que decidirlo tú.

CampoTipoNotas
tipoeCFintrequerido — 31, 32, 33, 34, 41, 43, 44, 45, 46 o 47
fecha_emisionstringrequerido
itemsarrayrequerido — al menos 1 ítem
rnc_compradorstringrequerido para tipo 31, 33, 34, 41, 45, 46, 47 (formato varía — ver formato por tipo)
encf_referenciadostringrequerido para tipo 33, 34 (nota que referencia otro e-CF)
encfstringopcional — si no se envía, se asigna de la secuencia
El formato exacto varía por tipo (32 y RFCE usan un objeto comprador anidado, tipo 47 pide pais_comprador, etc). Ver Formato de Documentos por tipo para el JSON completo de cada uno.
Request
curl -X POST https://api.clifactur.cloud/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"
}
422 si DGII rechazó el documento (el mensaje real de DGII viene en respuestaDGII) · 202 si fue aceptado o quedó en proceso con trackId · 502 si no se pudo comunicar con DGII.

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 (la pantalla de "Detalle de venta").

Response
{
  "success": true,
  "ecf": {
    "encf": "E320000025002",
    "tipo": 32,
    "tipo_descripcion": "Factura de Consumo Electrónica",
    "rnc_emisor": "132028414",
    "monto_total": 1700.00,
    "total_itbis": 259.32,
    "estado": "aceptado",
    "codigo_seguridad": "e7uml7",
    "ambiente": "testecf",
    "consulta_url": "https://fc.dgii.gov.do/testecf/ConsultaTimbreFC?...",
    "qr_url": "https://fc.dgii.gov.do/testecf/ConsultaTimbreFC?..."
  }
}

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

La imagen PNG del QR ya generada (300×300) — úsala directo en un <img>, no hace falta que tu POS genere el QR.

Como <img> no manda headers custom, en producción esta ruta normalmente se sirve detrás de tu propio backend, que agrega el X-API-Key server-side antes de reenviar la imagen. Respuesta: image/png binario.

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

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

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

La misma información, pero con la tabla completa de ítems (parseada del XML ya firmado) — para cuando necesitas mostrar el detalle línea por línea, no solo el total.

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

Envía el PDF por WhatsApp al número indicado — para "el cliente no se llevó el comprobante impreso".

Request
curl -X POST https://api.clifactur.cloud/api/ecf/detalle/E320000025002/reenviar-whatsapp \
  -H "X-API-Key: tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "numero": "18091234567" }'
Reenvío por correo llega más adelante (SMTP pendiente) — 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"
}
Código de estado: 0 No encontrado · 1 Aceptado · 2 Rechazado · 3 En proceso · 4 Aceptado condicional.

GET/api/ecf/estado?encf=E320000025002

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

Query paramNotas
encfrequerido
rnc_emisoropcional — por defecto el RNC de tu empresa
rnc_compradoropcional
codigo_seguridadopcional

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 tu base local, sin llamar a DGII — más rápido para verificar que algo se emitió sin gastar una consulta.

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/documentos

Listado de documentos emitidos, con filtros — para construir tu propio reporte o pantalla de "mis facturas" dentro de tu sistema.

Query paramNotas
desde / hastaopcional — YYYY-MM-DD, filtra por fecha de registro
tipoopcional — filtra por tipo de e-CF
estadoopcional
limiteopcional — por defecto 500, máximo 2000

GET/api/ecf/documentos/exportar.csv

Mismo listado que /documentos, mismos filtros, como descarga CSV directa (columnas: eNCF, Tipo, RNC Comprador, Monto Total, ITBIS, Estado, Track ID, Registrado).

GET/api/ecf/consumo?mes=AAAA-MM

Uso del mes de tu empresa: e-CF emitidos por tipo y por estado (aceptados, rechazados, otros), monto total, ITBIS y cantidad de facturas recibidas de proveedores. Sin mes toma el mes actual. Es informativo: la facturación electrónica está incluida en tu plan.

GET/api/ecf/recibidos

Las facturas electrónicas que tus proveedores te enviaron (llegan a tu subdominio, ver Recepción B2B). Cada una trae clave (RNC emisor + e-NCF), tipo, emisor, fecha, monto, cuándo llegó, tu aprobación comercial (aprobacion) y el último estado en la DGII (estado_dgii).

GET/api/ecf/recibidos/{clave}/estado

Consulta en vivo a la DGII el estado de una factura que te emitieron (como comprador: RNC emisor, e-NCF, tu RNC y el código de seguridad de la factura) y devuelve el historial de todas las consultas con fecha y hora: Aceptado, Rechazado, Aceptado Condicional, En Proceso o No encontrado. Con ?solo_historial=1 no consulta, solo devuelve el historial. La DGII da el estado, no los mensajes de rechazo (esos solo los recibe quien emitió). En el ambiente de certificación la DGII no ofrece esta consulta: responde no_disponible.

POST/api/ecf/recibidos/{clave}/aprobar

Envía a la DGII tu Aprobación Comercial (ACECF) de una factura recibida. Cuerpo: {"estado": 1} para aceptarla o {"estado": 2, "motivo": "..."} para rechazarla.

Recepción B2B — recibir e-CF de otro contribuyente

Si tu empresa también recibe facturas electrónicas de sus proveedores (no solo emite), DGII exige que expongas estos 4 endpoints en tu propio subdominio — no bajo X-API-Key, porque quien te llama es el sistema de otro contribuyente que no conoce ninguna key nuestra. El candado aquí es tu subdominio asignado (tuempresa.api.clifactur.cloud), no un header.

MétodoRutaPropósito
GET/fe/autenticacion/api/semillaSemilla para que el emisor se autentique contra tu sistema
POST/fe/autenticacion/api/validacioncertificadoValida el certificado del emisor que te envía el documento
POST/fe/recepcion/api/ecfRecibe el XML del e-CF y devuelve el acuse (ARECF) firmado
POST/fe/aprobacioncomercial/api/ecfRecibe/emite la aprobación comercial del documento recibido
Tu subdominio se genera automáticamente al activarte (a partir de tu razón social) y queda cubierto por un certificado wildcard — no tienes que configurar nada de SSL tú mismo.

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 antes de escribirnos.