Saltar al contenido principal

Consulta de e-CF

Después de enviar un e-CF, consulta aquí si ya se puede imprimir y si la DGII lo aceptó o lo rechazó.

En resumen
  • Una sola ruta para uno o varios documentos: POST /{ambiente}/documentos-ecf/status/batch, con hasta 100 eNCF o documentId por llamada.
  • La respuesta trae el estado, los datos para imprimir (printing), los mensajes de la DGII (dgiiMessages) y, si el documento no avanza, el motivo (lastError).
  • Deja de consultar un documento cuando su estado sea final: accepted, accepted_conditional o rejected.
  • Las consultas no consumen los e-CF de tu plan.

Cada cuánto consultar​

  1. Para imprimir: justo después del envío, consulta cada 1 o 2 segundos hasta que printing deje de ser null. Aparece cuando la DGII responde: el TrackID del e-CF o la respuesta del resumen RFCE de una factura de consumo menor a RD$250,000 (Cuándo aparece printing). Suele tardar unos segundos. Con Prefer: wait=10 en la emisión, printing llega en la misma respuesta (ver más).
  2. Para el estado ante la DGII: vuelve a consultar a los 30 segundos y a los 2 minutos.
  3. Si todavía no hay estado final, deja el documento como pendiente y revísalo en una consulta por lote cada 5 a 15 minutos, junto con los demás pendientes.
  4. Deja de consultar en cuanto el estado sea final.

Mientras tanto el documento puede aparecer como signed, sent, pending_dgii_status, rfce_pending_dispatch o contingency. No lo reenvíes: ZarelaFact sigue el proceso por su cuenta. Si se queda en signed, mira lastError (Por qué un documento no avanza). Solo transmission_failed pide que hagas algo: el envío falló de forma definitiva y ZarelaFact no lo reintenta solo.

¿Prefieres que te avisemos?

Con webhooks recibes los cambios sin preguntar. Aun así, conserva la consulta por lote para conciliar.

Consulta por lote​

POST /{ambiente}/documentos-ecf/status/batch

Requiere el permiso status:read. Acepta hasta 100 documentos por llamada; recomendamos grupos de 50.

El cuerpo lleva una lista de encfs o de documentIds. Para un solo documento, envía una lista de uno:

{ "encfs": ["E310000000010", "E320000000011"] }
{ "documentIds": ["548fbebf-56bd-41b7-a612-917f3a72cac7"] }
curl -X POST \
https://api.zarelafact.com/eCF/documentos-ecf/status/batch \
-H 'X-API-KEY: zrl_live_...' \
-H 'Content-Type: application/json' \
-d '{ "encfs": ["E310000000010", "E320000000011"] }'

Respuesta​

{
"ok": true,
"environment": "ecf",
"correlationId": "f3b684d3-7a4d-4baf-a2cd-9dc5570b8887",
"count": 4,
"recommendedBatchSize": 50,
"maxBatchSize": 100,
"results": [
{
"documentId": "6f89c3d2-5f83-4607-9b50-99527cc40e5a",
"encf": "E310000000010",
"status": "accepted",
"dgiiStatus": "Aceptado",
"trackId": "0cc42712-4a99-48be-b66d-346b33e36d7f",
"lastCheckedAt": "2026-10-01T14:31:10.000Z",
"printing": {
"securityCode": "AbC123",
"signatureDate": "01-10-2026 10:30:05",
"qrUrl": "https://ecf.dgii.gov.do/ecf/ConsultaTimbre?RncEmisor={{RNC}}&RncComprador={{RNC_COMPRADOR}}&ENCF=E310000000010&FechaEmision=01-10-2026&MontoTotal=4513.50&FechaFirma=01-10-2026%2010:30:05&CodigoSeguridad=AbC123",
"legends": []
},
"printingStatus": "available",
"dgiiMessages": [],
"lastError": null,
"contingency": null,
"errors": []
},
{
"documentId": "a51e2d0b-1c7e-4c4a-9d2e-3b1f0c9e8a77",
"encf": "E320000000011",
"status": "rejected",
"dgiiStatus": "Rechazado",
"trackId": null,
"lastCheckedAt": "2026-10-01T14:31:10.000Z",
"printing": null,
"printingStatus": "rejected",
"dgiiMessages": ["El campo MontoGravadoTotal del área Totales de la sección Encabezado no es válido"],
"lastError": null,
"errors": []
},
{
"documentId": "0b7d4c1e-2f3a-4b5c-8d6e-7f8091a2b3c4",
"encf": "E310000000011",
"status": "signed",
"dgiiStatus": "pending_query",
"trackId": null,
"lastCheckedAt": "2026-10-01T14:31:10.000Z",
"printing": null,
"printingStatus": "awaiting_dgii",
"dgiiMessages": [],
"lastError": {
"code": "DGII_CERTIFICATE_NOT_DELEGATED",
"message": "La DGII rechazó la autenticación: el certificado no está delegado",
"dgiiMessages": ["El RNC del certificado no está delegado para realizar transacciones para el RNC: {{RNC}}"],
"hint": "El titular del certificado no tiene el rol Firmante para este RNC. El administrador del contribuyente debe delegarle el rol «Firmante Autorizado» en la Oficina Virtual de la DGII (menú «Delegación de e-CF» → «Delegación de Roles») y firmar el XML de la delegación.",
"retrying": true,
"at": "2026-10-01T14:30:20.000Z"
},
"errors": [
{ "code": "DGII_CERTIFICATE_NOT_DELEGATED", "message": "La DGII rechazó la autenticación: el certificado no está delegado" }
]
},
{
"encf": "E319999999999",
"status": "not_found",
"dgiiStatus": null,
"trackId": null,
"lastCheckedAt": null,
"errors": [{ "code": "NOT_FOUND", "message": "Documento no encontrado" }]
}
],
"errors": [],
"warnings": []
}

Campos de cada resultado​

CampoQué es
documentIdIdentificador del documento en ZarelaFact.
encfNúmero del comprobante.
statusEstado en ZarelaFact; ver Estados del documento. Es not_found si el documento no existe en ese ambiente.
dgiiStatusEstado según la DGII. Vale pending_query mientras no hay respuesta.
trackIdIdentificador que asignó la DGII.
printingsecurityCode, signatureDate, qrUrl y legends (las leyendas del PDF, con su texto literal) para la representación impresa. Es null hasta que la DGII responde: el TrackID del e-CF o, en una factura de consumo menor a RD$250,000, la respuesta Aceptado o Aceptado Condicional del resumen RFCE. Si el envío se difirió por contingencia aparece igual, para imprimir con su leyenda.
contingency{ "startedAt": "..." } si el envío del e-CF a la DGII se difirió por contingencia, o null. Es permanente: sigue ahí aunque el documento quede accepted. Ver Leyendas.
printingStatusEn qué punto está la representación impresa: awaiting_signature, awaiting_dgii, available o rejected (la DGII rechazó el resumen RFCE, o el e-CF sin TrackID: no se imprime).
dgiiMessagesTextos de la respuesta final de la DGII: motivos de rechazo u observaciones de una aceptación condicional. Vacío mientras no hay respuesta final.
lastErrorPor qué el documento no avanza: code, message, dgiiMessages, hint (qué hacer, cuando aplica), retrying (si ZarelaFact lo sigue intentando solo; false en transmission_failed) y at. Es null si no hay problema o si el estado ya es final. Ver Por qué un documento no avanza.
receiverDeliveryLa entrega del e-CF a tu comprador cuando es receptor electrónico (B2B), después de que la DGII lo acepta: state (submitting, retry_scheduled, sent, failed, uncertain, dispatch_failed, not_electronic o not_applicable), attempts, lastAttemptAt, nextAttemptAt (solo en retry_scheduled), sentAt, reason (por qué no aplica) y lastError (code, message, statusCode y codigoMotivoNoRecibido del ARECF del receptor). Es null si el documento no tuvo entrega. Un uncertain se concilia con POST /{ambiente}/documentos-ecf/{documentId}/entrega-receptor/reconciliar.
lastCheckedAtÚltima actualización del documento.
errorsNOT_FOUND cuando el documento no existe; si no, el mismo error de lastError (code y message). Vacío si no hay error.

Por qué un documento no avanza​

Si un documento se queda en signed, en contingency o en transmission_failed, lastError dice por qué. ZarelaFact lo guarda con cada intento de envío fallido, lo borra cuando un envío sale bien y deja de mostrarlo cuando el estado es final.

  • Con retrying: true (signed, contingency) ZarelaFact sigue intentándolo solo: no lo reenvíes.
  • Con retrying: false el documento está en transmission_failed: el envío falló de forma definitiva (o no hay certificado activo), la DGII no lo tiene y ZarelaFact no lo reintenta solo. Corrige la causa (message y hint lo explican) y reenvíalo desde el portal con Re-enviar documento: sale el mismo XML firmado, sin firmarlo otra vez, y el estado vuelve a signed, sent y al estado final. Si no lo vas a enviar, 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.

Los códigos que puedes ver:

lastError.codeQué pasaQué hacer
DGII_CERTIFICATE_NOT_DELEGATEDLa DGII dice que tu certificado no está delegado para el RNC emisor. Ningún documento de la cuenta en ese ambiente puede llegar, así que ZarelaFact pausa los envíos y los reintenta cada 30 minutos, sin marcarlos como fallidos.El administrador de la empresa debe delegar el rol Firmante Autorizado al titular del certificado en la Oficina Virtual de la DGII (menú «Delegación de e-CF» → «Delegación de Roles») y firmar el XML de la delegación. lastError.hint lo repite. Cuando la delegación está hecha, los documentos salen solos en el siguiente reintento.
DGII_CERTIFICATE_REJECTEDLa DGII no acepta tu certificado digital: está revocado, es de un tipo que no admite o no es válido. Como con la delegación, ningún documento de ese ambiente puede llegar: ZarelaFact pausa los envíos y los reintenta cada 30 minutos, sin marcarlos como fallidos.Sube en ZarelaFact un certificado válido para procesos tributarios, emitido por una entidad autorizada por el INDOTEL. Con el certificado nuevo los envíos salen sin esperar la pausa. lastError.hint lo repite.
REFERENCED_ENCF_NOT_ACCEPTEDLa nota de crédito o débito modifica un e-NCF de tu cuenta que la DGII rechazó o que se canceló. La DGII la rechazaría («El eNCF modificado no ha sido emitido») y su secuencia se perdería, así que ZarelaFact no la envía. Mientras el e-NCF modificado no tiene estado final, la nota espera hasta 24 horas antes de enviarse.Emite la nota sobre un comprobante aceptado. Al emitir, la API ya responde 422 con este código en details.code si el e-NCF modificado está rechazado o cancelado.
DGII_RECEPTION_REJECTEDLa DGII respondió que no recibió el documento, con su motivo en lastError.dgiiMessages. Queda en transmission_failed.Lee el motivo. Si es un dato del documento, corrige y emite un comprobante nuevo (y anula este eNCF); si no, escríbenos con el documentId.
CERTIFICATE_NOT_CONFIGURED, CERTIFICATE_EXPIREDNo hay un certificado digital activo (o vigente) para ese ambiente: el documento no se puede firmar ni enviar. Queda en transmission_failed.Sube el certificado digital (.p12) del ambiente y reenvía el documento.
DGII_UNAVAILABLELa DGII no responde (sin conexión, tiempo de espera, errores 5xx o su autenticación caída, DGII_AUTH_UNAVAILABLE). El documento está en contingency.Nada: ZarelaFact lo envía cuando la DGII vuelva. Ver Contingencia.

Puede aparecer otro código con un fallo propio del documento, por ejemplo XSD_VALIDATION_FAILED; el message dice qué pasó.

Si tienes webhooks, recibes un document.state_changed con el mismo lastError la primera vez que aparece cada código, aunque el estado no cambie.

Documentos en contingencia​

Si la DGII está caída, los documentos quedan en contingency y ZarelaFact los reintenta solo, sin plazo fijo, hasta que la DGII responda. Para monitorearlos:

GET /{ambiente}/contingencia

Requiere status:read. dgiiService dice si la DGII responde en ese ambiente (state: available o degraded, desde since, con el code de la caída); cada cambio llega también como webhook dgii.service_degraded o dgii.service_restored. dgiiService.processing dice si la DGII está lenta (state: normal o slow, desde since), con sus webhooks dgii.service_slow y dgii.service_slow_cleared. Cada documento trae desde cuándo espera (since), cuántos intentos lleva (attempts) y el último motivo (lastError). No necesitas hacer nada con ellos: cuando la DGII vuelve, ZarelaFact los envía y su estado avanza en la consulta por lote. Su representación impresa lleva la leyenda de contingencia; ver Contingencia.

Lista de e-CF emitidos por período​

Para conciliar un mes, atender un requerimiento o llevarte tus comprobantes, lista los e-CF que emitiste en un ambiente y descarga cada XML firmado:

GET /{ambiente}/documentos-ecf?issueDateFrom=2026-09-01&issueDateTo=2026-09-30
curl "https://api.zarelafact.com/eCF/documentos-ecf?issueDateFrom=2026-09-01&issueDateTo=2026-09-30&limit=100" \
-H 'X-API-KEY: zrl_live_...'

Requiere ecf:read, que trae la clave estándar. No incluye las validaciones previas (?validate=true) ni los comprobantes reemplazados al reiniciar la certificación.

ParámetroQué filtra
issueDateFrom, issueDateToFechaEmision del e-CF, AAAA-MM-DD. Las dos fechas se incluyen.
documentTypeTipo de e-CF, por ejemplo E31.
statusEl status de la consulta por lote, por ejemplo accepted o rejected.
limitDocumentos por página: hasta 100; por defecto, 50.
cursorEl nextCursor de la página anterior.

Cada elemento trae documentId, encf, documentType, issueDate, buyerRnc (el RNCComprador del e-CF; null sin RNC o con IdentificadorExtranjero, que no es un RNC), buyerName, total, status, dgiiStatus, trackId, las fechas (createdAt, sentAt, acceptedAt, rejectedAt), printing y dgiiMessages. Van del más reciente al más antiguo según cuándo los recibió ZarelaFact. Repite con cursor igual al nextCursor hasta que llegue null; los filtros se mantienen. Con cada documentId (o encf) descarga el XML firmado en GET /{ambiente}/documentos-ecf/{documentId}/xml. Un filtro, limit o cursor inválido responde 400 INVALID_ISSUED_DOCUMENTS_QUERY.

Si necesitas el paquete completo de un período (XML firmados, respuestas de la DGII, acuses y aprobaciones comerciales, con un manifiesto de huellas SHA-256), escríbenos: ZarelaFact lo prepara desde su copia inmutable.

Recomendaciones​

  • Junta los documentos pendientes y consúltalos en el mismo lote.
  • Guarda los estados finales y no los vuelvas a consultar: ya no cambian.
  • Muestra los dgiiMessages a quien corrige la factura.
  • Si un documento sale not_found, revisa el ambiente y el eNCF antes de reenviar nada.

Siguiente: Webhooks (opcional) o Representación impresa.