Mejores prácticas
Implementar correctamente la facturación electrónica con ZarelaFact simplifica tu operación y garantiza el cumplimiento. Estas recomendaciones optimizan tu integración.
Arquitectura y diseño
Separación de responsabilidades
- Generación de datos: tu sistema genera los datos de la venta.
- Mapeo a e-CF: una capa traduce tus datos al JSON DGII/XSD (o al contrato simplificado).
- Comunicación con ZarelaFact: un servicio dedicado encapsula las llamadas a la API.
- Seguimiento: mantienes un registro local del estado de cada documento.
Manejo de errores
Diseña para distinguir y manejar cada tipo de error:
- Errores de validación (corrige el documento; no reintentes igual).
- Errores de comunicación (reintenta con backoff).
- Errores de procesamiento y rechazos de la DGII (registra mensajes y
trackId).
Implementación técnica
Autenticación
- Guarda las API keys en un secret manager, nunca en código fuente.
- Usa una key por integración y ambiente; rótala periódicamente.
- No registres keys completas en logs.
Generación de documentos
- Prevalida con
validate=trueantes de emitir; ahorra secuencias. - Implementa pruebas unitarias del mapeo a e-CF.
- Valida montos e indicadores de ITBIS localmente para reducir rechazos.
Envío de documentos
- Usa una cola para volumenes altos.
- Persiste la relación entre la venta, su eNCF, el JSON enviado y el
documentIddevuelto. - Aplica reintentos idempotentes con backoff exponencial para fallos temporales.
- Respeta el rate limit (global del despliegue, no depende del plan); ante
429esperaRetry-Aftery aplica backoff con jitter.
Seguimiento y estado
- Ejecuta consultas batch periódicas para actualizar estados.
- Usa webhooks para actualizaciones oportunas y conserva el batch como reconciliación.
- Notifica oportunamente rechazos o aceptaciones condicionales.
- Mantén un histórico de eventos por documento (
trackId,correlationId).
No bloquees la venta
El POS/ERP nunca debe esperar la aceptación de la DGII para completar la venta. Emite, entrega la RI y concilia el estado de forma asíncrona.
Operación y mantenimiento
Monitoreo
Monitorea: tasa de éxito/rechazo, tiempo a estado final, disponibilidad de la API y consumo de cuota.
Respaldos
- Respalda tus certificados digitales y planifica su renovación antes de expirar.
- Conserva copias de tus documentos enviados y recibidos; ZarelaFact también conserva los XML firmados y artifacts fiscales por 10 años.
Actualizaciones
- Mantente informado de cambios regulatorios de la DGII.
- Prueba cambios en
TesteCFantes de aplicarlos eneCF.
Seguridad
Protección de certificados y secretos
- Acceso restringido a certificados y API keys.
- Conexiones HTTPS para toda comunicación.
- Considera HSM para operaciones críticas a gran escala.
Control de acceso
- Roles y permisos para funciones de facturación.
- Auditoría de acciones sobre documentos fiscales.
Plan de contingencia
- Define un modo de operación cuando la DGII esté degradada: ZarelaFact deja los documentos en
contingencyy los reintenta solos, sin plazo fijo, hasta que la DGII responda. Tu sistema debe tolerar estados intermedios (signed,sent,contingency) y no reenviar ni anular esos eNCF. - Muestra
lastErrorcuando un documento no avanza: por ejemplo,DGII_CERTIFICATE_NOT_DELEGATEDsignifica que hay que delegar el rol Firmante Autorizado en la OFV. - Establece procedimientos de sincronización posterior al restablecerse el servicio.
- Prueba periódicamente tu plan de contingencia.