Versionado

Dos niveles de versión

• Versión mayor en la ruta: /v1. Cambia solo si cambia la forma general de la API.
• Versiones fechadas dentro de v1, elegidas con el header Kuida-Version. Cada cambio incompatible sale con una fecha nueva.

Versión vigente

La versión vigente es 2026-09-28. Versiones soportadas: 2026-09-28.

El header Kuida-Version

Sin header, cada pedido se responde con la versión vigente. Con el header, con la versión pedida. Toda respuesta indica en su propio header Kuida-Version con qué versión se armó.

curl https://www.kuida.ar/api/v1/account \
  -H "Authorization: Bearer kd_test_…" \
  -H "Kuida-Version: 2026-09-28"

Cada SDK fija la versión con la que fue construido y la envía en todos los pedidos; se puede cambiar con la opción apiVersion del cliente. En una integración sin SDK, conviene fijar el header para que un cambio de versión vigente no altere las respuestas. Una versión inexistente responde 400 con api_version_invalid.

Qué cambia sin versión nueva

Agregar una operación

Rompe (versión fechada nueva)Quitar o renombrar un campo

Agregar un campo a una respuesta

Rompe (versión fechada nueva)Cambiar el tipo de un campo

Agregar un parámetro opcional

Rompe (versión fechada nueva)Volver obligatorio un parámetro

Agregar un tipo de evento o de webhook

Rompe (versión fechada nueva)Cambiar el significado de un estado

Agregar un valor a un enum de salida

Por eso una integración tiene que ignorar los campos que no conoce y tolerar valores nuevos en los enums de las respuestas. Los SDKs ya lo hacen. Una versión se retira con aviso previo, nunca sin anunciarlo.