Reserva de grupo

O que este roteiro prova

• Cada real aportado guarda o nome de quem entrou com ele, então o grupo nunca vira um saldo anônimo.
• A quitação é por integrante: uma chamada move só o dinheiro de quem chamou, assinada só por quem chamou.
• O que está comprometido com o grupo aparece separado do que a pessoa pode gastar.

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

   Quatro pessoas: três integrantes e um recebedor externo ao grupo.

   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

   Criar o grupo

   Quem cria é integrante desde o começo. Os metadados de exibição são opacos para o ledger.

   POST /v1/squads

   corpoCopiar

   {
     "creator_account_id": "<conta da Alice>",
     "name": "Churrasco de sábado",
     "metadata": { "description": "Rateio do churrasco", "emoji": "🔥" }
   }

4. 04

   Convidar e aceitar

   O convite é uma projeção: o convidado aparece como convidado antes de virar integrante. Serialize as duas chamadas, esperando o convidado aparecer na lista antes de aceitar. Duas mutações de configuração disparadas juntas podem ambas responder 201, e a que perde a disputa no ledger é descartada em silêncio.

   POST /v1/squads/{sqd_id}/invitations, depois POST /v1/squads/{sqd_id}/invitations/accept
5. 05

   Aportar dinheiro de verdade

   Um aporte FUNDED move valor para o grupo. Ele sai do saldo disponível de quem aportou e aparece como comprometido.

   POST /v1/squads/{sqd_id}/contributions

   corpoCopiar

   {
     "kind": "FUNDED",
     "actor_account_id": "<conta da Alice>",
     "amount": { "currency": "BRL", "value": 30000 }
   }

6. 06

   Gastar da reserva

   O grupo paga um recebedor. Sai da reserva comum, não da conta de um integrante.

   POST /v1/squads/{sqd_id}/spends

   corpoCopiar

   {
     "actor_account_id": "<conta da Alice>",
     "recipient_account_id": "<conta do açougue>",
     "amount": { "currency": "BRL", "value": 18000 },
     "metadata": { "description": "Carne" }
   }

7. 07

   Ratear uma despesa que alguém já pagou

   Um aporte ACCOUNTING não move dinheiro: registra que alguém pagou por fora e que os outros devem a parte deles. É aqui que a dívida por integrante nasce.

   POST /v1/squads/{sqd_id}/contributions

   corpoCopiar

   {
     "kind": "ACCOUNTING",
     "actor_account_id": "<conta do Bob>",
     "amount": { "currency": "BRL", "value": 9000 },
     "split": { "kind": "EQUAL" },
     "description": "Bebidas"
   }

8. 08

   Ler o plano de acerto

   O plano diz quanto cada um deve e devolve, junto, o corpo exato que a chamada de acerto espera. Você não monta esse corpo à mão.

   GET /v1/accounts/{account_id}/squads/{sqd_id}/settlement-plan
9. 09

   Cada um quita a sua parte

   Uma chamada por devedor. Não existe acerto do grupo inteiro em uma transação: cada integrante move só o próprio dinheiro.

   POST /v1/squads/{sqd_id}/settle

   corpoCopiar

   { "caller_account_id": "<conta do devedor>" }

10. 10

    Fechar o grupo

    Fechar exige que não haja dívida em aberto. O que sobrou volta para quem aportou.

    POST /v1/squads/{sqd_id}/close

    corpoCopiar

    { "actor_account_id": "<conta da Alice>" }

A versão executável

Este roteiro é a espinha de scripts/demo-squad.sh, no repositório do núcleo. Esse script roda na nossa integração contínua a cada mudança relevante, então uma divergência entre o que está escrito aqui e o que o sistema faz quebra o build antes de chegar a esta página.

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