Saltar al contenido

Primeros pasos

Inicio rápido

En esta guía conectas una cuenta del Banco de Prueba y lees sus movimientos. Todo ocurre en modo test, con datos ficticios, así que puedes repetirla las veces que quieras.

Necesitas:

  • Acceso al panel de Banky (entras con tu cuenta de Google).
  • Un servidor propio donde guardar la llave secret. Los ejemplos usan Node.js 18 o superior, pero cualquier lenguaje sirve.

Crea una llave de API

En el panel, deja apagado el interruptor Modo producción (así trabajas en modo test), entra a API keys y crea una llave secret. Se muestra una sola vez: cópiala y guárdala como variable de entorno en tu servidor.

.env

BANKY_SECRET_KEY=banky_sk_test_…

Cada vez que una persona va a conectar su banco, tu servidor crea un link token. Indica si la cuenta es de empresa (business) o de persona (individual) y, si quieres, el nombre que verá la persona en el widget.

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"
  }'

Respuesta

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

En una aplicación real lo normal es exponer un endpoint propio que devuelva el token a tu frontend:

servidor.js

// servidor.js (Node.js 18 o superior, con Express)
import express from "express";

const app = express();
app.use(express.json());

// Tu frontend llama a este endpoint para obtener un link token nuevo cada vez que abre el widget.
app.post("/api/link-token", async (req, res) => {
  const respuesta = await fetch("https://api.banky.cl/v1/link_tokens", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.BANKY_SECRET_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ holder_type: "business", client_name: "Contable Austral" }),
  });
  if (!respuesta.ok) return res.status(502).json({ error: "No se pudo crear el link token" });
  const { link_token } = await respuesta.json();
  res.json({ link_token });
});

app.listen(3000);

Abre el widget

Carga connect.js en tu página y abre el widget con el token. El widget se muestra en un modal sobre tu aplicación; la persona elige su banco e ingresa sus credenciales.

index.html

<button id="conectar">Conectar mi banco</button>

<script src="https://banky.cl/connect.js"></script>
<script>
  document.getElementById("conectar").addEventListener("click", async () => {
    const { link_token } = await fetch("/api/link-token", { method: "POST" }).then((r) => r.json());

    Banky.open({
      token: link_token,
      onSuccess: (link) => {
        // Guarda link.id junto al usuario o la empresa en tu base de datos.
        fetch("/api/conexiones", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({ link_id: link.id }),
        });
      },
      onExit: (error) => {
        if (error) console.warn("La conexión no se completó:", error);
      },
    });
  });
</script>

En modo test, elige Banco de Prueba e ingresa el RUT 11.111.111-1 con la clave banky. Para una cuenta de empresa, el widget pide además el RUT de la empresa: usa cualquier RUT válido, como 76.123.874-4. En Modo test están todas las credenciales de prueba.

Cuando la conexión termina, onSuccess recibe el objeto link. Guarda su id: lo necesitas para leer los datos. Las cuentas y los últimos 90 días de movimientos ya quedaron leídos en ese momento.

link

{
  "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"
}

Si configuraste webhooks, además recibes link.created y, si hubo movimientos, movements.new. Usa los webhooks como fuente de verdad: onSuccess depende de que la persona mantenga abierta tu página.

Lee cuentas y movimientos

Lista las cuentas de la conexión:

curl "https://api.banky.cl/v1/accounts?link_id=link_9f2c41ab7e05d318" \
  -H "Authorization: Bearer $BANKY_SECRET_KEY"

Respuesta

200
{
  "object": "list",
  "data": [
    {
      "id": "acc_3f9a1c0e5b7d2468",
      "object": "account",
      "link_id": "link_9f2c41ab7e05d318",
      "number": "0012785975",
      "name": "Cuenta Corriente",
      "type": "checking_account",
      "currency": "CLP",
      "balance": {
        "available": 26593700,
        "current": 26638700
      },
      "refreshed_at": "2026-11-18T14:02:11.204Z"
    }
  ],
  "has_more": false
}

Y luego los movimientos de una cuenta, del más nuevo al más antiguo:

curl "https://api.banky.cl/v1/accounts/acc_3f9a1c0e5b7d2468/movements?since=2026-11-01&limit=50" \
  -H "Authorization: Bearer $BANKY_SECRET_KEY"

Respuesta

200
{
  "object": "list",
  "data": [
    {
      "id": "mov_e41b9c07a2d85f36",
      "object": "movement",
      "account_id": "acc_3f9a1c0e5b7d2468",
      "amount": 1315000,
      "currency": "CLP",
      "type": "inflow",
      "description": "Pago de factura de Constructora Valle Central SpA",
      "bank_description": "TRASPASO DE: CONSTRUCTORA VALLE CENTRAL SPA",
      "post_date": "2026-11-18",
      "transaction_date": "2026-11-18",
      "counterparty": {
        "name": "Constructora Valle Central SpA",
        "id": "76287005-3"
      },
      "reference_id": "479249273"
    }
  ],
  "has_more": true
}

Los montos vienen en pesos enteros: positivos para abonos y negativos para cargos. Si has_more es true, pide la página siguiente con starting_after (ver Paginación).

Pasar a producción

  • Crea una llave secret live y cámbiala en tu servidor. El código no cambia.
  • Registra un endpoint de webhooks live y verifica la firma de cada evento.
  • Revisa qué bancos están disponibles en Instituciones: hoy en live se conecta BCI Empresas.
  • Maneja los estados credentials_invalid y action_required: en esos casos la persona debe volver a conectar su cuenta con el widget.