Envío de e-CF
- Haz
POST /{ambiente}/documentos-ecfcon el JSON del comprobante (formato, ejemplos por tipo). - Recibes al instante
202con eldocumentId. Guárdalo junto al eNCF. - Unos segundos después, consulta el estado: en cuanto la DGII responde (TrackID del e-CF o respuesta del resumen RFCE) llegan el código de seguridad y el QR para imprimir. Un punto de venta puede recibirlos en la misma respuesta con
Prefer: wait=10(ver más).
Mientras desarrollas, agrega ?validate=true para encontrar errores sin emitir (ver más).
Endpoint
POST /{ambiente}/documentos-ecf
{ambiente} es TesteCF, CerteCF o eCF.
X-API-KEY: {tu_api_key}
Content-Type: application/json
El cuerpo es el JSON del comprobante, con el eNCF que asignó tu sistema.
Ejemplo: factura de consumo con varias tasas
Factura de consumo (32) con un producto exento, uno al 16 % y otro al 18 % con descuento:
{
"ECF": {
"Encabezado": {
"Version": "1.0",
"IdDoc": {
"TipoeCF": 32,
"eNCF": "E320000000010",
"IndicadorMontoGravado": 0,
"TipoIngresos": "01",
"TipoPago": 1
},
"Emisor": {
"RNCEmisor": "{{RNC}}",
"RazonSocialEmisor": "{{RAZON_SOCIAL}}",
"DireccionEmisor": "{{DIRECCION_EMISOR}}",
"FechaEmision": "01-10-2026"
},
"Comprador": {
"RazonSocialComprador": "CONSUMIDOR FINAL"
},
"Totales": {
"MontoGravadoTotal": 774.00,
"MontoGravadoI1": 324.00,
"MontoGravadoI2": 450.00,
"MontoExento": 70.00,
"ITBIS1": 18,
"ITBIS2": 16,
"TotalITBIS": 130.32,
"TotalITBIS1": 58.32,
"TotalITBIS2": 72.00,
"MontoTotal": 974.32
}
},
"DetallesItems": {
"Item": [
{
"NumeroLinea": 1,
"IndicadorFacturacion": 4,
"NombreItem": "Agua mineral 500 ml",
"IndicadorBienoServicio": 1,
"CantidadItem": 2,
"UnidadMedida": 43,
"PrecioUnitarioItem": 35.00,
"MontoItem": 70.00
},
{
"NumeroLinea": 2,
"IndicadorFacturacion": 2,
"NombreItem": "Café molido 1 lb",
"IndicadorBienoServicio": 1,
"CantidadItem": 1,
"UnidadMedida": 43,
"PrecioUnitarioItem": 450.00,
"MontoItem": 450.00
},
{
"NumeroLinea": 3,
"IndicadorFacturacion": 1,
"NombreItem": "Detergente líquido 1 L",
"IndicadorBienoServicio": 1,
"CantidadItem": 2,
"UnidadMedida": 43,
"PrecioUnitarioItem": 180.00,
"DescuentoMonto": 36.00,
"TablaSubDescuento": {
"SubDescuento": [
{
"TipoSubDescuento": "%",
"SubDescuentoPorcentaje": 10.00,
"MontoSubDescuento": 36.00
}
]
},
"MontoItem": 324.00
}
]
}
}
}
- Exento: el agua lleva
IndicadorFacturacion4 y suma enMontoExento. - Dos tasas: el café va al 16 % (
IndicadorFacturacion2) y el detergente al 18 % (1). Cada tasa tiene su base (MontoGravadoI2,MontoGravadoI1) y su ITBIS (TotalITBIS2,TotalITBIS1). - Descuento: el detergente lleva un 10 % (
DescuentoMontoyTablaSubDescuento); suMontoItemya lo resta. - Consumidor final: el 32 siempre lleva la sección
Comprador, pero por debajo de RD$250,000 basta conRazonSocialComprador. Desde RD$250,000 el comprador va identificado conRNCCompradoro, si es extranjero, conIdentificadorExtranjero(nunca los dos); si falta, la API responde422condetails.codeBUYER_ID_REQUIRED.
Validar sin emitir
Agrega ?validate=true para revisar el documento sin emitirlo:
POST /{ambiente}/documentos-ecf?validate=true
ZarelaFact revisa la estructura, los cálculos y los totales, genera el XML que enviaría y lo valida contra el XSD oficial del tipo. No firma, no envía nada a la DGII y no registra el eNCF, así que puedes repetir la validación con el mismo número.
El eNCF es obligatorio también al validar con el formato DGII (IdDoc.eNCF). Solo el contrato simplificado deja omitir encf: valida con un eNCF temporal y lo avisa en warnings. Lo mejor es validar con el número real que vas a asignar, porque así también se revisan su rango y su vencimiento. Si registraste rangos de ese tipo, un eNCF fuera de ellos responde 409 ENCF_NOT_IN_REGISTERED_RANGE también al validar.
Respuesta correcta (200, resumida):
{
"ok": true,
"mode": "preflight",
"environment": "testecf",
"correlationId": "ba8f33a2-acfe-4b60-9717-f0ad239318a1",
"preflight": {
"type": "E32",
"encf": "E320000000010",
"lineCount": 3,
"totals": { "taxableAmount": 774, "exemptAmount": 70, "tax": 130.32, "total": 974.32 },
"xsd": { "validated": true, "ok": true, "schema": "e32.xsd", "errors": [] }
},
"dgiiJson": { "Encabezado": { "...": "el JSON ordenado tal como se convertirá a XML" } },
"errors": [],
"warnings": [],
"dgiiPrediction": {
"status": "accepted",
"reasons": [],
"disclaimer": "Predicción orientativa: la DGII tiene la última palabra."
}
}
Respuesta con errores (422, resumida). Cada error indica el campo exacto:
{
"ok": false,
"mode": "preflight",
"correlationId": "9857fe46-8007-4902-a2bb-b4f7939aca26",
"errors": [
{
"field": "ECF.Encabezado.IdDoc.FechaVencimientoSecuencia",
"message": "FechaVencimientoSecuencia no aplica a E32 según el XSD oficial DGII; omite el campo",
"severity": "error",
"details": { "code": "SEQUENCE_EXPIRATION_DATE_NOT_APPLICABLE" }
}
],
"warnings": []
}
| Campo | Qué es |
|---|---|
errors[].field | Ruta del campo con el problema. |
errors[].message | Qué está mal, en español. |
errors[].details | Cuando aplica: valores esperados y recibidos, o un código como SEQUENCE_EXPIRATION_DATE_REQUIRED. |
preflight.xsd | Resultado de la validación contra el XSD oficial. |
correlationId | Identificador de la solicitud para soporte. |
dgiiPrediction: qué diría la DGII. La respuesta de ?validate=true trae también este campo, en las respuestas 200 y 422. Dice si la DGII aceptaría el documento (accepted), lo aceptaría como Aceptado condicional (accepted_conditional) o lo rechazaría (rejected), y por qué:
| Campo | Qué es |
|---|---|
dgiiPrediction.status | accepted, accepted_conditional o rejected. |
dgiiPrediction.reasons[] | Un motivo por cada aviso o error de la revisión. |
reasons[].code | Código de ZarelaFact, por ejemplo SQUARING_ABOVE_DGII_TOLERANCE. null si no tiene. |
reasons[].dgiiCode | El código DGII que devolvería, por ejemplo 2394. null si no tiene uno. |
reasons[].field | Campo de tu JSON al que se refiere. |
reasons[].message | Qué pasa, en español. |
reasons[].severity | error o warning. |
reasons[].effect | rejects lo rechazaría, conditional lo dejaría Aceptado condicional e info solo informa. |
dgiiPrediction.disclaimer | «Predicción orientativa: la DGII tiene la última palabra.» |
Es solo orientación. Sale de los mismos errores y avisos de la respuesta, así que no cambia ok, ni el código HTTP, ni lo que bloquea. No aparece en la emisión real: solo en ?validate=true.
Valida durante el desarrollo y en tus pruebas automáticas: como no se registra nada, iteras sobre el mismo documento sin gastar eNCF.
¿Validar o probar en el Sandbox? ?validate=true revisa la forma y los cálculos de tu JSON sin registrar nada. El Sandbox además te dice qué respondería la DGII (aceptado, condicional o rechazado) con los motivos, y guarda el documento para revisarlo después. No necesita certificado. Como guarda el documento, un e-NCF que ya usaste en el Sandbox se rechaza (1209); con ?validate=true puedes repetir el mismo número.
Emitir
TesteCF lo comparten todos los integradores de la DGII, y las secuencias bajas, como E310000000001, ya las usaron otros: la DGII responde «ya utilizado». Para tus pruebas usa secuencias altas, por ejemplo E310009000001.
Envía el mismo JSON sin validate:
- cURL
- JavaScript
- C#
- PHP
curl -X POST \
https://api.zarelafact.com/TesteCF/documentos-ecf \
-H 'X-API-KEY: zrl_test_...' \
-H 'Content-Type: application/json' \
-d @factura.json
async function emitir(documento) {
const response = await fetch("https://api.zarelafact.com/TesteCF/documentos-ecf", {
method: "POST",
headers: {
"X-API-KEY": process.env.ZARELA_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify(documento),
});
return await response.json(); // { ok, mode, result: { documentId, encf, status } }
}
var content = new StringContent(documentoJson, Encoding.UTF8, "application/json");
var response = await client.PostAsync(
"https://api.zarelafact.com/TesteCF/documentos-ecf", content);
var body = await response.Content.ReadAsStringAsync();
// 202: guarda result.documentId junto al eNCF de la venta
<?php
$ch = curl_init('https://api.zarelafact.com/TesteCF/documentos-ecf');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['X-API-KEY: ' . $apiKey, 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode($documento),
]);
$respuesta = json_decode(curl_exec($ch), true);
curl_close($ch);
Respuesta (202, resumida):
{
"ok": true,
"mode": "queued",
"environment": "testecf",
"correlationId": "33367451-bc0c-48fa-aaea-7c1b9f6fafc6",
"result": {
"documentId": "548fbebf-56bd-41b7-a612-917f3a72cac7",
"encf": "E320000000010",
"status": "queued_for_signing",
"qrUrl": null,
"securityCode": null,
"asyncStatusRequired": true
},
"errors": [],
"warnings": []
}
| Campo | Qué es |
|---|---|
result.documentId | Identificador del documento en ZarelaFact. Guárdalo junto al eNCF. |
result.encf | El eNCF que enviaste. |
result.status | Estado inicial: queued_for_signing. |
result.securityCode, result.qrUrl | null en el 202: llegan en la consulta en cuanto la DGII responde, o en la misma respuesta si pides esperarla. |
correlationId | Identificador de la solicitud para soporte. |
202 significa recibido y en cola, no aceptado por la DGII.
Antes de responder 202, la emisión corre la misma validación que ?validate=true: estructura, cálculos, cuadre y XSD oficial del tipo. Si algo falla, responde 422 con los mismos errors y no registra el documento, así que puedes corregirlo y emitirlo con el mismo eNCF. Si el documento tiene un aviso (por ejemplo, un dato que el tipo no lleva y se omitió, o un descuadre por encima de la tolerancia de la DGII, SQUARING_ABOVE_DGII_TOLERANCE, que la DGII deja Aceptado Condicional), viene en warnings y el documento se emite.
Respuesta inmediata para imprimir
Un punto de venta necesita el código de seguridad y el QR para imprimir el ticket. En vez de consultar después de emitir, pide que la emisión espere con la cabecera Prefer: wait=10:
- cURL
- JavaScript
curl -X POST \
https://api.zarelafact.com/TesteCF/documentos-ecf \
-H 'X-API-KEY: zrl_test_...' \
-H 'Content-Type: application/json' \
-H 'Prefer: wait=10' \
-d @factura.json
async function emitirParaImprimir(documento) {
const response = await fetch("https://api.zarelafact.com/TesteCF/documentos-ecf", {
method: "POST",
headers: {
"X-API-KEY": process.env.ZARELA_API_KEY,
"Content-Type": "application/json",
Prefer: "wait=10",
},
body: JSON.stringify(documento),
});
const body = await response.json();
// 201: la DGII ya respondió, imprime con result.printing.
// 202: no respondió a tiempo, consulta hasta que printing deje de ser null.
return { listoParaImprimir: response.status === 201, body };
}
ZarelaFact espera hasta esos segundos a que la representación impresa se pueda entregar. La DGII fija el orden (Informe Técnico e-CF v1.0, secciones 8 y 9.1): primero recibe el comprobante y responde, y después el emisor entrega la representación impresa. Por eso la espera no termina al firmar, sino cuando:
- la DGII devuelve el TrackID del e-CF (todos los tipos, incluida la factura de consumo de RD$250,000 o más);
- la DGII responde Aceptado o Aceptado Condicional al resumen RFCE de una factura de consumo menor a RD$250,000;
- o el envío del documento se difiere por contingencia (se imprime con la leyenda de
result.printing.legends, yresult.contingencytrae desde cuándo).
| Respuesta | Qué significa |
|---|---|
201 con Preference-Applied: wait=10 | La DGII respondió. result.securityCode, result.qrUrl y result.printing traen lo necesario para imprimir. |
202 con Retry-After | La DGII no respondió a tiempo, o rechazó el resumen RFCE. Es la respuesta de siempre: consulta hasta que printing deje de ser null; si printingStatus es rejected, no imprimas. |
Respuesta (201, resumida):
{
"ok": true,
"mode": "queued",
"environment": "testecf",
"correlationId": "33367451-bc0c-48fa-aaea-7c1b9f6fafc6",
"effects": { "signed": true, "dgiiSubmitted": true, "queued": true },
"result": {
"documentId": "548fbebf-56bd-41b7-a612-917f3a72cac7",
"encf": "E320000000010",
"documentType": "E32",
"status": "accepted",
"dgiiStatus": "Aceptado",
"trackId": null,
"securityCode": "Xy9Z8w",
"qrUrl": "https://fc.dgii.gov.do/testecf/ConsultaTimbreFC?RncEmisor={{RNC}}&ENCF=E320000000010&MontoTotal=974.32&CodigoSeguridad=Xy9Z8w",
"printing": {
"securityCode": "Xy9Z8w",
"signatureDate": "01-10-2026 10:29:40",
"qrUrl": "https://fc.dgii.gov.do/testecf/ConsultaTimbreFC?RncEmisor={{RNC}}&ENCF=E320000000010&MontoTotal=974.32&CodigoSeguridad=Xy9Z8w",
"legends": []
},
"printingStatus": "available",
"dgiiMessages": [],
"lastError": null,
"contingency": null,
"asyncStatusRequired": false
},
"errors": [],
"warnings": []
}
- N va de 1 a 15 segundos. Un valor mayor cuenta como 15. Un valor inválido (
wait=0,wait=abc) se ignora y la emisión responde202enseguida, como sin la cabecera. - Nunca espera más de N segundos, contados desde que llega la solicitud. Configura el timeout de tu cliente HTTP por encima de N.
- Normalmente la DGII responde en pocos segundos;
wait=10deja margen. La validación y los errores (422,409…) son los mismos de siempre. - Reintentos: el mismo JSON con el mismo eNCF y
Prefer: waitdevuelve el documento que ya existe. Si ya se puede imprimir, responde201sin esperar. - La aceptación final de un e-CF con TrackID sigue siendo asíncrona. Con el TrackID ya puedes imprimir el QR (Representación impresa), y el estado final ante la DGII llega después por la consulta o los webhooks.
asyncStatusRequiredsigue entruehasta un estado final. Una factura de consumo menor a RD$250,000 llega con su estado final, porque la DGII responde el resumen al recibirlo.
Aviso sobre el RNC del comprador
ZarelaFact revisa el RNC o la cédula del comprador en el padrón de contribuyentes que publica la DGII. Si no aparece o no está activo, la validación y la emisión siguen adelante y agregan un aviso en warnings:
warnings[].details.code | Qué significa |
|---|---|
BUYER_RNC_NOT_IN_DGII_REGISTRY | El RNC o la cédula no aparece en el padrón. Revisa el número antes de emitir un comprobante de crédito fiscal. |
BUYER_RNC_NOT_ACTIVE_IN_DGII | Aparece con otro estado (en details.status), por ejemplo suspendido o dado de baja. |
Estos avisos nunca bloquean la emisión: el padrón se publica una vez al día, una inscripción reciente puede no aparecer todavía y la DGII tiene la última palabra. Un RNC tampoco se rechaza por su dígito verificador.
Qué pasa después del 202
- ZarelaFact convierte el JSON a XML y lo firma con tu certificado.
- Lo envía a la DGII enseguida: el documento completo o, si es un 32 menor a RD$250,000, el resumen RFCE. Cuando la DGII responde (TrackID o respuesta del resumen), la consulta trae
printing, con el código de seguridad y el QR. - Sigue la respuesta de la DGII hasta el estado final y guarda el XML firmado 10 años.
- Si el comprador es receptor electrónico, le entrega el e-CF cuando la DGII lo acepta. Ver Entrega al comprador.
Si la DGII no está disponible, el documento pasa a contingency y ZarelaFact lo reintenta solo hasta que la DGII responda. No lo reenvíes. Ver Contingencia.
Si la DGII responde pero no recibe el documento por algo de toda la cuenta (por ejemplo, porque tu certificado no está delegado), el documento se queda en signed, la consulta trae el motivo en lastError y ZarelaFact lo reintenta solo. Si el envío falla de forma definitiva (la DGII rechaza la recepción, el XML no pasa el XSD o no hay un certificado activo), el documento pasa a transmission_failed: no llegó a la DGII y no se reintenta solo. Ver Por qué un documento no avanza.
Estados del documento
| Estado | Qué significa |
|---|---|
queued_for_signing | Recibido y en cola para firmarse. |
signed | Firmado, esperando el envío a la DGII. Todavía no se imprime (printing es null). Si no avanza, lastError dice por qué. |
rfce_pending_dispatch | Factura de consumo menor a RD$250,000 cuyo resumen RFCE quedó para el envío programado. Normalmente no aparece: el resumen sale al firmar. Si el envío programado falla, lastError dice por qué; si la DGII no responde, pasa a contingency. |
sent | Enviado a la DGII, que devolvió el TrackID. Desde aquí se imprime. |
pending_dgii_status | Esperando la respuesta final de la DGII. |
accepted | Final. Aceptado por la DGII. |
accepted_conditional | Final. Aceptado con observaciones; revisa dgiiMessages. |
rejected | Final. Rechazado; el motivo está en dgiiMessages. |
contingency | La DGII no respondió; ZarelaFact reintenta solo hasta que responda. |
transmission_failed | El envío a la DGII falló de forma definitiva, o algo impide transmitirlo (por ejemplo, no hay un certificado activo). La DGII no lo tiene y ZarelaFact no lo reintenta solo: lastError dice por qué, con retrying: false. No es final: corrige la causa y reenvíalo desde el portal (se envía el mismo XML firmado, sin firmarlo otra vez), o anula su eNCF con una ANECF. Un Partner no puede reenviarlo, ni por la API ni en el portal: anula su eNCF y emite la venta con un eNCF nuevo. |
cancelled | Cancelado. Por ejemplo, su eNCF se anuló con una ANECF aceptada antes de enviarse: ya no se envía a la DGII. |
accepted_conditional es un estado final y válido, pero la DGII dejó observaciones (por ejemplo, diferencias de redondeo). Muéstralas a quien factura y corrige la causa en las próximas emisiones.
Facturas de consumo (32) y resumen RFCE
La factura de consumo es la que entregas al consumidor final. No da derecho a crédito fiscal. La DGII la recibe de dos maneras según el monto:
| Modalidad | Qué recibe la DGII | Cuándo |
|---|---|---|
| Documento completo | Encabezado y todas las líneas | MontoTotal de RD$250,000 o más |
| Resumen (RFCE) | Totales, eNCF y código de seguridad | MontoTotal menor a RD$250,000 |
Tú siempre envías el documento completo. ZarelaFact mira el MontoTotal y decide:
- Por debajo de RD$250,000 envía el resumen, con el código de seguridad del documento firmado, y guarda el documento completo firmado durante 10 años. El documento completo también se valida contra el XSD de la factura de consumo, porque es el que recibe tu cliente.
- La forma de pago (
TablaFormasPago, por ejemplo la tarjeta) va solo en el documento completo. El resumen llevaTipoPagopero no la tabla, porque la DGII rechaza el resumen que la incluye. - Desde RD$250,000 envía el documento completo, y el comprador debe estar identificado con RNC, cédula o, si es extranjero, identificador extranjero. Las notas de débito y crédito que modifican una de estas facturas, también.
- No necesitas guardar los XML para cumplir la conservación de 10 años: ZarelaFact lo hace.
Cómo se envía el resumen:
- Sale apenas se firma la factura, como pide la DGII: mientras el resumen no llega, la consulta del QR que hace el consumidor no encuentra la factura. Un envío nocturno queda solo como red de seguridad para algún resumen que se haya quedado pendiente (
rfce_pending_dispatch). Si ese envío nocturno encuentra la DGII caída, el documento pasa acontingencyy se reintenta igual que un envío normal; si falla por otra causa,lastErrordice por qué y se intenta de nuevo en el siguiente envío nocturno. - Si la DGII corta la conexión o responde que el resumen ya existe («Registro duplicado»), ZarelaFact pregunta su estado en la consulta de resúmenes de la DGII (ConsultaRFCE). Si la DGII ya lo tiene aceptado o rechazado, ese es el estado final; si no lo encuentra, envía otra vez el mismo resumen.
- La factura nunca se vuelve a firmar: cambiaría el código de seguridad de la representación impresa que tu cliente ya pudo recibir.
- Si la DGII rechaza el resumen, el documento queda
rejectedcon susdgiiMessages, igual que cualquier otro rechazo. Reenvía la versión corregida con el mismo eNCF: se acepta si la DGII indicó que la secuencia se puede reutilizar; si responde409, emite un comprobante nuevo (ver Corregir y reenviar un rechazo).
Contingencia
Cuando la DGII no responde (sin conexión, tiempo de espera, errores 5xx o su autenticación caída), el documento pasa a contingency:
- No hay una ventana fija: ZarelaFact reintenta con espera creciente (5 minutos, el doble cada vez, hasta un intento cada 30 minutos) y lo envía en cuanto la DGII vuelve. Un documento en contingencia nunca se abandona.
- Cuando la DGII vuelve a responder en ese ambiente, los documentos en contingencia se reintentan enseguida, sin esperar su turno. En su historial queda el paso «Contingencia: reintento adelantado».
- Cómo sabemos que la DGII no responde: cada ambiente (TesteCF, CerteCF y eCF) se juzga por separado, con dos fuentes:
- Una revisión cada minuto: ZarelaFact pide la semilla de autenticación de la DGII, sin certificado ni efecto fiscal. Cuenta como falla si no hay conexión, si tarda más de 10 segundos, si responde un error HTTP o si responde algo que no es la semilla (por ejemplo, una página de mantenimiento).
- Los envíos y consultas de todas las cuentas: cualquier respuesta de la DGII, también un rechazo, cuenta como que respondió; un envío que entra en contingencia cuenta como falla.
- La revisión no afecta tu servicio: es una petición pequeña por ambiente cada minuto, que corre aparte de los envíos. No usa tu certificado, no consume tu plan y no hace más lentas tus llamadas a la API.
- Cuándo se declara caída: con 3 fallas entre los últimos 5 resultados de los últimos 10 minutos. Vuelve a estar disponible con 3 respuestas seguidas. Una falla suelta no basta, así el aviso no se enciende y se apaga a cada rato. Sin envíos en curso, cada cambio tarda unos 3 minutos en notarse; con envíos, menos.
- Aviso a todas las cuentas: al declararla caída, el portal muestra un aviso arriba y cada cuenta activa de ese ambiente recibe el webhook
dgii.service_degraded, aunque no esté enviando. Al volver, recibedgii.service_restoredy los documentos en contingencia salen enseguida (ver Webhooks). - Tu propio envío avisa antes: si un envío tuyo entra en contingencia, tu cuenta recibe
dgii.service_degradeden ese momento, sin esperar las 3 fallas, y la siguiente respuesta de la DGII a uno de tus envíos te mandadgii.service_restored. Por eso tus webhooks pueden adelantarse al aviso del portal, que sigue el estado general del ambiente. - A las 72 horas sin llegar a la DGII, el equipo de ZarelaFact recibe una alerta y el documento sigue reintentándose.
- La representación impresa de un e-CF cuyo envío se difirió lleva la leyenda literal de la DGII: «e-CF emitido en modalidad de Contingencia, el cual podrá ser consultado para su validez fiscal, a partir de las setenta y dos (72) horas.» La consulta y el webhook traen el antecedente para siempre, aunque después la DGII lo acepte:
contingency.startedAty la leyenda enprinting.legends. Si la DGII ya tenía el e-CF (TrackID) y solo dejó de responder la consulta de su estado, no se emitió en contingencia y no lleva la leyenda. Ver Leyendas. - No lo reenvíes ni lo anules: un eNCF en contingencia va a llegar a la DGII.
GET /{ambiente}/contingencialista los que esperan; ver Documentos en contingencia. - Si el envío falla de forma definitiva (no es una caída: la DGII rechaza la recepción, o no hay un certificado activo), el documento pasa a
transmission_failedy deja de reintentarse: corrige la causa y reenvíalo desde el portal con el mismo XML firmado, o anula su eNCF. - Sin comprobantes de papel: mientras la DGII no responde no hace falta facturar en papel (serie B). ZarelaFact no emite e-CF que reemplazan comprobantes de papel:
CodigoModificacion4responde422condetails.codeCONTINGENCY_PAPER_REPLACEMENT_UNSUPPORTED. Ver Contingencia: sin comprobantes de papel.
DGII lenta
A veces la DGII responde pero no procesa: recibe el e-CF, da su TrackID y contesta cada consulta al instante, pero lo deja «En Proceso» mucho más de lo normal antes de aceptarlo o rechazarlo. No es una caída: el documento no pasa a contingency y sigue en sent o pending_dgii_status.
- Cómo se decide: cada ambiente (TesteCF, CerteCF y eCF) por separado. Cada minuto ZarelaFact cuenta los e-CF de todas las cuentas que la DGII tiene «En Proceso». La DGII está lenta si en la última media hora hubo 2 e-CF distintos esperando más de 5 minutos, o si uno solo lleva más de 15. Vuelve a la normalidad cuando pasa media hora sin ninguno esperando más de 5 minutos. Lo normal es que la DGII resuelva en segundos.
- Aviso a todas las cuentas: el portal muestra un aviso arriba y cada cuenta activa de ese ambiente recibe el webhook
dgii.service_slow, aunque no esté enviando. Al terminar recibedgii.service_slow_cleared(ver Webhooks). Una vez por episodio, no por documento. - Si además la DGII deja de responder, manda el aviso de contingencia: mientras la DGII no responde no se declara lenta.
- Qué hacer: nada. ZarelaFact sigue consultando el estado de cada e-CF y su estado avanza en cuanto la DGII responde. No lo reenvíes ni lo anules: la DGII ya lo tiene.
Entrega al comprador
Si tu comprador es receptor electrónico, la DGII pide que también le llegue el e-CF. ZarelaFact se lo entrega solo, después de que la DGII lo acepta (o lo acepta condicionalmente):
- Qué se entrega: los tipos 31, 33, 34, 44 y 45 con
RNCComprador. Las facturas de consumo (32) y los tipos 41, 43, 46 y 47 no se entregan a un receptor. - Dónde: ZarelaFact busca la URL de recepción del comprador en el directorio de la DGII, con el token DGII de tu cuenta, en
TesteCFyeCF. EnCerteCFno hay directorio ni entrega. EnTesteCFel directorio de la DGII da su emisor-receptor simulado para cualquier RNC: si el comprador es cliente de ZarelaFact, se le entrega en el receptor de TesteCF de ZarelaFact. Ver Recibir e-CF en TesteCF. - Comprador que no es receptor electrónico: si el directorio no lo tiene, le entregas la representación impresa como siempre. ZarelaFact lo registra en el documento como
receiverDelivery.state=not_electronic; no es un error y no cambia el estado fiscal del documento. - Autenticación del receptor: si el comprador declaró en el directorio su servicio de autenticación, ZarelaFact pide su semilla, la firma con tu certificado y envía el e-CF con el token que recibe.
- Reintentos acotados: si el receptor no responde, o responde un error sin acuse válido, ZarelaFact reintenta con espera creciente hasta 5 veces. Un acuse (ARECF) con motivo 3 («envío duplicado») cuenta como entregado: el receptor ya lo tenía. Un acuse «e-CF No Recibido» por otro motivo es una entrega fallida y no se reintenta.
- Sin confirmación: si después de los reintentos el receptor nunca respondió, la entrega queda incierta (
uncertain). Cuando tengas el ARECF firmado del comprador, regístralo conPOST /{ambiente}/documentos-ecf/{documentId}/entrega-receptor/reconciliar(ver el OpenAPI).
Errores y reintentos
La regla principal: si no sabes si una emisión llegó, reenvía el mismo JSON con el mismo eNCF. ZarelaFact identifica cada emisión por cuenta, ambiente y eNCF: el mismo eNCF con el mismo JSON devuelve el documento que ya existe y no crea otro. La única excepción es un documento que la DGII rechazó con secuenciaUtilizada: false: ahí el mismo JSON se reenvía con el mismo eNCF (ver Corregir y reenviar un rechazo).
Qué hacer según la respuesta
| Respuesta | Qué hace tu sistema |
|---|---|
400 o 422 | Corrige el documento. No reintentes el mismo contenido. |
401 | Detén el envío y corrige la API key del ambiente. |
403 | Detén el envío: la clave no tiene el permiso necesario. |
409 | Lee error.code (ver la tabla siguiente). No cambies el eNCF ni el JSON automáticamente. |
402 | La producción necesita un plan pagado. No reintentes: muestra error.message y details.billingUrl a quien administra la cuenta. |
423 | La producción de tu cuenta aún no está activa. |
429 | Con RATE_LIMIT_EXCEEDED, espera Retry-After y reintenta con espera creciente. Con PLAN_LIMIT_EXCEEDED, no reintentes. |
500, 502, 503, 504, timeout o conexión cortada | Reintenta el mismo JSON con el mismo eNCF. Con 503 SERVICE_UNAVAILABLE, espera antes los segundos de Retry-After. |
Errores frecuentes
Los errores de la solicitud traen error.code:
{
"ok": false,
"correlationId": "494873f4-a7b3-4a31-8b49-ecdbac4b7a73",
"error": {
"code": "ENCF_PAYLOAD_MISMATCH",
"message": "El eNCF ya fue enviado con información fiscal diferente",
"details": { "encf": "E320000000010" }
}
}
| Código | Causa | Qué hacer |
|---|---|---|
400 ENCF_REQUIRED | El JSON no trae eNCF. | Asígnalo en tu sistema antes de emitir. |
409 ENCF_PAYLOAD_MISMATCH | Ese eNCF ya se usó con otro JSON: cambió algún valor o su tipo (el orden de los campos y los espacios no cuentan). | Investiga antes de actuar; no sobrescribas la venta original. |
409 ENCF_ANNULLED | El eNCF pertenece a un rango anulado. | Usa otro eNCF de un rango vigente. |
409 ENCF_NOT_IN_REGISTERED_RANGE | Registraste en tu cuenta rangos de eNCF de ese tipo, en ese ambiente, y el eNCF no cae en ninguno. details.registeredRanges lista los rangos. | Usa un eNCF de tus rangos o registra el rango que te autorizó la DGII. |
409 ENCF_RANGE_DISABLED | El eNCF solo cae en un rango registrado que está deshabilitado. | Usa un eNCF de un rango vigente. |
409 ENCF_REPLAY_UNVERIFIABLE | Hay un registro antiguo de ese eNCF que no se puede comparar. | Consulta su estado o escríbenos con el correlationId. |
422 en RNCEmisor | El emisor no es el RNC de tu cuenta. | Cada cuenta emite solo con su RNC. |
422 en FechaVencimientoSecuencia o sequenceExpirationDate | Falta o no es una fecha real. En el JSON DGII también sobra en los tipos 32 y 34 (SEQUENCE_EXPIRATION_DATE_NOT_APPLICABLE); en el contrato simplificado eso es solo un aviso y la fecha se omite. Es anterior a FechaEmision, así que el eNCF ya estaba vencido (SEQUENCE_EXPIRED_AT_ISSUE_DATE), o no es el vencimiento del rango que registraste en tu cuenta para ese eNCF (SEQUENCE_EXPIRATION_RANGE_MISMATCH). | Usa la fecha del rango autorizado y un eNCF vigente; en el 32 y el 34, quítala. |
422 en FechaHoraFirma o signatureDate (SIGNATURE_DATE_IN_FUTURE) | La fecha y hora de la firma que enviaste es posterior a la hora actual de RD (GMT-4), con más de 2 minutos de diferencia. La DGII rechaza un e-CF firmado en el futuro. | Omítela para que ZarelaFact ponga la hora de la firma, o envía la hora real de RD. |
422 en TotalITBIS1 o TotalITBIS2 (TOTAL_ITBIS_REQUIRED) | Hay MontoGravadoI1 o MontoGravadoI2 mayor que cero y falta su ITBIS. La DGII rechaza ese e-CF y el eNCF queda usado, también en una nota de crédito con IndicadorNotaCredito 1. | Declara TotalITBIS1 = MontoGravadoI1 × 18 % (o TotalITBIS2 × 16 %) y TotalITBIS. En la nota de crédito a más de 30 días, en 0.00 (details.expected lo dice). Ver Montos. |
422 en la nota (REFERENCED_BUYER_MISMATCH, REFERENCED_DATE_MISMATCH, CREDIT_NOTES_EXCEED_ORIGINAL) | La nota modifica un eCF de tu cuenta y es para otro comprador, su FechaNCFModificado no es la fecha de emisión de ese eCF, o las notas de crédito sumadas superan su monto total. | Emite la nota al mismo comprador, con la fecha del comprobante modificado y sin pasar su total. |
422 UNRESOLVED_PLACEHOLDER | Quedó un marcador sin reemplazar, como {{NCF_MODIFICADO}}. | Reemplázalo por el valor real. |
422 CONTINGENCY_PAPER_REPLACEMENT_UNSUPPORTED | CodigoModificacion (o reference.modificationCode) 4: un e-CF que reemplaza un comprobante de papel de contingencia. ZarelaFact no los emite. | Emite el e-CF sin esa referencia. Si la DGII no responde, el documento queda en contingencia y sale solo. |
402 PAYMENT_REQUIRED | Usaste los 50 e-CF gratis del mes, o tu pago está vencido tras la gracia (o, en un Partner, no hay plan pagado). | Paga el plan en details.billingUrl. El eNCF queda libre. Ver el error 402. |
423 PRODUCTION_NOT_ACTIVE | Tu producción todavía no está activa. | Termina la certificación. |
429 PLAN_LIMIT_EXCEEDED | Agotaste el cupo de tu plan más su margen de tolerancia en el periodo de cobro. Antes, cada e-CF que entró pasado el plan trajo el aviso PLAN_LIMIT_OVERAGE en warnings. | Sube de plan. Ver el margen de tolerancia. |
Cómo reintentar
- Pon un tiempo límite (timeout) a cada solicitud.
- Reintenta con espera creciente y un poco de azar, por ejemplo a los 1, 2, 4, 8 y 16 segundos.
- Respeta
Retry-Aftercuando venga. - Si se agotan los intentos, deja la venta en una cola de revisión sin cambiar el eNCF ni el JSON.
- Cuando ya tienes el
documentId, consulta el estado; no vuelvas a emitir para saber cómo va.
Un documento rejected ya tiene estado fiscal final. No lo reintentes como un fallo de red: el mismo JSON solo se reenvía si la DGII rechazó con secuenciaUtilizada: false; si no, la API te devuelve el rechazo guardado. Corrige la causa y sigue Corregir y reenviar un rechazo.
Corregir y reenviar un rechazo
En cada rechazo la DGII dice si el eNCF se puede volver a usar: secuenciaUtilizada (false = se puede reutilizar). ZarelaFact lo guarda con el documento rechazado y lo aplica por ti. La DGII lo permite, por ejemplo, cuando el rechazo fue por un error de confección, por el certificado o por un eNCF no autorizado (Decreto 587-24, art. 17 párr. III), y pide reenviar con el mismo eNCF el resumen de consumo rechazado.
- En la API Partner viene como
sequenceUseden la consulta del documento, en la consulta por lote y en el webhookdocument.state_changed, también para un resumen RFCE rechazado.false: la DGII rechazó consecuenciaUtilizada: falsey puedes reenviarlo con el mismo eNCF.true: rechazó consecuenciaUtilizada: truey el eNCF quedó usado.null: el documento no está rechazado o la DGII no mandó el dato. Ver Conciliar el estado. - En la API de la cuenta directa no viene en la consulta ni en los webhooks. Para saberlo, reenvía la versión corregida con el mismo eNCF:
202conENCF_REISSUED_AFTER_REJECTIONsi se pudo reutilizar,409 ENCF_PAYLOAD_MISMATCH(sin registrar nada) si no.
Qué hacer en cada caso:
- Con
secuenciaUtilizada: false(en producción y en TesteCF): reenvía con el mismo eNCF la versión corregida o, si la causa del rechazo no estaba en el documento, el mismo JSON. Por ejemplo, si la DGII todavía no había autorizado la secuencia o el certificado no estaba delegado, y ya lo arreglaste. Si la causa estaba en los datos, el mismo JSON vuelve a ser rechazado. La API responde202con undocumentIdnuevo,result.replacesDocumentId(el rechazado) y el avisoENCF_REISSUED_AFTER_REJECTION. La versión rechazada no se borra ni se modifica: se conserva con su XML firmado, sus respuestas de la DGII y su PDF como evidencia, y deja de aparecer en los listados; la nueva queda enlazada a ella (metadata.reissueOf) y ocupa el eNCF. Mientras el reenvío va en camino, o si la DGII lo acepta, repetir el mismo JSON te devuelve ese reenvío y no se envía otra vez; solo se reenvía de nuevo si la DGII lo vuelve a rechazar consecuenciaUtilizada: false. También puedes anular ese eNCF con una ANECF. - Sin esa respuesta (
secuenciaUtilizada: true, o la DGII no la envió): el eNCF quedó usado. El mismo JSON te devuelve el rechazo guardado y un JSON distinto con ese eNCF responde409 ENCF_PAYLOAD_MISMATCH; emite el comprobante corregido con un eNCF nuevo. - En CerteCF los reenvíos se hacen reiniciando el paso de la certificación.
Buenas prácticas
- Valida con
?validate=truedurante el desarrollo. - No bloquees la venta esperando a la DGII.
- Guarda por cada venta el eNCF, el JSON enviado, el
documentIdy elcorrelationId. - Reintenta solo los fallos temporales, siempre con el mismo eNCF y el mismo JSON.
- Concilia el estado por lote, o con webhooks, hasta que sea final.
El XML firmado y el PDF en formato carta se descargan por API (GET /{ambiente}/documentos-ecf/{documentId o eNCF}/xml y /pdf) o desde el detalle del documento en el portal. Ver Representación impresa.
Siguiente: Ejemplos JSON por tipo de e-CF.