Versionado y compatibilidad

Versión actual

La versión vigente es v1, accesible bajo el prefijo /api/v1/. Toda la documentación de esta sección se refiere a v1.

Política de compatibilidad

Dentro de una misma versión mayor (v1.x), garantizamos:

Cambios que son compatibles (no rompen integraciones)

• Agregar nuevos endpoints.
• Agregar nuevos campos opcionales en requests.
• Agregar nuevos campos en responses: su cliente debe ignorar campos que no conoce.
• Agregar nuevos valores a un enum existente: su cliente debe manejar el caso "valor desconocido" sin fallar.
• Agregar nuevos catálogos.
• Cambiar el orden de propiedades en respuestas JSON.
• Marcar un campo previamente requerido como opcional.
• Cambios internos en mensajes de error humanos (el campo message): no programes contra el texto literal, sólo contra el status code y el campo errors.

Cambios que requieren coordinación previa (breaking)

Los siguientes cambios sólo ocurren en una nueva versión mayor (v2) y se anuncian con al menos 90 días de aviso:

• Renombrar o eliminar un endpoint.
• Renombrar o eliminar un campo en un request o response.
• Cambiar el tipo de un campo (ej. string → integer).
• Cambiar el formato de un campo (ej. fecha ISO 8601 → epoch unix).
• Marcar un campo previamente opcional como requerido.
• Eliminar valores de un enum existente.
• Cambiar el comportamiento de un endpoint sin cambiar su shape.

Contrato canónico

La referencia canónica del contrato v1 es la Referencia de la API, generada desde la especificación OpenAPI (descargable en /openapi.yaml).

Contrato de campos per-organización

El contrato de campos requerido por cada organización (lo que valida el bulk POST) es independiente del versionado de la API. Refleja la configuración actual de Configuración → Campos configurables y puede cambiar en cualquier momento sin preaviso (es una operación administrativa interna).

Para tolerar estos cambios:

• Coordiná con el área de cumplimiento antes de poner en producción la integración, para confirmar la lista de campos requeridos.
• Implementá el cliente con un enum-set extensible: si aparece un valor nuevo en, por ejemplo, marital_status, debería caer a un caso "otros" sin romper.
• Cuando un nuevo despliegue de Campos configurables exija un campo nuevo, alertá a su equipo de operaciones para que cubra ese campo en la captura. El bulk POST devolverá 422 con el campo faltante en errors.

Cambios anunciados

Cuando se acerque una nueva versión mayor, los detalles aparecerán en este manual con suficiente antelación. Mientras no haya una sección "v2" en la navegación, no hay cambios breaking en curso.

Reportar incompatibilidades

Si encontrás un comportamiento que parece violar esta política (ej. un campo desapareció sin aviso), reportalo al área de soporte con:

• URL del endpoint y método HTTP.
• Request body (sin el token).
• Response body y status code recibido.
• Versión esperada del comportamiento.