Destinatários e Cobranças (Charges)

🎯 Fluxo de Cadastro de Destinatários (Beneficiários)

O cadastro de um destinatário (beneficiário) é um passo obrigatório para realizar transferências (Pix ou TED) de uma conta Livre ou para liquidar fundos de uma Retenção de Depósito.

Endpoints Criar Destinatário: POST /v1/accounts/:accountId/destinations Consultar/Listar: (Implícito) Você pode listar destinatários existentes. Atualizar/Excluir: PATCH e DELETE em /v1/accounts/:accountId/destinations/:accountDestinationId.

Mecânica de Negócio

Objetivo: Engessar (tornar fixo) o destinatário para garantir que a movimentação seja enviada apenas para contas previamente registradas, um requisito historicamente ligado ao modelo de Contas Escrow.

Pré-requisito: A conta de destino deve ser registrada antes de ser usada em uma transferência (POST /v1/postings) ou em uma regra de retenção (POST /v1/accounts/:accountId/deposit-retention).

Dados: O cadastro exige os dados bancários completos do beneficiário: taxpayerId (CPF/CNPJ), name, bank (ISPB do banco), branch, account e type (tipo de conta: CACC - Conta Corrente, SVGS - Poupança, etc.).

Pix: A API atualmente só suporta transferências Pix utilizando a chave composta (banco, agência, conta), não a chave Pix direta (e-mail, telefone, etc.).

Retorno: O endpoint de criação retorna um id (accountDestinationId), que é o que deve ser usado nos Postings.

💰 Fluxo de Cobranças (Charges)

O fluxo de cobranças é gerenciado por meio de Carteiras (Wallets). Uma Carteira deve ser criada primeiro, pois ela define as regras de negócio básicas que serão herdadas por todas as Cobranças (Charges) criadas dentro dela.

Criação e Gestão da Carteira (/v1/wallets)

Endpoint	Descrição	Configurações Herdadas
POST /v1/wallets	Cria uma nova Carteira, vinculada a um accountId.	Juros, Multa, Desconto (fine, interest, discountValue, discountModality) e Dias para Expirar (daysToExpireAfterPayment).
PATCH /v1/wallets/:walletId	Permite atualizar as configurações e o accountId da carteira.

Criação da Cobrança (/v1/wallets/:walletId/charges)

Endpoint	Descrição	Configurações Herdadas
POST /v1/wallets/:walletId/charges	Cria um boleto ou Pix Cobrança (Charge), especificando o walletId.	As configurações da Carteira são o default. É possível enviar campos como fine, interest, etc., no payload da Cobrança para sobrepor (sobrescrever) as regras da Carteira apenas para aquela Cobrança específica.
GET /v1/wallets/:walletId/charges/:chargeId/pdf	Retorna o link para o PDF do boleto/cobrança.

Updated about 20 hours ago