Alimentar KPIs e OKRs com números do seu sistema

Os números de um indicador — faturamento, NPS, prazo médio de entrega, chamados resolvidos — já existem no ERP ou no BI. Em vez de alguém digitá-los toda semana em Desempenho → Metas, o seu sistema envia cada medição para a TAI. A plataforma calcula variação, desvio da meta e tendência, gera os alertas do indicador e atualiza o progresso dos OKRs.

Quando usar	KPIs com coleta periódica a partir de uma fonte de dados; Key Results medidos por número; painéis de metas fora da TAI
Porta	REST · Webhook assinando eventos (alertas) · Agente (MCP)
Você vai precisar	Módulo DESEMPENHO; permissão KPI (indicadores e medições) e OKR (objetivos, Key Results e check-ins) com nível de edição; token JWT de um usuário de integração

Como funciona

seu BI/ERP ── GET /kpi/codigo/{codigo} ───────────▶ TAI  (acha o KPI pelo código)
seu BI/ERP ── POST /medicao-kpi/coletar ──────────▶ TAI  (registra a medição)
                 TAI calcula tendência e desvio, cria alertas (meta atingida, fora do limite)
seu BI/ERP ── POST /check-in ─────────────────────▶ TAI  (novo valor de um Key Result)
                 TAI recalcula o progresso do KR e do objetivo

O KPI é um indicador contínuo, com meta, mínimo, máximo e frequência de coleta. O Key Result pertence a um objetivo (OKR) e mede o avanço de um valor inicial até uma meta. São registros separados: uma medição alimenta o KPI; um check-in alimenta o Key Result.

Passo a passo

1. Dê um código a cada KPI. Na tela de KPIs, o campo Código (ex.: KPI-001) é a chave de correspondência mais estável. Pela API:

   GET /kpi/codigo/FAT-MENSAL
   Authorization: Bearer $TAI_TOKEN

   Guarde o id. Para listar todos, use GET /kpi/page ou GET /kpi/ativos.

2. Envie a medição. A forma curta recebe tudo na query string:

   POST /medicao-kpi/coletar?kpiId=8&valor=1284500.75&fonteDados=ERP&observacoes=Fechamento%20de%20setembro

   A resposta (201) traz a medição com valorAnterior, percentualVariacao, desvioMeta (em % da meta) e tendencia (CRESCENTE, DECRESCENTE, ESTAVEL ou VOLATIL). A data é a do momento do envio.

   Para uma carga histórica, com a data de cada medição, use o corpo completo:

   POST /medicao-kpi
   Content-Type: application/json
   
   { "kpi": { "id": 8 }, "data": "2026-09-30", "valor": 1284500.75, "fonteDados": "ERP" }

   Essa forma grava exatamente o que você envia: não calcula variação, desvio nem tendência e não gera alertas. Use-a só para o passado e o coletar para as medições correntes.

3. Atualize um Key Result. Encontre o KR pelo objetivo (GET /key-result/objetivo/{objetivoId}) e registre o check-in:

   POST /check-in
   Content-Type: application/json
   
   {
     "keyResult": { "id": 31 },
     "valorAtual": 42,
     "comentario": "Atualizado pelo BI em 03/10",
     "evidencias": "https://bi.suaempresa.com.br/painel/vendas"
   }

   O check-in grava o valor anterior, recalcula o progresso e o status do Key Result (NAO_INICIADO, EM_ANDAMENTO, ATINGIDO, NAO_ATINGIDO) e o progresso do objetivo.

4. Leia o que voltou. Para o painel do seu lado:

   Rota	Traz
   GET /medicao-kpi/historico/kpi/{kpiId}?page=0&size=50	Série histórica do indicador, paginada
   GET /alerta-kpi/nao-resolvidos	Alertas abertos: meta atingida, fora do limite, tendência negativa
   GET /kpi/sem-medicao-recente	KPIs sem medição há mais de 7 dias — a coleta parou?
   GET /objetivo/filtros?ano=2026&periodo=Q4	Objetivos do período com progresso e status

Receber os alertas no seu sistema

Os alertas que a TAI gera a partir das medições — meta atingida, fora do limite, tendência negativa — publicam Um alerta de indicador é gerado (ALERTA_KPI_CRIADO), com alertaId, kpiId, tipoAlerta, criticidade e colaboradorId; resolvido, sai ALERTA_KPI_RESOLVIDO. Assine-os num webhook para o BI ou o canal da equipe saberem na hora, sem ler GET /alerta-kpi/nao-resolvidos de tempos em tempos. Para ficar só com os alertas de uma criticidade, filtre no seu sistema por criticidade. Para mandar o alerta numa mensagem no formato do Slack, use um fluxo automatizado com o bloco Chamar outro sistema — veja Da TAI para o seu sistema.

Cada check-in também publica Um check-in de OKR é feito (CHECKIN_REGISTRADO), com keyResultId, objetivoId, valorAtual e progresso. A medição de KPI em si não publica evento.

Ler PDIs e metas de desenvolvimento

O PDI (plano de desenvolvimento individual) fica em Desempenho → PDI. Para levar os planos a outro sistema:

GET /pdi/page?page=0&size=100
GET /meta-pdi/page?page=0&size=100

O PDI traz titulo, colaborador, dataLimite e status. Cada meta traz descricao, tipo, status (NAO_INICIADA, EM_ANDAMENTO, CONCLUIDA, BLOQUEADA) e, quando é uma meta de treinamento ligada a um curso, cursoId, matriculaId, matriculaStatus e progressoPercentual — o progresso é o da matrícula no curso, não um número digitado. POST /meta-pdi/{id}/matricular matricula o dono do PDI no curso da meta. Cada meta concluída publica Uma meta do PDI é concluída (META_PDI_CONCLUIDA, com metaId, pdiId, colaboradorId e tipo).

GET /pdi/page exige o módulo PESSOAS e a permissão PDI; GET /meta-pdi/page, o módulo DESEMPENHO e a mesma permissão.

Pelo seu agente de IA

“Registre 1,28 milhão como medição de setembro do KPI de faturamento e me diga como ficou a tendência.”

Com escopo de escrita, o agente acha o KPI e registra a medição — o seu cliente de IA pede aprovação antes. Somente leitura, ele analisa séries, alertas e objetivos em risco. Veja Escrita e segurança.

Cuidados

• Uma chamada é uma medição. Repetir o envio grava outra medição (e pode gerar outro alerta). Guarde no seu lado o que já foi enviado — por exemplo, KPI + período — e consulte GET /medicao-kpi/ultima/{kpiId} antes de reenviar após uma falha de rede.
• desvioMeta e alertas dependem da meta. Sem valorMeta, valorMinimo e valorMaximo no KPI, a medição é gravada, mas não há desvio nem alerta de limite.
• Check-in substitui o valor atual do Key Result; o histórico fica nos check-ins (GET /check-in/historico/key-result/{keyResultId}).
• Valores com ponto decimal (1284500.75); datas como yyyy-MM-dd — veja Datas e formatos.
• Atingir a meta pontua. Medição que atinge a meta do KPI e check-in de Key Result somam pontos de gamificação ao responsável. Cargas de teste numa conta de produção aparecem no ranking.