# Inicio rápido (/docs/quickstart)

En esta guía haces en sandbox el recorrido completo: te autenticas, ves qué tienes disponible, abres un cobro, simulas el depósito del pagador y ves el dinero en tu saldo.

<Callout title="Antes de empezar">
Necesitas una clave de **sandbox** (`psp_test_…`). Caibo emite las claves al abrir tu cuenta; si aún no tienes una, pídela a tu contacto en Caibo. La clave se muestra una sola vez: guárdala en tu gestor de secretos, nunca en el código.
</Callout>

<Steps>
<Step>
### Configura tu clave [#configura-tu-clave]

```bash
export CAIBO_API_KEY="psp_test_..."
export CAIBO_API="https://api-sandbox.caibopay.app"
```
</Step>

<Step>
### Comprueba la conexión [#comprueba-la-conexión]

<Endpoint method="GET" path="/v1/account" href="/docs/api/account/get-account" />

```bash
curl "$CAIBO_API/v1/account" \
  -H "Authorization: Bearer $CAIBO_API_KEY"
```

```json
{
  "id": "acct_01m3sg8r0000000000000000",
  "name": "Mi Empresa",
  "status": "active",
  "environment": "sandbox",
  "primary_treasury_asset": "USDT",
  "credential": {
    "type": "api_key",
    "id": "key_01m3sg8s0000000000000000",
    "prefix": "abc123def456",
    "scopes": ["read", "write"],
    "created_at": "2026-10-18T12:00:00Z"
  },
  "created_at": "2026-10-01T09:00:00Z"
}
```

`environment` confirma dónde estás. `scopes` dice qué puede hacer la clave: `read` para consultar, `write` para crear y mover dinero.
</Step>

<Step>
### Mira qué puedes cobrar [#mira-qué-puedes-cobrar]

<Endpoint method="GET" path="/v1/capabilities" href="/docs/api/capabilities/list-capabilities" />

```bash
curl "$CAIBO_API/v1/capabilities?product=payin" \
  -H "Authorization: Bearer $CAIBO_API_KEY"
```

Cada elemento describe algo que puedes hacer: `method`, `currency`, `country`, los campos que pide, cómo se cobra (`collection`) y si está disponible ahora para ti (`available`). Ver [Qué puedes hacer](/docs/capabilities).
</Step>

<Step>
### Registra tu webhook [#registra-tu-webhook]

Así te enteras de cada cobro sin tener que consultar. La URL debe ser `https` y pública.

<Endpoint method="POST" path="/v1/webhook-endpoints" href="/docs/api/webhooks/create-webhook-endpoint" />

```bash
curl "$CAIBO_API/v1/webhook-endpoints" \
  -H "Authorization: Bearer $CAIBO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://tu-empresa.com/webhooks/caibo", "event_types": ["payin.completed", "funding_account.active"] }'
```

La respuesta trae `secret` (`whsec_…`) **una sola vez**. Guárdalo: con él [verificas la firma](/docs/webhook-signatures) de cada aviso.
</Step>

<Step>
### Abre un cobro [#abre-un-cobro]

Sandbox tiene una cuenta de prueba en USD que recibe cualquier depósito y que puedes "pagar" tú mismo. Cada creación lleva un `Idempotency-Key` único por operación.

<Endpoint method="POST" path="/v1/funding-accounts" href="/docs/api/funding/create-funding-account" />

```bash
curl "$CAIBO_API/v1/funding-accounts" \
  -H "Authorization: Bearer $CAIBO_API_KEY" \
  -H "Idempotency-Key: quickstart-cobro-001" \
  -H "Content-Type: application/json" \
  -d '{ "method": "bank_transfer", "currency": "USD" }'
```

```json
{
  "id": "fa_01m3sg9w0000000000000000",
  "status": "pending",
  "method": "bank_transfer",
  "currency": "USD",
  "settlement_currency": "USDT",
  "created_at": "2026-10-18T12:00:00Z"
}
```

En segundos pasa a `active`, te llega `funding_account.active` y la cuenta trae en `instructions` los datos para el pagador:

```bash
curl "$CAIBO_API/v1/funding-accounts/fa_01m3sg9w0000000000000000" \
  -H "Authorization: Bearer $CAIBO_API_KEY"
```
</Step>

<Step>
### Simula el depósito del pagador [#simula-el-depósito-del-pagador]

Solo en sandbox: deposita en la cuenta como lo haría tu cliente. El monto va en la moneda de tu saldo (`settlement_currency`).

<Endpoint method="POST" path="/v1/sandbox/deposits" href="/docs/api/sandbox/simulate-deposit" />

```bash
curl "$CAIBO_API/v1/sandbox/deposits" \
  -H "Authorization: Bearer $CAIBO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "funding_account_id": "fa_01m3sg9w0000000000000000", "amount": "100.00" }'
```

Responde `202`. El depósito recorre el mismo camino que uno real y, cuando se confirma, recibes `payin.completed`.
</Step>

<Step>
### Mira tu saldo [#mira-tu-saldo]

<Endpoint method="GET" path="/v1/balances" href="/docs/api/balances/list-balances" />

```bash
curl "$CAIBO_API/v1/balances" -H "Authorization: Bearer $CAIBO_API_KEY"
```

```json
{
  "data": [
    {
      "currency": "USDT",
      "primary": true,
      "available": "100.000000",
      "pending": "0.000000",
      "reserved": "0.000000",
      "in_settlement": "0.000000",
      "earnings": "0.000000",
      "total": "100.000000",
      "as_of": "2026-10-18T12:01:00Z"
    }
  ]
}
```
</Step>
</Steps>

## Siguientes pasos [#siguientes-pasos]

<Cards>
  <Card title="Cobrar un monto exacto" href="/docs/collect-one-payment">PIX en Brasil y transferencia en Perú.</Card>
  <Card title="Pagar a una cuenta" href="/docs/pay-out">Cliente, beneficiario, cotización y pago.</Card>
  <Card title="Webhooks" href="/docs/webhooks">Reintentos, orden y buenas prácticas.</Card>
  <Card title="Pasar a producción" href="/docs/go-live">La lista de verificación.</Card>
</Cards>