Ir al contenido

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.

Ventana de terminal
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.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.
  • rncEmisor debe ser el RNC de la empresa.
  • Con errores de validación, 422 ecf.validation_failed con la lista en errors (code, field, message). Con solo avisos (diferencias dentro de la tolerancia de la DGII) se envía igual y los avisos vienen en warnings.

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.

Ventana de terminal
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"

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.

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 202 repite la clave en el header Idempotency-Key, y GET /v1/invoices/{id} la devuelve en idempotencyKey.

  • La misma clave con otro cuerpo: 409 idempotency.key_reused.

  • Sin el header: 400 idempotency.key_required.

  • Un error 4xx no 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.

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.

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.

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.

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.

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.

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