Relatórios e Integração de BI

Para alimentar painéis de Business Intelligence (BI) e dashboards gerenciais, o Perpetuus oferece um endpoint otimizado que retorna dados analíticos consolidados do seu funil.

Endpoint Analítico

Diferente das listagens padrão de cards (que retornam dados linha a linha e exigem paginação), o endpoint de relatório consolida os dados financeiros e de conversão diretamente no servidor.

Obter Relatório de Conversão do Quadro

Retorna métricas agregadas por fase (SLA, quantidade de cards e valor acumulado) e um sumário consolidado do período selecionado.

• Método: GET
• Caminho: /boards/{boardId}/report
• Parâmetros de Consulta:
  • from: Data inicial no formato YYYY-MM-DD (ex: 2026-07-01).
  • to: Data final no formato YYYY-MM-DD (ex: 2026-07-10).
  • statsTodayStart: Opcional. Data/hora ISO representando a meia-noite no fuso horário do usuário para cálculo preciso de cards atrasados (overdueCount).

Exemplo de Requisição e Resposta

curl "https://api.perpetuus.com.br/api/boards/BOARD_ID/report?from=2026-07-01&to=2026-07-10" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "x-tenant-id: acme"

A API retorna um payload em formato Report (analítico consolidado):

{
  "boardId": "board_sales_01",
  "summary": {
    "totalCards": 145,
    "activeValue": 1250000.00,
    "wonValue": 450000.00,
    "lostValue": 85000.00,
    "conversionRate": 0.81
  },
  "phases": [
    {
      "documentId": "phase_inbound",
      "name": "Leads Recebidos",
      "cardsCount": 32,
      "valueSum": 160000.00,
      "slaBreachedCount": 2
    },
    {
      "documentId": "phase_negotiation",
      "name": "Negociação",
      "cardsCount": 12,
      "valueSum": 250000.00,
      "slaBreachedCount": 0
    }
  ],
  "period": {
    "from": "2026-07-01",
    "to": "2026-07-10"
  }
}

Boas Práticas para Integrações de BI

Quando estiver conectando a API do Perpetuus ao Power BI, Looker Studio ou Metabase, siga estas diretrizes:

1. Alimentação de Gráficos de Conversão e Funil: Utilize o GET /boards/{boardId}/report para desenhar funis de conversão comerciais, SLAs de fase e métricas financeiras globais. Este endpoint consome poucos recursos e executa de forma quase instantânea.
2. Consultas Detalhadas e Gráficos de Vendedores: Para agrupar vendas por vendedor (assignees), visualizar detalhes de cards individuais ou analisar campos customizados específicos, utilize a listagem de cards (GET /boards/{boardId}/cards) com paginação e o parâmetro populate configurado para trazer assignees e fieldData.
3. Cache de Consultas: Evite fazer requisições em tempo real a cada atualização de página do usuário no dashboard. Configure o seu data warehouse (ou a ferramenta de BI) para realizar cargas de sincronização (ingestão agendada) em intervalos (ex: a cada 1 hora ou uma vez por dia).