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.
POST, firmado y enviado a DGII automáticamente.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.
Recibes un link de onboarding
Válido por 14 días, sin necesidad de crear una cuenta ni contraseña.
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.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).
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.
X-API-Key: tu_api_key_aqui
Content-Type: application/json
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ú.
| 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, 33, 34, 41, 45, 46, 47 (formato varía — ver formato por tipo) |
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 |
comprador anidado, tipo 47 pide pais_comprador, etc). Ver Formato de Documentos por tipo para el JSON completo de cada uno.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 }
]
}'
{
"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"
}
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").
{
"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.
<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".
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" }'
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.
{
"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 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.
{
"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 param | Notas |
|---|---|
desde / hasta | opcional — YYYY-MM-DD, filtra por fecha de registro |
tipo | opcional — filtra por tipo de e-CF |
estado | opcional |
limite | opcional — 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étodo | Ruta | Propósito |
|---|---|---|
| GET | /fe/autenticacion/api/semilla | Semilla para que el emisor se autentique contra tu sistema |
| POST | /fe/autenticacion/api/validacioncertificado | Valida el certificado del emisor que te envía el documento |
| POST | /fe/recepcion/api/ecf | Recibe el XML del e-CF y devuelve el acuse (ARECF) firmado |
| POST | /fe/aprobacioncomercial/api/ecf | Recibe/emite la aprobación comercial del documento recibido |
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.