Idempotência

Chamadas de rede falham de formas ambíguas: uma requisição expira depois que o servidor a processou mas antes de a resposta chegar até você, e não dá para saber se teve sucesso. A idempotência é o que permite repetir com segurança nessa situação — uma requisição repetida produz o mesmo resultado da primeira, em vez de um duplicado.

A API de Remessas não usa um cabeçalho Idempotency-Key. Em vez disso, todo endpoint de criação é idempotente com base no externalId que você fornece — a mesma convenção em todo lugar, então repetir após um timeout é seguro desde que você envie um externalId estável. Esta página é a referência única de quais operações são seguras para repetir e como.

A única regra: envie o seu próprio externalId único em toda criação (remetente, beneficiário, transação). É a chave de idempotência — o que transforma uma repetição ambígua em uma segura.

Criação de Pessoa — Idempotente em externalId

Criar um remetente ou beneficiário é idempotente quando você fornece um externalId:

• POST /organizations/{tenant}/v2/senders
• POST /organizations/{tenant}/v2/beneficiaries
• POST /organizations/{tenant}/v2/people (obsoleto)

Se uma pessoa com o mesmo externalId já existir no seu tenant, a criação retorna a pessoa existente com HTTP 200 — nenhum duplicado é criado. Uma pessoa realmente nova retorna 201.

Primeira chamada → 201 Created   (pessoa nova, id abc-123)
Repetição        → 200 OK        (a mesma pessoa abc-123 é retornada, nada novo é criado)

Envie sempre o seu próprio externalId ao criar pessoas. É a sua rede de segurança para repetições: sem ele, uma criação repetida após uma falha de rede produz um segundo registro de pessoa para o mesmo indivíduo.

Desativação de Conta — Idempotente

Desativar uma conta de financiamento ou uma conta de destinatário é seguro para repetir:

• DELETE /organizations/{tenant}/payout/participants/{participantId}/fundingAccounts/{fundingAccountId}
• DELETE /organizations/{tenant}/payout/recipientAccounts/{recipientAccountId}

Desativar uma conta que já está inativa é bem-sucedido e retorna a conta inalterada (isActive: false). Não há erro na segunda chamada nem mudança de estado adicional.

Criação de Transação — Idempotente em externalId

POST /organizations/{tenant}/fx/transactions é idempotente quando você fornece um externalId. Uma repetição com o mesmo externalId retorna a transação existente com HTTP 200 e não inicia um segundo payout; uma transação realmente nova retorna 202 Accepted.

Primeira chamada → 202 Accepted   (transação nova, id tx-abc)
Repetição        → 200 OK         (a mesma transação tx-abc é retornada, sem segundo payout)

Como aqui há movimentação de dinheiro, este é o lugar mais importante para acertar nas repetições:

• Envie sempre um externalId único por transação pretendida. É a chave de idempotência — sem ele, uma criação repetida após uma falha de rede inicia um segundo payout.
• Reutilize o mesmo externalId ao repetir a mesma transação pretendida. A correspondência é por tenant e respaldada por uma restrição de unicidade, então até duas repetições concorrentes resolvem para uma única transação.
• Um timeout agora é seguro para repetir desde que você envie o mesmo externalId — a repetição cria a transação (se a primeira nunca chegou) ou retorna a já criada.

Trate um 200 neste endpoint como "já criada, aqui está" e um 202 como "recém-aceita" — ambos são sucesso. Consulte o status da transação retornada de qualquer forma.

Cotações

As cotações não são idempotentes e não devem ser — cada POST /payout/quotes gera uma cotação nova com o seu próprio id e validade. Não há nada para deduplicar: solicite uma cotação nova quando precisar, e nunca faça cache nem reutilize um quoteId entre transações. Veja Cotações (FX).

Leituras

Todos os endpoints GET são naturalmente idempotentes e sem efeitos colaterais — repita à vontade.

Resumo

A API de Wallet é um produto separado e usa um cabeçalho Idempotency-Key explícito nos seus endpoints de escrita — veja a Referência da API de Wallet. A orientação desta página é apenas para a API de Remessas.