API Facturación

Sistema de Contingencia

El Sistema de Contingencia permite la continuidad operativa del proceso de emisión de documentos fiscales electrónicos cuando existen problemas de conexión con los servicios del Ministerio de Hacienda.

¿Qué es el Sistema de Contingencia?

El Sistema de Contingencia es un mecanismo que permite la emisión de documentos fiscales electrónicos válidos aun cuando no es posible establecer comunicación con los servicios del Ministerio de Hacienda. Este sistema garantiza la continuidad operativa de los contribuyentes, permitiéndoles seguir facturando y generando documentos que luego, una vez restablecida la conexión, serán transmitidos automáticamente.

Importante

Los documentos emitidos en contingencia son completamente válidos fiscalmente. La única diferencia es que no contarán con el sello de recepción hasta que sean transmitidos a Hacienda.

Diagrama de Flujo del Proceso

flowchart TB A[Cliente inicia emisión] --> B{Verificar Conexión} B -->|Disponible| C[Emisión Normal] B -->|No Disponible| D[Modo Contingencia] C --> E[Preparar Documento] E --> F[Firmar Documento] F --> G[Transmitir a Hacienda] G --> H{Respuesta OK?} H -->|Sí| I[Documento Recibido] H -->|No| J[Evaluar Error] J -->|Recuperable| K[Reintentar] K --> G J -->|No Recuperable| D D --> M[Marcar como pendiente] M --> N[Entregar DTE sin sello] I --> O[Almacenar documento] N --> O O --> P[Fin del proceso]
graph LR Q[Conexión restablecida] --> R[Procesar documentos pendientes] R --> S[Actualizar estado]

Activación del Sistema de Contingencia

El sistema de contingencia se activa automáticamente cuando se detecta alguna de las siguientes situaciones:

  • No hay respuesta del servidor de Hacienda (timeout)
  • Se reciben errores 5XX del servidor de Hacienda
  • El tiempo de respuesta excede 30 segundos
  • El servicio de firmador no está funcionando

Tipos de Contingencia

Según el catálogo CAT-005, existen cinco tipos de contingencia reconocidos por el Ministerio de Hacienda:

Código Descripción
1 No disponibilidad de sistema del MH
2 No disponibilidad de sistema del emisor
3 Falla en el suministro de servicio de Internet del Emisor
4 Falla en el suministro de servicio de energía eléctrica del emisor
5 Otro (requiere descripción detallada)

Proceso de Emisión en Contingencia

Cuando el sistema está en modo contingencia, el proceso de emisión funciona de la siguiente manera:

  1. Detección: El sistema detecta automáticamente la necesidad de activar el modo contingencia.
  2. Documentación: Se registra el motivo de la contingencia (tipo 1-5) y se establece el tipo de transmisión como 2 (Contingencia).
  3. Almacenamiento local: El documento se firma digitalmente y se almacena en la base de datos local con estado "PENDING".
  4. Entrega: Se genera el DTE sin sello de recepción y se entrega al receptor.
  5. Monitoreo: El sistema verifica periódicamente la disponibilidad de los servicios de Hacienda.

Ejemplo de Respuesta en Contingencia

Respuesta de Documento en Contingencia 

{
  "success": true,
  "data": {
    "identificacion": {
      "version": 1,
      "ambiente": "00",
      "tipoDte": "01",
      "numeroControl": "DTE-01-C0020000-000000000000123",
      "codigoGeneracion": "BC3F4F6F-C16D-4F5E-9AC2-BE3C10C1A89D",
      "tipoModelo": 2, // Diferida
      "tipoOperacion": 2, // Contingencia
      "tipoContingencia": 1, // Código de identificación de la contingencia
      "motivoContin": "No disponibilidad de sistema del MH", // Descripción de la contingencia
      "fecEmi": "2025-04-12",
      "horEmi": "19:35:06",
      "tipoMoneda": "USD"
    },
    // ... resto del documento
  }
}

Observe que en la respuesta se incluyen los campos tipoContingencia con valor 1 (No disponibilidad del sistema del MH), tipoTransmision con valor 2 (Contingencia) y el estado como "PENDING".

Transmisión Posterior de Documentos

Una vez que se detecta que los servicios de Hacienda están disponibles nuevamente, el sistema realiza las siguientes acciones:

  1. Verificación: Confirma la disponibilidad de los servicios con una prueba de conexión.
  2. Agrupación: Recopila todos los documentos en estado "PENDING" que fueron emitidos durante la contingencia.
  3. Priorización: Ordena los documentos por fecha y tipo para su procesamiento.
  4. Transmisión por lotes: Envía los documentos en lotes para optimizar el rendimiento.
  5. Actualización: Una vez recibida la confirmación de Hacienda, actualiza el estado de los documentos a "RECEIVED" y almacena el sello de recepción.

Automatización

Todo este proceso es completamente automático y no requiere intervención manual. El sistema intentará transmitir los documentos pendientes cada 30 minutos con backoff exponencial hasta que todos sean procesados.

Consulta de Estado de Transmisión

Puedes verificar el estado de transmisión de tus documentos emitidos en contingencia mediante el endpoint de consulta de DTE:

Consulta de Documentos Pendientes en Contingencia 

GET /api/v1/dte?status=PENDING&transmission=CONTINGENCY

Buenas Prácticas

  • Mantén sincronizados los relojes de tus servidores para evitar problemas con las fechas y horas de emisión.
  • Considera almacenar los documentos emitidos en contingencia en un respaldo adicional para mayor seguridad.
  • Informa a tus clientes cuando se emitan documentos en contingencia, explicando que estos son igualmente válidos.
  • Revisa periódicamente el log de contingencias para identificar patrones o problemas recurrentes.

Preguntas Frecuentes sobre Contingencia

¿Los documentos emitidos en contingencia son válidos legalmente?

Sí, son completamente válidos. La normativa del Ministerio de Hacienda reconoce los documentos emitidos en contingencia como documentos fiscales oficiales.

¿Qué ocurre si el sistema de Hacienda no se restablece durante varios días?

El sistema mantendrá los documentos en estado "PENDING" y continuará intentando transmitirlos. No hay límite de tiempo para la transmisión posterior, aunque se recomienda mantener respaldos adicionales en casos extremos.

¿Puedo activar manualmente el modo contingencia?

Si, puedes activar el modo contingencia manualmente en caso de que desees probar esta funcionalidad, para ello debes ir a las variables de entorno y buscar `FORCE_CONTINGENCY` y establecerla en `true` de esta manera el sistema simulara un estado de contingencia hasta que se cambie su estado a `false`. Es recomendable que solamente actives esta funcionalidad en un ambiente de pruebas y no en producción.