API de Facturación Electrónica para Desarrolladores — Integración e-CF DGII

¿Por qué una API para facturación electrónica?

La mayoría de las empresas dominicanas ya cuentan con un sistema para gestionar su operación: un ERP, un punto de venta, un sistema contable desarrollado a medida, o incluso hojas de cálculo conectadas a bases de datos. Cuando la DGII exige facturación electrónica, la pregunta natural es: ¿tengo que reemplazar todo lo que ya funciona?

La respuesta es no. Un enfoque API-first permite que cualquier sistema existente adquiera capacidad de emisión de comprobantes fiscales electrónicos (e-CF) sin modificar su lógica de negocio. Tu sistema sigue generando las facturas como siempre; la API se encarga de convertirlas en documentos electrónicos válidos ante la DGII.

Esto es especialmente relevante para dos perfiles: las software houses que desarrollan soluciones para múltiples clientes y necesitan una integración reutilizable, y los integradores que conectan sistemas heterogéneos dentro de una misma empresa o grupo corporativo. En ambos casos, una API bien diseñada elimina la necesidad de implementar la complejidad del protocolo e-CF en cada proyecto.

Construir la capa de facturación electrónica internamente implica dominar la generación de XML según los esquemas XSD de la DGII, la firma digital con certificados P12, el envío SOAP al servicio de recepción, el manejo de estados asincrónicos, y la recepción de documentos de terceros. Es un esfuerzo significativo que no genera valor diferencial para tu producto. Una API lo abstrae por completo.

La API de DGMax

DGMax expone una API RESTful que cubre el ciclo completo del comprobante fiscal electrónico. El flujo es directo: tu sistema envía un JSON con los datos de la factura, y DGMax se encarga del resto: genera el XML conforme al XSD vigente, aplica la firma digital con el certificado de tu empresa, envía el documento a la DGII, y te devuelve el resultado con el e-NCF asignado y el estado de recepción.

Todos los tipos de documentos electrónicos están soportados: facturas de crédito fiscal (E31), facturas de consumo (E32), notas de débito (E33), notas de crédito (E34), compras (E41), gastos menores (E43), pagos al exterior (E44), y comprobantes de regímenes especiales (E45, E46, E47). También se maneja la recepción de documentos de otros emisores, generando automáticamente los acuses ARECF y ACECF que exige la DGII.

La autenticación se realiza mediante API keys asociadas a cada empresa. Cada solicitud se autentica con un token en el header, lo que facilita la integración en cualquier entorno: servidores, funciones serverless, scripts de migración, o procesos batch automatizados.

Ejemplo de integración

Emitir un comprobante fiscal electrónico a través de la API requiere una sola solicitud HTTP. Tu sistema construye un JSON con los datos comerciales de la transacción y DGMax transforma eso en un e-CF válido. El siguiente ejemplo ilustra la estructura de la solicitud:

POST /api/v1/fiscal-invoices/
Authorization: Bearer tu_api_key

{
  "company": {
    "id": "tu_company_id"
  },
  "ecf": {
    "encabezado": {
      "id_doc": {
        "tipo_ecf": 31,
        "e_ncf": "E310000000337",
        "fecha_vencimiento_secuencia": "31-12-2026",
        "indicador_monto_gravado": 0,
        "tipo_ingresos": "01",
        "tipo_pago": 1
      },
      "emisor": {
        "rnc_emisor": "132786262",
        "razon_social_emisor": "Almax Solutions EIRL",
        "direccion_emisor": "Carretera Mella 1099, Santo Domingo",
        "fecha_emision": "21-02-2026"
      },
      "comprador": {
        "rnc_comprador": "132056892",
        "razon_social_comprador": "Activatec SRL",
        "correo_comprador": "info@activatec.do"
      },
      "totales": {
        "monto_gravado_total": "2000.00",
        "monto_gravado_i1": "2000.00",
        "itbis1": "18",
        "total_itbis": "360.00",
        "total_itbis1": "360.00",
        "monto_total": "2360.00"
      }
    },
    "detalles_items": {
      "item": [
        {
          "numero_linea": "1",
          "indicador_facturacion": 1,
          "nombre_item": "Servicio de consultoría técnica",
          "indicador_bien_o_servicio": 1,
          "cantidad_item": "1",
          "unidad_medida": 43,
          "precio_unitario_item": "1000.00",
          "monto_item": "1000.00"
        },
        {
          "numero_linea": "2",
          "indicador_facturacion": 1,
          "nombre_item": "Licencia software anual",
          "indicador_bien_o_servicio": 1,
          "cantidad_item": "10",
          "unidad_medida": 32,
          "precio_unitario_item": "100.00",
          "monto_item": "1000.00"
        }
      ]
    }
  }
}

La respuesta incluye toda la información que tu sistema necesita para actualizar sus registros: el estado del documento, el código de seguridad, la URL del timbre fiscal, y los enlaces al XML firmado y al PDF generado:

{
  "id": "069965d2-342d-7385-8000-6564e46e003a",
  "status": "REGISTERED",
  "rnc": "132786262",
  "encf": "E310000000337",
  "document_stamp_url": "https://ecf.dgii.gov.do/ecf/ConsultaTimbre?...",
  "security_code": "KsFzfA",
  "signature_date": "21-02-2026 14:30:23",
  "signed_xml": "https://storage.dgmax.do/docs/E310000000337.xml",
  "pdf": "https://storage.dgmax.do/docs/E310000000337.pdf"
}

Detrás de esa solicitud, DGMax ejecuta varios pasos de forma transparente: valida los datos contra las reglas de negocio de la DGII, genera el XML según el esquema XSD correspondiente al tipo de documento, aplica la firma digital con el certificado P12 de tu empresa, envía el documento al servicio de recepción de la DGII, y espera la confirmación. El campo document_stamp_url apunta directamente al timbre fiscal verificable en el portal de la DGII. Todo esto ocurre en segundos y sin intervención adicional de tu sistema.

Compatibilidad

La API de DGMax funciona con cualquier lenguaje de programación o plataforma que pueda realizar solicitudes HTTP. No hay dependencia de un stack tecnológico específico. Si tu sistema puede enviar un POST con un cuerpo JSON y leer la respuesta, puede emitir comprobantes electrónicos.

Esto incluye los lenguajes más comunes en el ecosistema de desarrollo dominicano: Python, PHP, .NET (C#), Node.js, Java, Ruby, y Go. También funciona desde herramientas low-code como Zapier, Make, o Power Automate, y desde cualquier plataforma que soporte webhooks o integraciones HTTP.

Para desarrolladores Python, DGMax ofrece dgmaxclient, un SDK nativo que encapsula las llamadas a la API en métodos idiomáticos de Python. En lugar de construir solicitudes HTTP manualmente, puedes emitir documentos con llamadas como client.documents.create(data). El SDK maneja autenticación, serialización, reintentos y manejo de errores automáticamente.

Límites soft: tu facturación nunca se detiene

Un problema frecuente con las APIs de facturación electrónica es el comportamiento cuando se alcanza el límite mensual de documentos del plan contratado. Muchos proveedores implementan un bloqueo duro (hard limit): al documento número 801, si tu plan incluye 800, la solicitud falla con un error 429 y tu sistema deja de poder facturar.

Esto es especialmente peligroso en integraciones automatizadas. Si tu ERP envía facturas a la API en un proceso batch nocturno y una solicitud es rechazada, el error puede cascadear: la factura queda sin e-NCF, el cliente no recibe su comprobante, y la contabilidad se desincroniza. Peor aún si el bloqueo ocurre un viernes por la noche y nadie lo detecta hasta el lunes.

DGMax utiliza límites soft. Si excedes la asignación mensual de tu plan, los documentos se siguen procesando normalmente. No hay interrupción, no hay errores, no hay facturas perdidas. El excedente se factura según las tarifas de tu plan, y recibes una notificación para que puedas evaluar si conviene ajustar tu suscripción. La facturación de tu empresa nunca se detiene por un límite artificial.

Multi-empresa vía API

Una sola integración con la API de DGMax puede gestionar múltiples empresas (RNCs). Cada empresa tiene su propio certificado digital, su configuración fiscal, y sus secuencias de e-NCF, pero todas se administran desde la misma conexión API.

Este modelo es ideal para tres escenarios comunes. Primero, las software houses que desarrollan un sistema y lo despliegan para múltiples clientes: en lugar de configurar una integración de facturación electrónica para cada cliente, integran una vez contra DGMax y crean empresas adicionales vía API. Segundo, las firmas contables que gestionan la facturación de decenas de clientes: un solo dashboard para monitorear el estado de emisión de todos los RNCs. Tercero, los grupos corporativos con múltiples razones sociales que necesitan consolidar la facturación electrónica bajo una sola plataforma.

La separación entre empresas es estricta: cada RNC opera de forma independiente con su propio certificado, sus documentos, y su historial. No hay riesgo de mezcla de datos entre entidades.

Empieza a integrar hoy

El proceso para comenzar a usar la API de DGMax es inmediato. Crea una cuenta, obtén tus credenciales API, y empieza a enviar documentos de prueba en el entorno de certificación de la DGII. La prueba gratuita de 14 días incluye acceso completo a la API, todos los tipos de documentos, y soporte técnico para tu integración.

Durante el período de prueba puedes enviar documentos al entorno de pruebas de la DGII (TesteCF), validar que tu integración genera los e-CF correctamente, y completar el set de pruebas requerido para la certificación. Una vez certificado, el cambio a producción es un ajuste de configuración: misma API, mismos endpoints, diferente ambiente.