Quais KPIs acompanhar ao integrar publicações judiciais por API?
Acompanhe latência, eventos perdidos, duplicidades e reconciliação para transformar publicações judiciais em dados operacionais confiáveis.
Conheça boas práticas para estruturar seu monitoramento
Neste artigo8 seções
- Por que acompanhar KPIs de uma integração de publicações judiciais?
- KPIs essenciais para medir latência, perda e qualidade
- Como medir e reduzir a latência entre o diário e a API
- O que é perda de evento e como fazer a reconciliação?
- Checklist técnico para instrumentar a integração por API
- Exemplo de payload e de métricas para uma prova de conceito
- Como montar um painel de operação em tempo real
- Erros comuns ao definir KPIs de uma API jurídica
Por que acompanhar KPIs de uma integração de publicações judiciais?
Os KPIs de integração de publicações judiciais mostram se um evento publicado em diário ou tribunal chegou ao sistema interno no tempo esperado, com o conteúdo correto e sem duplicação. Sem essas métricas, uma API pode aparentar funcionamento normal enquanto acumula atrasos, falhas silenciosas ou registros que nunca chegam ao ERP, CRM ou software jurídico.
A consequência não é apenas técnica. Uma publicação ausente pode impedir a criação de uma tarefa, atrasar a análise de um despacho ou aumentar o risco de perda de prazo. Por isso, o desempenho da integração precisa ser relacionado ao fluxo jurídico, e não somente à disponibilidade do servidor.
Comece definindo o evento de ponta a ponta: captura da publicação, validação do processo, envio pela API, recebimento pelo sistema de destino, gravação, criação da tarefa e confirmação para a equipe. Essa visão ajuda a interpretar corretamente o guia sobre como integrar publicações judiciais ao ERP ou CRM sem perder prazos.
A disponibilidade também precisa ser analisada com critério. Uma API pode responder em 200 milissegundos e ainda entregar dados incompletos, enquanto uma indisponibilidade curta em horário de grande volume pode gerar uma fila relevante. O KPI certo combina velocidade, completude, integridade e impacto operacional.
KPIs essenciais para medir latência, perda e qualidade
- ✓Latência de entrega: tempo entre o registro da publicação na origem e a disponibilização no sistema consumidor. Acompanhe média, mediana, percentil 95 e percentil 99, pois a média pode esconder atrasos extremos.
- ✓Taxa de entrega dentro do SLA: percentual de publicações recebidas até o limite acordado. Separe eventos urgentes, publicações comuns e reprocessamentos para não misturar situações operacionais diferentes.
- ✓Taxa de perda de eventos: proporção de publicações identificadas na origem, mas ausentes no destino após o período de reconciliação. O ideal é calcular por diário, tribunal, tipo de evento e janela de tempo.
- ✓Taxa de duplicidade: quantidade de eventos repetidos em relação ao total recebido. Duplicidades são comuns quando há reentrega após uma falha de confirmação e devem ser tratadas com idempotência.
- ✓Taxa de sucesso de processamento: percentual de mensagens aceitas, validadas e persistidas pelo consumidor. Uma entrega HTTP bem-sucedida não garante que o ERP tenha concluído a transação.
- ✓Taxa de correspondência automática: proporção de publicações associadas corretamente a um processo, parte, nome ou termo sem revisão manual. O indicador deve registrar também falsos positivos e falsos negativos.
- ✓Taxa de reconciliação: percentual de divergências resolvidas automaticamente ou manualmente dentro do prazo definido. Registre separadamente o volume pendente e o tempo médio para resolver.
- ✓Tempo de recuperação: intervalo entre a detecção de uma falha e a retomada do processamento normal. Acompanhe também o tamanho máximo da fila e a quantidade de eventos reprocessados.
- ✓Completude do payload: percentual de mensagens com campos obrigatórios, documento, identificador processual, tribunal, data da publicação e metadados esperados. Um evento incompleto pode ser tão prejudicial quanto um evento perdido.
- ✓Horas poupadas por semana: diferença entre o esforço médio de conferência manual antes e depois da integração. Use amostras reais de chamados, planilhas, consultas e tarefas para evitar uma estimativa inflada.
Como medir e reduzir a latência entre o diário e a API
Latência não é apenas o tempo de resposta do endpoint. Para o jurídico, o indicador relevante é o tempo entre a publicação disponível na origem e a entrega utilizável no sistema interno. Esse intervalo pode incluir captura, validação do processo, enriquecimento de dados, fila, transmissão, processamento e criação da tarefa.
Registre pelo menos quatro marcas de tempo: captura na origem, envio ao consumidor, recebimento pelo consumidor e persistência concluída. Com elas, você consegue separar atraso do fornecedor, da rede, da fila e do próprio ERP ou CRM. O percentil 95 é especialmente útil para identificar o comportamento dos casos mais lentos sem ser distorcido por poucos extremos.
Um exemplo de painel pode mostrar mediana de 4 minutos, percentil 95 de 18 minutos e percentil 99 de 47 minutos. A média de 7 minutos pareceria aceitável, mas os percentis revelariam uma parcela relevante de eventos que chega tarde demais para uma rotina com triagem no início do expediente.
Para reduzir a latência, use recebimento assíncrono, filas duráveis, confirmação rápida do webhook e processamento posterior. Evite que o endpoint fique aguardando a extração de documentos ou a classificação por IA antes de responder. A documentação do padrão HTTP para códigos de status e controle de requisições ajuda a estruturar respostas previsíveis, enquanto políticas de retentativa devem respeitar limites e evitar tempestades de chamadas.
Defina o SLA por impacto. Uma publicação urgente pode exigir entrega em poucos minutos após a disponibilidade, enquanto uma atualização histórica pode ser processada em uma janela maior. O contrato também deve informar a origem do relógio, as exceções, o período de medição e o que acontece quando o evento é reprocessado.
O que é perda de evento e como fazer a reconciliação?
Há perda de evento quando uma publicação existente na origem não aparece no destino dentro da janela esperada. Ela pode ocorrer por indisponibilidade, erro de autenticação, fila descartada, limite de requisições, falha de transformação, timeout após processamento parcial ou ausência de uma confirmação adequada.
Não confunda perda com atraso. Um evento que chega depois do SLA é uma violação de latência; um evento que não aparece após a janela de reconciliação é uma possível perda. Essa distinção orienta a resposta: ampliar capacidade resolve atraso, mas não corrige um identificador inconsistente ou uma regra que descarta mensagens.
A reconciliação compara duas visões do mesmo período. Use uma chave composta com identificador do processo, tribunal, data, tipo de movimentação e identificador da publicação quando disponível. Para documentos, um hash do arquivo ou do conteúdo normalizado ajuda a identificar alterações, duplicidades e downloads incompletos.
Um processo de reconciliação pode rodar em três níveis: contagem diária por origem, comparação de identificadores e validação de conteúdo. Quando a contagem diverge, a equipe investiga o lote; quando o identificador existe apenas em um lado, dispara reconsulta ou reentrega; quando o identificador coincide, mas o hash diverge, preserva as versões e abre uma análise de integridade.
O Pocket Jurídico trabalha com monitoramento de centenas de fontes, incluindo mais de 490 diários e tribunais, e a integração deve considerar que cada origem pode apresentar ritmos, formatos e comportamentos distintos. Logs de validação do processo, arquivos de publicações e relatórios diários em documentos ou planilhas podem servir como fontes complementares de auditoria, sem substituir a observabilidade contínua.
Para temas de prazo, a reconciliação deve ter prioridade operacional. A equipe pode consultar o guia sobre preclusão e prevenção da perda de prazos processuais e definir uma fila separada para divergências ligadas a intimações, decisões e despachos com ação necessária.
Checklist técnico para instrumentar a integração por API
- 1
Defina o contrato do evento
Documente campos obrigatórios, tipos, limites, versão do esquema e comportamento para campos desconhecidos. Inclua identificadores estáveis, data e hora com fuso, origem, tipo de evento e referência ao documento.
- 2
Gere um identificador de rastreamento
Use um identificador único por evento e um identificador de correlação para acompanhar reentregas e etapas internas. O mesmo valor deve aparecer nos logs do fornecedor, da fila e do sistema consumidor.
- 3
Registre a confirmação de recebimento
O consumidor deve confirmar que recebeu e colocou a mensagem em processamento, sem afirmar que toda a operação jurídica foi concluída. Uma segunda confirmação pode indicar persistência, associação ao processo e criação da tarefa.
- 4
Implemente idempotência
Armazene a chave do evento processado e devolva o mesmo resultado quando a mensagem for reenviada. Nunca crie uma nova tarefa apenas porque o fornecedor repetiu um evento após um timeout.
- 5
Configure retentativas com limite
Use espera progressiva, limite de tentativas e uma fila de mensagens não processadas. Registre o motivo de cada falha e evite retentar erros permanentes, como esquema inválido ou processo inexistente.
- 6
Programe reconciliações independentes
Faça comparações periódicas por janela, fonte e tipo de evento. A reconciliação não deve depender exclusivamente do webhook, porque justamente precisa detectar o que não foi entregue.
- 7
Proteja dados e logs
Reduza dados pessoais desnecessários nos logs, controle acesso e defina retenção. O checklist de segurança para jurídicos ajuda a relacionar observabilidade, continuidade e proteção de informações.
Exemplo de payload e de métricas para uma prova de conceito
Um payload mínimo pode ser estruturado assim: {"id_evento":"evt_8f31","id_processo":"0000000-00.0000.0.00.0000","tribunal":"TJXX","tipo":"publicacao","capturado_em":"2026-09-17T09:12:10-03:00","disponibilizado_em":"2026-09-17T09:14:02-03:00","documento_hash":"sha256:...","versao_esquema":"1.0","url_documento":"..."}. Em produção, aplique autenticação, assinatura, controle de acesso e política de retenção adequada.
Na POC, não use apenas um caso bem-sucedido. Selecione uma amostra que inclua diferentes tribunais, horários, volumes, processos com múltiplas instâncias, documentos e publicações sem documento. O período deve ser longo o suficiente para capturar dias de pico, indisponibilidades e reentregas.
A planilha de medição pode conter: total de eventos na origem, total recebido, total persistido, mediana de entrega, percentis 95 e 99, eventos duplicados, eventos incompletos, correspondência automática, divergências, reconciliações manuais, tempo de resolução e horas gastas pela equipe. A fonte de cada número precisa estar identificada.
Não é correto apresentar como resultado real uma taxa de perda ou de horas poupadas sem executar a medição. Para a operação do Pocket Jurídico, esses números devem ser extraídos dos logs de validação, relatórios diários e registros de processamento do período avaliado. O método é mais importante do que uma promessa genérica de desempenho.
Um cálculo simples de economia é: horas poupadas = horas médias semanais de consulta manual antes da integração menos horas semanais de conferência, exceções e reconciliação depois da integração. Registre também o volume de nomes e termos monitorados, porque o esforço varia muito entre um escritório com poucos processos e um departamento com contencioso de massa.
Como montar um painel de operação em tempo real
O painel deve responder a três perguntas em poucos segundos: a integração está recebendo eventos, os eventos estão sendo processados e existe algum risco jurídico imediato? Um gráfico de disponibilidade sozinho não responde a nenhuma delas completamente.
Na primeira camada, mostre volume por hora, latência mediana e percentis, taxa de sucesso, tamanho da fila e erros por código. Na segunda, apresente eventos sem correspondência, documentos ausentes, duplicidades, reconciliações pendentes e fontes com queda de volume. Na terceira, destaque publicações relacionadas a prazos, decisões ou tarefas que ainda não foram atribuídas.
Use cores com parcimônia e estabeleça limites acionáveis. Por exemplo, uma fila acima do normal durante dez minutos pode gerar alerta técnico; uma divergência de identificadores associada a uma publicação urgente deve abrir uma ocorrência operacional. O limite precisa considerar o histórico da fonte, não apenas um número fixo para todos os tribunais.
O painel executivo pode consolidar taxa de entrega no SLA, incidentes, horas poupadas, volume processado e pendências de reconciliação. Para uma visão mais completa de indicadores e modelos, consulte o modelo de dashboard jurídico com métricas para diretoria e operações.
Também documente quem age diante de cada alerta. Um KPI sem responsável, prazo e procedimento vira apenas informação visual. O mapa deve indicar se a ocorrência é tratada pelo fornecedor, pela equipe de integração, pelo administrador do sistema jurídico ou pelo advogado responsável.
Erros comuns ao definir KPIs de uma API jurídica
- ✓Medir somente o tempo de resposta HTTP e ignorar o tempo até a persistência no sistema de destino.
- ✓Usar a média como único indicador de latência, escondendo atrasos nos percentis 95 e 99.
- ✓Contar como entregue qualquer mensagem respondida com sucesso, sem confirmar gravação, associação ao processo ou criação da tarefa.
- ✓Não diferenciar atraso, duplicidade, evento inválido e perda definitiva, dificultando a causa raiz.
- ✓Reprocessar sem idempotência e criar tarefas duplicadas para a mesma publicação.
- ✓Fazer reconciliação apenas por quantidade, sem comparar identificadores, hashes e dados essenciais.
- ✓Desconsiderar fontes específicas. Um resultado global pode esconder uma falha concentrada em determinado diário ou tribunal.
- ✓Guardar logs com excesso de dados pessoais ou sem controle de acesso, ampliando o risco de exposição.
- ✓Definir SLA sem estabelecer o momento inicial da contagem, as exceções, a janela de reconciliação e a responsabilidade por cada etapa.
- ✓Calcular horas poupadas com base em percepção, sem comparar amostras reais de consultas manuais, triagem e tratamento de exceções.
Perguntas Frequentes
Quais são os principais KPIs de uma integração de publicações judiciais?▼
Os principais são latência de entrega, taxa de eventos dentro do SLA, perda, duplicidade, sucesso de processamento, completude do conteúdo, correspondência automática e reconciliação. Também vale acompanhar o tempo de recuperação e o volume de eventos pendentes. Para o jurídico, esses indicadores devem ser relacionados à criação de tarefas e ao risco de prazo, não apenas à infraestrutura.
Como calcular a latência de uma publicação judicial entregue por API?▼
Subtraia o horário em que a publicação ficou disponível na origem do horário em que o registro foi persistido e ficou utilizável no sistema interno. Registre as etapas intermediárias para separar captura, fila, transmissão e processamento. Analise mediana, percentil 95 e percentil 99, sempre com fuso horário padronizado e uma definição clara do início e do fim da medição.
O que é perda de evento em uma API de publicações?▼
É a situação em que uma publicação existente na origem não aparece no sistema de destino dentro da janela definida. A causa pode ser falha de rede, indisponibilidade, erro de autenticação, descarte de fila, transformação inválida ou ausência de retentativa. A detecção depende de comparação independente entre as bases, porque um webhook não consegue avisar sobre o evento que nunca chegou.
Como fazer a reconciliação de publicações judiciais?▼
Compare os eventos por identificadores estáveis, como ID da publicação, processo, tribunal, data e tipo de movimentação. Para documentos, use hash do arquivo ou do conteúdo normalizado e preserve versões quando houver divergência. Classifique cada diferença como atraso, ausência, duplicidade, conteúdo incompleto ou associação incorreta, atribuindo responsável e prazo para resolução.
Qual taxa de perda de eventos deve ser aceita?▼
Para publicações que podem gerar prazo, a expectativa operacional deve ser de perda zero, com detecção e recuperação documentadas. Isso não significa que toda infraestrutura seja infalível, mas que o processo precisa identificar exceções, reter eventos e permitir reconciliação. O SLA deve especificar a janela de detecção, o tempo de recuperação e a comunicação de incidentes, em vez de apresentar somente uma porcentagem agregada.
Qual SLA exigir de um fornecedor de monitoramento de publicações?▼
O SLA deve cobrir disponibilidade, tempo de entrega, completude, suporte, recuperação, retenção de logs e reconciliação. Solicite métricas por fonte ou tribunal, percentis de latência, critérios de exclusão e relatórios de incidentes. Também verifique a cobertura efetiva, a validação do processo e os mecanismos de reentrega, pontos tratados no guia para avaliar a qualidade de um serviço de monitoramento de publicações.
Como evitar duplicidade quando a API reenvia uma publicação?▼
Implemente idempotência usando uma chave estável do evento e registre o resultado do processamento. Se a mesma mensagem aparecer novamente, o consumidor deve reconhecer a operação anterior sem criar uma nova tarefa ou comentário. A lógica também deve considerar alterações legítimas, diferenciando uma nova versão do documento de uma repetição do mesmo evento.
Como saber quantas horas a integração economizou para o jurídico?▼
Compare uma linha de base anterior com o período posterior, medindo consultas manuais, triagem, conferência, distribuição e reconciliação. Subtraia do esforço antigo o trabalho residual de exceções, validações e acompanhamento da integração. O resultado deve ser segmentado por volume de nomes e termos, quantidade de processos e complexidade da operação.