Integrações

Guia de referência para ligar quiosques Navegante QEV a ferramentas de observabilidade e gestão de incidentes. Os exemplos assumem um middleware por quiosque (API REST) e um agregador central alimentado pelo backoffice ou por um message bus.

Arquitectura alvo

  1. Quiosque — UI Angular + middleware local (/api/v1/health, /api/v1/devices).
  2. Agregador — serviço que recolhe telemetria de todos os quiosques (push ou pull periódico).
  3. Backoffice — inventário, alarmes de negócio, publicação de i18n e configuração.
  4. Ferramentas externas — Grafana (visualização), Zabbix (disponibilidade clássica), ITSM (tickets).
Quiosque middleware ──metrics/logs──► Agregador ──► Prometheus / Loki
                                              │
                                              ├──► Grafana (dashboards + alertas)
                                              ├──► Zabbix (hosts + triggers SNMP/HTTP)
                                              └──► Webhook ──► ITSM (ServiceNow / Jira SM / GLPI)

Grafana

Métricas de séries temporais e logs correlacionados por kiosk_id.

Métricas (Prometheus)

  • Expor no agregador (ou middleware) endpoint GET /metrics no formato Prometheus.
  • Labels recomendados: kiosk_id, region, device_id, severity.
  • Exemplos de métricas: qev_health_up, qev_device_status, qev_supply_cards, qev_transactions_total, qev_sales_amount_eur.

Logs (Loki)

  • Promtail ou agente equivalente no host do quiosque; stream label job=qev-middleware.
  • Correlacionar falhas de periféricos com transacções via trace_id no JSON de log.

Dashboards e alertas

  • Painel operacional: quiosques offline, fila de alarmes abertos, insumos abaixo do limiar.
  • Alert rule Grafana → contact point (e-mail, Slack, PagerDuty) ou webhook para ITSM.
  • Exemplo de condição: qev_health_up == 0 durante 5m ou qev_supply_cards < 5.

Zabbix

Monitorização de infraestrutura e disponibilidade HTTP/SNMP por quiosque.

Inventário

  • Um host Zabbix por quiosque; grupo QEV / {região}; macros {$KIOSK_ID}, {$MW_URL}.
  • Template com itens: ping, porta middleware, scrape de /api/v1/health, espaço em disco, serviço UI (nginx).

Triggers sugeridos

Trigger Condição Severidade
Middleware indisponível HTTP check falha 3 vezes consecutivas Alta
Periférico em falha JSON devices[].status != Ativo Média
Insumo crítico cartões < 5 ou papel < 10% Aviso
Sem sincronização last_sync > 30 min (backoffice) Média

Acções Zabbix podem invocar scripts remotos (reinício middleware) ou apenas notificar — alinhado com permissões do backoffice.

Gestor de chamados (ITSM)

Abertura automática de incidentes a partir de alertas Grafana ou Zabbix.

Fluxo recomendado

  1. Alerta dispara com payload normalizado (ver exemplo JSON abaixo).
  2. Webhook do backoffice ou ITSM cria ticket com categoria QEV-Operations.
  3. Deduplicação por alarm_code + kiosk_id — reabrir se resolvido há menos de 24h.
  4. Encerramento automático quando métrica/health regressa a OK (opcional).

Sistemas típicos

  • ServiceNow — Integration Hub / REST Table API, mapear short_description e cmdb_ci do quiosque.
  • Jira Service Management — incoming webhook + automation rule para prioridade P2/P3.
  • GLPI — plugin webhook ou API Ticket para operação em rede fechada.
{
  "source": "grafana|zabbix",
  "kiosk_id": "QEV-LIS-014",
  "alarm_code": "DEVICE_READER_DOWN",
  "severity": "high",
  "message": "Leitor Navegante inactivo",
  "since": "2026-05-21T10:15:00Z",
  "runbook_url": "https://wiki.example/qev/reader-down"
}

APIs já disponíveis no protótipo

Endpoint Uso na integração
GET /api/v1/health Liveness do middleware; uptime e kioskId
GET /api/v1/devices Estado de periféricos e métricas embutidas (ex.: stock de cartões)
Backoffice /kiosks/{id} Alarmes de negócio, insumos e acções de gestão (simulado)

Protótipo · dados simulados. Em produção, autenticar webhooks (HMAC ou mTLS) e não expor /metrics publicamente sem rede de gestão.