> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rail.cl/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Conecta una cuenta bancaria y lee movimientos en 5 minutos.

## 1. Obtén tus API keys

1. Ve a [dashboard.rail.cl](https://dashboard.rail.cl) y crea una cuenta.
2. En **Para desarrolladores → API keys**, vas a tener 4 keys:
   * `rail_sk_test_…` — secret key de test
   * `rail_pk_test_…` — publishable key de test
   * `rail_sk_live_…` — secret key de live
   * `rail_pk_live_…` — publishable key de live

<Warning>
  Las `sk_*` van solo en tu backend. Nunca en frontend ni en git.
</Warning>

## 2. Lista los links existentes

Un **link** es la conexión de un usuario tuyo con su banco. Para empezar listamos los que ya existen (al inicio, vacío):

```bash theme={null}
curl https://api.rail.cl/v1/links \
  -H "Authorization: Bearer rail_sk_test_…"
```

Response:

```json theme={null}
[]
```

## 3. Crea tu primer link con el widget

El widget de Rail Connect maneja el flow de credenciales y MFA sin que tu app las vea nunca.

### Backend: emite un widget token

```bash theme={null}
curl https://api.rail.cl/v1/widget_tokens \
  -X POST \
  -H "Authorization: Bearer rail_sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
    "bank_id": "banco_estado"
  }'
```

Response:

```json theme={null}
{
  "object": "widget_token",
  "id": "wt_a1b2c3d4_sec_…",
  "expires_at": "2026-06-03T20:00:00Z"
}
```

<Note>
  Para conectar una **cuenta de empresa**, agrega `"holder_type": "business"` al
  body. El widget pide RUT empresa + RUT persona + clave del portal. Ver
  [Banca empresa](/guides/banca-empresa).
</Note>

### Frontend: abre el widget

```html theme={null}
<script src="https://widget.rail.cl/v1/embed.js"></script>
<script>
  Rail.openWidget({
    token: 'wt_a1b2c3d4_sec_…',
    publishableKey: 'rail_pk_test_…',
    onSuccess: (et) => {
      // Envía el exchange token a tu backend para canjearlo
      fetch('/api/rail-callback', {
        method: 'POST',
        body: JSON.stringify({ exchange_token: et })
      });
    },
  });
</script>
```

### Backend: canjea el exchange token por el link

```bash theme={null}
curl https://api.rail.cl/v1/exchange_tokens/et_… \
  -X POST \
  -H "Authorization: Bearer rail_sk_test_…"
```

Response:

```json theme={null}
{
  "object": "exchange_token",
  "link_id": "link_8a2f4c6e1b9d5037",
  "consumed_at": "2026-06-03T20:01:23Z"
}
```

Guarda `link_id` asociado al usuario en tu DB — es la referencia para leer sus cuentas.

## 4. Lee las cuentas

```bash theme={null}
curl "https://api.rail.cl/v1/accounts?link_id=link_8a2f4c6e1b9d5037" \
  -H "Authorization: Bearer rail_sk_test_…"
```

Response:

```json theme={null}
[
  {
    "object": "account",
    "id": "acc_7d2f3a8c1e9b4502",
    "link_id": "link_8a2f4c6e1b9d5037",
    "name": "CuentaRUT",
    "type": "checking",
    "currency": "CLP",
    "balance": {
      "available": 500000,
      "current": 500000
    },
    "last_4": "5678"
  }
]
```

## 5. Lee los movimientos

```bash theme={null}
curl "https://api.rail.cl/v1/accounts/acc_7d2f3a8c1e9b4502/movements?per_page=10" \
  -H "Authorization: Bearer rail_sk_test_…"
```

Response (array de movimientos):

```json theme={null}
[
  {
    "object": "movement",
    "id": "mov_6c8d1f3a9e5b2074",
    "amount": -30000,
    "currency": "CLP",
    "type": "card_payment",
    "description": "MERCADOLIBRE CL",
    "post_date": "2026-06-01T04:00:00+00:00"
  }
]
```

<Note>
  Los amounts son **bigint en minor units**. CLP no tiene centavos → el valor entero es directamente pesos. El signo es parte del valor (negativo = egreso).
</Note>

## Próximos pasos

<CardGroup cols={2}>
  <Card title="Refresh Intents" icon="rotate" href="/concepts/refresh-intents">
    Cómo forzar un sync con MFA async.
  </Card>

  <Card title="Webhooks" icon="bell" href="/guides/webhooks">
    Recibe eventos en tiempo real (link.refreshed, etc).
  </Card>
</CardGroup>