La facturación electrónica es una obligación que ha transformado cómo las empresas manejan su contabilidad y relaciones fiscales. En República Dominicana, la Dirección General de Impuestos Internos (DGII) ha implementado el sistema de e-CF (Comprobante Fiscal Electrónico) para garantizar la eficiencia y transparencia en los procesos fiscales.
En esta guía, exploraremos cómo integrar la API de facturación electrónica de la DGII usando la plataforma de Alanube. Desde los conceptos básicos hasta las buenas prácticas de integración, pruebas, seguridad y manejo de contingencias, aprenderás todo lo necesario para realizar una implementación exitosa.
¿Para qué sirve una API de e-CF en RD?
Casos típicos: ERP propio, e-commerce/checkout, POS retail, integraciones multisucursal
La API de facturación electrónica permite automatizar el proceso de emisión de facturas y otros documentos fiscales en cumplimiento con las normativas de la DGII. Este tipo de integración es útil en varios casos de uso:
- ERP propio: empresas con sistemas de gestión interna que necesitan automatizar la facturación y enviar los e-CF a la DGII de forma transparente.
- e-Commerce/checkout: plataformas de comercio electrónico que requieren emitir facturas electrónicas automáticamente después de un proceso de compra en línea.
- POS retail: sistemas de punto de venta que gestionan ventas físicas y deben enviar los comprobantes fiscales electrónicos en tiempo real.
- Integraciones multisucursal: empresas con múltiples puntos de venta o sucursales que necesitan centralizar la emisión de facturas a través de una única plataforma.
Tipos de e-CF soportados y cuándo usar cada uno
Los principales tipos de documentos fiscales que se pueden emitir mediante la API de la DGII son:
- Factura: documento estándar para ventas de productos o servicios.
- Nota de Crédito (NC): usada para ajustar o anular facturas previamente emitidas.
- Nota de Débito (ND): similar a la nota de crédito, pero se utiliza cuando se incrementa el valor de una factura original.
Visión de negocio y técnica: la correcta elección entre estos tipos depende del flujo de negocio y las necesidades de reconciliación fiscal de la empresa. La API de Alanube soporta todos estos tipos de documentos, garantizando un manejo adecuado de las operaciones fiscales.
Resultado esperado: envío, validación DGII, estados y resguardo
El resultado esperado tras la integración de la API de e-CF es el envío de los documentos fiscales (facturas, notas de crédito, etc.) a la DGII, la validación de estos por parte de la entidad y la correcta asignación de estados que confirmen el proceso (aceptado, rechazado, en proceso, etc.).
Es crucial mantener un sistema de resguardo y auditoría, ya que los documentos fiscales deben almacenarse por 10 años según las normativas de la DGII.
Arquitectura en 1 minuto: cómo fluye un e-CF desde tu app → Alanube → DGII
La integración de la API de facturación electrónica involucra múltiples pasos, pero podemos entenderla de manera sencilla. A continuación, se describe el flujo básico:
Diagrama narrado: Cliente → Backend → API Alanube → DGII → Webhooks/ERP
- Cliente: el cliente realiza una transacción o compra en el sistema (ERP, e-commerce, POS).
- Backend: la aplicación backend procesa la información de la transacción y genera el e-CF.
- API Alanube: el backend llama a la API de Alanube para enviar el documento fiscal a la DGII.
- DGII: La DGII recibe el documento, valida la información y retorna el estado de aceptación.
- Webhooks/ERP: la API de Alanube envía un webhook al sistema backend, informando sobre el estado de la factura (aceptada, rechazada, en proceso, etc.).
Flujo de emisión paso a paso
- Generación de e-CF: el sistema genera el comprobante fiscal en el formato requerido por la DGII.
- Envío a la API: el comprobante se envía mediante una llamada API a Alanube.
- Validación DGII: La DGII valida el e-CF, revisando su formato y contenido fiscal.
- Estados de respuesta: Alanube retorna el estado del e-CF, que puede ser “accepted”, “rejected”, “processing”, o “accepted_conditional”.
- Almacenamiento: una vez validado, el comprobante se almacena de forma segura según las normativas.
Entornos: Sandbox vs Producción y cómo alternar
Es crucial realizar pruebas exhaustivas en el entorno Sandbox antes de pasar a producción. En Sandbox, podrás simular la emisión de e-CF y verificar que todo esté funcionando correctamente.
- Sandbox: ideal para pruebas y validación de integraciones.
- Producción: una vez las pruebas sean exitosas, podrás mover tu integración a producción.
Para alternar entre ambos entornos, solo necesitas configurar las credenciales adecuadas de API y cambiar el endpoint de la API de Alanube.
Checklist de prerrequisitos: RNC, certificado digital, credenciales de API y buenas prácticas
RNC y roles necesarios
Antes de integrar la API, necesitas asegurarte de tener el RNC (Registro Nacional de Contribuyentes) registrado correctamente ante la DGII, así como los roles de usuario necesarios para operar con la plataforma de facturación electrónica.
Certificado digital: obtención, vinculación y rotación
El certificado digital es esencial para la autenticidad de los documentos fiscales. Puedes obtenerlo a través de la DGII y vincularlo a tu cuenta en Alanube. Además, debes implementar un sistema para rotar el certificado digital periódicamente para mantener la seguridad de tus transacciones.
Credenciales de API: llaves, scopes y buenas prácticas
Al generar tus credenciales de API, asegúrate de usar las mejores prácticas de seguridad:
- Llaves de API: no expongas tus claves API en el frontend.
- Scopes: define los alcances necesarios para cada operación.
- Seguridad: utiliza HTTPS y cifrado para todas las comunicaciones.
How-To: tu primer e-CF por API
¿Cómo emitir tu primer e-CF?
En menos de 15 minutos, puedes enviar tu primer comprobante fiscal utilizando Node.js, Python o .NET. Aquí te mostramos cómo hacerlo en Node.js:
- Instala las dependencias: usa NPM o Yarn para instalar las librerías necesarias.
- Obtén las credenciales: asegúrate de tener las llaves de API y el certificado digital.
- Configura la solicitud: configura la URL de la API de Alanube y los datos de la factura.
- Envía la solicitud: realiza una llamada POST a la API con los datos de la factura.
- Maneja la respuesta: recibe el estado de la transacción y actúa en consecuencia.
Postman + Sandbox: arranca en 10 pasos
- Crea una cuenta en Alanube.
- Obtén tus credenciales de API.
- Configura Postman: importa las colecciones de Alanube.
- Define las variables: establece las variables de tu entorno (RNC, certificado, etc.).
- Realiza tu primer request: envía una factura de prueba.
- Revisa la respuesta: verifica los estados de la transacción.
- Simula los webhooks: testea los webhooks de Alanube.
- Realiza pruebas de error: simula posibles errores.
- Reintentos: prueba los reintentos en caso de fallos temporales.
- Ajusta la configuración: asegúrate de que todo esté funcionando correctamente.
Estados DGII y errores comunes: tabla “estado → causa → acción recomendada”
| Estado | Causa probable | Acción recomendada |
| processing | En espera de validación en DGII | Reintenta más tarde, espera hasta 15 minutos. |
| accepted | Aceptado por DGII | Almacena el comprobante, envía a ERP. |
| accepted_conditional | Aceptado con condiciones | Revisa condiciones, resuelve y reenvía si es necesario. |
| rejected | Error en la validación del comprobante | Revisa el formato o datos de la factura y corrige. |
Códigos y mensajes comunes
- timeout: asegúrate de que la conexión de red sea estable.
- schema error: verifica el esquema de los datos enviados.
- certificado inválido: renueva o valida tu certificado digital.
Patrones de reintento
- Exponencial backoff: espaciar los intentos de reintento.
- Circuit breaker: detener intentos después de múltiples fallos.
- Dead-letter queue: colocar los errores en una cola separada para ser procesados manualmente.
Contingencia sin internet o caída del servicio: qué emitir, cómo reconciliar y recuperar trazabilidad
Si el servicio de facturación está caído o no tienes acceso a internet, debes registrar los comprobantes de forma manual. Una vez recuperado el servicio, envíalos a la DGII y asegúrate de mantener la trazabilidad de las transacciones.
Seguridad y cumplimiento: OWASP + resguardo de XML/PDF por 10 años
La seguridad es esencial para proteger los datos fiscales de los clientes. Utiliza KMS/HSM para el almacenamiento seguro de claves y certificados. Implementa auditoría continua para garantizar el cumplimiento y el acceso a los documentos.
Observabilidad SRE para e-CF: métricas clave, alertas sugeridas y tableros por tipo de comprobante
Las métricas clave incluyen tiempos de respuesta, tasas de error y latencia. Configura alertas para el monitoreo constante del sistema y utiliza tableros para visualizar el estado de los documentos fiscales por tipo de comprobante.
Comparativa rápida: API Alanube vs Facturador Gratuito vs conector propio (TCO, SLA, escalabilidad)
¿Cuándo usar cada opción?
| Opción | Ideal para | Características |
| API Alanube | Escalabilidad, integraciones | SLA alto, soporte, seguridad, webhooks |
| Facturador Gratuito | Empresas pequeñas, bajo volumen | Sin costo, limitado a facturación básica |
| Conector propio | Empresas con requerimientos específicos | Personalización total, mayor costo y tiempo de desarrollo |
Costos y riesgos
- TCO: El costo total de propiedad dependerá de la escala y la complejidad de la integración.
- Mantenimiento: La API Alanube es más fácil de mantener, mientras que un conector propio requiere actualizaciones frecuentes.
Decisión en 60 segundos
| Criterio | API Alanube | Facturador Gratuito | Conector Propio |
| API/Webhooks | Sí | No | Sí |
| Soporte | Premium | Básico | Personalizado |
| Escalabilidad | Alta | Baja | Alta |
| Seguridad | Alta | Media | Alta |
| Costo | Medio | Bajo | Alto |
Con esta guía, ahora tienes toda la información para integrar de manera eficiente y segura la API de facturación electrónica de la DGII en tu sistema.
