Saltar al contenido principal

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=true antes 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 documentId devuelto.
  • Aplica reintentos idempotentes con backoff exponencial para fallos temporales.
  • Respeta el rate limit (global del despliegue, no depende del plan); ante 429 espera Retry-After y 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 TesteCF antes de aplicarlos en eCF.

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 contingency y 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 lastError cuando un documento no avanza: por ejemplo, DGII_CERTIFICATE_NOT_DELEGATED significa 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.