API Contracts e versionamento: como evitar regressões ao integrar publicações judiciais

Um bom contrato começa pelo evento ou recurso que o consumidor realmente precisa. Em vez de modelar uma resposta genérica, descreva a publicação como uma unidade operacional: identificação do processo, origem, data, conteúdo, nível de confiança, documentos, prazos extraídos e histórico de alterações.

Um exemplo simplificado de resposta pode ser representado assim:

{
 "id_publicacao": "pub_83921",
 "numero_processo": "0001234-56.2026.8.26.0100",
 "data_publicacao": "2026-10-27",
 "tribunal": "TJSP",
 "tipo_ato": "intimacao",
 "texto": "Fica a parte intimada para apresentar manifestação...",
 "confianca_extracao": 0.96,
 "prazo": {
 "quantidade": 5,
 "unidade": "dias_uteis",
 "necessita_revisao": true
 }
}

Os nomes precisam ser estáveis e semanticamente claros. data_publicacao deve representar a data do ato publicado, enquanto a data de recebimento, a data de captura e o momento de processamento devem ter campos próprios. Separar esses conceitos evita que um consumidor calcule prazos a partir do instante errado.

Também defina nulidade e ausência com precisão. confianca_extracao: null pode significar que a análise ainda não ocorreu, enquanto 0 pode representar confiança mínima. Se o ERP tratar os dois valores da mesma forma, a equipe pode interpretar uma informação pendente como uma informação negativa.

O mapeamento entre sistemas deve ser mantido como artefato versionado. O campo numero_processo pode alimentar caseNumber em um CRM, processo.identificador em um software jurídico e uma chave externa em um data warehouse. O guia de modelos JSON e mapeamento de campos para ERP e CRM ajuda a estruturar essa camada sem espalhar regras duplicadas pelo código.

Além do esquema, documente regras que não aparecem no JSON: idempotência, ordenação dos eventos, política de reenvio, limite de paginação, autenticação, códigos de erro e retenção dos documentos. Um contrato incompleto pode parecer detalhado e ainda assim falhar justamente nos cenários de indisponibilidade ou duplicidade.

O rollout mais seguro não começa pelo consumidor mais complexo. Comece por uma carteira controlada, com processos não críticos ou uma unidade que tenha disponibilidade para validar o fluxo. O objetivo é descobrir incompatibilidades sem colocar todos os prazos do contencioso em uma única mudança.

Na primeira etapa, faça inventário dos consumidores e congele o contrato atual como referência. Em seguida, selecione uma amostra de publicações com diferentes tribunais, classes processuais e formatos de documento. Registre o resultado esperado para cada caso, incluindo o vínculo ao processo e a tarefa que deve ser criada.

Na segunda etapa, publique a nova versão em homologação e execute testes de contrato, carga moderada, reprocessamento e permissões. Se houver assistentes baseados em ChatGPT, Claude, Gemini ou MCP, valide também se a nova estrutura preserva o contexto, as fontes e os avisos de revisão humana.

Na terceira etapa, faça uma execução paralela limitada. A versão antiga continua alimentando o fluxo oficial, enquanto a versão nova é comparada em uma amostra. Compare identificadores, datas, conteúdo, anexos, prazos e ações geradas, em vez de verificar somente o código de status.

Depois, avance por ondas. Uma empresa que centraliza correspondentes pode migrar primeiro uma região ou carteira, depois um grupo de escritórios terceirizados e finalmente o restante da operação. O guia sobre rollout do monitoramento em fases, big bang ou modelo híbrido ajuda a avaliar o ritmo conforme risco, dependências e capacidade de suporte.

Mantenha um botão operacional de retorno, mas não confie apenas nele. O plano de contingência precisa dizer como reprocessar eventos, como evitar tarefas duplicadas, quem autoriza a reversão e como comunicar a equipe. Em um fluxo de prazos, voltar ao código anterior não desfaz automaticamente registros criados pela versão nova.

Durante todo o rollout, acompanhe reconciliação entre eventos recebidos e registros criados, falhas por consumidor, publicações sem vínculo e tempo de correção. Esses indicadores complementam os testes de contrato e mostram se a integração continua útil para a rotina jurídica.

O primeiro erro é considerar que adicionar campos nunca quebra consumidores. Alguns sistemas usam validação rígida e recusam propriedades desconhecidas; outros serializam o objeto inteiro para relatórios, alterando colunas ou regras de importação. A compatibilidade precisa ser testada no consumidor real.

Outro problema é usar o número da versão sem definir sua política. Uma rota /v2 não explica quais mudanças ocorreram, por quanto tempo /v1 será mantida ou como o consumidor identifica eventos produzidos por cada versão. Versionamento só reduz risco quando acompanha documentação, janela de transição e critérios de encerramento.

Também é arriscado alterar o significado de um campo mantendo o mesmo nome. Se data_publicacao passar a representar a data de captura, nenhuma falha técnica será necessariamente registrada, mas os cálculos de prazo poderão ficar errados. Quando o significado muda, crie um novo campo ou uma nova versão com migração explícita.

A ausência de eventos de correção é outra fonte de inconsistência. Publicações podem ser atualizadas, complementadas ou associadas a documentos posteriormente. O contrato deve informar como o consumidor recebe a correção e como distingue um novo ato de uma atualização do ato anterior.

Por fim, não trate o teste de contrato como substituto da validação jurídica. Um JSON pode cumprir o esquema e ainda trazer uma extração de prazo que exige revisão humana. A validação automática combinada com revisão humana no monitoramento ajuda a definir quais decisões podem ser automatizadas e quais precisam de confirmação.

Uma boa disciplina é revisar o contrato sempre que houver mudança de tribunal, novo tipo de documento, alteração no modelo de IA ou inclusão de um consumidor. Essa revisão curta evita que exceções locais se tornem regras invisíveis espalhadas pela operação.