Ir al contenido

Consultar

Con el id que devolvió el envío:

Ventana de terminal
curl "https://api.ecfhub.com.do/v1/invoices/$INVOICE_ID" -H "X-Api-Key: $ECF_API_KEY"

Trae el estado, el e-NCF, el trackId, los datos para imprimir, la respuesta de la DGII con sus mensajes, los avisos, el historial de estados, las versiones (si se corrigió) y las entregas al comprador.

Si tu sistema guardó el trackId de la DGII o el e-NCF, y no el id, consulta con ellos. Devuelven el mismo detalle que la consulta por id.

Endpoint Busca
GET /v1/invoices/by-track-id/{trackId} El comprobante con ese trackId.
GET /v1/invoices/by-encf/{encf}?companyId=…&environment=… El comprobante vigente de ese e-NCF en una empresa y un ambiente.

Por e-NCF:

  • companyId es obligatorio si la API key sirve para varias empresas (422 company.required). Con una API key de una sola empresa se puede omitir; si es de otra empresa, la respuesta es 403 company.not_in_key.
  • environment (TestEcf, CertEcf o Ecf) es opcional: sin él, se usa el ambiente actual de la empresa. El mismo e-NCF puede existir en Pruebas y en Producción.
  • Si el e-NCF se rechazó y luego se corrigió, devuelve la corrección. Si solo hay versiones rechazadas, la más reciente.

Si no existe (o es de una empresa que tu API key no ve), la respuesta es 404.

Ventana de terminal
# Por trackId
curl "https://api.ecfhub.com.do/v1/invoices/by-track-id/$TRACK_ID" -H "X-Api-Key: $ECF_API_KEY"
# Por e-NCF, en Producción
curl "https://api.ecfhub.com.do/v1/invoices/by-encf/E310000000001?companyId=$COMPANY_ID&environment=Ecf" \
-H "X-Api-Key: $ECF_API_KEY"

En el portal, el detalle de cada comprobante muestra su id con el botón «Copiar».

Signed → Sent → Accepted | AcceptedConditional | Rejected
Estado Significa Qué hacer
Queued Recibido, por firmar Esperar.
Signed Firmado, por enviar a la DGII (o en contingencia) Esperar.
Sent La DGII lo recibió (trackId) y lo está validando Esperar el resultado.
Accepted Aceptado Listo.
AcceptedConditional Aceptado condicional: es válido, con observaciones Revisar dgii.messages y corregirlo en los siguientes.
Rejected Rechazado Corregir y reenviar (ver Cómo enviar).
Failed Error técnico (no es un rechazo de la DGII) Reenviar con POST /v1/invoices/{id}/resend, sin cambiar el documento.

Todos los comprobantes de producción que siguen en Sent, página por página:

Ventana de terminal
curl "https://api.ecfhub.com.do/v1/invoices?status=Sent&environment=Ecf&limit=100" -H "X-Api-Key: $ECF_API_KEY"
# Página siguiente: agrega &cursor=<nextCursor de la respuesta anterior>

Filtros: companyId, status, ecfType (E31…), from y to (fecha con zona, por ejemplo 2026-11-16T00:00:00-04:00), buyerRnc (RNC o cédula del comprador), encf (el e-NCF completo o su comienzo, por ejemplo E31), environment (TestEcf, CertEcf o Ecf), receiverUnconfirmed=true (solo los de producción que debían llegar al buzón del comprador y no tenemos su URL de recepción; ver Webhooks) y limit (hasta 200).

Los resultados vienen del más reciente al más antiguo. Para la página siguiente, envía el nextCursor de la respuesta como cursor. totalCount es el total con los filtros aplicados.

Para traer un solo e-NCF, usa la consulta por e-NCF.

Endpoint Devuelve
GET /v1/invoices/{id}/xml El XML firmado del e-CF (con ?kind=Rfce, el resumen enviado a la DGII en el tipo 32 menor).
GET /v1/invoices/{id}/pdf La representación impresa (PDF), con código de seguridad y QR.
GET /v1/invoices/{id}/acknowledgement El acuse de recibo del receptor electrónico del comprador.
GET /v1/invoices/{id}/commercial-approval La aprobación o el rechazo comercial del comprador.
  1. Webhooks (recomendado). Recibe invoice.status_changed en tu sistema. Ver Webhooks.
  2. Consulta con espera creciente, si no puedes recibir webhooks: la primera a los ~5 s, luego a los 10, 20 y 30 s, y después cada minuto como máximo. Para en un estado final. Con muchos comprobantes, usa el listado (?status=Sent) en lugar de consultar uno por uno.
  3. Conciliación periódica, también con webhooks: cada 5–15 minutos, lista los que siguen en Queued, Signed o Sent desde hace rato. Cubre un webhook perdido o una caída de tu sistema.

Cada mensaje de dgii.messages trae code y value tal como los devolvió la DGII y, cuando tenemos una explicación, hint: qué significa y qué hacer. Ver Errores.