# Contas Digitais, Saldos e Extratos (`/v2/accounts`)

A rota de `accounts` da API v2 fornece acesso em tempo real aos dados cadastrais, saldos e extratos bancários vinculados aos seus vendedores (sellers), consultando diretamente o provedor BaaS (BMP) e normalizando o retorno no padrão Luri v2.

> **Segurança e Webhooks de Conta (`account.*`):** Todos os sub-recursos de `accounts` exigem **obrigatoriamente** que a requisição venha assinada via **JWT RS256** (JSON Web Token) no cabeçalho (*Bearer Token*), além dos escopos `api.ext api.conta.saldo` e `api.ext api.conta.extrato` vinculados à credencial do marketplace. O método *Basic Auth* não tem permissão de leitura neste endpoint. Além disso, marketplaces que possuem credencial **JWT ativa** e `url_webhook` configurada recebem automaticamente todos os webhooks de eventos e movimentações em conta (`account.pix.*`, `account.ted.*`, `account.transfer.*`, `account.bill_payment.*`, `account.utility_payment.*`, `account.service_fee`, `account.split`, etc.).

---

## Endpoints do Módulo Accounts

| Método | Endpoint | Autenticação | Escopo Requerido | Descrição |
| :--- | :--- | :--- | :--- | :--- |
| `GET` | `/v2/accounts` | **Exclusivo JWT (Bearer)** | — | Lista todas as contas ativas vinculadas aos sellers do marketplace. |
| `GET` | `/v2/accounts/{account_id}/balance` | **Exclusivo JWT (Bearer)** | `api.ext api.conta.saldo` | Consulta em tempo real o saldo disponível, bloqueado e agendado da conta na BMP (`api/Conta/Saldo`). |
| `GET` | `/v2/accounts/{account_id}/statements` | **Exclusivo JWT (Bearer)** | `api.ext api.conta.extrato` | Consulta em tempo real o extrato da conta na BMP (`api/Conta/Extrato`), retornando o resumo de saldos do período (`items.balance`) e as movimentações normalizadas (`items.transactions`). Por padrão (sem filtros de data), consulta os **últimos 30 dias**. |

### Query Parameters de Saldo (`GET /v2/accounts/{account_id}/balance`)
- `seller_id` (`text`, opcional): ID único que identifica o estabelecimento comercial e sua conta.
- `seller_ein` (`text`, opcional): Documento (CPF/CNPJ) do seller.

### Query Parameters de Extrato (`GET /v2/accounts/{account_id}/statements`)
- `limit` (`text`, opcional): Quantidade de itens (movimentações) por requisição (padrão `300`, máximo `1000`).
- `page` (`text`, opcional): Número da página para paginação (padrão `1`).
- `seller_id` (`text`, opcional): ID único que identifica o estabelecimento comercial e sua conta.
- `seller_ein` (`text`, opcional): Documento (CPF/CNPJ) do seller.
- `created_date_lte` (`text`, opcional): Data da movimentação no extrato no formato `YYYY-MM-DD`, menor ou igual a este valor.
- `created_date_gte` (`text`, opcional): Data da movimentação no extrato no formato `YYYY-MM-DD`, maior ou igual a este valor.
- `operacao` (`text`, opcional): Filtra pela descrição ou identificador da operação (ex: `ENVIO PIX`, `RECEBIMENTO PIX`, `PIXENV`, `PIXREC`).
- `d_c` (`text`, opcional): Filtra por `D` (Débito) ou `C` (Crédito).
- `dt_mov` (`text`, opcional): Data específica da movimentação (`YYYY-MM-DD`).

---

## Webhooks de Movimentação em Conta (`account.*`)

Marketplaces autenticados com **credencial JWT ativa** (`/v2/auth/public-keys`) e `url_webhook` configurada recebem automaticamente eventos em tempo real para todas as operações bancárias na conta do seller:
- **Pix em Conta**: `account.pix.received` (Pix avulso na chave), `account.pix.sent`, `account.pix.failed`, `account.pix.refunded`, `account.pix.reversed`, `account.pix.refund_failed`.
- **TED e Transferências Internas**: `account.ted.received`, `account.ted.sent`, `account.ted.refunded`, `account.transfer.received`, `account.transfer.sent`.
- **Pagamentos de Títulos e Concessionárias**: `account.bill_payment.paid`, `account.bill_payment.refunded`, `account.utility_payment.paid`, `account.utility_payment.refunded`.
- **Tarifas, Split, Cartões e Boletos**: `account.service_fee` (`movimentoServico`), `account.split` (`MovimentoSplit`), `account.movement.other`, `account.boleto.credit_preview`, `account.boleto.protested`, `account.card.*`, `account.cnab.*`.

Consulte a [Documentação Completa de Webhooks (WEBHOOKS.md)](WEBHOOKS.md) para ver o dicionário de campos e exemplos de payload de cada evento `account.*`.