API Contracts and Versioning: Preventing Regressions in Judicial Publication Monitoring

Start with a canonical publication model that represents the business event rather than the database behind it. A simple example might include id_publicacao, numero_processo, data_publicacao, tribunal, instancia, texto_original, resumo, confianca_extracao, and documentos.

For example, a response could be represented as {"id_publicacao":"pub_78421","numero_processo":"0001234-56.2026.8.26.0100","data_publicacao":"2026-10-27","tribunal":"TJSP","instancia":"1","confianca_extracao":0.96,"resumo":"Intimação para manifestação","documentos":[]}. The exact payload will vary, but each property should have an explicit semantic definition.

Field mapping is essential when the consumer uses different names. An ERP might map numero_processo to case_id, data_publicacao to publication_date, and confianca_extracao to extraction_score. Store that mapping in version control, review it like application code, and test it with representative payloads.

Do not use a field name as a substitute for a business definition. data_publicacao should specify whether it means the date shown in the official publication, the date captured by the monitoring service, or the date delivered to the consumer. These dates can differ, and the distinction matters when a legal team calculates response windows.

The contract should also distinguish facts from interpretations. texto_original is source content, while resumo, prazo_estimado, and acao_sugerida may be generated or extracted values. Consumers should be able to identify which fields came from the source and which require human validation.

For AI-enabled workflows, define whether a model-generated summary is optional, how its confidence is represented, and what happens when extraction fails. A missing summary should not prevent the original publication from reaching the legal team, especially when the publication may contain a deadline.

Pocket Jurídico is designed for legal teams that monitor names, terms, cases, publications, and procedural movements across more than 490 journals and courts. When those publications are synchronized with an ERP, CRM, legal management platform, or internal application, the integration should treat each publication as an auditable business event rather than as an unstructured notification.

A useful implementation starts with a mapping table. For example, numero_processo can map to the ERP case key, data_publicacao can map to the publication-date field, tribunal can map to the court code, and confianca_extracao can determine whether an extracted deadline enters automatic processing or manual review.

The field confianca_extracao deserves special care. A score of 0.94 may mean that extraction is highly reliable, but it does not prove that the suggested deadline is legally correct. Keep the original text, extracted value, source metadata, and human confirmation status available to preserve context.

The same principle applies when teams connect publications to ChatGPT, Claude, Gemini, or an MCP connector. The assistant should receive stable identifiers and source content, while the contract defines which values are authoritative and which are suggestions. This prevents an AI-generated summary from replacing the publication that a lawyer may need to inspect.

A safe CI/CD pipeline for this ecosystem can combine OpenAPI schema checks, consumer-driven contract tests, anonymized court fixtures, Postman scripts, duplicate-event tests, and MCP or LLM response checks. Run the pipeline against a staging feed, then compare the old and new payloads for process identity, publication date, document count, and extracted action.

This approach supports gradual adoption without requiring a legal team to abandon existing software. Pocket Jurídico can sit alongside an established ERP or legal platform, while the contract and mapping layer prevent the same publication from becoming multiple manual tasks in disconnected systems.

The first mistake is treating optional fields as harmless. A consumer may technically accept a missing documentos array, but its workflow may interpret the absence as proof that no document exists. Define the difference between an empty list, a null value, an omitted property, and an unavailable source.

Another mistake is changing date formats without testing legal meaning. ISO 8601 timestamps are useful, but a consumer may need the official publication date in Brazil rather than the capture timestamp. Return both when necessary, with names that make the distinction unmistakable.

Many teams also test only successful responses. Add cases for 401 and 403 authentication failures, 404 records, 409 duplicates, 429 rate limits, 5xx provider errors, malformed payloads, and timeout retries. Every error should tell the consumer whether it is safe to retry.

Avoid relying on production data as the only test source. Build anonymized fixtures that preserve structural variety without exposing sensitive case information, personal data, or confidential documents. The Brazilian data protection authority, ANPD provides official regulatory material that can inform data governance decisions under Brazil's privacy framework.

Finally, do not make the API contract responsible for decisions that belong to legal review. A contract can preserve source text, provenance, confidence, and extraction status, but it cannot guarantee that an automated deadline interpretation is correct in every procedural context.

Before approving a release, ask whether the team can answer these questions: Which consumers are affected? What happens to old payloads? Can an event be replayed? How is a duplicate detected? Which field is authoritative? How will a lawyer know that a value was extracted rather than confirmed? If the answers are unclear, the contract is not ready.