Fluxo essencial

Documentação da API de Banking & Escrow

🚀 Documentação de Negócio

1. Introdução e Propósito

A API fornece uma interface programática completa para a gestão de contas financeiras, permitindo que parceiros criem, gerenciem e movimentem fundos em dois principais tipos de conta: Conta de Pagamento (Livre) e Conta Escrow (Vinculada), além de oferecer serviços de cobrança e retenção.

2. Fluxo Essencial (Criação de Conta)

O fluxo de onboarding é sequencial:

1. Criação da Pessoa (/persons): É o primeiro passo. Cria-se o registro da pessoa física ou jurídica que será titular ou parte relacionada de uma conta.
   1. Documentação: Documentos devem ser enviados antes do cadastro (e-mail e nome do arquivo) por meio de um fluxo de Pré-Signed Upload via /documents/upload para obter uma Key (chave/ID) do documento, que é então usada no payload de criação de Pessoa.
2. Criação da Conta (/v1/accounts): Utiliza-se o personId do titular e define-se o accountType como PAYMENT (Conta Livre/Corrente) ou ESCROW (Conta Vinculada).
   1. Partes Relacionadas (parties): Uma conta sempre terá múltiplas pessoas (partes relacionadas) ligadas a ela, no mínimo o titular. Em Contas Escrow, é comum ter mais partes (Administrador, Custodiante, etc.) definidas com permissões específicas.
   2. Permissões: As permissões das partes relacionadas (permissions) devem ser definidas na criação e não podem ser alteradas via API após a criação (característica do modelo Escrow).
3. Tipos de Conta e Suas Funções

4. Movimentação de Fundos (/v1/postings)

A transferência de fundos é tratada como um Posting:

a. Conta de Origem (accountId): A conta (Livre ou Escrow) de onde o valor será debitado.

b. Destinatários (/v1/accounts/:accountId/destinations): Antes de transferir (Pix/TED), o destinatário deve ser registrado previamente via /destinations, gerando um accountDestinationId. Este ID é usado no Posting.

c. Aprovação: O campo automaticallyApprove permite aprovar a transação imediatamente, desde que a credencial usada tenha a permissão POSTING_REVIEW (Revisar Movimentação), além da POSTING_CREATE (Criar Movimentação). Caso contrário, a transação fica pendente de aprovação (Review).

d. Tipo de Transação: Suporta PIX, TED e BOLETO (Pagamento de Boleto via Barcode).

5. Mecanismo de Garantia e Retenção (/v1/accounts/:accountId/deposit-retention)

Este recurso permite reter automaticamente uma porcentagem de futuros depósitos (entradas) na conta para uma finalidade específica (garantia/caução), similar a uma Conta Escrow de Fluxo.

Lógica: Define-se uma porcentagem (amountPercentage) e um período (startDate / endDate). Max Amount: Permite definir um teto de retenção (maxAmount): a retenção para quando o valor acumulado atinge esse limite. Origem: Pode-se restringir a retenção a depósitos originados de CPFs/CNPJs específicos (ou reter de todos, se não especificado). SLC (Cartões): O parâmetro shouldRetainSlc ativa a retenção sobre recebíveis de cartão (eventos SLC), além de Pix e TED. Liquidação: Ao final do endDate ou ao atingir o maxAmount, o valor retido é transferido (liquidado) automaticamente para a Conta Destino (accountDestination) que deve ser previamente cadastrada no endpoint /destinations.

⚙️ Documentação Técnica (Resumo dos Endpoints)

| Recurso | Método | Path | **Descrição da funcionalidade ** | Conceito financeiro | | :----------- | :--------- | :--------------------------------------------- | :----------------------------------------------------------------------------------------------------------------- | :------------------------------- | | Contas | POST | /v1/accounts | Cria uma nova conta digital, definindo o tipo (PAYMENT ou ESCROW) e as permissões das partes relacionadas. | Onboarding de Cliente/Conta | | Extrato | GET | /v1/accounts/:accountId/statement | Consulta extrato de movimentações de uma conta por período e tipo de saldo. | Conciliação e Auditoria | | Saldo | GET | /v1/accounts/:accountId/balance | Consulta o saldo (livre e bloqueado) de uma conta. | Saldo Contábil | | Destinatário | POST | /v1/accounts/:accountId/destinations | Cria um registro de conta de terceiros (chave composta: banco, agência, conta) para transferências futuras. | Cadastro de Beneficiário | | Retenção | POST | /v1/accounts/:accountId/deposit-retention | Cria uma regra automática para reter % de depósitos em um período, até um teto, liquidando para uma conta destino. | Conta Escrow de Fluxo / Garantia | | Movimentação | POST | /v1/postings | Cria uma transferência (Pix/TED) ou pagamento de boleto. | Inicia a Transação / Posting | | Revisão | PUT | /v1/postings/:postingId/review | Aprova ou reprova uma movimentação criada (se automaticallyApprove=false). | Fluxo de Aprovação Interna | | Carteira | POST | /v1/wallets | Cria um grupo de cobrança com regras padrão (juros, multas, dias de expiração). | Configuração de Cobrança | | Cobrança | POST | /v1/wallets/:walletId/charges | Cria um novo boleto/Pix Cobrança dentro de uma carteira. Configurações herdam da Wallet. | Emissão de Título / Charge | | Documentos | POST | /v1/wallets/:walletId/charges | Cria um novo boleto/Pix Cobrança dentro de uma carteira. Configurações herdam da Wallet. | Emissão de Título / Charge | | Webhooks | POST | /v1/accounts/:accountId/webhook-configurations | Cadastra URLs de callback para notificações de eventos (exceto status de onboarding). | Notificações Assíncronas |

O fluxo de Retenção de Depósitos (Deposit Retention), acessado via /v1/accounts/:accountId/deposit-retention, é o mecanismo da API que simula uma** Conta Escrow de Fluxo** ou uma garantia de recebíveis.

Ele permite que uma porcentagem dos valores que entram na conta seja retida (bloqueada) automaticamente e transferida para uma conta de destino específica, após o cumprimento de um critério.