Visão Geral
O Painel de Analítica (/analytics, /analytics/passes, /analytics/downloads, /templates/:id/analytics ao nível do modelo e vistas personalizadas em /dashboards) fornece telemetria operacional em tempo real e agregação histórica de séries temporais em todo o seu espaço de trabalho, sem necessitar de pipelines externos de business intelligence. Alimentada por Dashboard Analytics API (/api/v1/dashboards/*) e Analytics API (/api/v1/analytics/*), a consola apresenta métricas multidimensionais que abrangem emissão de passes, registos de dispositivos ativos, divisões de instalação por plataforma e diagnósticos proativos de Saúde dos Passes.
Os operadores podem alternar entre o modo de alto nível Visão Geral — otimizado para KPIs executivos, alertas de saúde e estado operacional imediato — e o modo aprofundado Analítica para análises detalhadas de coortes em modelos específicos, canais de distribuição e intervalos temporais.
Arquitetura de Agregação de Telemetria
O Passinstance separa os contadores operacionais em tempo real das consolidações históricas de séries temporais para garantir uma apresentação no painel em menos de um segundo, mesmo em espaços de trabalho com centenas de milhares de passes ativos:
Importante: Todos os intervalos de séries temporais (
day,week,month) são alinhados e avaliados de acordo com o fuso horário regional configurado no seu espaço de trabalho (GET /api/v1/customer/:customerId/regional-settings), garantindo que os limites diários correspondem ao horário de funcionamento local das suas lojas.
Modos de Visão Geral do Espaço de Trabalho vs. Analítica Aprofundada
| Vista do Painel | Endpoints da API de Suporte | Telemetria Principal e Capacidades |
|---|---|---|
Visão Geral do Espaço de Trabalho (/analytics) | GET /api/v1/dashboards/analyticsGET /api/v1/dashboards/metrics/realtimeGET /api/v1/dashboards/insights | Contador de passes ativos em tempo real, variações de crescimento a 30 dias, velocidade de leitura em direto, avisos de expiração de certificados e recomendações acionáveis de Saúde dos Passes. |
Analítica Aprofundada (/analytics/passes e /analytics/downloads) | GET /api/v1/analyticsGET /api/v1/analytics/overviewGET /api/v1/dashboards/analytics/range | Gráficos multissérie de criação de passes vs. instalação na carteira, variações líquidas por plataforma (walletAppsChanges), comparações de intervalos de datas personalizados e filtragem por entidade com âmbito definido. |
| Desempenho do Sistema | GET /api/v1/dashboards/performance | Latência de envio de notificações push, taxas de sucesso de sincronização APNs/Google Wallet e tempos de resposta de verificação do leitor. |
Enumerações de Filtragem: AnalyticsScope, AnalyticsRange e AnalyticsBucket
Ao consultar GET /api/v1/analytics ou GET /api/v1/analytics/overview (request payload), pode segmentar a telemetria do espaço de trabalho através de três enumerações ortogonais:
-
1
AnalyticsScope(scope):
- customer: Agrega todos os modelos, fluxos de passes e configurações de leitura dentro do espaço de trabalho autenticado (derivado automaticamente da sua sessão/chave de API). - owner: Agrega métricas entre múltiplos espaços de trabalho para proprietários de organizações que gerem vários ambientes associados. - template: Isola métricas de emissão, registo e remoção para um único UUID templateId. - passFlow: Isola visitas públicas de registo, submissões de formulários e taxas de conversão para um UUID passFlowId específico.
-
2
AnalyticsRange(range):
- Janelas predefinidas: last_7days, last_30days, last_12_months. - Intervalos personalizados: custom combinado com parâmetros de consulta ISO YYYY-MM-DD from e to (from=2026-10-15&to=2026-11-16).
-
3
AnalyticsBucket(bucket):
- day: Pontos de dados diários (predefinição para janelas de 7 e 30 dias). - week: Consolidações por semana ISO para análise de tendências ao longo de vários meses. - month: Consolidações por mês civil (predefinição para last_12_months).
Referência da API de Telemetria Programática
Obter Analítica Multissérie do Espaço de Trabalho
Obtenha curvas de séries temporais para eventos do ciclo de vida dos passes, registos de dispositivos e distribuição pelos ecossistemas de carteira:
GET /api/v1/analytics?range=last_30days&bucket=day&scope=template&templateId=b4f29c10-83e1-4a7b-9d12-56e8012a9c04 HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
Payload de Resposta (200 OK)
{
"range": {
"preset": "last_30days",
"startDate": "2026-10-17T00:00:00.000Z",
"endDate": "2026-11-15T23:59:59.999Z",
"bucket": "day",
"timezone": "Europe/Berlin"
},
"scope": {
"type": "template",
"targetId": "b4f29c10-83e1-4a7b-9d12-56e8012a9c04"
},
"summary": {
"totalPasses": 4820,
"activePasses": 3915,
"inactivePasses": 245,
"unclaimedPasses": 660,
"installedDevices": 4380
},
"series": {
"passes": [
{ "bucketStart": "2026-11-14", "created": 145, "active": 3810, "deactivated": 8 },
{ "bucketStart": "2026-11-15", "created": 162, "active": 3915, "deactivated": 5 }
],
"registrations": [
{ "bucketStart": "2026-11-14", "active": 4260, "deactivated": 11 },
{ "bucketStart": "2026-11-15", "active": 4380, "deactivated": 6 }
],
"walletAppsChanges": [
{ "bucketStart": "2026-11-14", "appleNetChange": 84, "googleNetChange": 32 },
{ "bucketStart": "2026-11-15", "appleNetChange": 91, "googleNetChange": 29 }
]
},
"walletAppsShare": {
"apple": 2980,
"google": 1400,
"total": 4380,
"applePercentage": 68.04,
"googlePercentage": 31.96
}
}
Consultar Métricas em Tempo Real e Diagnósticos de Saúde dos Passes
Para consultar os estados dos contadores em direto e as recomendações de diagnóstico através de Dashboard Analytics API:
GET /api/v1/dashboards/insights HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
{
"generatedAt": "2026-11-15T23:30:00.000Z",
"healthScore": 94,
"insights": [
{
"code": "HIGH_UNCLAIMED_RATIO",
"severity": "warning",
"templateId": "b4f29c10-83e1-4a7b-9d12-56e8012a9c04",
"message": "13.7% of issued passes remain unclaimed after 72 hours.",
"recommendedAction": "Enable automated 48-hour reminder sendouts in Delivery Center."
}
]
}
Documentação Relacionada
-
Consulte as fórmulas exatas de KPI em Métricas de Emissão e Utilização de Passes.
-
Analise as taxas de conversão por canal em Analítica de Distribuição e Envolvimento.
-
Exporte conjuntos de dados brutos subjacentes através de Exportação de Dados e Relatórios.
