Factura electrónica en 5 minutos, con un JSON que cualquiera entiende.

Simple de integrar, completa ante la DGII

Escribes solo lo que tu negocio ya sabe: el cliente y los productos, con su precio y su ITBIS. EF2 hace el resto.

Tu primera factura en 3 pasos

URL base:

Autenticación

Envía tu token en cada petición con el header estándar:

Authorization: Bearer TU_TOKEN

• El token identifica a tu empresa: con él sabemos quién es el emisor.
• Por seguridad no se acepta en la URL (así nunca queda en historiales ni logs).
• Si tu token tiene IPs permitidas, llama desde esas IPs. Error IP_NO_AUTORIZADA.
• Nunca pongas el token en el código de una página web pública o en una app móvil: llama a la API desde tu servidor.
• Todo viaja por HTTPS. Las respuestas son JSON en UTF-8.

Públicos (sin token): GET /, GET /estado, GET /catalogos, GET /catalogos/geografia.

Lo que EF2 completa por ti

ITBIS por producto

El ITBIS va en cada línea, al lado del precio. Así una misma factura puede tener productos que llevan ITBIS y productos que no:

Es obligatorio en cada producto. En el encabezado solo se indica si tus precios ya incluyen el ITBIS: "itbis_incluido": true o false (por defecto).

Descuentos

• Por producto: "descuento": 200 (monto) o "descuento": "10%".
• General: "descuento_porcentaje": 5 o "descuento_monto": 500 en el encabezado. Se reparte proporcionalmente entre los productos.
• Los descuentos se aplican sobre la misma base que tus precios: sin ITBIS (por defecto) o con ITBIS si el encabezado dice "itbis_incluido": true.

Resultado: subtotal , ITBIS , total .

Dólares y otras monedas

Envía "moneda": "USD" y la tasa del día en "tasa". Los precios van en la moneda indicada; la DGII recibe el comprobante en pesos (precio × tasa) y el PDF muestra la moneda original.

La respuesta trae ambos: totales.total en pesos y totales.moneda_original (USD, total y tasa).

Crédito y formas de pago

• "pago": "contado" (por defecto), "credito" o "gratuito".
• A crédito: "dias_credito": 30 (por defecto 30) o "vence": "2026-12-31".
• Forma de pago (opcional): "forma_pago": "transferencia", que equivale al total completo.
• Varias formas (hasta 7): "pagos": [{"forma":"efectivo","monto":500},{"forma":"tarjeta","monto":450}]. La suma debe ser igual al total.
• Formas: efectivo, transferencia, cheque, deposito, tarjeta, credito, bono, permuta, nota_credito, otra.

Referencia: nunca más facturas duplicadas

Si se cae el internet justo después de enviar, ¿se emitió o no? Con "referencia" (tu número de pedido o ticket, hasta 20 caracteres) no tienes que adivinar:

• Reenvía exactamente lo mismo con la misma referencia: recibes el mismo e-NCF con "repetido": true y el header Idempotent-Replayed: true. No se emite otra.
• Si dos envíos llegan a la vez, uno emite y el otro recibe EN_PROCESO.
• Si usas la misma referencia con otros datos, recibes REFERENCIA_USADA (protege contra errores de numeración).
• Si la DGII rechazó, puedes corregir y reenviar con la misma referencia.
• La referencia se imprime en la factura (número de factura interna) y sirve para buscar: GET /facturas?referencia=PED-1001.

Validaciones antes de la DGII

Un rechazo de la DGII puede quemar tu número e-NCF. Por eso, antes de enviar, revisamos todo lo que causaría un rechazo. Si algo falla, respondemos NO_PASA_VALIDACION_DGII y no se usa ninguna secuencia.

Estados del comprobante

Pruebas y producción

• Mismo endpoint, mismo token. El ambiente DGII (certificación o producción) lo define tu empresa en EF2. Míralo en GET /cuenta → ambiente.
• Para probar sin emitir nada, usa POST /simular: hace todas las validaciones y cálculos y te muestra el e-CF completo, sin enviar ni usar secuencia.
• En certificación, los comprobantes van al ambiente de pruebas de la DGII y no tienen validez fiscal.

Endpoints

Base: · JSON en UTF-8 · Todas las respuestas traen ok y el header X-Request-Id.

{
  "encabezado": {
    "tipo": "31",
    "referencia": "PED-1001",
    "itbis_incluido": false
  },
  "cliente": {
    "rnc": "131703836",
    "nombre": "GRUPO MEDIA SOFT TECHNOLOGY GMS SRL",
    "correo": "compras@cliente.com"
  },
  "productos": [
    {
      "nombre": "Laptop HP 15",
      "cantidad": 2,
      "precio": 25000,
      "itbis": 18
    },
    {
      "nombre": "Instalación y configuración",
      "precio": 1500,
      "itbis": 18,
      "servicio": true
    }
  ]
}

{
  "ok": true,
  "estado": "aceptado",
  "mensaje": "¡Listo! La DGII aceptó el comprobante E310000000123.",
  "encf": "E310000000123",
  "tipo": "31",
  "tipo_nombre": "Factura de Crédito Fiscal",
  "fecha": "04-11-2026",
  "referencia": "PED-1001",
  "cliente": {
    "rnc": "131703836",
    "nombre": "GRUPO MEDIA SOFT TECHNOLOGY GMS SRL",
    "correo": "compras@cliente.com"
  },
  "totales": {
    "subtotal": 51500.0,
    "descuento": 0.0,
    "itbis": 9270.0,
    "total": 60770.0,
    "moneda": "DOP"
  },
  "enlaces": {
    "qr": "https://ecf.dgii.gov.do/ecf/ConsultaTimbre?RncEmisor=101000001&RncComprador=131703836&ENCF=E310000000123&FechaEmision=04-11-2026&MontoTotal=60770.00&FechaFirma=04-11-2026%2010%3A15%3A42&CodigoSeguridad=Xy9Zq1",
    "pdf": "https://storage.googleapis.com/ef2-facturas/101000001_E310000000123.pdf?X-Goog-Signature=…",
    "xml": "https://storage.googleapis.com/ef2-facturas/101000001E310000000123.xml?X-Goog-Signature=…",
    "consulta": "https://lite.ef2.do/v1/facturas/E310000000123"
  },
  "dgii": {
    "estado": "Aceptado",
    "mensaje": null,
    "track_id": "5f7a1c2e-90b4-4c1d-9a51-2b7d0c3e8f11",
    "codigo_seguridad": "Xy9Zq1"
  },
  "correo": {
    "enviado": true,
    "para": "compras@cliente.com",
    "detalle": null
  },
  "secuencia_vence": "31-12-2028",
  "id_ef2": 48211,
  "avisos": [],
  "request_id": "req_7c1e0a9b3f2d4e11"
}

{
  "encabezado": {
    "tipo": "32",
    "referencia": "TK-55821",
    "itbis_incluido": true,
    "forma_pago": "efectivo"
  },
  "productos": [
    {
      "nombre": "Café americano",
      "cantidad": 2,
      "precio": 150,
      "itbis": 18
    },
    {
      "nombre": "Croissant",
      "precio": 125,
      "itbis": 18
    }
  ]
}

{
  "ok": true,
  "simulacion": true,
  "valido": true,
  "mensaje": "Todo correcto: este comprobante pasa las validaciones. Envíalo igual a POST /v1/facturas.",
  "errores": [],
  "tipo": "32",
  "tipo_nombre": "Factura de Consumo",
  "cliente": null,
  "productos": [
    {
      "linea": 1,
      "nombre": "Café americano",
      "cantidad": 2.0,
      "precio": 127.12,
      "itbis_tasa": 18,
      "subtotal": 254.24,
      "itbis": 45.76,
      "total": 300.0,
      "descuento": 0.0
    },
    {
      "linea": 2,
      "nombre": "Croissant",
      "cantidad": 1.0,
      "precio": 105.93,
      "itbis_tasa": 18,
      "subtotal": 105.93,
      "itbis": 19.07,
      "total": 125.0,
      "descuento": 0.0
    }
  ],
  "totales": {
    "subtotal": 360.17,
    "descuento": 0.0,
    "itbis": 64.83,
    "total": 425.0,
    "moneda": "DOP"
  },
  "avisos": [],
  "ecf": {
    "ECF": {
      "Encabezado": {
        "Version": "1.0",
        "IdDoc": {
          "TipoeCF": "32",
          "…": "…"
        },
        "Emisor": {
          "RNCEmisor": "101000001",
          "…": "…"
        },
        "Totales": {
          "…": "…"
        }
      },
      "DetallesItems": {
        "Item": [
          "…"
        ]
      }
    }
  }
}

{
  "ok": true,
  "comprobante": {
    "encf": "E310000000123",
    "tipo": "31",
    "tipo_nombre": "Factura de Crédito Fiscal",
    "estado": "aceptado",
    "estado_texto": "aceptada",
    "fecha": "04-11-2026",
    "referencia": "PED-1001",
    "cliente": {
      "rnc": "131703836",
      "nombre": "GRUPO MEDIA SOFT TECHNOLOGY GMS SRL",
      "correo": "compras@cliente.com"
    },
    "totales": {
      "gravado": 51500.0,
      "exento": 0.0,
      "itbis": 9270.0,
      "descuento": 0.0,
      "total": 60770.0,
      "moneda": "DOP"
    },
    "enlaces": {
      "qr": "https://ecf.dgii.gov.do/ecf/ConsultaTimbre?…",
      "pdf": "https://storage.googleapis.com/…pdf",
      "xml": "https://storage.googleapis.com/…xml"
    },
    "dgii": {
      "track_id": "5f7a1c2e-90b4-4c1d-9a51-2b7d0c3e8f11",
      "mensaje": null
    },
    "secuencia_vence": "31-12-2028",
    "productos": [
      {
        "linea": 1,
        "nombre": "Laptop HP 15",
        "cantidad": 2.0,
        "precio": 25000.0,
        "subtotal": 50000.0,
        "itbis": 18,
        "servicio": false
      },
      {
        "linea": 2,
        "nombre": "Instalación y configuración",
        "cantidad": 1.0,
        "precio": 1500.0,
        "subtotal": 1500.0,
        "itbis": 18,
        "servicio": true
      }
    ]
  }
}

curl -L -H "Authorization: Bearer TU_TOKEN" -o factura.pdf \
  https://lite.ef2.do/v1/facturas/E310000000123/pdf

{
  "motivo": "La venta se canceló"
}

{
  "ok": true,
  "estado": "aceptado",
  "mensaje": "¡Listo! La DGII aceptó el comprobante E340000000045.",
  "encf": "E340000000045",
  "tipo": "34",
  "tipo_nombre": "Nota de Crédito",
  "fecha": "04-11-2026",
  "referencia": null,
  "totales": {
    "total": 60770.0,
    "moneda": "DOP"
  },
  "nota": {
    "factura": "E310000000123",
    "tipo": "total",
    "motivo": "La venta se canceló"
  },
  "enlaces": {
    "qr": "https://ecf.dgii.gov.do/ecf/ConsultaTimbre?…",
    "pdf": "https://storage.googleapis.com/ef2-facturas/…pdf",
    "xml": "https://storage.googleapis.com/ef2-facturas/…xml",
    "consulta": "https://lite.ef2.do/v1/facturas/E340000000045"
  },
  "dgii": {
    "estado": "Aceptado",
    "mensaje": null,
    "track_id": "0c2d…",
    "codigo_seguridad": "Qw8Rt2"
  },
  "correo": {
    "enviado": true,
    "para": "compras@cliente.com",
    "detalle": null
  },
  "secuencia_vence": "31-12-2027",
  "id_ef2": 48230,
  "avisos": [],
  "request_id": "req_1f2e3d4c5b6a7980"
}

{
  "factura": "E310000000123",
  "motivo": "Devolución total de la mercancía",
  "tipo": "total"
}

{
  "factura": "E310000000123",
  "motivo": "Cliente devolvió 1 laptop",
  "tipo": "parcial",
  "devolver": [
    {
      "linea": 1,
      "cantidad": 1
    }
  ]
}

{
  "factura": "E310000000123",
  "motivo": "Corrección del nombre del cliente",
  "tipo": "texto"
}

{
  "factura": "E310000000123",
  "motivo": "Cargo por envío express",
  "productos": [
    {
      "nombre": "Envío express",
      "precio": 750,
      "itbis": 18,
      "servicio": true
    }
  ]
}

{
  "ok": true,
  "empresa": {
    "rnc": "101000001",
    "razon_social": "MI EMPRESA SRL",
    "nombre_comercial": "MI EMPRESA",
    "direccion": "Av. Winston Churchill #25, Santo Domingo",
    "municipio": "010101",
    "provincia": "010000",
    "correo": "facturas@miempresa.com",
    "telefono": "809-555-0000"
  },
  "ambiente": "produccion",
  "correos": {
    "envia_al_cliente": true,
    "copia_a": "contabilidad@miempresa.com"
  },
  "lista_para_facturar": true,
  "pendientes": [],
  "secuencias": [
    {
      "tipo": "31",
      "nombre": "Crédito Fiscal",
      "disponibles": 1250,
      "vence": "2028-12-31",
      "estado": "lista",
      "rangos": [
        {
          "desde": "E310000000001",
          "hasta": "E310000002000",
          "ultimo_usado": "E310000000750",
          "disponibles": 1250,
          "vence": "2028-12-31",
          "estado": "activa"
        }
      ]
    },
    {
      "tipo": "32",
      "nombre": "Consumo",
      "disponibles": 98500,
      "vence": null,
      "estado": "lista",
      "rangos": [
        "…"
      ]
    },
    {
      "tipo": "34",
      "nombre": "Nota de Crédito",
      "disponibles": 40,
      "vence": "2027-12-31",
      "estado": "por_agotarse",
      "rangos": [
        "…"
      ]
    }
  ]
}

{
  "ok": true,
  "encontrado": true,
  "rnc": "131703836",
  "nombre": "GRUPO MEDIA SOFT TECHNOLOGY GMS SRL",
  "nombre_comercial": "GRUPO MEDIA SOFT TECHNOLOGY GMS",
  "estado": "ACTIVO",
  "categoria": "",
  "facturador_electronico": true
}

{
  "ok": true,
  "estado": "operativo",
  "version": "1.0.0",
  "hora": "2026-11-04T10:15:42-04:00",
  "componentes": {
    "motor_ef2": {
      "ok": true,
      "ms": 38
    },
    "base_de_datos": {
      "ok": true
    },
    "envio_dgii": {
      "ok": true
    },
    "almacenamiento": {
      "ok": true
    }
  }
}

Diccionario de campos

Todo lo que no es obligatorio tiene un valor por defecto sensato. Los nombres alternativos (entre paréntesis) también se aceptan, para que conectes tu sistema sin renombrar nada.

encabezado

Opcional por completo. Cualquier campo puede ir también al nivel raíz del JSON.

cliente

Opcional en Consumo (32, menos de RD$250,000) y no aplica en Gastos Menores (43). También se acepta como comprador, o como proveedor en Compras (41) y Pagos al Exterior (47).

productos

Lista de 1 a 1,000 líneas. También se acepta como items, detalle o lineas.

Notas de crédito y débito

Respuesta de emisión

Igual para facturas y notas (201).

{
  "ok": true,
  "estado": "aceptado",
  "mensaje": "¡Listo! La DGII aceptó el comprobante E310000000123.",
  "encf": "E310000000123",
  "tipo": "31",
  "tipo_nombre": "Factura de Crédito Fiscal",
  "fecha": "04-11-2026",
  "referencia": "PED-1001",
  "cliente": {
    "rnc": "131703836",
    "nombre": "GRUPO MEDIA SOFT TECHNOLOGY GMS SRL",
    "correo": "compras@cliente.com"
  },
  "totales": {
    "subtotal": 51500.0,
    "descuento": 0.0,
    "itbis": 9270.0,
    "total": 60770.0,
    "moneda": "DOP"
  },
  "enlaces": {
    "qr": "https://ecf.dgii.gov.do/ecf/ConsultaTimbre?RncEmisor=101000001&RncComprador=131703836&ENCF=E310000000123&FechaEmision=04-11-2026&MontoTotal=60770.00&FechaFirma=04-11-2026%2010%3A15%3A42&CodigoSeguridad=Xy9Zq1",
    "pdf": "https://storage.googleapis.com/ef2-facturas/101000001_E310000000123.pdf?X-Goog-Signature=…",
    "xml": "https://storage.googleapis.com/ef2-facturas/101000001E310000000123.xml?X-Goog-Signature=…",
    "consulta": "https://lite.ef2.do/v1/facturas/E310000000123"
  },
  "dgii": {
    "estado": "Aceptado",
    "mensaje": null,
    "track_id": "5f7a1c2e-90b4-4c1d-9a51-2b7d0c3e8f11",
    "codigo_seguridad": "Xy9Zq1"
  },
  "correo": {
    "enviado": true,
    "para": "compras@cliente.com",
    "detalle": null
  },
  "secuencia_vence": "31-12-2028",
  "id_ef2": 48211,
  "avisos": [],
  "request_id": "req_7c1e0a9b3f2d4e11"
}

Ejemplos por tipo de comprobante

Todos están verificados con /simular. Cópialos, cambia los datos y envíalos. También están en lite.ef2.do/ejemplos/ y en la colección de Postman.

Código listo para copiar

Una función que emite y maneja los errores. Reemplaza TU_TOKEN; en producción léelo de una variable de entorno.

Probar en vivo

Llama a la API real desde tu navegador. Por defecto usa Simular, que no envía nada a la DGII. Tu token solo se guarda en esta pestaña si marcas "Recordar".

Errores y cómo resolverlos

Todos los errores tienen la misma forma. detalles lista cada campo a corregir, y ayuda enlaza a esta tabla.

Lista para producción

Preguntas frecuentes

Catálogos: lo que puedes enviar

Todos los valores que acepta cada campo y su código oficial de la DGII. Tú envías el valor de la primera columna (o un alias) y EF2 lo convierte. También en JSON: GET /v1/catalogos y GET /v1/catalogos/geografia.

Tipo de comprobante

Campo: encabezado.tipo

Si no lo envías: 31 si el cliente tiene RNC o cédula; 32 si no.

ITBIS de cada producto

Campo: productos[].itbis · encabezado.itbis_incluido

Es obligatorio en cada producto (en 43, 44, 46 y 47 puedes omitirlo: la ley lo fija en 0). En el encabezado solo va "itbis_incluido": true si tus precios ya incluyen el ITBIS, o false (por defecto).

Bien o servicio

Campo: productos[].servicio

También acepta "tipo": "bien" o "tipo": "servicio". En Pagos al Exterior (47) todo va como servicio.

Tipo de pago

Campo: encabezado.pago

Formas de pago

Campo: encabezado.forma_pago · encabezado.pagos[].forma

Con pagos puedes combinar hasta 7 formas; la suma debe ser igual al total.

Tipo de ingresos

Campo: encabezado.tipo_ingresos

Por defecto 01. No aplica en 41, 43 ni 47.

Unidades de medida

Campo: productos[].unidad

Por defecto unidad. Escribe el nombre o el código DGII. Hoy EF2 registra estas 16:

Monedas

Campo: encabezado.moneda · encabezado.tasa

Por defecto DOP. Con otra moneda envía también "tasa" (tasa de cambio a pesos): la DGII recibe pesos y el PDF muestra la moneda original.

Notas de crédito y débito

Campo: tipo (en POST /v1/notas-credito)

Retenciones

Provincias, municipios y distritos municipales

Campo: cliente.provincia · cliente.municipio

Códigos oficiales de 6 dígitos de la DGII (582: 32 provincias, 157 municipios y 393 distritos municipales). Toca una provincia para ver los suyos.

Versiones y soporte

La versión va en la URL (/v1). Cualquier cambio que pueda romper tu integración irá en /v2; en /v1 solo se agregan campos nuevos y opcionales.

¿Dudas? Usa el asistente de la documentación principal o escribe a tu ejecutivo de EF2. Incluye siempre el request_id de la respuesta.

Si necesitas enviar el formato e-CF completo, la API principal de EF2 usa el mismo token y las mismas secuencias.