Ir al contenido

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. Tu cuenta y tu empresa, con su certificado digital (.p12) cargado.
  2. 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.
  3. 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.
  4. 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.

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.

Ventana de terminal
# 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 }
]
}
}'

Con una API key restringida a una empresa no hace falta companyId: se usa la de la key.

{
"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.
  • id es el ID del comprobante en nuestro sistema: úsalo para consultarlo.
  • encf, securityCode, signedAt y timbreUrl (el QR) son los datos de la representación impresa.
  • status: Sent con trackId: 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.

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 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 de Sent a Accepted). La respuesta trae el encabezado Idempotent-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.

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 ejemplo 422 por 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.

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.

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.

Ventana de terminal
# 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: true
  • Guarda con la factura, en tu sistema, su Idempotency-Key (antes de enviar) y el id del comprobante (al recibir la respuesta).
  • Configura un webhook para enterarte de Accepted o Rejected.
  • 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.