API Facturación

Monitoreo y Estado del Sistema

Esta sección describe los endpoints para monitorear el estado del sistema, verificar la salud de sus componentes y obtener métricas de rendimiento.

Autenticación

Todos los endpoints de esta sección de monitoreo requieren autenticación JWT excepto el endpoint de health check. Consulta la sección de Autenticación para más detalles.

Health Check

GET /api/v1/health

Verifica el estado de salud del sistema y sus componentes

Este endpoint verifica el estado de salud del sistema y todos sus componentes, proporcionando información sobre la disponibilidad de cada servicio.

Ejemplo de Respuesta

Response 

{
  "success": true,
  "data": {
    "status": "UP",
    "components": {
      "database": {
        "status": "UP",
        "details": "Database service is healthy"
      },
      "redis": {
        "status": "UP",
        "details": "Cache service is healthy"
      },
      "filesystem": {
        "status": "UP",
        "details": "Storage system is healthy"
      },
      "hacienda": {
        "status": "UP",
        "details": "Service is healthy"
      },
      "dte_signer": {
        "status": "UP",
        "details": "Service is healthy"
      }
    },
    "timestamp": "2024-02-01T10:30:00Z"
  }
}

El endpoint de health check es útil para:

  • Verificar si el sistema está operativo
  • Identificar qué componentes específicos pueden estar fallando
  • Monitoreo automático y alertas
  • Verificaciones de balanceadores de carga

Nota

Si algún componente tiene estado 'DOWN', el estado global del sistema también será 'DOWN'.

Métricas del Sistema

GET /api/v1/metrics

Recupera métricas del sistema para monitoreo

Este endpoint proporciona métricas detalladas sobre el rendimiento del sistema, incluyendo tiempos de respuesta y tasas de éxito/error.

Parámetros de consulta

  • endpoint - Filtrar métricas por ruta específica (opcional)
  • method - Filtrar métricas por método HTTP (opcional)

Ejemplo de Respuesta

Response 

{
  "success": true,
  "data": {
    "path": "invoices",
    "method": "POST",
    "system_nit": "06140101231101",
    "total_requests": 1500,
    "success_count": 1450,
    "error_count": 50,
    "current_average_ms": 245,
    "max_duration_ms": 850,
    "min_duration_ms": 120,
    "last_durations": [235, 242, 238, 251, 240]
  }
}

Prueba del Sistema

GET /api/v1/test

Ejecuta pruebas del sistema para verificar la conexión con servicios externos

Este endpoint ejecuta una serie de pruebas diagnósticas para verificar la conectividad y funcionalidad de los componentes clave del sistema, especialmente aquellos que implican servicios externos como la conexión con Hacienda.

Ejemplo de Respuesta

Response 

{
  "success": true,
  "data": {
    "success": true,
    "tests": [
      {
        "name": "database_connection",
        "success": true,
        "duration_ms": 1
      },
      {
        "name": "dte_mapping",
        "success": true,
        "duration_ms": 0
      },
      {
        "name": "sequence_generation",
        "success": true,
        "duration_ms": 4
      },
      {
        "name": "hacienda_transmission",
        "success": true,
        "duration_ms": 364
      }
    ],
    "duration_ms": 370
  }
}

Pruebas Ejecutadas

database_connection

Verifica la conectividad con la base de datos realizando una consulta simple. Esta prueba asegura que el sistema puede realizar operaciones básicas de lectura/escritura.

dte_mapping

Valida el correcto funcionamiento del mapeo de documentos tributarios electrónicos (DTE). Comprueba que las transformaciones de datos y validaciones funcionen según lo esperado.

sequence_generation

Prueba la generación de secuencias únicas para documentos. Verifica que el sistema pueda generar correctamente números correlativos para los diferentes tipos de documentos.

hacienda_transmission

Comprueba la conectividad con los servicios del Ministerio de Hacienda. Verifica que el sistema pueda establecer conexión y realizar transmisiones de prueba exitosas.