Saltar al contenido principal

Envío de e-CF

En resumen
  1. Haz POST /{ambiente}/documentos-ecf con el JSON del comprobante (formato, ejemplos por tipo).
  2. Recibes al instante 202 con el documentId. Guárdalo junto al eNCF.
  3. 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 IndicadorFacturacion 4 y suma en MontoExento.
  • Dos tasas: el café va al 16 % (IndicadorFacturacion 2) y el detergente al 18 % (1). Cada tasa tiene su base (MontoGravadoI2, MontoGravadoI1) y su ITBIS (TotalITBIS2, TotalITBIS1).
  • Descuento: el detergente lleva un 10 % (DescuentoMonto y TablaSubDescuento); su MontoItem ya lo resta.
  • Consumidor final: el 32 siempre lleva la sección Comprador, pero por debajo de RD$250,000 basta con RazonSocialComprador. Desde RD$250,000 el comprador va identificado con RNCComprador o, si es extranjero, con IdentificadorExtranjero (nunca los dos); si falta, la API responde 422 con details.code BUYER_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": []
}
CampoQué es
errors[].fieldRuta del campo con el problema.
errors[].messageQué está mal, en español.
errors[].detailsCuando aplica: valores esperados y recibidos, o un código como SEQUENCE_EXPIRATION_DATE_REQUIRED.
preflight.xsdResultado de la validación contra el XSD oficial.
correlationIdIdentificador 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é:

CampoQué es
dgiiPrediction.statusaccepted, accepted_conditional o rejected.
dgiiPrediction.reasons[]Un motivo por cada aviso o error de la revisión.
reasons[].codeCódigo de ZarelaFact, por ejemplo SQUARING_ABOVE_DGII_TOLERANCE. null si no tiene.
reasons[].dgiiCodeEl código DGII que devolvería, por ejemplo 2394. null si no tiene uno.
reasons[].fieldCampo de tu JSON al que se refiere.
reasons[].messageQué pasa, en español.
reasons[].severityerror o warning.
reasons[].effectrejects 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.

Ahorra secuencias

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​

En TesteCF, usa secuencias altas

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 -X POST \
https://api.zarelafact.com/TesteCF/documentos-ecf \
-H 'X-API-KEY: zrl_test_...' \
-H 'Content-Type: application/json' \
-d @factura.json

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": []
}
CampoQué es
result.documentIdIdentificador del documento en ZarelaFact. Guárdalo junto al eNCF.
result.encfEl eNCF que enviaste.
result.statusEstado inicial: queued_for_signing.
result.securityCode, result.qrUrlnull en el 202: llegan en la consulta en cuanto la DGII responde, o en la misma respuesta si pides esperarla.
correlationIdIdentificador 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 -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

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, y result.contingency trae desde cuándo).
RespuestaQué significa
201 con Preference-Applied: wait=10La DGII respondió. result.securityCode, result.qrUrl y result.printing traen lo necesario para imprimir.
202 con Retry-AfterLa 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 responde 202 enseguida, 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=10 deja margen. La validación y los errores (422, 409…) son los mismos de siempre.
  • Reintentos: el mismo JSON con el mismo eNCF y Prefer: wait devuelve el documento que ya existe. Si ya se puede imprimir, responde 201 sin 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. asyncStatusRequired sigue en true hasta 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.codeQué significa
BUYER_RNC_NOT_IN_DGII_REGISTRYEl 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_DGIIAparece 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​

  1. ZarelaFact convierte el JSON a XML y lo firma con tu certificado.
  2. 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.
  3. Sigue la respuesta de la DGII hasta el estado final y guarda el XML firmado 10 años.
  4. 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​

EstadoQué significa
queued_for_signingRecibido y en cola para firmarse.
signedFirmado, esperando el envío a la DGII. Todavía no se imprime (printing es null). Si no avanza, lastError dice por qué.
rfce_pending_dispatchFactura 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.
sentEnviado a la DGII, que devolvió el TrackID. Desde aquí se imprime.
pending_dgii_statusEsperando la respuesta final de la DGII.
acceptedFinal. Aceptado por la DGII.
accepted_conditionalFinal. Aceptado con observaciones; revisa dgiiMessages.
rejectedFinal. Rechazado; el motivo está en dgiiMessages.
contingencyLa DGII no respondió; ZarelaFact reintenta solo hasta que responda.
transmission_failedEl 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.
cancelledCancelado. Por ejemplo, su eNCF se anuló con una ANECF aceptada antes de enviarse: ya no se envía a la DGII.
Aceptado condicional

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:

ModalidadQué recibe la DGIICuándo
Documento completoEncabezado y todas las líneasMontoTotal de RD$250,000 o más
Resumen (RFCE)Totales, eNCF y código de seguridadMontoTotal 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 lleva TipoPago pero 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 a contingency y se reintenta igual que un envío normal; si falla por otra causa, lastError dice 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 rejected con sus dgiiMessages, 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 responde 409, 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, recibe dgii.service_restored y 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_degraded en ese momento, sin esperar las 3 fallas, y la siguiente respuesta de la DGII a uno de tus envíos te manda dgii.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.startedAt y la leyenda en printing.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}/contingencia lista 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_failed y 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: CodigoModificacion 4 responde 422 con details.code CONTINGENCY_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 recibe dgii.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 TesteCF y eCF. En CerteCF no hay directorio ni entrega. En TesteCF el 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 con POST /{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​

RespuestaQué hace tu sistema
400 o 422Corrige el documento. No reintentes el mismo contenido.
401Detén el envío y corrige la API key del ambiente.
403Detén el envío: la clave no tiene el permiso necesario.
409Lee error.code (ver la tabla siguiente). No cambies el eNCF ni el JSON automáticamente.
402La producción necesita un plan pagado. No reintentes: muestra error.message y details.billingUrl a quien administra la cuenta.
423La producción de tu cuenta aún no está activa.
429Con 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 cortadaReintenta 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ódigoCausaQué hacer
400 ENCF_REQUIREDEl JSON no trae eNCF.Asígnalo en tu sistema antes de emitir.
409 ENCF_PAYLOAD_MISMATCHEse 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_ANNULLEDEl eNCF pertenece a un rango anulado.Usa otro eNCF de un rango vigente.
409 ENCF_NOT_IN_REGISTERED_RANGERegistraste 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_DISABLEDEl eNCF solo cae en un rango registrado que está deshabilitado.Usa un eNCF de un rango vigente.
409 ENCF_REPLAY_UNVERIFIABLEHay un registro antiguo de ese eNCF que no se puede comparar.Consulta su estado o escríbenos con el correlationId.
422 en RNCEmisorEl emisor no es el RNC de tu cuenta.Cada cuenta emite solo con su RNC.
422 en FechaVencimientoSecuencia o sequenceExpirationDateFalta 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_PLACEHOLDERQuedó un marcador sin reemplazar, como {{NCF_MODIFICADO}}.Reemplázalo por el valor real.
422 CONTINGENCY_PAPER_REPLACEMENT_UNSUPPORTEDCodigoModificacion (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_REQUIREDUsaste 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_ACTIVETu producción todavía no está activa.Termina la certificación.
429 PLAN_LIMIT_EXCEEDEDAgotaste 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​

  1. Pon un tiempo límite (timeout) a cada solicitud.
  2. Reintenta con espera creciente y un poco de azar, por ejemplo a los 1, 2, 4, 8 y 16 segundos.
  3. Respeta Retry-After cuando venga.
  4. Si se agotan los intentos, deja la venta en una cola de revisión sin cambiar el eNCF ni el JSON.
  5. Cuando ya tienes el documentId, consulta el estado; no vuelvas a emitir para saber cómo va.
Un rechazo de la DGII no es un error de transporte

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 sequenceUsed en la consulta del documento, en la consulta por lote y en el webhook document.state_changed, también para un resumen RFCE rechazado. false: la DGII rechazó con secuenciaUtilizada: false y puedes reenviarlo con el mismo eNCF. true: rechazó con secuenciaUtilizada: true y 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: 202 con ENCF_REISSUED_AFTER_REJECTION si 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 responde 202 con un documentId nuevo, result.replacesDocumentId (el rechazado) y el aviso ENCF_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 con secuenciaUtilizada: 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 responde 409 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​

  1. Valida con ?validate=true durante el desarrollo.
  2. No bloquees la venta esperando a la DGII.
  3. Guarda por cada venta el eNCF, el JSON enviado, el documentId y el correlationId.
  4. Reintenta solo los fallos temporales, siempre con el mismo eNCF y el mismo JSON.
  5. 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.