Saltar al contenido principal

Mejores practicas

Implementar correctamente la facturacion electronica con Zarela simplifica tu operacion y garantiza el cumplimiento. Estas recomendaciones optimizan tu integracion.

Arquitectura y diseno​

Separacion de responsabilidades​

  • Generacion 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).
  • Comunicacion con Zarela: 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 validacion (corrige el documento; no reintentes igual).
  • Errores de comunicacion (reintenta con backoff).
  • Errores de procesamiento y rechazos de la DGII (registra mensajes y trackId).

Implementacion tecnica​

Autenticacion​

  • Guarda las API keys en un secret manager, nunca en codigo fuente.
  • Usa una key por integracion y ambiente; rotala periodicamente.
  • No registres keys completas en logs.

Generacion de documentos​

  • Prevalida con validate=true antes de emitir; ahorra secuencias.
  • Implementa pruebas unitarias del mapeo a e-CF.
  • Valida montos e indicadores de ITBIS localmente para reducir rechazos.

Envio de documentos​

  • Usa una cola para volumenes altos.
  • Persiste la relacion entre la venta, su eNCF, el JSON enviado y el documentId devuelto.
  • Aplica reintentos idempotentes con backoff exponencial para fallos temporales.
  • Respeta el rate limit de tu plan; maneja el 429.

Seguimiento y estado​

  • Ejecuta consultas batch periodicas para actualizar estados.
  • Usa webhooks para actualizaciones oportunas y conserva el batch como reconciliacion.
  • Notifica oportunamente rechazos o aceptaciones condicionales.
  • Mantén un historico de eventos por documento (trackId, correlationId).
No bloquees la venta

El POS/ERP nunca debe esperar la aceptacion de la DGII para completar la venta. Emite, entrega la RI y concilia el estado de forma asincrona.

Operacion y mantenimiento​

Monitoreo​

Monitorea: tasa de exito/rechazo, tiempo a estado final, disponibilidad de la API y consumo de cuota.

Respaldos​

  • Respalda tus certificados digitales y planifica su renovacion antes de expirar.
  • Conserva copias de tus documentos enviados y recibidos; Zarela tambien conserva los XML firmados y artifacts fiscales por 10 anos.

Actualizaciones​

  • Mantente informado de cambios regulatorios de la DGII.
  • Prueba cambios en TesteCF antes de aplicarlos en eCF.

Seguridad​

Proteccion de certificados y secretos​

  • Acceso restringido a certificados y API keys.
  • Conexiones HTTPS para toda comunicacion.
  • Considera HSM para operaciones criticas a gran escala.

Control de acceso​

  • Roles y permisos para funciones de facturacion.
  • Auditoria de acciones sobre documentos fiscales.

Plan de contingencia​

  • Define un modo de operacion cuando la DGII este degradada (Zarela encola y reintenta; tu sistema debe tolerar estados pending).
  • Establece procedimientos de sincronizacion posterior al restablecerse el servicio.
  • Prueba periodicamente tu plan de contingencia.