Saltar al contenido

Referencia de API

Link tokens

Un link token autoriza a abrir el widget una vez, para una persona. Lo crea tu servidor justo antes de abrir el widget y vence a los 30 minutos o cuando se usa para crear una conexión.

POST/v1/link_tokens

Acepta llave secret o publishable. URL completa: https://api.banky.cl/v1/link_tokens

Responde 201 con el token (lt_ seguido de 48 caracteres hexadecimales), su fecha de vencimiento y el modo, que es el de la llave usada.

Cuerpo (JSON)

holder_typestringobligatorio
Tipo de titular de la cuenta que se va a conectar. Define qué bancos y qué formulario muestra el widget.individualbusiness
client_namestring
Nombre que ve la persona en el widget («Contable Austral se conectará con tu banco»). Hasta 80 caracteres. Si no lo envías, se usa el nombre de tu organización.
allow_mcpboolean
Si la conexión podrá leerse desde el servidor MCP. Por defecto false. Puedes cambiarlo después desde el panel.
webhook_urlstring
URL HTTPS pública que recibirá los eventos de esta conexión, además de tus endpoints registrados. Solo puertos 443 u 8443, sin usuario ni clave en la URL, hasta 2048 caracteres. Los eventos se firman con el secreto de webhooks de links que muestra el panel (ver Webhooks). Requiere llave secret.

Ejemplo de petición

curl -X POST "https://api.banky.cl/v1/link_tokens" \
  -H "Authorization: Bearer $BANKY_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "holder_type": "business",
    "client_name": "Contable Austral",
    "allow_mcp": true,
    "webhook_url": "https://contableaustral.cl/webhooks/banco"
  }'

Respuesta

application/json

201
{
  "object": "link_token",
  "link_token": "lt_7c1e9a4f2b8d6035e1a7c94b2f0d8e6a1c3b5d7f9e2a4c6b",
  "expires_at": "2026-11-18T14:31:52.104Z",
  "mode": "test"
}

Errores propios de este endpoint

HTTPcodeCuándo ocurre
400invalid_holder_typeFalta holder_type o no es individual ni business.
400invalid_parameterUn campo tiene el tipo incorrecto o supera su largo máximo.
400invalid_webhook_urlwebhook_url no es HTTPS, no es pública o usa un puerto no permitido.
400invalid_bodyEl cuerpo no es un objeto JSON válido.
403secret_key_requiredSe envió webhook_url con una llave publishable.
413body_too_largeEl cuerpo supera 32 KB.

Navegador

// Solo si no puedes crear el token en tu servidor. Usa la llave publishable, nunca la secret.
const respuesta = await fetch("https://api.banky.cl/v1/link_tokens", {
  method: "POST",
  headers: {
    Authorization: "Bearer banky_pk_test_…",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ holder_type: "individual" }),
});
const { link_token } = await respuesta.json();

Con el token, abre el widget como se explica en Widget de conexión.