Primeros pasos
Al terminar esta guía habrás enviado un e-CF tipo 31 (crédito fiscal) al ambiente de pruebas de la DGII (TesteCF), tendrás su TrackID y sabrás cómo reintentar un envío sin crear una factura duplicada.
1. Lo que necesitas (en el portal)
Sección titulada «1. Lo que necesitas (en el portal)»- Tu cuenta y tu empresa, con su certificado digital (.p12) cargado.
- Tu empresa de pruebas: en Empresas, «Empresa de pruebas». Emite en TesteCF con tu mismo RNC y certificado; nada de lo que hagas ahí cuenta ante la DGII como real.
- Una secuencia e-NCF de TesteCF para el tipo 31, registrada en la ficha de la empresa de pruebas → Secuencias. En TesteCF la DGII no autoriza secuencias: tú defines el rango (por ejemplo, del 1 al 1,000,000 para cada tipo) y lo registras en la ficha de tu empresa de pruebas. Si tu sistema va a poner su propio e-NCF, no hace falta registrarla: ver Numeración.
- Una API key restringida a la empresa de pruebas: en API keys, «Crear», y elige esa empresa. Cópiala: se muestra una sola vez.
En los ejemplos, la API key se lee de la variable de entorno ECF_API_KEY. Nunca la pongas en el código.
2. Envía la factura
Sección titulada «2. Envía la factura»Sin e-NCF: lo asignamos de tu secuencia. Cambia los datos del emisor (rncEmisor es el RNC de tu empresa;
fechaEmision, la fecha de hoy en formato dd-MM-yyyy) y el RNC del comprador, que en TesteCF debe ser un RNC
válido (un contribuyente registrado en la DGII).
Cada factura lleva una Idempotency-Key que genera tu sistema: un identificador único por factura, por ejemplo
un UUID. Se explica en el paso 4.
# Una clave nueva por factura. Guárdala con la factura antes de enviar.IDEMPOTENCY_KEY=$(uuidgen)
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 '{ "document": { "encabezado": { "idDoc": { "tipoeCF": "E31", "tipoIngresos": "IngresosOperaciones", "tipoPago": "Contado", "indicadorMontoGravado": false }, "emisor": { "rncEmisor": "TU_RNC", "razonSocialEmisor": "TU RAZON SOCIAL", "direccionEmisor": "TU DIRECCION", "fechaEmision": "16-11-2026" }, "comprador": { "rncComprador": "RNC_DEL_COMPRADOR", "razonSocialComprador": "Comprador de prueba" }, "totales": { "montoGravadoTotal": 1000, "montoGravadoI1": 1000, "itbis1": 18, "totalItbis": 180, "totalItbis1": 180, "montoTotal": 1180 } }, "items": [ { "numeroLinea": 1, "indicadorFacturacion": "Itbis1", "nombreItem": "Servicio", "indicadorBienoServicio": "Servicio", "cantidadItem": 1, "precioUnitarioItem": 1000, "montoItem": 1000 } ] } }'using 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"));
// Una clave nueva por factura. Guárdala con la factura antes de enviar.var idempotencyKey = Guid.NewGuid().ToString();
var factura = """{ "document": { "encabezado": { "idDoc": { "tipoeCF": "E31", "tipoIngresos": "IngresosOperaciones", "tipoPago": "Contado", "indicadorMontoGravado": false }, "emisor": { "rncEmisor": "TU_RNC", "razonSocialEmisor": "TU RAZON SOCIAL", "direccionEmisor": "TU DIRECCION", "fechaEmision": "16-11-2026" }, "comprador": { "rncComprador": "RNC_DEL_COMPRADOR", "razonSocialComprador": "Comprador de prueba" }, "totales": { "montoGravadoTotal": 1000, "montoGravadoI1": 1000, "itbis1": 18, "totalItbis": 180, "totalItbis1": 180, "montoTotal": 1180 } }, "items": [ { "numeroLinea": 1, "indicadorFacturacion": "Itbis1", "nombreItem": "Servicio", "indicadorBienoServicio": "Servicio", "cantidadItem": 1, "precioUnitarioItem": 1000, "montoItem": 1000 } ] }}""";
using var request = new HttpRequestMessage(HttpMethod.Post, "v1/invoices?wait=sent"){ Content = new StringContent(factura, 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()}");// Node.js 18 o superior (fetch incluido).import { randomUUID } from "node:crypto";
// Una clave nueva por factura. Guárdala con la factura antes de enviar.const idempotencyKey = randomUUID();
const factura = { document: { encabezado: { idDoc: { tipoeCF: "E31", tipoIngresos: "IngresosOperaciones", tipoPago: "Contado", indicadorMontoGravado: false }, emisor: { rncEmisor: "TU_RNC", razonSocialEmisor: "TU RAZON SOCIAL", direccionEmisor: "TU DIRECCION", fechaEmision: "16-11-2026" }, comprador: { rncComprador: "RNC_DEL_COMPRADOR", razonSocialComprador: "Comprador de prueba" }, totales: { montoGravadoTotal: 1000, montoGravadoI1: 1000, itbis1: 18, totalItbis: 180, totalItbis1: 180, montoTotal: 1180 }, }, items: [ { numeroLinea: 1, indicadorFacturacion: "Itbis1", nombreItem: "Servicio", indicadorBienoServicio: "Servicio", cantidadItem: 1, precioUnitarioItem: 1000, montoItem: 1000 }, ], },};
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: JSON.stringify(factura), signal: AbortSignal.timeout(15_000),});console.log(response.status, await response.json());Con una API key restringida a una empresa no hace falta companyId: se usa la de la key.
3. Lee la respuesta
Sección titulada «3. Lee la respuesta»{ "id": "8f6c2a0e-…", "environment": "TestEcf", "ecfType": "E31", "encf": "E310000000001", "status": "Sent", "sentWait": "Sent", "trackId": "c1a2…", "securityCode": "Ab3dE9", "signedAt": "2026-11-16T10:15:02-04:00", "timbreUrl": "https://ecf.dgii.gov.do/testecf/ConsultaTimbre?…", "warnings": []}202 Accepted: el comprobante quedó firmado y enviado a la DGII.ides el ID del comprobante en nuestro sistema: úsalo para consultarlo.encf,securityCode,signedAtytimbreUrl(el QR) son los datos de la representación impresa.status: SentcontrackId: la DGII lo recibió. El resultado final llega unos segundos después: consúltalo o recíbelo por webhook.
La respuesta repite tu Idempotency-Key en el encabezado Idempotency-Key: compárala con la que enviaste para
confirmar a qué factura corresponde. Más adelante, la consulta del comprobante (GET /v1/invoices/{id}) también la
devuelve, en el campo idempotencyKey.
4. La Idempotency-Key
Sección titulada «4. La Idempotency-Key»Un identificador que genera tu sistema, uno por factura (un UUID es lo más sencillo; hasta 100 caracteres), y que
se envía en el encabezado Idempotency-Key de POST /v1/invoices y POST /v1/invoices/signed. Es obligatorio: sin
él, la respuesta es 400 idempotency.key_required.
Para qué sirve
Sección titulada «Para qué sirve»Para reintentar sin riesgo de emitir dos veces. Si tu solicitud no recibe respuesta (timeout, corte de red, caída
de tu servidor), no sabes si la factura se creó. Repite la misma solicitud con la misma Idempotency-Key:
- Si la primera llegó, recibes la misma factura: mismo
id, mismo e-NCF, misma firma y mismo código de seguridad, con su estado actual (que puede haber avanzado, por ejemplo deSentaAccepted). La respuesta trae el encabezadoIdempotent-Replayed: true. No se crea otra factura ni se consume otro e-NCF. - Si la primera no llegó, esta es la que crea la factura.
Con una clave nueva emitirías otra factura, con otro e-NCF. Por eso la clave se genera una vez, se guarda con la factura antes de enviarla y se reutiliza en cada intento.
Si se reutiliza con otro cuerpo
Sección titulada «Si se reutiliza con otro cuerpo»La clave queda unida al contenido con que se creó la factura: la empresa (companyId) y el document. Los espacios
y el orden de los campos no importan; cualquier valor distinto, sí. El parámetro ?wait no forma parte del contenido.
- La misma clave con otro contenido:
409 idempotency.key_reused. No se crea nada. - Si la solicitud falló con un error
4xx(por ejemplo422por un dato inválido), no se creó ninguna factura: corrige el cuerpo y envíalo de nuevo, con la misma clave o con una nueva. - Para corregir una factura rechazada por la DGII no se usa la clave: se reenvía con
POST /v1/invoices/{id}/resend.
Cuánto tiempo es válida
Sección titulada «Cuánto tiempo es válida»No vence. Queda unida a esa factura de forma permanente y es única en toda tu cuenta (todas tus empresas y ambientes). Nunca la reutilices para otra factura, aunque hayan pasado meses.
Reintentar sin duplicar
Sección titulada «Reintentar sin duplicar»Reintenta solo cuando no hubo respuesta, o con 429 o 5xx. Los demás errores (400, 401, 403, 404, 409,
422) no se arreglan repitiendo: corrige la causa.
# Misma $IDEMPOTENCY_KEY en todos los intentos: si el primero llegó, devuelve la misma factura.# --retry repite ante un timeout, 429 o 5xx; no ante 4xx (no uses --retry-all-errors).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 --retry 3 --retry-delay 2 \ -i -d @factura.json# En un reintento que encontró la factura ya creada, la respuesta trae: Idempotent-Replayed: trueusing System.Text;
// idempotencyKey: la que guardaste con la factura. La MISMA en cada intento.static async Task<HttpResponseMessage> EnviarConReintentosAsync(HttpClient http, string factura, string idempotencyKey){ for (var intento = 1; ; intento++) { using var request = new HttpRequestMessage(HttpMethod.Post, "v1/invoices?wait=sent") { Content = new StringContent(factura, Encoding.UTF8, "application/json"), }; request.Headers.Add("Idempotency-Key", idempotencyKey);
TimeSpan espera; try { var response = await http.SendAsync(request); var code = (int)response.StatusCode; if ((code != 429 && code < 500) || intento == 3) { // Idempotent-Replayed: true si la factura ya existía (un intento anterior sí llegó). return response; }
espera = response.Headers.RetryAfter?.Delta ?? TimeSpan.FromSeconds(2 * intento); response.Dispose(); } catch (Exception ex) when (ex is HttpRequestException or TaskCanceledException && intento < 3) { // Timeout o corte de red: no sabemos si llegó. Se repite con la misma clave. espera = TimeSpan.FromSeconds(2 * intento); }
await Task.Delay(espera); }}// idempotencyKey: la que guardaste con la factura. La MISMA en cada intento.async function enviarConReintentos(factura, idempotencyKey) { for (let intento = 1; ; intento++) { let espera = 2000 * intento; try { 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: JSON.stringify(factura), signal: AbortSignal.timeout(15_000), }); if ((response.status !== 429 && response.status < 500) || intento === 3) { // Idempotent-Replayed: true si la factura ya existía (un intento anterior sí llegó). return response; } espera = Number(response.headers.get("Retry-After")) * 1000 || espera; } catch (error) { // Timeout o corte de red: no sabemos si llegó. Se repite con la misma clave. if (intento === 3) throw error; } await new Promise((resolve) => setTimeout(resolve, espera)); }}5. Siguientes pasos
Sección titulada «5. Siguientes pasos»- Guarda con la factura, en tu sistema, su
Idempotency-Key(antes de enviar) y eliddel comprobante (al recibir la respuesta). - Configura un webhook para enterarte de
AcceptedoRejected. - Lee errores y contingencia antes de pasar a producción.
- Para pasar a producción, tu código no cambia, pero tu empresa tiene que estar certificada por la DGII como emisor
electrónico, emitir en Producción (
Ecf) y tener sus secuencias de producción registradas. Después usas una API key de tu empresa real. Los pasos están en Ambientes.