Contratos de API y versionado para evitar regresiones en publicaciones judiciales
Aprende a definir campos, detectar cambios incompatibles y desplegar nuevas versiones sin romper el flujo entre publicaciones, ERPs, CRMs y equipos legales.
Conoce un flujo más seguro para tus integraciones
En este artículo9 secciones
- Qué son los contratos de API y por qué importan en el ámbito jurídico
- Qué debe incluir un contrato de API para publicaciones judiciales
- Cómo versionar una API de publicaciones sin interrumpir el flujo
- Pruebas automatizadas para detectar regresiones antes de cambiar un campo
- Cómo comunicar cambios incompatibles a varios consumidores
- Lista de verificación de CI/CD para integraciones jurídicas
- Cómo aplicar este modelo al monitoreo de publicaciones con Pocket Jurídico
- Plan de despliegue gradual para despachos con varios ERPs y corresponsales
- Errores frecuentes al versionar una API jurídica
Qué son los contratos de API y por qué importan en el ámbito jurídico
Los contratos de API y el versionado son la base para integrar publicaciones judiciales sin regresiones. Un contrato define qué datos entrega un servicio, con qué formato, qué campos son obligatorios, qué valores pueden aparecer y cómo debe responder ante errores. El versionado establece cómo evolucionará esa interfaz sin interrumpir a quienes ya dependen de ella.
En un flujo jurídico, un cambio aparentemente pequeño puede tener consecuencias operativas importantes. Si un ERP espera el campo numero_proceso y la API lo renombra, el expediente puede dejar de asociarse correctamente, aunque la publicación siga llegando al sistema de origen.
La criticidad aumenta cuando el dato alimenta alertas, agendas, informes o tareas de plazo. Una alteración en data_publicacao, una fecha con otro formato o una modificación en confianca_extracao puede provocar duplicados, fechas mal interpretadas o revisiones manuales innecesarias.
Por eso, una integración de publicaciones no debe tratarse como una simple conexión entre dos sistemas. Es un acuerdo operacional entre el proveedor de datos y todos sus consumidores: gestores de procesos, ERPs, CRMs, automatizaciones internas, abogados, corresponsales y herramientas de inteligencia artificial.
Qué debe incluir un contrato de API para publicaciones judiciales
Un contrato útil empieza por el modelo de datos, pero no termina allí. También debe describir la autenticación, los códigos HTTP, la paginación, los límites de uso, la idempotencia, los reintentos, los eventos y la política para cambios incompatibles.
La especificación OpenAPI ofrece una forma estructurada de documentar rutas, parámetros, respuestas y esquemas. En la práctica, permite que desarrollo, producto y operaciones revisen la misma definición antes de construir o modificar una integración.
Para una publicación judicial, un modelo mínimo podría incluir id_publicacion, numero_proceso, data_publicacao, tribunal, vara, tipo_movimentacao, texto_original, documentos, prazo_identificado y confianca_extracao. Cada campo debe indicar tipo, obligatoriedad, formato, posibles valores nulos y reglas de actualización.
El mapeo entre campos también debe quedar documentado. Por ejemplo, numero_processo puede alimentar processNumber en un CRM, mientras que data_publicacao puede transformarse en publishedAt dentro de un gestor interno. La transformación debe especificar zona horaria, máscara de fecha, tratamiento de valores ausentes y conducta ante datos no válidos.
Una regla especialmente relevante es distinguir entre ausencia y valor vacío. Un campo que no aparece puede significar que el dato no fue informado, mientras que un campo con valor nulo puede indicar que fue evaluado y no aplica. Si el consumidor no conoce esa diferencia, puede crear tareas incorrectas o sobrescribir información existente.
El contrato debe describir también la semántica de entrega. ¿La API devuelve una publicación una sola vez o puede repetirla? ¿Existe un identificador estable para deduplicar? ¿El texto puede corregirse después de la primera entrega? Estas respuestas son tan importantes como el nombre de cada propiedad.
Cómo versionar una API de publicaciones sin interrumpir el flujo
- 1
Clasifica el cambio antes de publicarlo
Agrega un catálogo de cambios con tres categorías: compatible, potencialmente riesgoso e incompatible. Añadir un campo opcional suele ser compatible, pero cambiar su tipo, eliminarlo o modificar su significado exige una evaluación más rigurosa.
- 2
Conserva los campos existentes durante la transición
Cuando un nombre necesita cambiar, mantén el campo anterior y agrega el nuevo durante un período definido. Por ejemplo, puedes conservar
data_publicacaoy presentar tambiéndata_publicacion_iso, documentando cuál debe adoptar cada consumidor. - 3
Elige una estrategia de versión explícita
Las versiones pueden expresarse en la ruta, mediante encabezados o con negociación de contenido. Lo esencial es que el consumidor pueda identificar la versión que recibe y que exista una política clara de soporte, correcciones y retiro.
- 4
Publica un contrato ejecutable
No guardes la documentación solamente en una página que alguien debe leer. Convierte el esquema en validaciones automáticas, ejemplos, simulaciones de respuestas y pruebas que fallen cuando una modificación rompe las expectativas de un consumidor.
- 5
Ejecuta pruebas con datos representativos
Incluye publicaciones con procesos de distintas instancias, documentos adjuntos, textos extensos, fechas límite, caracteres especiales y campos sin extracción concluyente. Un contrato validado únicamente con respuestas ideales no protege la operación real.
- 6
Define una ventana de convivencia
Mantén la versión anterior mientras los consumidores migran, pero establece una fecha de retiro y métricas de adopción. No desactives una versión basándote en la suposición de que todos leyeron el aviso.
- 7
Observa el comportamiento después del despliegue
Monitorea errores de esquema, códigos 4xx y 5xx, latencia, duplicados, reintentos y volumen por versión. Una liberación segura se confirma con evidencia de uso, no solo con una implementación exitosa.
Pruebas automatizadas para detectar regresiones antes de cambiar un campo
- ✓Pruebas de estructura: validan que cada respuesta respete tipos, campos obligatorios, formatos de fecha, enumeraciones y restricciones del esquema. Deben comprobar tanto respuestas completas como casos con valores nulos o colecciones vacías.
- ✓Pruebas de compatibilidad: comparan el contrato nuevo con el anterior y alertan sobre propiedades eliminadas, cambios de tipo, nuevas restricciones, modificaciones de obligatoriedad y cambios en códigos de respuesta. Son esenciales antes de publicar una nueva versión.
- ✓Pruebas de mapeo: verifican que
numero_processollegue al identificador correcto del ERP, quedata_publicacaoconserve la zona horaria esperada y queconfianca_extracaono se convierta accidentalmente en texto cuando el consumidor espera un número. - ✓Pruebas de idempotencia: envían dos veces la misma publicación y confirman que el sistema receptor no cree dos tareas, dos expedientes ni dos alertas. Este control es decisivo cuando existen reintentos después de una interrupción de red.
- ✓Pruebas de orden y actualización: simulan una publicación inicial, una corrección posterior y la llegada atrasada de un evento. El consumidor debe saber cuál versión del dato prevalece y no reemplazar información nueva por una respuesta antigua.
- ✓Pruebas con simulaciones de diarios: utilizan respuestas ficticias que reproducen variaciones reales, como procesos con formatos distintos, documentos ausentes, movimientos repetidos y nombres de partes con acentos o caracteres especiales.
- ✓Pruebas de carga y límites: comprueban paginación, volumen elevado, límites de solicitudes y tiempos de respuesta. Un despacho que funciona con 10 publicaciones puede fallar cuando un departamento jurídico recibe miles de movimientos en un período corto.
- ✓Pruebas de inteligencia artificial y MCP: verifican que los conectores mantengan el contexto del proceso, que una IA reciba el texto y los metadatos correctos, y que un cambio de esquema no altere la interpretación de plazos, acciones urgentes o documentos.
Cómo comunicar cambios incompatibles a varios consumidores
Un cambio incompatible no se resuelve con un correo enviado el día del despliegue. Los equipos que mantienen ERPs, automatizaciones, conectores de IA y procesos manuales necesitan conocer qué cambia, por qué, cuándo y qué acción deben tomar.
La comunicación debe incluir un identificador del cambio, la versión afectada, ejemplos antes y después, fecha de disponibilidad, fecha prevista de retiro, impacto esperado y procedimiento de prueba. También conviene indicar si el cambio afecta solamente la estructura o si modifica el significado jurídico u operativo del dato.
Considera un campo como confianca_extracao. Si pasa de una escala de 0 a 1 a una escala de 0 a 100, la estructura puede parecer similar porque el tipo sigue siendo numérico. Sin embargo, las reglas del ERP que activan una revisión humana pueden quedar completamente alteradas.
Para consumidores externos o equipos descentralizados, utiliza un registro de cambios accesible, avisos con anticipación y un canal de soporte durante la migración. En un despacho que centraliza correspondentes, cada oficina puede tener automatizaciones diferentes, por lo que el inventario técnico debe incluir integraciones que no estén bajo el control directo del equipo principal.
La documentación debe responder una pregunta práctica: qué debe hacer cada consumidor. Una nota como “se actualizó el esquema” es insuficiente; una instrucción como “cambia la lectura de prazo_identificado.data a prazo_identificado.data_limite y ejecuta el conjunto de pruebas de recepción” permite actuar.
Lista de verificación de CI/CD para integraciones jurídicas
- 1
Contrato y control de versiones
Guarda el esquema de la API junto con el código y revisa cada modificación mediante solicitudes de cambio. La revisión debe mostrar campos agregados, eliminados o alterados, no solamente diferencias de implementación.
- 2
Datos ficticios realistas
Mantén una colección de ejemplos de diarios, tribunales y tipos de movimiento. Incluye casos de texto largo, archivos, acentos, procesos en distintas instancias, publicaciones repetidas y extracción de plazo con baja confianza.
- 3
Pruebas de contrato
Ejecuta pruebas del proveedor y del consumidor en cada integración. Herramientas como Pact pueden servir como referencia para validar que lo que el proveedor publica sigue cumpliendo las expectativas declaradas por cada consumidor.
- 4
Colecciones de solicitudes
Automatiza scripts de Postman o una herramienta equivalente para probar autenticación, paginación, filtros, errores, reintentos y respuestas de cada versión. El conjunto debe ejecutarse en un entorno aislado antes de llegar a producción.
- 5
Compatibilidad con MCP y modelos de lenguaje
Prueba que el conector MCP exponga las entidades correctas, preserve permisos y entregue contexto suficiente para que ChatGPT, Claude o Gemini interpreten una publicación. No evalúes solamente que la respuesta sea válida, verifica que el dato usado para el plazo sea el correcto.
- 6
Puerta de aprobación
Bloquea el despliegue si falla una prueba de compatibilidad, aumenta la tasa de errores o desaparece un campo protegido. Las excepciones deben quedar registradas con responsable, justificación y fecha de revisión.
- 7
Supervisión posterior
Configura alertas para errores por versión, publicaciones no asociadas, duplicados, retrasos de entrega y fallas en la creación de tareas. Los tableros deben ser visibles para tecnología y para el equipo que responde por los plazos.
Cómo aplicar este modelo al monitoreo de publicaciones con Pocket Jurídico
En el monitoreo judicial, el contrato debe reflejar el ciclo completo de la información, no solo la publicación aislada. Cuando una nueva publicación es identificada, el sistema puede relacionarla con el proceso, capturar su historial, movimientos y documentos, y entregar una visión más completa para la operación del despacho.
Un ejemplo de mapeo puede ser: numero_processo hacia el número único del expediente en el gestor; data_publicacao hacia la fecha oficial de publicación; tribunal hacia la unidad responsable; texto_original hacia el contenido íntegro; y confianca_extracao hacia un indicador que determine si el plazo extraído necesita revisión humana.
Pocket Jurídico trabaja con monitoreo en más de 490 diarios y tribunales, además de integraciones por API con software jurídico, ERPs y CRMs. Para una operación de alto volumen, el consumidor debe identificar cada publicación de forma estable y registrar cuándo fue recibida, procesada, asociada y enviada a la agenda.
Si el equipo utiliza IA para resumir despachos, extraer plazos o responder preguntas dentro del flujo, el contrato debe preservar el contexto. El texto de la publicación no debería llegar separado del número de proceso, la fecha, el tribunal y los documentos relacionados, porque la interpretación pierde precisión cuando se elimina esa relación.
El mismo principio se aplica a conectores MCP para ChatGPT, Claude o Gemini. Antes de cambiar un nombre de campo, prueba consultas reales: localizar una publicación, resumirla, identificar un plazo y explicar qué documento sustenta la respuesta. El resultado debe seguir siendo trazable hasta el dato original.
La integración también debe contemplar entregas por correo, archivos y hojas de cálculo cuando formen parte del flujo operativo. Un cambio en el contrato de la API no puede romper silenciosamente el informe diario que utiliza el equipo para revisar publicaciones, distribuir tareas o coordinar despachos externos.
Plan de despliegue gradual para despachos con varios ERPs y corresponsales
- 1
Inventaria todos los consumidores
Relaciona cada ERP, CRM, gestor jurídico, hoja automatizada, conector de IA y equipo externo con la versión que utiliza. Incluye integraciones antiguas que no generan incidencias visibles, pero que pueden fallar cuando reciben un campo nuevo.
- 2
Selecciona un grupo piloto
Comienza con un área controlada, pocos procesos y consumidores representativos. El piloto debe incluir al menos un ERP, una automatización de agenda y un flujo con revisión humana de plazos.
- 3
Ejecuta ambas versiones cuando sea necesario
Durante la transición, entrega la versión anterior y la nueva para un conjunto controlado de consumidores. Compara conteo de publicaciones, asociaciones, plazos extraídos, duplicados y errores antes de ampliar el alcance.
- 4
Amplía por grupos de riesgo
Migra primero a consumidores con pruebas automatizadas y responsables identificados. Deja para una segunda etapa las conexiones manuales o de alto impacto, siempre con soporte y un procedimiento claro de reversión.
- 5
Define criterios de éxito
No uses solamente disponibilidad técnica. Mide publicaciones asociadas correctamente, tiempos de entrega, tareas creadas, alertas procesadas, errores de esquema y cantidad de revisiones manuales generadas por la migración.
- 6
Retira la versión anterior con evidencia
Desactiva una versión únicamente después de confirmar que no existen consumidores activos o que todos aceptaron la migración. Conserva registros y un mecanismo de recuperación para incidentes posteriores.
Errores frecuentes al versionar una API jurídica
El primer error es considerar que agregar un campo nunca puede causar problemas. Algunos consumidores rechazan propiedades desconocidas, tienen validaciones rígidas o convierten el objeto completo a una estructura interna con reglas no documentadas.
Otro problema es cambiar el significado sin cambiar el nombre. Si prazo_identificado empieza a incluir fechas sugeridas por un modelo de lenguaje además de plazos expresos del tribunal, el consumidor debe distinguir ambos orígenes y conocer el nivel de confianza asociado.
También es arriesgado usar solamente pruebas unitarias del proveedor. Estas pruebas confirman que el servicio funciona según su propia lógica, pero no demuestran que un ERP, un conector MCP o una automatización de agenda pueda interpretar la respuesta sin pérdida de información.
La ausencia de datos de producción anonimizado es otra fuente de regresiones. Los diarios pueden contener variaciones de formato, documentos faltantes y publicaciones repetidas que no aparecen en ejemplos preparados manualmente. Un conjunto de simulaciones realistas revela problemas antes de que lleguen al equipo jurídico.
Finalmente, muchas organizaciones no establecen quién decide sobre la compatibilidad. El contrato necesita un propietario técnico y uno operativo. La tecnología valida la estructura, mientras que el área jurídica confirma que el cambio no altera la identificación del proceso, la lectura de fechas ni la gestión de plazos.
Preguntas Frecuentes
¿Qué es un contrato de API en una integración jurídica?▼
Es la definición formal de cómo dos sistemas intercambian información. Describe rutas, campos, tipos de datos, valores obligatorios, errores, autenticación y reglas de actualización. En una integración jurídica, también debe explicar cómo se identifican las publicaciones, cómo se relacionan con los procesos y qué datos pueden utilizarse para generar tareas o plazos.
¿Cómo versionar una API de publicaciones sin interrumpir mi ERP?▼
Primero identifica la versión que utiliza cada consumidor y clasifica el cambio como compatible o incompatible. Después, conserva los campos anteriores durante una ventana de transición, publica la nueva versión y prueba ambas con respuestas representativas. Retira la versión antigua solamente cuando las métricas y los registros confirmen que los consumidores fueron migrados.
¿Cambiar el nombre de un campo siempre es un cambio incompatible?▼
En la mayoría de los casos, sí, porque el consumidor deja de encontrar la propiedad que esperaba. La práctica más segura es agregar el nuevo nombre, mantener temporalmente el anterior y documentar la equivalencia. También debes revisar transformaciones, filtros, informes y reglas de negocio que dependan del nombre original.
¿Qué pruebas debo ejecutar antes de cambiar un campo del feed de publicaciones?▼
Ejecuta pruebas de esquema, compatibilidad, mapeo, idempotencia, paginación, errores y orden de eventos. Añade ejemplos con procesos de distintas instancias, documentos ausentes, textos extensos y valores de baja confianza. Si utilizas MCP o modelos de lenguaje, comprueba que las respuestas sigan conservando el contexto del proceso y la fuente del plazo.
¿Cómo probar una API judicial si los diarios cambian de formato?▼
Crea simulaciones basadas en variaciones observadas en los diarios y actualízalas cuando aparezcan nuevos patrones. Incluye procesos con diferentes formatos, movimientos repetidos, publicaciones sin documentos, nombres con acentos y fechas en situaciones límite. Las simulaciones no reemplazan la supervisión de producción, pero permiten detectar regresiones antes del despliegue.
¿Cómo comunicar un cambio incompatible a varios despachos y corresponsales?▼
Envía una comunicación con la versión afectada, ejemplos antes y después, impacto, acciones requeridas, fecha de disponibilidad y fecha de retiro. Mantén un registro de cambios y confirma qué consumidores completaron las pruebas. Cuando existan equipos externos, ofrece una colección de solicitudes o un entorno de validación para que puedan comprobar la migración.
¿Qué papel cumple la confianza de extracción en una API de publicaciones?▼
El campo confianca_extracao puede ayudar a distinguir datos que requieren revisión humana de aquellos que cumplen un umbral operativo. Su escala, tipo y significado deben estar documentados porque un cambio de 0 a 1 hacia 0 a 100 puede alterar las reglas del ERP. Además, conviene conservar el texto original y la fuente para que el abogado pueda verificar el plazo identificado.
¿Cómo evitar duplicados cuando una publicación se entrega nuevamente?▼
Utiliza un identificador estable de la publicación y define la idempotencia en el contrato. El sistema receptor debe reconocer que una segunda entrega puede ser un reintento, no un nuevo evento, y evitar crear otra tarea o alerta. También conviene registrar el estado de recepción, procesamiento y asociación para investigar diferencias entre sistemas.