# Casos de uso

Fluxos comuns de integração, combinando os endpoints do catálogo. Todos pressupõem um token válido (veja [Autenticação](/autenticacao)).

## 1. Onboarding de um cliente com conta

Cadastre o cliente e abra a conta em uma única chamada.

1. `POST /api/partner/v1/customers` com `document`, `name` e `password` (escopo `customer:create`).
2. A resposta traz o cliente, a conta aberta e o resultado da verificação de conformidade.
3. Consulte o status depois com `GET /api/partner/v1/customers/{id}` (escopo `customer:read`).

## 2. Consulta de saldo e extrato

1. `GET /api/partner/v1/accounts` para listar as contas dos seus clientes (escopo `account:read`).
2. `GET /api/partner/v1/accounts/{id}/balance` para o saldo atual (escopo `account:read`).
3. `GET /api/partner/v1/accounts/{id}/statement` para o extrato por período (escopo `statement:read`).

## 3. Envio de um PIX

1. (Opcional) `GET /api/partner/v1/pix/dict/{key}` para resolver a chave de destino (escopo `pix:read`).
2. `POST /api/partner/v1/pix/payments` com `account_id`, `amount` (em centavos), `pixKey` e `recipientIspb` (escopo `pix:write`). Envie um `Idempotency-Key`.
3. Acompanhe com `GET /api/partner/v1/pix/payments/{id}` (escopo `pix:read`).

## 4. Recebimento via cobrança PIX (QR Code)

1. `POST /api/partner/v1/pix/charges` com `account_id` e `amount` (escopo `pix:write`). A resposta traz o BR Code e a imagem do QR.
2. Acompanhe o pagamento com `GET /api/partner/v1/pix/charges/{id}` (escopo `pix:read`).
3. Para notificação automática, cadastre um [webhook](/endpoints/webhooks).

## 5. Transferência TED para outro banco

1. `POST /api/partner/v1/transfers/ted` com `account_id`, `amount`, `recipientBankCode` (ISPB do banco destino) e os dados do favorecido (escopo `transfer:write`). Envie um `Idempotency-Key`.
2. Acompanhe com `GET /api/partner/v1/transfers/{id}` (escopo `transfer:read`).

## 6. Notificações por webhook

1. `POST /api/partner/v1/webhooks` com a `url` pública e a lista de `events` (escopo `webhook:write`).
2. Valide cada entrega com o segredo de assinatura retornado na criação.
3. Use `POST /api/partner/v1/webhooks/{id}/test` para uma entrega de teste. O evento `webhook.test` vai somente ao webhook informado.