Versionamiento

Varios objetos de la API cambian de forma con el tiempo. Para que esos cambios no rompan tu integración, Toku versiona por fecha: una misma fecha siempre devuelve la misma forma del objeto, tanto en las respuestas de la API como en los payloads de los webhooks.

No hay números de versión. La fecha es el identificador.

Cómo se resuelve una fecha

Toku publica una versión nueva sólo el día en que la forma de un objeto cambia. Tú envías una fecha cualquiera y se aplica la última versión publicada anterior o igual a esa fecha.

Tomemos el objeto Invoice, que hoy tiene cuatro versiones publicadas:

Con esas versiones, la fecha que envías resuelve así:

Una fecha nunca deja de funcionar: cuando se publica una versión nueva, las fechas anteriores siguen resolviendo igual que siempre.

Endpoints

Envía el header x-api-version con una fecha en formato AAAA-MM-DD.

curl https://api.trytoku.com/invoices/in_9K0bTq3xR7yA2sVpLmZ4wE1nHdJf6UcQ \
  -H "x-api-key: $TOKU_API_KEY" \
  -H "x-api-version: 2026-01-20"

Esa fecha resuelve a la versión 2025-11-10 del Invoice, así que la respuesta trae la forma base más lo que agregaron 2025-09-03 y 2025-11-10:

{
  "id": "in_9K0bTq3xR7yA2sVpLmZ4wE1nHdJf6UcQ",
  "customer": "cus_ejC08yLqOWoFhVx4Fx42E3IR9X50tNx2",
  "subscription": "sub_Y_EgOXMloD5-IJn6d9S2IxkNvp9p0iiP",
  "product_id": "plan-oro-marzo-2025",
  "invoice_external_id": "F-2025-000123",
  "amount": 19990,
  "currency_code": "CLP",
  "due_date": "2025-03-10",
  "is_paid": false,
  "is_void": false,
  "status": "unpaid",
  "paid_amount": 0,
  "expiration_date": "2025-04-10T00:00:00Z",
  "expiration_action": "VOID",
  "max_collection_attempts": 3,
  "remaining_collection_attempts": 3,
  "refund_data": null
}

Fíjate en que no trae account: ese campo llegó en 2026-06-12, y la fecha enviada es anterior. Repitiendo la misma petición con x-api-version: 2026-06-12 —o cualquier fecha posterior— la respuesta lo incluye.

❗️

El formato debe ser exactamente AAAA-MM-DD

2026-1-20, 20/01/2026 o una fecha con hora son rechazados. Envía siempre mes y día con dos dígitos.

Cada objeto avanza por su cuenta

Una fecha no es "la versión 3 de la API": es un punto en el tiempo. Cada objeto tiene su propio historial de versiones, así que una misma fecha resuelve a versiones publicadas en momentos distintos según el objeto.

Con x-api-version: 2026-01-20, por ejemplo:

Las cuatro son "la última versión anterior o igual al 20 de enero de 2026" para su propio objeto. Por eso basta una sola fecha para fijar toda tu integración: cubre a la vez todos los objetos que consumas, sin que tengas que seguir el historial de cada uno.

No todos los objetos están versionados. Los que nunca cambiaron de forma tienen una sola versión, y la fecha que envíes no los afecta.

Si no envías el header

Recomendamos enviarlo siempre.

Sin x-api-version la versión aplicada es implícita y no es la misma en todos los recursos: en la mayoría se deriva de la fecha en que se creó tu organización, y en los recursos de facturación se usa la forma base. Dos organizaciones pueden entonces recibir formas distintas para la misma petición, y tu integración queda atada a un valor que nunca elegiste.

Fija una fecha explícita y súbela cuando quieras adoptar campos nuevos.

Webhooks

Un webhook no puede mandar headers: la versión vive en la configuración del Webhook Endpoint, en el campo webhook_version. Esa fecha se resuelve con la misma regla y determina la forma del objeto que viaja en cada evento.

Puedes fijarla al crear el endpoint:

{
  "url": "https://example.com/webhooks/toku",
  "enabled_events": ["transaction.success", "transaction.failed"],
  "webhook_version": "2026-01-20"
}

Si omites webhook_version, queda fijada en la fecha de creación del endpoint. En ambos casos queda congelada: cuando se publica una versión nueva de un objeto, los payloads que ya estás recibiendo no cambian.

Para adoptar una versión nueva, actualiza el endpoint con la fecha que quieras. El cambio aplica a los eventos enviados desde ese momento.

{
  "webhook_version": "2026-06-12"
}

La versión vigente de cada endpoint se ve en su campo webhook_version al consultarlo. Ver Objeto Webhook Endpoint.

Qué versiones existen y qué trae cada una

El selector de versiones, arriba en esta referencia, lista todas las fechas publicadas. Al elegir una, la referencia completa —incluidas las páginas «Objeto …» de cada recurso— pasa a mostrar exactamente los campos que esa fecha retorna.

Para el detalle campo a campo, entra a la página del objeto que te interese: Objeto Invoice, Objeto Transaction, Objeto Customer, Objeto Payment, Objeto Subscription, Objeto Checkout Session.