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.
Listar links
/v1/linksRequiere 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
iddel ú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
| HTTP | code | Cuándo ocurre |
|---|---|---|
| 400 | invalid_limit | limit no es un entero entre 1 y 100. |
| 400 | invalid_cursor | starting_after no es el id de un link de esta lista. |
Obtener un link
/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
| HTTP | code | Cuándo ocurre |
|---|---|---|
| 404 | resource_missing | No existe un link con ese id en tu organización y en el modo de la llave. |
Actualizar un link
/v1/links/{id}/refreshRequiere 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
| HTTP | code | Cuándo ocurre |
|---|---|---|
| 404 | resource_missing | No existe el link. |
| 409 | link_disconnected | El link fue revocado. |
| 409 | credentials_invalid | El banco rechazó la clave en el último ingreso (status credentials_invalid). |
| 409 | action_required | El banco pide una acción a la persona (status action_required). |
Eliminar un link
/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
| HTTP | code | Cuándo ocurre |
|---|---|---|
| 404 | resource_missing | No existe el link. |