# Cuentas y saldo

Lectura de cuentas, saldo, extracto y comprobante. Todos los recursos están acotados al socio del token. Saldo, extracto y comprobante se devuelven en **reales**.

## Listar cuentas

```http
GET /api/partner/v1/accounts?page=1&page_size=20
Authorization: Bearer {{access_token}}
```

- **Alcance:** `account:read`

```json
{
  "data": [
    { "id": 1042, "account_type": "payment", "agency": "0001", "account_number": "12345-6", "status": "active" }
  ],
  "meta": { "page": 1, "page_size": 20, "total": 1 }
}
```

## Detallar cuenta

```http
GET /api/partner/v1/accounts/{id}
Authorization: Bearer {{access_token}}
```

- **Alcance:** `account:read`

## Consultar saldo

```http
GET /api/partner/v1/accounts/{id}/balance
Authorization: Bearer {{access_token}}
```

- **Alcance:** `account:read`

```json
{
  "data": { "account_id": 1042, "balance": 1500.00, "available": 1500.00, "blocked": 0, "currency": "BRL" }
}
```

## Consultar extracto

```http
GET /api/partner/v1/accounts/{id}/statement?date_from=2026-06-01&date_to=2026-06-30
Authorization: Bearer {{access_token}}
```

- **Alcance:** `statement:read`

Devuelve los movimientos del período (paginado). Valores en reales.

### Movimientos de tarifa

La tarifa es siempre un movimiento separado de la transacción principal. Los movimientos con `type: "fee"` llevan dos campos de correlación: `feeTransactionId`, el identificador del cobro de tarifa, y `originTransactionId`, la transacción que originó el cobro.

```json
{
  "direction": "debit",
  "type": "fee",
  "amount": 350,
  "status": "settled",
  "feeTransactionId": "5f6a7b8c-9d0e-4f1a-8b2c-3d4e5f6a7b8c",
  "originTransactionId": "E4602656220260714210000aabbccdd0"
}
```

Los demás campos son los mismos de los otros movimientos. El detalle de las tarifas está en [Tarifas](/es/endpoints/tarifas).

## Obtener comprobante

```http
GET /api/partner/v1/accounts/{id}/statement/{entry_id}/receipt
Authorization: Bearer {{access_token}}
```

- **Alcance:** `statement:read`

Devuelve el comprobante de un movimiento del extracto.

## Rastro de auditoría de la cuenta

```http
GET /api/partner/v1/accounts/{id}/events?limit=50
Authorization: Bearer {{access_token}}
```

- **Alcance:** `account:read` · Filtros opcionales `from` y `to` (ISO8601) y `limit` (por defecto 50, máximo 100).

Devuelve el rastro de auditoría de la cuenta (creación, bloqueo, cambios de límites y demás cambios administrativos), los más recientes primero:

```json
{
  "data": {
    "events": [
      { "id": "5f6a7b8c-9d0e-4f1a-8b2c-3d4e5f6a7b8c", "action": "update", "resourceType": "account", "actorType": "admin", "changes": { "status": "blocked" }, "metadata": {}, "occurredAt": "2026-07-14T21:00:00Z" }
    ],
    "source": "audit_trail"
  }
}
```

No es el catálogo de notificaciones: los eventos de webhook viven en `GET /webhooks/events` y en [Webhooks](/es/endpoints/webhooks).

## Eventos de cuenta

Los eventos de webhook `account.created`, `account.blocked`, `account.unblocked` y `account.closed` notifican la creación de la cuenta y los cambios de estado. Los payloads están en [Webhooks](/es/endpoints/webhooks).