Casos de uso

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

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.

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.