Integración e-CF

01Qué hace Lume y qué haces tú

02Antes de escribir código

El emisor tiene que estar certificado ante la DGII con software = Lume. Sin eso no hay emisión válida, por perfecta que sea la integración. Ese proceso lo acompañamos nosotros y toma entre 7 y 18 días hábiles.

• Un contribuyente no puede estar postulado con dos proveedores a la vez. Si venía en proceso con otro sistema, hay que reiniciar.
• Iniciar la certificación con Lume no lo desconecta de su proveedor actual. Puede seguir facturando hasta que termine.

Puedes crear credenciales y desarrollar contra certecf desde el primer día. Lo que no funciona hasta que la certificación cierre es emitir en producción.

03Tu credencial

Authorization: Bearer lum_cert_...

La credencial identifica a tu sistema, y está autorizada sobre una lista explícita de RNC emisores. El RNC viaja siempre explícito en cada petición; si no estás autorizado sobre él, la respuesta es 403 nombrando ambos.

Si tu sistema atiende a varios emisores, puedes indicar quién disparó la operación:

X-Lume-Actor: cliente_42/usuario_7

Se guarda para auditoría. No otorga permisos.

Auto-inscripción de emisores (credenciales sistema)

Si tu credencial es de scope sistema (un SaaS que atiende a muchos emisores), puedes autorizar tus propios emisores sin intervención nuestra — ideal para altas self-service:

{ "rnc": "131123456" }   → { "ok": true, "rnc": "131123456" }

Es idempotente y queda auditado. La emisión real igual exige que ese RNC esté certificado ante la DGII con software = Lume; inscribir un RNC no certificado no permite emitir todavía.

04El token de DGII

Este es el paso que sorprende, así que va primero.

Transmitir a la DGII exige firmar una semilla con el certificado del emisor y cambiarla por un token de una hora. No basta con que el comprobante venga firmado: la autenticación misma necesita la llave.

Como no custodiamos certificados, ese paso lo haces tú:

# 1. Pedir la semilla
curl https://ecf.dgii.gov.do/certecf/autenticacion/api/autenticacion/semilla

# 2. Firmarla con el certificado del emisor (XML-DSig)

# 3. Cambiarla por un token
curl -X POST https://ecf.dgii.gov.do/certecf/autenticacion/api/autenticacion/validarsemilla \
  -F 'xml=@semilla-firmada.xml;type=text/xml'
# → { "token": "...", "expira": "...", "expedido": "..." }

{
  "token": "...",
  "expira": "2026-09-01T18:09:38Z",
  "environment": "certecf"
}

Lo cacheamos por emisor y ambiente. Renuévalo antes de que venza: sin token vigente no transmitimos — aunque el comprobante sí queda registrado y sale solo cuando entregues uno nuevo.

05Armar el XML (recomendado) o numerar tú

El eNCF va dentro del XML firmado, y la firma cubre el contenido: no se puede renumerar después. Hay dos caminos.

Opción A — Lume arma el XML desde tu venta (recomendado)

Le pasas la venta; Lume reserva el eNCF, arma el e-CF XSD-ordenado con la identidad del emisor tomada del padrón (no del payload), lo valida y te devuelve el XML sin firmar. No reimplementas la lógica fiscal de los 10 tipos.

{
  "environment": "certecf",
  "tipo": "31",
  "rnc": "133281201",
  "referencia": "POS-2026-09-01-00412",
  "comprador": { "rnc": "131123456", "razonSocial": "Ferretería La Nacional" },
  "items": [
    { "descripcion": "Servicio", "cantidad": 1, "precioUnitario": 1000, "indicadorFacturacion": "1" }
  ]
}

{ "encf": "E310000001501", "tipo": "31", "xml": "<ECF>…</ECF>", "vencimiento": "31-12-2026" }

indicadorFacturacion: 1=gravado 18% · 2=gravado 16% · 3=gravado 0% · 4=exento.

Luego firmas ese XML (tu vault / stack) y lo emites en el paso 6.

Opción B — armas tu propio XML

Si ya generas el e-CF en tu stack, pide sólo el número:

{ "rnc": "131123456", "ecfType": "31", "environment": "certecf" }

→ { "encf": "E310000001501", "vencimiento": null }

La reserva es atómica: dos llamadas concurrentes nunca obtienen el mismo número.

06Emitir

Firma el XML (de armar o propio) y envíalo:

Idempotency-Key: {tu-id-de-venta}

{
  "xml": "<ECF>…</ECF>",
  "kind": "ecf",
  "environment": "certecf",
  "referencia": "POS-2026-09-01-00412"
}

{
  "id": "febb8ff5-…",
  "encf": "E320000000103",
  "estado": "transmitido",
  "track_id": "e8c09c43-…",
  "codigo_seguridad": "abc123",
  "qr": "https://ecf.dgii.gov.do/…"
}

Es 202, no 200. Aceptamos el comprobante y la DGII decide después. Tu cajero no espera.

El Idempotency-Key es obligatorio. Reintentar con la misma clave devuelve el mismo comprobante con "idempotente": true y nunca crea un segundo. Es lo que hace seguro reintentar tras un timeout, cuando no sabes si llegamos a recibirlo.

07Saber qué pasó

Y para listar los de un emisor:

Acepta ambiente, estado y limite. Devuelve solo los de ese RNC; si tu credencial no está autorizada sobre él, 403. Para paginar, pasa antes_de con el creado_at del último que recibiste.

Nosotros consultamos el veredicto por ti y reconciliamos. No tienes que hacer polling contra la DGII.

08Errores

Todos verificados contra el servicio, no inventados.

El cuerpo de los errores trae como_resolver cuando hay algo concreto que hacer.

09Ambientes

environment es obligatorio en cada petición. No hay valor por defecto, y testecf está rechazado explícitamente.

10Lo que no está en v0

• Recepción de e-CF de terceros, ARECF y aprobación comercial
• Anulación de secuencias no utilizadas
• Webhooks — hoy se consulta con GET /documentos/{id}
• Sub-rangos por punto de emisión, para POS offline con varias cajas

11Referencia rápida