Como projetar webhooks e APIs para integrar publicações judiciais ao seu ERP ou CRM
Um guia prático para desenhar payloads, webhooks, retries, segurança e regras de integração para escritórios e departamentos jurídicos.
Conheça boas práticas para estruturar sua integração
Neste artigo9 seções
- Por que projetar webhooks para publicações judiciais?
- Quais campos a API de publicações judiciais deve enviar?
- Exemplo de payload JSON para uma publicação judicial
- Como garantir idempotência, ordenação e entrega confiável
- Segurança, limites de uso e SLAs para webhooks jurídicos
- Evento único ou lote: qual padrão escolher para o jurídico?
- Como aplicar esse desenho ao Pocket Jurídico e ao seu fluxo interno
- Roteiro de implementação em seis etapas
- Erros frequentes ao integrar publicações judiciais por API
Por que projetar webhooks para publicações judiciais?
Projetar webhooks e APIs para publicações judiciais significa definir como um evento capturado em um diário ou tribunal será transformado em informação útil no ERP, CRM ou gestor de processos. Em vez de alguém consultar telas, baixar arquivos e cadastrar tarefas manualmente, o sistema de origem envia uma notificação estruturada assim que existe uma nova movimentação relevante.
A diferença entre uma integração funcional e uma integração confiável está nos detalhes. O evento precisa identificar corretamente o processo, informar quando foi capturado, preservar o conteúdo original, indicar se há prazo e permitir que o sistema receptor processe a mesma mensagem mais de uma vez sem criar tarefas duplicadas.
Um webhook é adequado para avisos quase em tempo real. A API, por sua vez, serve para consultar detalhes, buscar histórico, reprocessar eventos e conferir se o ERP ou CRM está sincronizado. Usados juntos, os dois recursos reduzem a dependência de consultas periódicas e criam uma trilha operacional mais clara.
Para compreender o contexto jurídico antes de definir campos técnicos, consulte o guia prático para interpretar publicações judiciais. Uma integração só gera valor quando o dado recebido pode ser entendido e convertido em uma ação segura pelo time responsável.
Quais campos a API de publicações judiciais deve enviar?
O contrato de dados é a base da integração. Ele deve ser documentado como uma interface estável, com nomes de campos, tipos, obrigatoriedade, formato de datas, valores possíveis e regras de atualização. Evite enviar apenas texto livre da publicação: o ERP ou CRM precisa receber dados suficientes para criar uma tarefa, relacioná-la a um caso e permitir auditoria.
Para um evento de publicação judicial, dez campos formam um conjunto mínimo bastante útil:
- identificador único do processo, preferencialmente o número CNJ normalizado;
- instância, como primeiro grau, segundo grau ou tribunal superior;
- tribunal e órgão julgador;
- data e hora da captura;
- tipo de publicação ou movimentação;
- resumo produzido por IA, quando disponível;
- prazo extraído, com data final, unidade e nível de confiança;
- URL do anexo ou do documento relacionado;
- metadados de validação, incluindo status, origem e versão do processamento;
- identificador do monitorado, que pode representar nome, termo, parte ou grupo acompanhado.
Além desses campos, inclua um identificador imutável do evento, a versão do esquema, o momento em que a mensagem foi emitida e uma referência de correlação. Esses atributos não substituem os dez dados jurídicos, mas ajudam o time técnico a investigar falhas sem depender de planilhas ou buscas manuais.
Datas devem ser transmitidas em ISO 8601, com fuso horário explícito. O número do processo deve ter uma forma canônica para relacionamento, enquanto o texto original deve ser preservado para conferência. Um resumo ou prazo gerado por IA deve ser tratado como apoio à triagem, não como substituto da validação profissional.
A extração automática precisa conversar com a rotina de prazos. Veja como estruturar um calendário de prazos processuais mais confiável, especialmente quando o ERP cria atividades para equipes diferentes.
Exemplo de payload JSON para uma publicação judicial
Um payload bem desenhado deve ser legível por pessoas e previsível para máquinas. O exemplo abaixo apresenta uma estrutura de referência com os dez campos principais e alguns atributos técnicos adicionais. Os nomes podem variar, mas a semântica deve permanecer documentada e estável.
{
"evento_id": "evt_01J9PUBL123",
"versao_esquema": "1.0",
"processo_id": "0001234-56.2026.8.26.0100",
"instancia": "segundo_grau",
"tribunal": "TJSP",
"capturado_em": "2026-09-13T14:32:18-03:00",
"tipo_publicacao": "intimacao",
"resumo_ia": "Intimação para manifestação sobre o laudo pericial.",
"prazo_extraido": {
"data_final": "2026-09-21",
"quantidade_dias": 5,
"confianca": 0.94
},
"anexo_url": "https://api.exemplo.com/documentos/doc_789",
"metadados_validacao": {
"processo_validado": true,
"origem": "diario_oficial",
"validado_em": "2026-09-13T14:35:02-03:00"
},
"monitorado_id": "mon_456",
"emitido_em": "2026-09-13T14:36:10-03:00",
"correlacao_id": "corr_abc789"
}
O ERP pode usar processo_id como chave de relacionamento e evento_id como chave de idempotência. O prazo_extraido.data_final pode alimentar a data de vencimento de uma tarefa, enquanto resumo_ia aparece na descrição para orientar a triagem. O anexo_url deve exigir autenticação e ter validade controlada, em vez de ficar exposto indefinidamente.
Quando o prazo tiver baixa confiança ou a publicação não for conclusiva, o evento pode ser criado com status “revisão necessária”. Essa regra evita que um sistema trate toda sugestão automatizada como prazo definitivo. O campo de validação também permite separar eventos capturados, conferidos e aprovados.
Para conectar uma publicação a um CRM, mapeie o processo para um caso, cliente, conta ou objeto personalizado. No Salesforce, por exemplo, o identificador do processo pode ser uma chave externa em um objeto jurídico, enquanto o tipo de publicação cria uma tarefa relacionada. Em um ERP como o TOTVS, o mesmo evento pode alimentar uma ocorrência ou atividade vinculada ao cadastro da parte e ao centro de responsabilidade.
Como garantir idempotência, ordenação e entrega confiável
- 1
Crie uma chave idempotente
Use o identificador único do evento como chave de deduplicação no sistema receptor. Antes de criar uma tarefa ou atualizar um caso, consulte se essa chave já foi processada. Se já existir, responda com sucesso e não replique a operação.
- 2
Separe evento, processamento e efeito
Registre a mensagem recebida antes de executar ações no ERP ou CRM. Essa separação permite reprocessar um evento sem perder o conteúdo original e ajuda a identificar se a falha ocorreu na entrega, na validação ou na criação da tarefa.
- 3
Não confie na ordem de chegada
Redes e filas podem entregar eventos fora de ordem. Use a data de captura, um número de sequência por processo ou uma versão do recurso para decidir se uma atualização é mais recente. Nunca substitua um estado novo por uma mensagem antiga apenas porque ela chegou depois.
- 4
Responda rapidamente ao webhook
O endpoint deve validar autenticação, persistir o evento e retornar uma resposta de sucesso em poucos segundos. Processamentos demorados, como baixar anexos ou criar múltiplas tarefas, devem ocorrer em fila assíncrona.
- 5
Faça novas tentativas com critério
Para erros temporários, aplique espera exponencial, por exemplo 1, 2, 4, 8 e 16 minutos, com limite máximo e aleatoriedade. Erros de autenticação, esquema inválido ou recurso inexistente devem ir para uma fila de exceção, não para tentativas infinitas.
- 6
Registre o resultado de cada tentativa
Guarde horário, código HTTP, duração, motivo da falha e número da tentativa. Um painel com eventos pendentes, processados e mortos permite que o jurídico e a tecnologia acompanhem o impacto operacional.
Segurança, limites de uso e SLAs para webhooks jurídicos
- ✓Autenticação: prefira assinatura HMAC no corpo da mensagem, chaves rotacionáveis ou OAuth 2.0 quando o cenário exigir autorização por escopo. Valide também timestamp e nonce para reduzir risco de repetição maliciosa.
- ✓Criptografia: use HTTPS com TLS atualizado em todos os endpoints. Documentos, nomes de partes e detalhes processuais podem conter dados pessoais e devem ser protegidos em trânsito, em repouso e nos registros de log.
- ✓Princípio do menor privilégio: o consumidor deve acessar apenas os recursos necessários. Uma integração que recebe eventos não precisa automaticamente de permissão para alterar processos, usuários ou configurações.
- ✓Controle de taxa: limite requisições por cliente, janela de tempo e recurso. Quando o limite for atingido, informe o consumidor com HTTP 429 e, se possível, um cabeçalho indicando quando tentar novamente. A especificação HTTP sobre limitação de requisições documenta o uso do código 429.
- ✓Proteção de segredos: não coloque tokens em código-fonte, URLs, mensagens de erro ou campos visíveis para usuários. Use cofre de segredos, rotação periódica e ambientes separados para testes e produção.
- ✓Observabilidade: registre o ID do evento, correlação, status e tempo de processamento, mas mascare documentos e dados pessoais desnecessários. Logs devem ajudar na investigação sem criar uma nova superfície de exposição.
- ✓Disponibilidade: defina um TTL para eventos pendentes, por exemplo 24 ou 48 horas, conforme a criticidade e a capacidade de reprocessamento. Depois desse período, encaminhe o caso para uma fila de intervenção, preservando a mensagem e o motivo da falha.
- ✓Acordo técnico: documente um objetivo de entrega, como notificar o consumidor em até alguns minutos após a publicação estar disponível, sem prometer que o tribunal publica ou atualiza dados em horário previsível. O SLA deve separar captura, emissão, recebimento e processamento.
Evento único ou lote: qual padrão escolher para o jurídico?
O evento único é mais simples para avisos urgentes. Cada nova publicação dispara uma mensagem independente, o que reduz a latência e permite que uma intimação gere uma tarefa assim que for validada. O custo é maior volume de chamadas e mais necessidade de controle de duplicidade.
O envio em lote reúne vários eventos em uma única requisição. Ele é útil para uma carga inicial, reconciliação noturna, reprocessamento ou escritórios que acompanham grande quantidade de processos. O lote deve conter um identificador próprio, a lista de eventos e o resultado individual de cada item, porque uma falha em um processo não deve invalidar todos os demais.
Uma arquitetura híbrida costuma funcionar melhor. Use evento único para publicações com prazo ou prioridade alta e lote para sincronizar histórico, anexos e alterações de menor urgência. A escolha deve considerar volume, latência, limites do ERP e capacidade da fila, como detalhado no guia sobre arquitetura de integração para publicações judiciais e ERP ou CRM.
O consumidor também precisa de uma API de reconciliação. Mesmo com webhooks confiáveis, podem existir indisponibilidade, expiração de credencial ou falha de rede. Uma consulta por período, processo ou evento_id permite comparar o que foi emitido com o que chegou e fechar lacunas.
A documentação deve explicar o comportamento de atualização. Se um resumo de IA for corrigido, o sistema deve receber um novo evento de atualização ou consultar o recurso novamente. Alterar silenciosamente o mesmo evento torna auditorias e investigações muito mais difíceis.
Como aplicar esse desenho ao Pocket Jurídico e ao seu fluxo interno
Em uma operação que monitora mais de 490 diários e tribunais, a integração precisa lidar com variações de origem, validação do processo, documentos e volume. O Pocket Jurídico pode entregar publicações e movimentações por API, permitindo sincronizar o conteúdo com ERPs, CRMs, gestores jurídicos e plataformas internas sem obrigar a equipe a repetir o cadastro em sistemas diferentes.
Um fluxo prático começa quando uma nova publicação é capturada e o processo é validado em suas diferentes instâncias. O evento pode incluir o resumo de IA, a indicação de prazo e o documento relacionado, enquanto o ERP decide se deve criar uma tarefa, atualizar um caso, notificar um responsável ou encaminhar a publicação para revisão.
O MCP do Pocket Jurídico amplia esse fluxo ao conectar processos e publicações a ferramentas de IA, como ChatGPT, Claude e Gemini. Antes do envio ao sistema interno, o conector pode enriquecer o evento com resumo, classificação, perguntas respondidas e prazo sugerido, sempre mantendo o texto original e os metadados que permitem revisão humana. Para aprofundar esse modelo, consulte o guia sobre MCP jurídico e conexão de IA a processos e publicações.
No Google Agenda ou Outlook, o campo de prazo pode criar um compromisso ou lembrete com o número do processo, responsável, data limite e link seguro para a publicação. No Salesforce, pode gerar uma tarefa vinculada ao caso; em uma plataforma TOTVS ou sistema próprio, pode alimentar uma ocorrência no fluxo do departamento jurídico.
O mapeamento deve prever exceções. Um prazo sem data conclusiva, uma publicação sem processo validado ou um anexo indisponível não deve desaparecer nem gerar uma tarefa falsa. Nesses casos, o sistema pode criar uma pendência de conferência com prioridade definida e preservar o evento para análise.
A experiência operacional também importa. Comentários internos, alertas e histórico devem permanecer associados ao processo ou à publicação, evitando que decisões se percam em e-mails e planilhas paralelas. Para entender como reduzir retrabalho na operação, veja o playbook de automação da triagem e priorização com IA.
Roteiro de implementação em seis etapas
- 1
Mapeie os eventos jurídicos
Liste publicações, movimentações, correções, documentos e alterações de prazo. Para cada tipo, defina quem recebe, qual ação é esperada e qual informação precisa ficar disponível para auditoria.
- 2
Defina o contrato da API
Documente os dez campos essenciais, os identificadores, os estados possíveis, a paginação, os filtros e as versões. Inclua exemplos válidos e inválidos, além da política para mudanças incompatíveis.
- 3
Escolha o destino de cada campo
Crie uma matriz de mapeamento entre origem e destino. Relacione processo ao caso, prazo à tarefa, resumo à descrição, anexo ao documento e monitorado ao cliente, unidade ou carteira responsável.
- 4
Construa a camada de recebimento
Implemente autenticação, validação de esquema, idempotência, persistência inicial e fila assíncrona. O endpoint não deve depender de uma tela aberta nem executar toda a regra de negócio antes de responder.
- 5
Teste falhas reais
Simule mensagens repetidas, eventos fora de ordem, token expirado, limite de requisições, anexo indisponível e indisponibilidade do ERP. O teste só termina quando a equipe consegue recuperar um evento sem duplicar tarefas.
- 6
Monitore e revise
Acompanhe taxa de sucesso, tempo entre captura e processamento, eventos em retry, duplicidades evitadas e prazos encaminhados para revisão. Faça uma revisão mensal do contrato e das regras de negócio com jurídico e tecnologia.
Erros frequentes ao integrar publicações judiciais por API
O primeiro erro é tratar webhook como uma chamada única e garantida. Redes falham, sistemas entram em manutenção e consumidores podem responder lentamente. O desenho correto assume reenvio, duplicidade e necessidade de reconciliação desde o início.
Outro problema é usar apenas o número do processo como identificador do evento. Um mesmo processo pode receber dezenas de publicações, retificações ou documentos. A chave de deduplicação deve identificar o evento, enquanto o processo funciona como chave de relacionamento.
Também é arriscado transformar qualquer data encontrada no texto em prazo definitivo. Expressões relacionadas a feriados, suspensão, ciência, publicação e contagem podem exigir interpretação. O sistema deve indicar a origem, a confiança e o status de validação, além de permitir revisão pelo advogado ou responsável.
Logs excessivos representam um risco de privacidade. Grave o necessário para rastrear o processamento e mantenha o conteúdo sensível protegido. O checklist de segurança para departamentos jurídicos ajuda a organizar controles de acesso, continuidade e proteção de dados.
Por fim, não deixe a documentação apenas com o fornecedor ou com um desenvolvedor específico. O jurídico precisa saber o que acontece quando uma publicação chega, quem recebe a tarefa, qual é o prazo de resposta e como corrigir uma exceção. Uma integração sustentável é compreendida pelas pessoas que dependem dela todos os dias.
Perguntas Frequentes
O que é um webhook e por que ele é útil para integrar publicações judiciais?▼
Webhook é uma notificação enviada automaticamente por um sistema quando ocorre um evento, como a captura de uma nova publicação. Ele é útil porque reduz a necessidade de consultas repetidas e permite que o ERP ou CRM reaja rapidamente. Em um fluxo jurídico, a mensagem pode criar uma tarefa, atualizar um caso ou encaminhar um prazo para revisão. A API complementa o webhook ao permitir consultas, histórico e reconciliação.
Quais campos mínimos uma API de monitoramento judicial deve enviar?▼
O conjunto mínimo deve incluir identificador único do processo, instância, tribunal, data e hora da captura, tipo de publicação, resumo, prazo extraído, URL do anexo, metadados de validação e identificador do monitorado. Também é recomendável incluir ID imutável do evento, versão do esquema e data de emissão. Esses dados permitem relacionar a publicação ao caso correto, criar tarefas e investigar falhas. O texto original deve ser preservado para conferência.
Como evitar que a mesma publicação crie tarefas duplicadas no ERP?▼
Use o identificador único do evento como chave de idempotência e armazene o resultado do processamento. Quando a mesma mensagem for recebida novamente, o sistema deve reconhecer a chave, retornar sucesso e não executar o efeito pela segunda vez. O número do processo sozinho não é suficiente, porque um processo pode ter várias publicações. Também é recomendável criar testes específicos para reenvio, timeout e processamento parcial.
Como lidar com publicações judiciais que chegam fora de ordem?▼
Não use a ordem de chegada como critério de atualização. Compare data de captura, sequência do evento, versão do recurso ou outro marcador fornecido pela origem. Eventos antigos devem ser armazenados, mas não podem sobrescrever informações mais recentes sem uma regra explícita. Quando não for possível determinar a ordem, encaminhe o caso para reconciliação ou revisão.
Qual é a melhor estratégia de retry para webhooks jurídicos?▼
Use novas tentativas com espera exponencial e um limite máximo, como 1, 2, 4, 8 e 16 minutos, acrescentando variação aleatória para evitar picos simultâneos. Erros temporários, como indisponibilidade ou timeout, podem ser reenviados. Já erros de autenticação, esquema inválido ou recurso inexistente devem ir para uma fila de exceção. Registre cada tentativa com horário, código HTTP e motivo da falha.
É melhor enviar uma publicação por webhook ou várias em um lote?▼
O evento único reduz a latência e é adequado para intimações, prazos e movimentações prioritárias. O lote economiza chamadas e funciona bem para carga inicial, histórico e reconciliação. Muitas operações adotam um modelo híbrido, com evento único para alta urgência e lote para sincronizações periódicas. Em qualquer formato, cada item precisa ter identificador próprio e resultado individual.
Como integrar prazos judiciais ao Google Agenda, Outlook ou CRM?▼
Mapeie a data final do prazo para o campo de vencimento e inclua processo, tribunal, responsável, prioridade e link seguro para a publicação. No Google Agenda ou Outlook, crie um evento ou lembrete conforme a política do escritório. No CRM, associe a atividade ao caso ou cliente por meio de uma chave externa. Prazos sem validação suficiente devem gerar revisão, não compromissos definitivos.
O resumo feito por IA pode criar automaticamente um prazo processual?▼
O resumo e a extração por IA podem acelerar a triagem, mas devem ser acompanhados de fonte, confiança e status de validação. A regra de automação precisa diferenciar uma sugestão de prazo de um prazo aprovado pelo responsável. Para publicações ambíguas, o sistema deve preservar o conteúdo original e solicitar conferência. A decisão jurídica continua sob responsabilidade do profissional habilitado.