Levar os dados de processos para o BI

Quanto tempo um pedido de compra leva da abertura à conclusão? Quantos estouram o SLA, e em que fase param? Nesta jornada, uma rotina do seu BI lê os fluxos, as fases, os cards e os valores dos campos, monta as tabelas de dimensão e fato, e depois carrega só o que mudou.

Quando usar	Painéis e análises sobre processos fora da TAI
Porta	REST (leitura) · Agente (MCP) para perguntas pontuais
Você vai precisar	módulo GESTAO_PROCESSOS; permissão PROCESSO (leitura); JWT de um usuário de integração só com leitura

Como funciona

dimensões (1x por dia):  GET /pipe/page ─► GET /phase/by-pipe/{id} ─► GET /field-schema/by-pipe/{id}
fato card (carga cheia): GET /card/by-pipe/{id}/page?sort=id,asc   ─► GET /card-field-value/by-card/{cardId}
incremental:             GET /card-movimentacao/by-pipe/{id}/periodo?inicio=…&fim=…  ─► relê só esses cards
indicadores prontos:     GET /pipe/{id}/metricas

Passo a passo

1. Dimensões: fluxos, fases e campos.

   curl -s "https://api.taitecnologia.com/pipe/page?page=0&size=100" \
     -H "Authorization: Bearer $TAI_TOKEN"

   Para cada fluxo, GET /phase/by-pipe/{pipeId} (fases com ordem, tipo, isDone, slaHoras) e GET /field-schema/by-pipe/{pipeId} (campos com identificador e tipo). Use o identificador do campo como nome de coluna: ele é estável, o nome exibido pode mudar.

2. Fato: os cards de cada fluxo.

   curl -s "https://api.taitecnologia.com/card/by-pipe/14/page?page=0&size=100&sort=id,asc" \
     -H "Authorization: Bearer $TAI_TOKEN"

   Avance page até last ser true. Cada card traz id, numero, status (ABERTO, EM_ANDAMENTO, AGUARDANDO, BLOQUEADO, CONCLUIDO, CANCELADO), phaseAtual, dataCriacao, dataConclusao, dataEntradaFase, dataVencimentoSla, slaVencido, colaboradorCriador, responsavel e origemReferencia. A lista não traz os valores dos campos.

3. Os valores dos campos de cada card.

   curl -s https://api.taitecnologia.com/card-field-value/by-card/90412 \
     -H "Authorization: Bearer $TAI_TOKEN"

   Cada item traz fieldIdentificador, fieldTipo e o valor na propriedade do tipo: valorTexto, valorNumero, valorData, valorBoolean ou valorReferenciaId (colaborador, departamento, centro de custo). valorFormatado traz o valor como texto. Pivote por fieldIdentificador para ter uma coluna por campo.

4. Histórico de fases, para tempo por etapa.

   curl -s https://api.taitecnologia.com/card-movimentacao/by-card/90412 \
     -H "Authorization: Bearer $TAI_TOKEN"

   Cada movimentação traz phaseOrigem, phaseDestino, dataMovimentacao, tipo (AVANCO, RETROCESSO, ROTEAMENTO_IA, AUTOMACAO, MANUAL), motivo e quem moveu (colaboradorExecutor). GET /card/{id} traz também cardPhases, com o tempo em cada fase (tempoPermanenciaMinutos) e as decisões de aprovação.

5. Carga incremental. Em vez de reler tudo, peça as movimentações do período e releia só esses cards:

   curl -s "https://api.taitecnologia.com/card-movimentacao/by-pipe/14/periodo?inicio=2026-10-02&fim=2026-10-03" \
     -H "Authorization: Bearer $TAI_TOKEN"

   inicio e fim são datas AAAA-MM-DD, lidas como meia-noite: para cobrir o dia 2 inteiro, use fim = dia 3. Para os cards novos, compare o maior id que você já tem com a página mais recente de GET /card/by-pipe/{pipeId}/page?sort=id,desc. Mudança só de valor de campo, sem troca de fase, não gera movimentação: rode a carga cheia de tempos em tempos.

Em tempo quase real

Se o BI precisa dos movimentos assim que acontecem, assine num webhook os eventos de Processos — Um card é aberto num fluxo (CARD_CRIADO), Um card muda de fase (CARD_MOVIDO_FASE), Um card é concluído (CARD_CONCLUIDO), Um card é cancelado (CARD_CANCELADO). Cada um traz cardId, pipeId, faseId, faseNome e, no movimento, faseOrigemNome, e chega com ocorridoEm; releia o card pelo cardId quando precisar dos valores dos campos. Mantenha a carga incremental do passo 5 como reconciliação: o webhook tenta de novo por cerca de um dia, não para sempre.

Indicadores prontos

Para painéis que não precisam do dado bruto, a TAI já calcula por fluxo:

Rota	O que traz
GET /pipe/{id}/metricas	Totais por status, tempo médio de ciclo e de lead time, throughput diário, semanal e mensal, cumprimento de SLA, métricas por fase, criados e concluídos por dia
GET /pipe/{id}/metricas/resumo	As mesmas métricas, sem o detalhe por fase
GET /pipe/{id}/metricas/fase/{phaseId}	Uma fase
GET /pipe/{id}/metricas/tendencias	Criação e conclusão de cards ao longo do tempo

Tempo de ciclo e concluídos contam a partir da entrada numa Fase de Conclusão — fluxos sem nenhuma fase marcada não têm cards concluídos.

Pelo seu agente de IA

“Quantos cards de Compras foram concluídos em setembro, por centro de custo?”

É leitura: o agente agrega os dados sem baixar tudo (ferramenta analisar_dados) e pode gerar a planilha (exportar_para_excel). Veja Ferramentas.

Cuidados

• Uma chamada por card para os valores (passo 3): espalhe a carga e use size entre 50 e 200. O limite é de 5.000 requisições a cada 5 minutos por IP — veja Limites de uso.
• Cards excluídos somem das listas. Para o BI não guardar card fantasma, compare a carga cheia periódica com o que você tem.
• Datas vêm em ISO 8601 — veja Datas e formatos. dataConclusao é limpa se o card volta de uma fase de conclusão.
• Leitura não precisa de escrita: dê ao usuário do BI só a permissão PROCESSO em leitura.