Cómo enviar
Hay dos formas de enviar un e-CF. Las dos responden igual y siguen el mismo flujo después.
| Forma | Endpoint | Quién arma y firma el XML |
|---|---|---|
| JSON | POST /v1/invoices |
Nosotros: generamos el XML, lo validamos contra los esquemas de la DGII y lo firmamos con el certificado de tu empresa. |
| XML firmado | POST /v1/invoices/signed |
Tu sistema. Validamos el esquema y la firma, y lo enviamos tal cual. |
Tipos soportados: 31, 32, 33, 34, 41, 43, 44, 45, 46 y 47 ("tipoeCF": "E31"; también se acepta "31").
El cuerpo es { "companyId": "…", "document": { "encabezado": { … }, "items": [ … ] } }. Aquí se lee de un archivo
factura.json; un documento completo de ejemplo está en Primeros pasos.
IDEMPOTENCY_KEY=$(uuidgen) # una por factura; guárdala con ella antes de enviar
curl -X POST "https://api.ecfhub.com.do/v1/invoices?wait=sent" \ -H "X-Api-Key: $ECF_API_KEY" \ -H "Idempotency-Key: $IDEMPOTENCY_KEY" \ -H "Content-Type: application/json" \ --max-time 15 \ -d @factura.jsonusing System.Text;
using var http = new HttpClient{ BaseAddress = new Uri("https://api.ecfhub.com.do/"), Timeout = TimeSpan.FromSeconds(15),};http.DefaultRequestHeaders.Add("X-Api-Key", Environment.GetEnvironmentVariable("ECF_API_KEY"));
var idempotencyKey = Guid.NewGuid().ToString(); // una por factura; guárdala con ella antes de enviar
using var request = new HttpRequestMessage(HttpMethod.Post, "v1/invoices?wait=sent"){ Content = new StringContent(await File.ReadAllTextAsync("factura.json"), Encoding.UTF8, "application/json"),};request.Headers.Add("Idempotency-Key", idempotencyKey);
using var response = await http.SendAsync(request);Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");import { randomUUID } from "node:crypto";import { readFile } from "node:fs/promises";
const idempotencyKey = randomUUID(); // una por factura; guárdala con ella antes de enviar
const response = await fetch("https://api.ecfhub.com.do/v1/invoices?wait=sent", { method: "POST", headers: { "X-Api-Key": process.env.ECF_API_KEY, "Idempotency-Key": idempotencyKey, "Content-Type": "application/json", }, body: await readFile("factura.json", "utf8"), signal: AbortSignal.timeout(15_000),});console.log(response.status, await response.json());companyId: opcional con una key restringida a una empresa; obligatorio con una key para todas.document: el e-CF con los nombres de campo de los formatos de la DGII en camelCase (encabezado.idDoc.tipoeCF,encabezado.emisor.rncEmisor,items[].montoItem…). El esquema completo está en la referencia.rncEmisordebe ser el RNC de la empresa.- Con errores de validación,
422 ecf.validation_failedcon la lista enerrors(code,field,message). Con solo avisos (diferencias dentro de la tolerancia de la DGII) se envía igual y los avisos vienen enwarnings.
XML firmado
Sección titulada «XML firmado»multipart/form-data con estos campos:
| Campo | Obligatorio | Contenido |
|---|---|---|
xml |
Sí | El e-CF firmado (hasta 5 MB). |
rfce |
Solo tipo 32 menor de RD$250,000 | El resumen (RFCE) firmado, que debe cuadrar con el e-CF. |
pdf |
No | Tu representación impresa. Si no la envías, puedes pedir que la generemos (ajuste de la empresa en el portal). |
En los ejemplos, el archivo sigue el nombre que pide la DGII, {RNC emisor}{e-NCF}.xml: cambia TU_RNC por el RNC de
tu empresa.
IDEMPOTENCY_KEY=$(uuidgen) # una por factura; guárdala con ella antes de enviar
curl -X POST "https://api.ecfhub.com.do/v1/invoices/signed?wait=sent" \ -H "X-Api-Key: $ECF_API_KEY" \ -H "Idempotency-Key: $IDEMPOTENCY_KEY" \ --max-time 15 \ -F "xml=@TU_RNCE310000000001.xml;type=application/xml"using System.Net.Http.Headers;
using var http = new HttpClient{ BaseAddress = new Uri("https://api.ecfhub.com.do/"), Timeout = TimeSpan.FromSeconds(15),};http.DefaultRequestHeaders.Add("X-Api-Key", Environment.GetEnvironmentVariable("ECF_API_KEY"));
var idempotencyKey = Guid.NewGuid().ToString(); // una por factura; guárdala con ella antes de enviar
// Los bytes exactos del archivo firmado: no lo leas como texto ni lo reformatees.var xml = new ByteArrayContent(await File.ReadAllBytesAsync("TU_RNCE310000000001.xml"));xml.Headers.ContentType = new MediaTypeHeaderValue("application/xml");
using var form = new MultipartFormDataContent { { xml, "xml", "TU_RNCE310000000001.xml" } };using var request = new HttpRequestMessage(HttpMethod.Post, "v1/invoices/signed?wait=sent") { Content = form };request.Headers.Add("Idempotency-Key", idempotencyKey);
using var response = await http.SendAsync(request);Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");import { randomUUID } from "node:crypto";import { readFile } from "node:fs/promises";
const idempotencyKey = randomUUID(); // una por factura; guárdala con ella antes de enviar
// Los bytes exactos del archivo firmado: no lo leas como texto ni lo reformatees.const form = new FormData();const bytes = await readFile("TU_RNCE310000000001.xml");form.append("xml", new Blob([bytes], { type: "application/xml" }), "TU_RNCE310000000001.xml");
const response = await fetch("https://api.ecfhub.com.do/v1/invoices/signed?wait=sent", { method: "POST", headers: { "X-Api-Key": process.env.ECF_API_KEY, "Idempotency-Key": idempotencyKey }, body: form, // fetch pone el Content-Type multipart con su boundary signal: AbortSignal.timeout(15_000),});console.log(response.status, await response.json());Guardamos y enviamos los bytes exactos que recibimos. Validamos el esquema, la firma, que el certificado estuviera
vigente a la FechaHoraFirma y que el RNCEmisor sea una empresa de tu cuenta. El e-NCF sigue las reglas de
numeración propia.
Idempotency-Key (obligatorio)
Sección titulada «Idempotency-Key (obligatorio)»Cada envío lleva un header Idempotency-Key nuevo por factura (por ejemplo, un UUID). Guárdalo con la factura.
-
Repetir la solicitud con la misma clave y el mismo cuerpo devuelve la misma factura (mismo e-NCF y misma firma), con su estado actual y el header
Idempotent-Replayed: true. Nunca se crea otra. -
Toda respuesta
202repite la clave en el headerIdempotency-Key, yGET /v1/invoices/{id}la devuelve enidempotencyKey. -
La misma clave con otro cuerpo:
409 idempotency.key_reused. -
Sin el header:
400 idempotency.key_required. -
Un error
4xxno crea nada: puedes corregir y reenviar con la misma clave. -
La clave no vence: queda unida a su factura y es única en toda tu cuenta.
Si tu solicitud se corta (timeout, red), repítela con la misma clave. Con una clave nueva emitirías otra factura, con otro e-NCF. La explicación completa y un ejemplo de reintento están en Primeros pasos.
Cuánto espera la respuesta: ?wait
Sección titulada «Cuánto espera la respuesta: ?wait»| Valor | Responde cuando | Trae |
|---|---|---|
?wait=sent (recomendado) |
La DGII recibió el comprobante (o, como máximo, a los 6 s) | trackId y los datos para imprimir |
?wait=result |
La DGII dio el resultado final (o, como máximo, a los 8 s) | Además, el estado final (Accepted, AcceptedConditional o Rejected) con los mensajes de la DGII |
?wait=signed |
Está firmado, antes de enviarlo a la DGII | Los datos para imprimir; el trackId llega por webhook o consulta |
| Sin el parámetro | Según el ajuste «TrackID por defecto» de tu cuenta: como sent si está activado; si no, como signed |
Recomendación: envía siempre ?wait=sent de forma explícita.
Con ?wait=sent, el campo sentWait dice cómo terminó la espera:
sentWait |
Qué pasó | Qué hacer |
|---|---|---|
Sent |
La DGII lo recibió: viene el trackId |
Imprimir. El resultado final llega por webhook o consulta. |
Contingency |
La DGII no respondió a tiempo o falló | Imprimir con la leyenda de contingency.legend. El envío sigue solo. Ver Contingencia. |
TimedOut |
No alcanzó a enviarse en el tiempo de la respuesta (no es una falla de la DGII) | Esperar el webhook, o repetir con la misma Idempotency-Key. |
Failed |
Error técnico | Se reintenta; ver Errores. |
Esperar el resultado: ?wait=result
Sección titulada «Esperar el resultado: ?wait=result»Espera lo mismo que ?wait=sent y, con el trackId, hasta 4 s más por el resultado de la DGII, sin pasar de 8 s desde
que llegó la solicitud. Sirve si tu sistema necesita saber en el momento si la factura fue aceptada o rechazada.
La respuesta sigue siendo 202, también con un rechazo (un rechazo de la DGII no es un error de la solicitud). El campo
resultWait dice cómo terminó:
resultWait |
Qué pasó | Qué hacer |
|---|---|---|
Final |
Llegó el estado final: status es Accepted, AcceptedConditional o Rejected, y dgii.messages trae los mensajes con su explicación (hint) |
Imprimir si es aceptado; corregir y reenviar si es rechazado. |
TimedOut |
Se envió (trae trackId), pero la DGII no dio el resultado a tiempo |
Imprimir como con Sent. El resultado llega por webhook o consulta. |
NotSent |
No se envió: mira sentWait (Contingency, TimedOut o Failed) |
Lo que diga sentWait. |
Repetir la solicitud con la misma Idempotency-Key y ?wait=result espera igual; si ya tiene el estado final,
responde en el momento.
Tipo 32 menor de RD$250,000
Sección titulada «Tipo 32 menor de RD$250,000»En la factura de consumo menor de RD$250,000 la DGII recibe el resumen (RFCE), no el e-CF completo, y responde el
resultado en el momento. Por eso no hay trackId: con ?wait=sent la respuesta ya trae el estado final (Accepted o
Rejected). El XML completo se guarda igual. El QR (timbreUrl) es el de la consulta de facturas de consumo.
Timeout de tu cliente HTTP: al menos 10 s
Sección titulada «Timeout de tu cliente HTTP: al menos 10 s»La respuesta puede esperar a la DGII. Configura un timeout de al menos 10 segundos. Si aun así se corta, repite
con la misma Idempotency-Key.
La respuesta
Sección titulada «La respuesta»202 Accepted con el comprobante. Los campos más usados:
| Campo | Qué es |
|---|---|
id |
El ID del comprobante. Úsalo para consultarlo. |
encf |
El e-NCF. |
status |
Signed, Sent, Accepted, AcceptedConditional, Rejected o Failed (y Queued si la firma se hizo después). |
trackId |
El TrackID de la DGII. |
securityCode, signedAt, timbreUrl |
Código de seguridad, fecha y hora de la firma (hora de Santo Domingo) y URL del QR, para la representación impresa. |
dgii |
La última respuesta de la DGII: código, estado y mensajes (con su explicación en hint). |
warnings |
Avisos de tolerancia. |
sentWait, contingency |
Cómo terminó la espera, y los datos de contingencia si aplica. |
Si la firma no se pudo hacer en la misma solicitud, la respuesta viene en Queued, sin los datos para imprimir:
llegan por webhook o consulta.
Reenviar y corregir
Sección titulada «Reenviar y corregir»POST /v1/invoices/{id}/resend (y POST /v1/invoices/{id}/resend/signed para XML firmado):
| Estado | Qué hace |
|---|---|
Rejected |
Exige el documento corregido y crea una nueva versión (version + 1) con firma nueva. Reimprime con los datos nuevos. |
Failed |
Reintenta el mismo comprobante (mismo e-NCF). Antes consultamos a la DGII si ya lo había recibido, para no duplicarlo. |
| Otro | 409 invoice.not_resendable |