Cómo funciona la integración
Ya tienes cuenta, certificado y API key. Ahora adaptas tu sistema. Todo el trabajo técnico son estas piezas, en este orden:
| # | Pieza | Qué haces | Página |
|---|---|---|---|
| 1 | Autenticación | Envías tu API key en el header X-API-KEY. | Autenticación API |
| 2 | Formato JSON | Conviertes tu venta al JSON de la DGII. | Formato JSON de e-CF |
| 3 | Envío | Haces un POST con el JSON y recibes el documentId. | Envío de e-CF |
| 4 | Consulta | Preguntas por lote si ya se firmó y si la DGII lo aceptó. | Consulta de e-CF |
| 5 | Impresión | Imprimes la factura con el código de seguridad y el QR, en tu formato o con el PDF del portal. | Representación impresa |
| 6 | Anulación (opcional) | Anulas secuencias de eNCF que no llegaron a la DGII. | Anulación de e-NCF |
¿Necesitas el JSON de un tipo concreto (31, 32, 33, 34, 41, 43…)? Está en Ejemplos JSON por tipo.
ZarelaFact convierte el JSON a XML, lo firma con tu certificado, lo envía a la DGII y guarda el XML firmado. No necesitas generar ni firmar XML.
Ambientes
Entre ambientes solo cambian la URL base y la API key; el resto de tu código es igual.
| Ambiente | URL base | Uso |
|---|---|---|
| TesteCF | https://api.zarelafact.com/TesteCF | Desarrollo y pruebas |
| CerteCF | https://api.zarelafact.com/CerteCF | Certificación con la DGII |
| eCF | https://api.zarelafact.com/eCF | Producción |
El envío es asíncrono
La API responde al instante con 202 y un documentId. Unos segundos después ZarelaFact firma el documento (desde ese momento ya tienes el código de seguridad y el QR para imprimir) y lo envía a la DGII, cuya respuesta llega más tarde. Por eso consultas el estado en un segundo paso.
Tres reglas desde el inicio
- El eNCF lo asigna tu sistema. Guárdalo con la venta antes de llamar a la API; ZarelaFact no reserva números.
- Los reintentos son seguros. Reenviar el mismo JSON con el mismo eNCF devuelve el documento que ya existe; nunca crea otro. La única excepción es un e-CF que la DGII rechazó con
secuenciaUtilizada: false: ese se reenvía (Corregir y reenviar un rechazo). - No frenes la venta esperando a la DGII: emite, imprime y concilia el estado después.
Esta sección usa la API de una cuenta directa (X-API-KEY y rutas /{ambiente}). Un ERP o POS con varios clientes usa la API Partner, con el mismo formato JSON.
¿Programas con un asistente de IA? En Integra con IA tienes el prompt listo para copiar.
Empieza por la autenticación.