Versionado

La API actual es v1, montada en /api/v1/*. La forma de cada response es un contrato — lo cuidamos como tal.

Cambios "seguros" (no rompen tu integración)

Hacemos estos sin previo aviso:

• Agregar campos a una respuesta. Si llega created_by en una próxima iteración de Customer, tu código no se debe romper — usa los campos que ya conoces y ignora el resto.
• Agregar endpoints. Una nueva ruta POST /api/v1/refunds no afecta tus calls existentes.
• Agregar valores nuevos a un enum. Si hoy lead.status puede ser new|in_progress|won|lost, mañana puede tener disqualified también. Si tu UI tiene un switch case, el default debe manejarlo razonablemente.

Cambios "que rompen" (requieren v2)

NO los haremos en v1:

• Renombrar un campo.
• Eliminar un campo.
• Cambiar el tipo de un campo (de string a integer, etc.).
• Cambiar el formato de un campo (ej. de centavos a unidades decimales).
• Cambiar el shape de un error (error codes son estables).
• Cambiar la semántica de un endpoint.

Cualquiera de esos requeriría un namespace nuevo (/api/v2/). Cuando llegue, te avisaremos vía email con tiempo de gracia antes de que v1 se deprecate.

Período de deprecation

Cuando v2 salga, v1 seguirá funcionando mínimo 12 meses en paralelo. Te enviaremos:

• Un email inicial al lanzamiento de v2.
• Recordatorios a los 6 y 3 meses antes del cutoff.
• Un header Sunset en las respuestas de v1 con la fecha exacta de fin de servicio.

Forward compat en tu código

Algunos hábitos que te van a evitar dolor:

• Lee campos por nombre, no por posición (los responses son objetos JSON, no arrays — esto ya está bien).
• No valides la lista completa de campos del response. Solo verifica que estén los que usas.
• Maneja valores desconocidos en enums con un fallback explícito en lugar de un crash.
• Loguea respuestas inesperadas en lugar de descartarlas — facilita identificar cuando agregamos algo nuevo.

¿Beta features?

Si en algún momento exponemos algo en preview, lo marcaremos así:

• Header X-Finova-Beta: <feature-name> en las respuestas relacionadas.
• Documentación con un badge (beta) en el sidebar.
• Aviso explícito de que puede cambiar antes de GA.

Si NO ves ninguno de esos marcadores, el endpoint es estable.