Transferências por template

O que este roteiro prova

• Um repasse para várias partes é uma transação, não uma sequência. Todas as pernas entram juntas ou nenhuma entra.
• A taxa vai para uma conta de receita no mesmo movimento, não em um lançamento posterior.
• O template é versionado: você fixa a versão e uma mudança nossa não muda o seu resultado sem você saber.

Os passos

Os corpos abaixo estão abreviados nos identificadores, que você substitui pelos que as respostas anteriores devolvem. Cada escrita que cria valor precisa de um cabeçalho Idempotency-Key. Com credenciais aprovadas, as mesmas chamadas rodam contra o ambiente de avaliação. Peça o acesso.

1. 01

   Criar as partes e as contas

   Um devedor e três recebedores.

   POST /v1/parties, depois POST /v1/accounts
2. 02

   Financiar a conta

   Não existe endpoint de torneira. Valor entra porque algo de fora diz que entrou: vincule uma coordenada à conta e depois registre um crédito que a nomeie. A data de efetivação é um dia contábil de São Paulo, não UTC.

   POST /v1/accounts/{account_id}/payment-methods, depois POST /v1/evidence
3. 03

   Transferência com taxa

   R$ 100,00 saem do devedor, o recebedor fica com o líquido e 2,5% vão para a conta de receita. Duas pernas, uma transação.

   POST /v1/template-transfers

   corpoCopiar

   {
     "template_id": "fee_bearing_transfer",
     "params": {
       "debtor_account_id": "<devedor>",
       "creditor_account_id": "<recebedor>",
       "amount_cents": 10000,
       "fee_bps": 250
     }
   }

4. 04

   Repasse para vários titulares

   Um valor dividido entre dois recebedores em proporção definida na chamada. Os dois recebem no mesmo instante.

   POST /v1/template-transfers

   corpoCopiar

   {
     "template_id": "multi_leg_payout",
     "params": {
       "debtor_account_id": "<devedor>",
       "amount_cents": 6000,
       "payee_a_account_id": "<recebedor A>",
       "payee_b_account_id": "<recebedor B>",
       "payee_a_bps": 5000
     }
   }

5. 05

   Cobrar uma tarifa

   Uma perna só, do devedor para a receita.

   POST /v1/template-transfers

   corpoCopiar

   {
     "template_id": "sponsor_fee_apply",
     "params": { "debtor_account_id": "<devedor>", "fee_cents": 500 }
   }

6. 06

   Listar os templates

   O que existe e em que versão. Fixe a versão nas suas chamadas.

   GET /v1/templates, depois GET /v1/templates/{template_id}
7. 07

   A varredura de erros

   A parte mais útil do roteiro. Repetir a mesma chave de idempotência com o mesmo corpo devolve o resultado original; com um corpo diferente é 409 IDEMPOTENCY_KEY_REUSED. Template inexistente é 404, versão errada é 409, parâmetro desconhecido é 400 e uma taxa de 100% é 422. Cada código com o gatilho exato.

A versão executável

Este roteiro é a espinha de scripts/demo-templates.sh, no repositório do núcleo. Atenção: este é o único dos quatro cujo script não roda na integração contínua. Ele depende de execução manual, então trate esta página como a menos protegida contra envelhecimento das quatro.

./scripts/devlocal.sh up
./scripts/demo-templates.sh