Consultar
Un comprobante
Sección titulada «Un comprobante»Con el id que devolvió el envío:
curl "https://api.ecfhub.com.do/v1/invoices/$INVOICE_ID" -H "X-Api-Key: $ECF_API_KEY"using System.Net.Http.Json;using System.Text.Json;
using var http = new HttpClient { BaseAddress = new Uri("https://api.ecfhub.com.do/") };http.DefaultRequestHeaders.Add("X-Api-Key", Environment.GetEnvironmentVariable("ECF_API_KEY"));
var invoice = await http.GetFromJsonAsync<JsonElement>($"v1/invoices/{invoiceId}");Console.WriteLine($"{invoice.GetProperty("encf")}: {invoice.GetProperty("status")}");const response = await fetch(`https://api.ecfhub.com.do/v1/invoices/${invoiceId}`, { headers: { "X-Api-Key": process.env.ECF_API_KEY },});const invoice = await response.json();console.log(`${invoice.encf}: ${invoice.status}`);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.
Por trackId o por e-NCF
Sección titulada «Por trackId o por e-NCF»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:
companyIdes 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 es403 company.not_in_key.environment(TestEcf,CertEcfoEcf) 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.
# Por trackIdcurl "https://api.ecfhub.com.do/v1/invoices/by-track-id/$TRACK_ID" -H "X-Api-Key: $ECF_API_KEY"
# Por e-NCF, en Produccióncurl "https://api.ecfhub.com.do/v1/invoices/by-encf/E310000000001?companyId=$COMPANY_ID&environment=Ecf" \ -H "X-Api-Key: $ECF_API_KEY"using System.Net.Http.Json;using System.Text.Json;
using var http = new HttpClient { BaseAddress = new Uri("https://api.ecfhub.com.do/") };http.DefaultRequestHeaders.Add("X-Api-Key", Environment.GetEnvironmentVariable("ECF_API_KEY"));
// Por trackIdvar byTrackId = await http.GetFromJsonAsync<JsonElement>($"v1/invoices/by-track-id/{Uri.EscapeDataString(trackId)}");
// Por e-NCF, en Producciónvar byEncf = await http.GetFromJsonAsync<JsonElement>( $"v1/invoices/by-encf/E310000000001?companyId={companyId}&environment=Ecf");Console.WriteLine($"{byEncf.GetProperty("id")}: {byEncf.GetProperty("status")}");const headers = { "X-Api-Key": process.env.ECF_API_KEY };
// Por trackIdconst byTrackId = await fetch( `https://api.ecfhub.com.do/v1/invoices/by-track-id/${encodeURIComponent(trackId)}`, { headers },).then((r) => r.json());
// Por e-NCF, en Producciónconst url = new URL("https://api.ecfhub.com.do/v1/invoices/by-encf/E310000000001");url.searchParams.set("companyId", companyId);url.searchParams.set("environment", "Ecf");const byEncf = await fetch(url, { headers }).then((r) => r.json());console.log(`${byEncf.id}: ${byEncf.status}`);En el portal, el detalle de cada comprobante muestra su id con el botón «Copiar».
Estados
Sección titulada «Estados»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. |
Listado
Sección titulada «Listado»Todos los comprobantes de producción que siguen en Sent, página por página:
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>using System.Net.Http.Json;using System.Text.Json;
using var http = new HttpClient { BaseAddress = new Uri("https://api.ecfhub.com.do/") };http.DefaultRequestHeaders.Add("X-Api-Key", Environment.GetEnvironmentVariable("ECF_API_KEY"));
string? cursor = null;do{ var url = "v1/invoices?status=Sent&environment=Ecf&limit=100" + (cursor is null ? "" : $"&cursor={cursor}"); var page = await http.GetFromJsonAsync<JsonElement>(url); foreach (var invoice in page.GetProperty("items").EnumerateArray()) { Console.WriteLine($"{invoice.GetProperty("encf")}: {invoice.GetProperty("status")}"); }
cursor = page.TryGetProperty("nextCursor", out var next) && next.ValueKind == JsonValueKind.String ? next.GetString() : null;}while (cursor is not null);let cursor = null;do { const url = new URL("https://api.ecfhub.com.do/v1/invoices?status=Sent&environment=Ecf&limit=100"); if (cursor) url.searchParams.set("cursor", cursor); const response = await fetch(url, { headers: { "X-Api-Key": process.env.ECF_API_KEY } }); const page = await response.json(); for (const invoice of page.items) console.log(`${invoice.encf}: ${invoice.status}`); cursor = page.nextCursor ?? null;} while (cursor);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.
Archivos
Sección titulada «Archivos»| 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. |
Cómo seguir el estado
Sección titulada «Cómo seguir el estado»- Webhooks (recomendado). Recibe
invoice.status_changeden tu sistema. Ver Webhooks. - 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. - Conciliación periódica, también con webhooks: cada 5–15 minutos, lista los que siguen en
Queued,SignedoSentdesde hace rato. Cubre un webhook perdido o una caída de tu sistema.
Mensajes de la DGII
Sección titulada «Mensajes de la DGII»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.