Versiones

Tu integración ve la forma del contrato que había el día que emitiste tu credencial, y no cambia sola. Ésa es toda la promesa de esta página. Lo demás es cómo comprobarlo y cómo moverte cuando quieras.

La ruta no es la versión

/v1 identifica la API. La fecha identifica el contrato. Son cosas distintas a propósito:

• Si la versión viviera en la ruta, adoptar un cambio de un solo campo te obligaría a reescribir todas tus URL.
• Con fechas, cada cambio incompatible se adopta por separado. No hay una migración grande que nadie quiere hacer.

Es el mismo modelo de Stripe y de GitHub, y por el mismo motivo.

Cómo se decide qué versión te aplica

En este orden, y el primero que exista gana:

Orden	De dónde sale
1	La cabecera Binkio-Version de tu petición.
2	La versión fijada en tu credencial cuando se emitió. No cambia sola.
3	La actual — sólo donde no hay credencial (el checkout del pagador).

Toda respuesta te dice con cuál se construyó, la hayas pedido o no:

HTTP/1.1 200 OK
Binkio-Version: 2026-09-09
X-Request-Id: req_9f2a4c8b7e1d3a5f

No hace falta que la guardes en ningún sitio ni que leas nada para saber en qué versión estás: mírala en cualquier respuesta.

Probar una versión nueva sin arriesgar nada

Manda la cabecera en una llamada suelta. No toca la configuración de tu credencial ni afecta al resto de tu tráfico:

curl https://api.binkio.com/v1/payment_links/PL-9C2X-4T7B-1KD8 \
  -H "Authorization: Bearer bk_live_sec_…" \
  -H "Binkio-Version: 2026-09-09"

Cuando hayas comprobado que tu código aguanta la versión nueva, pídenos que subamos la de tu credencial. Es un acto explícito tuyo, nunca un efecto de uno de nuestros despliegues.

:::tip Rotar tu secreto NO cambia tu versión Si rotas la credencial —normalmente porque el secreto se filtró— la sucesora hereda la versión de la anterior. Rotar es una operación de seguridad; que además te cambiara la forma de las respuestas, y a las tres de la mañana, es exactamente lo que este mecanismo existe para evitar. :::

Una versión que no existe se rechaza

No caemos en silencio a la actual:

{
  "error": {
    "type": "invalid_request",
    "code": "unknown_api_version",
    "message": "La versión \"2026-9-09\" no existe. Versiones válidas: 2026-09-09.",
    "param": "Binkio-Version",
    "request_id": "req_9f2a4c8b7e1d3a5f"
  }
}

Es deliberado. Aceptar un dedazo y aplicar «la de siempre» convierte un error de tecleo en «mi integración cambió de comportamiento sola», que es el fallo del que todo esto te protege. El mensaje enumera las válidas, así que se arregla sin salir de la terminal.

Catálogo

Versión	Qué trae
2026-09-09	Línea de salida del contrato versionado. Incluye los eventos de enlace de pago con code y amount alineados con la API REST, y el neto del comercio en net_amount / net_currency.

Toda credencial emitida antes de esa fecha se considera fijada ahí: es exactamente el contrato que estaba viendo.

El catálogo vivo va también en la portada de la referencia OpenAPI, y el propio documento lleva la versión en info.version — útil si generas tu cliente en CI y quieres dejar constancia de contra qué forma se generó.

Qué cuenta como cambio de versión

Publicamos una versión nueva cuando algo puede romper una integración que ya funciona:

• Quitar un campo de una respuesta, o cambiar su tipo.
• Cambiar el significado de un campo — aunque el nombre y el tipo se queden igual. Es el más peligroso porque no se ve compilando.
• Volver obligatorio un campo de entrada que era opcional.
• Quitar un valor de una enumeración, o cambiar el código de un error existente.

No publicamos versión nueva por añadir cosas: un campo nuevo en una respuesta, un endpoint nuevo, un valor nuevo en una enumeración de salida, o un código de error nuevo para un caso que antes caía en uno genérico.

:::caution Por eso tu cliente tiene que tolerar campos que no conoce Como añadir campos no cambia la versión, tu deserializador no puede fallar al encontrarse uno que no esperaba. Si usas un cliente generado, comprueba que no esté configurado en modo estricto; si lo escribes a mano, ignora lo que no conozcas en vez de rechazar la respuesta.

Lo mismo con las enumeraciones: puede aparecer un status o un method nuevo. Trátalos con una rama por defecto que no reviente. :::