Emitir comprobantes fiscales electrónicos (e-CF)
Permiso de la clave: facturas:emitir. Consultar: facturas:leer.
Dos formas de emitir
| Endpoint | Cuándo usarlo |
|---|---|
POST /v1/facturas |
Factura simple. Usted envía líneas (descripción, cantidad, precio, tasa de ITBIS); BusinessLink calcula totales e impuestos y, si la empresa usa numeración de BusinessLink, asigna el e-NCF. Ideal para apps nuevas. |
POST /v1/ecf |
Documento completo de la DGII (Encabezado, DetallesItems, ...). Para ERP que ya calculan todo y ya numeran (como el conector de Odoo). BusinessLink no recalcula: firma, valida contra el XSD y envía. |
Ambos exigen la cabecera Idempotency-Key.
Tipos de e-CF
| Tipo | Uso |
|---|---|
| 31 | Crédito fiscal: el comprador tiene RNC y puede usarlo como gasto. |
| 32 | Consumo (consumidor final). No es una nota de crédito. RNC del comprador obligatorio desde RD$250,000. |
| 33 | Nota de débito (lleva referencia). |
| 34 | Nota de crédito (siempre con referencia al e-NCF que modifica; no puede devolver más de lo facturado). |
| 41 | Compras a proveedor informal (proveedor y retencion por línea). |
| 43 | Gastos menores (sin comprador, líneas exentas). |
| 44 | Regímenes especiales (exento). |
| 45 | Gubernamental. |
| 46 | Exportaciones (ITBIS tasa 0; comprador extranjero con id_extranjero y pais). |
| 47 | Pagos al exterior (proveedor extranjero, exento, ISR retenido en cada línea). |
Ejemplo de factura simple
{
"tipo_ecf": "31",
"comprador": {"rnc": "101000228", "razon_social": "Cliente Ejemplo SRL", "correo": "compras@cliente.do"},
"lineas": [
{"descripcion": "Consultoria", "cantidad": 2, "precio_unitario": 1500, "itbis": "18", "tipo": "servicio"},
{"descripcion": "Libro", "cantidad": 1, "precio_unitario": 800, "itbis": "exento", "tipo": "bien", "descuento": {"porcentaje": 10}}
],
"tipo_pago": "credito",
"fecha_limite_pago": "2026-11-30"
}
itbispor línea:"18","16","0"o"exento".precios_incluyen_itbis: truesi el precio ya trae el impuesto.- Otra moneda:
moneda: "USD"y precios en dólares;tipo_cambioes opcional con USD (por defecto, venta del Banco Central del cierre anterior; verGET /v1/tasas). - Si omite
razon_socialy el RNC está en el directorio de la DGII, se completa sola.
Nota de crédito (E34)
{
"tipo_ecf": "34",
"comprador": {"rnc": "101000228"},
"lineas": [{"descripcion": "Devolución consultoría", "cantidad": 1, "precio_unitario": 1500, "itbis": "18", "tipo": "servicio"}],
"referencia": {"encf": "E310000000123", "fecha": "2026-11-02", "codigo_modificacion": "3"}
}
codigo_modificacion: 1 anula, 2 corrige texto, 3 corrige montos, 4 reemplazo por contingencia, 5 referencia a consumo.
Estados del comprobante
en_proceso (enviado, esperando a la DGII) → Aceptado, Aceptado Condicional o Rechazado. Con clave bl_test_ el resultado se simula al instante; use numero_factura_interna: "SIMULAR-RECHAZO" o "SIMULAR-CONDICIONAL" para probar esos casos.
GET /v1/facturas/{encf}estado de uno.POST /v1/ecf/estadoscon{"encfs": [...]}estado de hasta 500.GET /v1/facturas/{encf}/pdfy/xmlrepresentación impresa (con QR) y XML firmado. En sandbox el PDF lleva el sello "SIN VALIDEZ FISCAL".- Webhooks: ver webhooks.md.
Numeración (e-NCF)
Cada empresa numera de una de dos maneras (nunca las dos a la vez): su ERP (el e-NCF viene en el documento) o BusinessLink (el secuenciador lo asigna). Detalles en secuencias-encf.md.
Reglas de seguridad
- Con
bl_live_el comprobante es real y se reporta a la DGII; no se puede deshacer desde la API. - Una clave
bl_test_solo ve comprobantes de prueba y unabl_live_solo los reales. - Siempre repita el mismo
Idempotency-Keyal reintentar una factura tras un timeout. Si el documento cambia, use otra clave.