Documentación de la API

API REST con JSON. Base: https://api-facturador.ltd.do. Ambientes en la ruta: test (TesteCF), cert (CerteCF) y prod (eCF). El mismo código sirve para los tres; solo cambia el segmento y la API key.

Cómo empezar

  1. Cree su cuenta y su empresa.
  2. Suba el certificado .p12 del representante (también se requiere en pruebas).
  3. Cree una API key de TesteCF en «API keys y webhooks».
  4. Emita, consulte y reciba webhooks. Cuando todo funcione, certifíquese con el asistente y cambie a producción.

Autenticación

Envíe la llave en la cabecera X-API-KEY. Cada llave pertenece a un ambiente; usarla en otro responde 403 API_KEY_ENV_MISMATCH.

curl https://api-facturador.ltd.do/v1/test/ecf?limit=5 -H "X-API-KEY: sk_test_xxxxxxxx"

Emitir un e-CF

POST /v1/{env}/ecf. Los nombres de los campos son las etiquetas del XML e-CF v1.0 de la DGII; las fechas van en DD-MM-AAAA. Si omite el e-NCF, lo tomamos de su secuencia vigente. Si omite los datos del emisor, se completan con los de su empresa. Con autoCalc calculamos los montos por línea y los totales.

{
  "ECF": {
    "Encabezado": {
      "IdDoc": {
        "TipoeCF": 31,
        "TipoIngresos": "01",
        "TipoPago": 2,
        "FechaLimitePago": "21-12-2026"
      },
      "Comprador": {
        "RNCComprador": "131880681",
        "RazonSocialComprador": "CLIENTE DE EJEMPLO SRL"
      }
    },
    "DetallesItems": {
      "Item": [
        {
          "NumeroLinea": 1,
          "IndicadorFacturacion": 1,
          "NombreItem": "Servicio de consultoría",
          "IndicadorBienoServicio": 2,
          "CantidadItem": 10,
          "UnidadMedida": 31,
          "PrecioUnitarioItem": 2500
        }
      ]
    }
  },
  "autoCalc": true,
  "externalRef": "PED-1001",
  "notifyEmails": [
    "[email protected]"
  ]
}

Envíe la cabecera Idempotency-Key con un valor único por pedido: si repite la solicitud con la misma llave obtiene la misma respuesta y no se emite un segundo comprobante. Obtenga un ejemplo válido de cualquier tipo con GET /v1/examples?tipo=46.

Validación: por defecto es estricta; un error responde 400 ECF_VALIDATION_FAILED y no se firma, no se envía ni se consume el e-NCF. Con ?validate=false los errores pasan como advertencias. Para validar sin emitir use POST /v1/{env}/ecf/validate.

Respuesta y estados

La respuesta es inmediata (202). Puede imprimir con el código de seguridad y la URL del QR sin esperar a la DGII.

{
  "id": "8b0c1d9e-…",
  "rnc": "101672919",
  "ecf": "E310000000045",
  "internalTrackId": "8b0c1d9e-…",
  "securityCode": "fWCZCV",
  "qr_url": "https://ecf.dgii.gov.do/testecf/consultatimbre?RncEmisor=…",
  "signedDate": "21-11-2026 10:14:09",
  "status": "queued",
  "sendMode": "full"
}
queuedEn cola para enviarse
sentEnviado; esperando resultado
in_processLa DGII lo está procesando
acceptedAceptado (final)
accepted_conditionalAceptado con observaciones (final)
rejectedRechazado (final); vea dgiiMessages
contingencyLa DGII no respondió; se reenvía solo
errorFalló tras varios intentos; reintente con /resend

Consultar

GET  /v1/{env}/ecf/{eNCF}             # un comprobante
POST /v1/{env}/ecf/status              # {"ecfs": [... hasta 100]}
GET  /v1/{env}/ecf/{eNCF}/xml          # XML firmado (?kind=rfce para el resumen)
GET  /v1/{env}/ecf/{eNCF}/print?format=letter|ticket80|ticket58
POST /v1/{env}/ecf/{eNCF}/email        # {"to": ["[email protected]"]}

No consulte comprobantes con estado final: no cambian. Prefiera webhooks; si consulta, espere 3-5 s, 30 s y 2 min, y luego en lote cada 15-30 min.

Factura de consumo y RFCE

Envíe siempre el documento completo. Si el MontoTotal es menor de RD$250,000, a la DGII se envía el Resumen de Factura de Consumo (RFCE) con el código de seguridad del documento firmado, y guardamos el documento completo durante 10 años. La respuesta indica sendMode: "summary". Desde RD$250,000 se envía el documento completo y el comprador debe estar identificado.

Recibidos y aprobación comercial

Registre en la DGII la URL de recepción que le mostramos en el portal. Validamos la firma del emisor, respondemos el acuse de recibo (ARECF) firmado y le avisamos con el webhook INCOMING_INVOICE.

GET  /v1/{env}/received?approval=pending
POST /v1/{env}/received/{id}/approval   # {"approved": false, "rejectionReason": "Precio distinto al cotizado"}

Una aprobación ya enviada responde 409 ALREADY_SENT. Solo las que quedaron en error pueden reenviarse.

Anulación de secuencias

POST /v1/{env}/voids
{"ranges": [{"tipoeCF": 31, "secuenciaDesde": "E310000000100", "secuenciaHasta": "E310000000150"}]}

Hasta 10 bloques por tipo y 10,000 números por bloque, sin solapes ni números ya emitidos. No es idempotente: si recibe un error, consulte el historial antes de reintentar.

Webhooks

Eventos: DOCUMENT_STATUS_UPDATE, INCOMING_INVOICE, COMMERCIAL_APPROVAL y CERTIFICATE_EXPIRING. Cabeceras: X-Ecf-Event, X-Ecf-Delivery-Id, X-Ecf-Timestamp y X-Ecf-Signature con formato t=…,sha256=…. La firma es HMAC-SHA256 con su secreto sobre {t}.{cuerpo}. Compare en tiempo constante y rechace firmas de más de 5 minutos. Responda 2xx en menos de 10 segundos. Reintentamos a 1 min, 5 min, 30 min y 2 h; use X-Ecf-Delivery-Id para no procesar dos veces. Los eventos de prueba traen "test": true.

Cuentas de clientes (casas de software)

Con una cuenta de proveedor crea las cuentas de sus clientes en una sola llamada: usuario, empresa, base de datos aislada, certificado opcional y API key. La contraseña y la llave se devuelven una sola vez.

POST /v1/provider/tenants          (Authorization: Bearer <token del proveedor>)
{"rnc":"130900002","businessName":"CLIENTE SRL","email":"[email protected]","givenName":"Carla",
 "authorizationConfirmed":true,"termsAccepted":true,
 "certificate":{"content":"<base64 .p12>","filename":"cliente.p12"},"certificatePassword":"****"}

GET  /v1/provider/tenants/quota    # {"limit":10,"used":3,"remaining":7}
GET  /v1/provider/usage            # consumo del mes por cliente
POST /v1/provider/tenants/{rnc}/api-keys

SDK oficiales

Sin dependencias externas, con reintentos seguros e idempotencia, y con una función para verificar la firma de los webhooks.

// Node / TypeScript (sdks/node)
import { FacturadorClient } from "@facturador/ecf";   // FacturadorClient.verifyWebhook(secreto, cabecera, cuerpo)
const fe = new FacturadorClient(process.env.FACTURADOR_API_KEY, "test", "https://api-facturador.ltd.do");

# Python 3.9+ (sdks/python/facturador_ecf.py)
from facturador_ecf import FacturadorClient            # FacturadorClient.verify_webhook(...)

// PHP 8.1+ (sdks/php/FacturadorClient.php)
use Facturador\Ecf\FacturadorClient;

// Go (sdks/go)
import facturador "github.com/facturador-rd/ecf-go"

Compatibilidad con MSeller

Si su sistema ya está integrado con MSeller ECF, cambie solo la URL base: aceptamos sus mismas rutas, cabeceras y campos. El ambiente va con el nombre de la DGII: TesteCF, CerteCF o eCF.

POST /{amb}/customer/authentication                       {"email","password"} o {"refreshToken","username"}
POST /{amb}/documentos-ecf                               emitir (X-API-KEY); responde rnc, ecf, internalTrackId, securityCode, qr_url, signedDate
GET  /{amb}/documentos-ecf?ecf=E310000000001             estado: En Cola, Enviado a la DGII, En Proceso, Aceptado, Aceptado Condicional, Rechazado, Error
GET  /{amb}/customer/usage                               consumo del mes
POST /{amb}/customer/provider/sub-accounts               crear la cuenta de un cliente (token de proveedor)
GET  /{amb}/customer/provider/sub-accounts/quota|linked|usage
POST /{amb}/customer/apikey                              {"action":"create"} con X-Tenant-Rnc

Los webhooks usan las mismas cabeceras (X-Ecf-Event, X-Ecf-Delivery-Id, X-Ecf-Signature: t=…,sha256=…) y la misma forma de verificar la firma. El cuerpo del evento sigue el formato de esta API (ver Webhooks).

Errores

Todos los errores tienen la forma {"code","message","requestId","details"}. Incluya el requestId al escribir a soporte.

400ECF_VALIDATION_FAILED, VALIDATION_ERROR, RNC_EMISOR_MISMATCHCorrija los datos; no reintente igual
401UNAUTHORIZEDToken vencido o inválido
403INVALID_API_KEY, API_KEY_ENV_MISMATCH, ENVIRONMENT_NOT_ENABLEDRevise la llave o la etapa de certificación
409DUPLICATE_NCF, NO_SEQUENCE_AVAILABLE, ALREADY_SENTConflicto con el estado actual
412CERTIFICATE_NOT_CONFIGUREDCargue su certificado .p12
429QUOTA_EXCEEDED, RATE_LIMITEDCuota del mes agotada o más de 25 solicitudes por segundo
500INTERNAL_ERROREscríbanos con el requestId

Buenas prácticas

  • Guarde en su sistema el e-NCF, el código de seguridad, la URL del QR, la fecha de firma y el id interno.
  • Si se corta la conexión, consulte el comprobante (o repita con la misma Idempotency-Key) antes de emitir otro.
  • Separe la generación del documento, el envío a la API y el seguimiento; use colas si emite mucho volumen.
  • Nunca ponga API keys, contraseñas ni el certificado en el navegador, en apps móviles ni en chats de IA.
  • Pruebe todo en TesteCF: es ilimitado y responde igual que producción.