# Contas e saldo

Listar contas, consultar saldo e extrato, definir limites e gerenciar o ciclo de vida da conta. Toda conta acessada precisa pertencer ao parceiro do token.

## Tipos de conta

Ao abrir uma conta (em [Cadastrar cliente](/endpoints/clientes#cadastrar-cliente) ou em [Abrir conta adicional](/endpoints/clientes#abrir-conta-adicional)), o campo `account_type` aceita:

| `account_type` | Descrição |
|---|---|
| `payment` (padrão) | Conta de pagamento |
| `checking` | Conta corrente |
| `savings` | Conta poupança |
| `salary` | Conta salário |
| `client` | Conta de cliente |
| `client_external` | Conta de cliente externo |
| `escrow` | Conta escrow (garantia) |

O valor é tratado sem diferenciar maiúsculas de minúsculas. Um valor fora desta lista responde `422` com `invalid account_type`.

## Unidades

Saldo, extrato e limites são devolvidos em **centavos** (número inteiro). R$ 15,00 é `1500`.

## Listar contas

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

- **Escopo:** `account:read` · Filtro opcional `document` (CPF/CNPJ do titular, com ou sem máscara).

```json
{
  "data": [
    { "id": 10024270, "user_id": 25154, "kind": 3, "account_type": "payment", "agency": "0001", "account_number": "119306-6", "status": "active" }
  ],
  "meta": { "page": 1, "page_size": 50, "total": 1 }
}
```

## Detalhar conta

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

- **Escopo:** `account:read`

```json
{ "data": { "id": 10024270, "user_id": 25154, "kind": 3, "account_type": "payment", "agency": "0001", "account_number": "119306-6", "status": "active", "currency": "BRL", "created_at": "...", "updated_at": "..." } }
```

## Consultar saldo

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

- **Escopo:** `account:read`

```json
{ "data": { "account_id": 10024270, "balance": 99997, "available": 99997, "blocked": 0, "currency": "BRL", "updated_at": "2026-07-11T02:21:28Z" } }
```

## Consultar extrato

```http
GET /api/partner/v1/accounts/{id}/statement?date_from=2026-07-01&date_to=2026-07-10&page=1&page_size=50
Authorization: Bearer {{access_token}}
```

- **Escopo:** `statement:read` · Filtros opcionais `date_from`, `date_to`.

```json
{
  "data": [
    {
      "id": "PIXOUT20260710abc123",
      "direction": "debit",
      "type": "pix",
      "amount": 5000,
      "description": "PIX enviado",
      "status": "settled",
      "end_to_end_id": "E4602656220260710...",
      "created_at": "2026-07-10T10:12:00Z",
      "completed_at": "2026-07-10T10:12:01Z"
    }
  ],
  "meta": { "account_id": 10024270, "page": 1, "page_size": 50, "total": 1 }
}
```

### Lançamentos de tarifa

A tarifa é sempre um lançamento separado da transação principal. Os lançamentos com `type: "fee"` carregam dois campos de correlação: `feeTransactionId`, o identificador da cobrança de tarifa, e `originTransactionId`, a transação que originou a cobrança.

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

Os demais campos são os mesmos dos outros lançamentos. O detalhe das tarifas está em [Tarifas](/endpoints/tarifas).

### Comprovante de um lançamento

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

- **Escopo:** `statement:read` · Um `entry_id` inexistente responde `404`.

## Limites

Cada conta tem limites para PIX de saída e TED nas janelas transacional, diária, mensal e noturna. O limite noturno atende à Resolução BCB 142.

### Consultar limites

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

- **Escopo:** `account:read`

```json
{
  "data": {
    "account_id": 10024270,
    "currency": "BRL",
    "pix_out": { "transaction_limit": 1500000, "daily_limit": 10000000000, "monthly_limit": 10000000000, "nighttime_limit": 100000 },
    "ted": { "transaction_limit": 1500000, "daily_limit": 10000000000, "monthly_limit": 10000000000, "nighttime_limit": 100000 },
    "overrides": { "pix_out_transaction_limit": null, "pix_out_daily_limit": null, "pix_out_monthly_limit": null, "nighttime_limit": null }
  }
}
```

`pix_out` e `ted` são os limites efetivos da conta. `overrides` mostra os valores definidos especificamente nesta conta; `null` significa herdado do padrão.

### Alterar limites

```http
PUT /api/partner/v1/accounts/{id}/limits
Authorization: Bearer {{access_token}}
Content-Type: application/json

{ "pix_out_transaction_limit": 500000, "nighttime_limit": 100000 }
```

- **Escopo:** `account:write`
- Campos aceitos (em centavos): `pix_out_transaction_limit`, `pix_out_daily_limit`, `pix_out_monthly_limit`, `nighttime_limit`. Só os campos presentes são alterados; enviar `null` remove o override e a conta volta a herdar o padrão. A resposta traz os limites efetivos e os overrides atualizados.

## Bloqueio e encerramento

O bloqueio impede a conta de originar saída de dinheiro (PIX, TED e transferência interna). Uma conta bloqueada continua podendo receber.

```http
POST /api/partner/v1/accounts/{id}/block      # bloquear
POST /api/partner/v1/accounts/{id}/unblock    # desbloquear
POST /api/partner/v1/accounts/{id}/close       # encerrar
Authorization: Bearer {{access_token}}
```

- **Escopo:** `account:write`

Enquanto bloqueada, todo envio a partir da conta responde `422` com `code: "account_blocked"`. O encerramento exige **saldo zero**; uma conta com saldo responde `422`:

```json
{ "error": { "status": 422, "message": "conta com saldo diferente de zero não pode ser encerrada", "balance": 99994, "currency": "BRL" } }
```

Com saldo zero, o encerramento responde `200` com `status: "closed"` e `closing_date`.

## Trilha de eventos da conta

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

- **Escopo:** `account:read` · Filtros opcionais `from` e `to` (ISO8601) e `limit` (padrão 50, máximo 100).

Devolve a trilha de auditoria da conta (criação, bloqueio, alteração de limites e demais mudanças administrativas), mais recente primeiro:

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

Não é o catálogo de notificações: os eventos de webhook ficam em `GET /webhooks/events` e em [Webhooks](/endpoints/webhooks).

## Eventos de conta

Os eventos de webhook `account.created`, `account.blocked`, `account.unblocked` e `account.closed` notificam a criação da conta e as mudanças de estado. Os payloads estão em [Webhooks](/endpoints/webhooks).