Integracion con Zarela PSFE
Esta seccion explica el proceso tecnico para integrar tu sistema con Zarela y emitir e-CF ante la DGII.
Flujo de integracion
La integracion sigue un flujo simple y asincrono:
- Autenticacion — usa tu API key del ambiente (
X-API-KEY). - Prevalidacion (opcional pero recomendada) — envia el documento con
validate=truepara detectar errores sin registrar una emision. - Emision — tu POS asigna el eNCF y lo incluye en el JSON; Zarela lo valida, convierte a XML, firma, encola el envio y responde de inmediato.
- Consulta y seguimiento — consulta el estado final por lote hasta que la DGII lo acepte o rechace.
El POS/ERP no debe bloquear la venta esperando la aceptacion de la DGII. El procesamiento es asincrono y la DGII puede estar degradada. Emite, entrega la representacion impresa y concilia el estado despues.
Entornos disponibles
Zarela expone la misma API separada por ambiente:
| Ambiente | URL base | Proposito |
|---|---|---|
TesteCF | https://ecf.api.zarela.do/TesteCF | Pruebas tecnicas internas y desarrollo. |
CerteCF | https://ecf.api.zarela.do/CerteCF | Certificacion DGII del contribuyente. |
eCF | https://ecf.api.zarela.do/eCF | Produccion fiscal oficial. |
Cada ambiente debe tener API keys y rangos de secuencia separados.
Requisitos tecnicos
Para una integracion exitosa necesitas:
- Una API key generada para el ambiente correspondiente, con los scopes adecuados.
- Un certificado digital valido cargado en la plataforma.
- Capacidad de generar JSON con estructura DGII/XSD (
{ "ECF": ... }) desde tu sistema. - Capacidad de asignar y conservar el eNCF en tu POS/ERP antes de enviar la venta.
- Un cliente HTTP con timeouts y reintentos idempotentes.
Si una emision termina en timeout o error de red, reintenta el mismo JSON con el mismo eNCF. Zarela devolvera el documento existente si el contenido coincide y rechazara el intento si ese eNCF llega con datos fiscales diferentes.
El contrato: JSON DGII/XSD
Aunque envias JSON, la estructura debe seguir el esquema XML de la DGII. Zarela no inventa etiquetas fiscales ni oculta campos obligatorios: ordena segun XSD, limpia vacios, valida, convierte a XML, firma y envia.
Existe ademas un contrato simplificado (canonico) de Zarela como helper opcional para integraciones pequenas. No sustituye los campos fiscales que pide la DGII; se documenta en Formato de documentos.
Siguientes pasos
Continua con cada paso del proceso: