Saltar al contenido

Referencia de API

Links

Un link es la conexión entre tu organización y las cuentas de un titular en un banco. Se crea cuando la persona termina el widget; desde la API puedes consultarlo, pedir una sincronización o revocarlo. Campos en Objetos › Link.

GET/v1/links

Requiere llave secret. URL completa: https://api.banky.cl/v1/links

Devuelve los links del modo de la llave, del más reciente al más antiguo. Incluye los revocados (con status disconnected).

Parámetros de consulta

limitinteger
Cantidad de elementos por página, entre 1 y 100. Por defecto 50.
starting_afterstring
Cursor: el id del último elemento de la página anterior. Devuelve los elementos que vienen después.

Ejemplo de petición

curl "https://api.banky.cl/v1/links?limit=20" \
  -H "Authorization: Bearer $BANKY_SECRET_KEY"

Respuesta

application/json

200
{
  "object": "list",
  "data": [
    {
      "id": "link_9f2c41ab7e05d318",
      "object": "link",
      "institution": {
        "id": "sandbox",
        "name": "Banco de Prueba"
      },
      "holder_type": "business",
      "holder_name": "Panadería La Espiga SpA",
      "holder_id": "76123874-4",
      "status": "active",
      "status_message": null,
      "mode": "test",
      "allow_mcp": true,
      "last_refreshed_at": "2026-11-18T14:02:11.482Z",
      "next_refresh_at": "2026-11-19T14:02:11.482Z",
      "created_at": "2026-11-18T14:02:09.917Z"
    }
  ],
  "has_more": false
}

Errores propios de este endpoint

HTTPcodeCuándo ocurre
400invalid_limitlimit no es un entero entre 1 y 100.
400invalid_cursorstarting_after no es el id de un link de esta lista.
GET/v1/links/{id}

Requiere llave secret. URL completa: https://api.banky.cl/v1/links/{id}

Úsalo para revisar el estado de una conexión: status, status_message y las fechas de la última y la próxima sincronización.

Parámetros de ruta

idstringobligatorio
Id del link, por ejemplo link_9f2c41ab7e05d318.

Ejemplo de petición

curl "https://api.banky.cl/v1/links/link_9f2c41ab7e05d318" \
  -H "Authorization: Bearer $BANKY_SECRET_KEY"

Respuesta

application/json

200
{
  "id": "link_9f2c41ab7e05d318",
  "object": "link",
  "institution": {
    "id": "sandbox",
    "name": "Banco de Prueba"
  },
  "holder_type": "business",
  "holder_name": "Panadería La Espiga SpA",
  "holder_id": "76123874-4",
  "status": "active",
  "status_message": null,
  "mode": "test",
  "allow_mcp": true,
  "last_refreshed_at": "2026-11-18T14:02:11.482Z",
  "next_refresh_at": "2026-11-19T14:02:11.482Z",
  "created_at": "2026-11-18T14:02:09.917Z"
}

Errores propios de este endpoint

HTTPcodeCuándo ocurre
404resource_missingNo existe un link con ese id en tu organización y en el modo de la llave.
POST/v1/links/{id}/refresh

Requiere llave secret. URL completa: https://api.banky.cl/v1/links/{id}/refresh

Pide una sincronización inmediata y responde 202 sin esperar al banco, que puede tardar más de un minuto. Cuando termina recibes el webhook link.refreshed y, si hubo movimientos nuevos, movements.new. Si el banco rechaza la clave, recibes link.credentials_invalid o link.action_required.

No necesitas llamarlo para mantener los datos al día: sincronizamos solos cada 6 horas en live y cada 24 horas en test. Si ya hay una sincronización en curso, la nueva solicitud no inicia otra.

Parámetros de ruta

idstringobligatorio
Id del link, por ejemplo link_9f2c41ab7e05d318.

Ejemplo de petición

curl -X POST "https://api.banky.cl/v1/links/link_9f2c41ab7e05d318/refresh" \
  -H "Authorization: Bearer $BANKY_SECRET_KEY"

Respuesta

application/json

202
{
  "id": "link_9f2c41ab7e05d318",
  "object": "link",
  "status": "syncing"
}

Errores propios de este endpoint

HTTPcodeCuándo ocurre
404resource_missingNo existe el link.
409link_disconnectedEl link fue revocado.
409credentials_invalidEl banco rechazó la clave en el último ingreso (status credentials_invalid).
409action_requiredEl banco pide una acción a la persona (status action_required).
DELETE/v1/links/{id}

Requiere llave secret. URL completa: https://api.banky.cl/v1/links/{id}

Revoca la conexión: borra de inmediato las credenciales y el dispositivo de confianza guardados, deja el link en disconnected y envía el webhook link.deleted. No se vuelve a sincronizar.

Las cuentas y movimientos ya leídos se conservan para tu historial y siguen disponibles por API. Responde el link actualizado con deleted: true.

Parámetros de ruta

idstringobligatorio
Id del link, por ejemplo link_9f2c41ab7e05d318.

Ejemplo de petición

curl -X DELETE "https://api.banky.cl/v1/links/link_9f2c41ab7e05d318" \
  -H "Authorization: Bearer $BANKY_SECRET_KEY"

Respuesta

application/json

200
{
  "id": "link_9f2c41ab7e05d318",
  "object": "link",
  "institution": {
    "id": "sandbox",
    "name": "Banco de Prueba"
  },
  "holder_type": "business",
  "holder_name": "Panadería La Espiga SpA",
  "holder_id": "76123874-4",
  "status": "disconnected",
  "status_message": "La conexión fue revocada.",
  "mode": "test",
  "allow_mcp": true,
  "last_refreshed_at": "2026-11-18T14:02:11.482Z",
  "next_refresh_at": null,
  "created_at": "2026-11-18T14:02:09.917Z",
  "deleted": true
}

Errores propios de este endpoint

HTTPcodeCuándo ocurre
404resource_missingNo existe el link.