Versionado

Cómo se fija

curl -sS "$BELFORT_API/v1/persons"   -H "Authorization: Bearer $BELFORT_KEY"   -H "Belfort-Version: 2026-07-30"

Toda respuesta ecoa la versión con la que se atendió, la hayas pedido o no. Así puedes comprobar en cualquier momento contra qué contrato está hablando tu integración, sin depender de lo que crees que configuraste.

Si mandas una versión que no existe, recibes 400 UNSUPPORTED_API_VERSION, y el error no repite la versión que pediste: eco de entrada en un mensaje de error es cómo se cuelan payloads ajenos en los registros de terceros.

Por qué una fecha

Un número mayor obliga a decidir qué cambio "merece" subirlo, y esa discusión siempre acaba metiendo un cambio incompatible en una versión menor. Una fecha no admite grados: o tu integración apunta al 15 de marzo o apunta a otro día. Y dice algo útil por sí sola — cuánto hace que no actualizas.

Qué puede cambiar sin avisar

Estos cambios son aditivos y pueden llegar en cualquier momento. Tu cliente tiene que tolerarlos:

• Campos nuevos en una respuesta.
• Valores nuevos en un enum de respuesta. Los que pueden crecer están marcados con x-extensible-enum en el contrato: trátalos con un caso por defecto, no con un switch exhaustivo.
• Códigos de error nuevos. El catálogo es append-only, pero crece.
• Endpoints nuevos, y parámetros opcionales nuevos.

Lo que no cambia sin una versión nueva: quitar o renombrar un campo, cambiar el tipo de uno, quitar un endpoint o un valor de enum, o volver obligatorio algo que era opcional.

Si no mandas la cabecera

Se atiende con la versión vigente. Va bien para explorar, y mal para producción: el día que salga una versión nueva, tu integración cambia de contrato sin que tú hayas tocado nada. Fíjala.