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ó.
- Una sola ruta para uno o varios documentos:
POST /{ambiente}/documentos-ecf/status/batch, con hasta 100 eNCF odocumentIdpor 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_conditionalorejected. - Las consultas no consumen los e-CF de tu plan.
Cada cuánto consultar
- Para imprimir: justo después del envío, consulta cada 1 o 2 segundos hasta que
printingdeje de sernull. 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 apareceprinting). Suele tardar unos segundos. ConPrefer: wait=10en la emisión,printingllega en la misma respuesta (ver más). - Para el estado ante la DGII: vuelve a consultar a los 30 segundos y a los 2 minutos.
- 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.
- 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.
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
- JavaScript
- PHP
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"] }'
async function consultarLote(encfs) {
const response = await fetch(
"https://api.zarelafact.com/eCF/documentos-ecf/status/batch",
{
method: "POST",
headers: {
"X-API-KEY": process.env.ZARELA_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({ encfs }),
}
);
return await response.json();
}
<?php
function consultarLote(array $encfs, string $apiKey) {
$ch = curl_init('https://api.zarelafact.com/eCF/documentos-ecf/status/batch');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['X-API-KEY: ' . $apiKey, 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode(['encfs' => $encfs]),
]);
$result = curl_exec($ch);
curl_close($ch);
return json_decode($result, true);
}
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
| Campo | Qué es |
|---|---|
documentId | Identificador del documento en ZarelaFact. |
encf | Número del comprobante. |
status | Estado en ZarelaFact; ver Estados del documento. Es not_found si el documento no existe en ese ambiente. |
dgiiStatus | Estado según la DGII. Vale pending_query mientras no hay respuesta. |
trackId | Identificador que asignó la DGII. |
printing | securityCode, 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. |
printingStatus | En 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). |
dgiiMessages | Textos de la respuesta final de la DGII: motivos de rechazo u observaciones de una aceptación condicional. Vacío mientras no hay respuesta final. |
lastError | Por 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. |
receiverDelivery | La 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. |
errors | NOT_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: falseel documento está entransmission_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 (messageyhintlo explican) y reenvíalo desde el portal con Re-enviar documento: sale el mismo XML firmado, sin firmarlo otra vez, y el estado vuelve asigned,senty 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.code | Qué pasa | Qué hacer |
|---|---|---|
DGII_CERTIFICATE_NOT_DELEGATED | La 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_REJECTED | La 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_ACCEPTED | La 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_REJECTED | La 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_EXPIRED | No 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_UNAVAILABLE | La 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ámetro | Qué filtra |
|---|---|
issueDateFrom, issueDateTo | FechaEmision del e-CF, AAAA-MM-DD. Las dos fechas se incluyen. |
documentType | Tipo de e-CF, por ejemplo E31. |
status | El status de la consulta por lote, por ejemplo accepted o rejected. |
limit | Documentos por página: hasta 100; por defecto, 50. |
cursor | El 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
dgiiMessagesa 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.