Saltar al contenido principal

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:

#PiezaQué hacesPágina
1AutenticaciónEnvías tu API key en el header X-API-KEY.Autenticación API
2Formato JSONConviertes tu venta al JSON de la DGII.Formato JSON de e-CF
3EnvíoHaces un POST con el JSON y recibes el documentId.Envío de e-CF
4ConsultaPreguntas por lote si ya se firmó y si la DGII lo aceptó.Consulta de e-CF
5ImpresiónImprimes la factura con el código de seguridad y el QR, en tu formato o con el PDF del portal.Representación impresa
6Anulació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.

Tú envías JSON, no XML

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.

AmbienteURL baseUso
TesteCFhttps://api.zarelafact.com/TesteCFDesarrollo y pruebas
CerteCFhttps://api.zarelafact.com/CerteCFCertificación con la DGII
eCFhttps://api.zarelafact.com/eCFProducció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.
¿Atiendes a varios clientes?

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.