Aller au contenu

Executa payouts

POST/api/payouts

Auth
Jeton requis
Qui peut l’appeler:
owner
admin
Clé d’API:
Clé d’API non acceptée
X-CommunityId
X-CommunityId Envoyez le X-CommunityId de la communauté où l’opération a lieu.
Les descriptions des endpoints viennent directement de la spécification de l’API et sont en portugais pour l’instant. L’interface autour est traduite.

Exige autenticação e papel owner ou admin na comunidade do X-CommunityId. `amount` é o valor que a comunidade recebe; a taxa de saque da plataforma é somada a ele, e `amount + transferFee` sai do saldo disponível. Saldo que não cobre os dois responde 400 com a mensagem traduzida mostrando a taxa. A resposta traz, além do saque, `transferFee` e `totalDebited` (strings com duas casas, como `amount`). O extrato registra a taxa numa entrada própria (`PAYOUT_REQUESTED` com `metadata.isTransferFee = true`), devolvida se o saque for cancelado ou falhar. A taxa vigente pode ser consultada antes em `GET .../payouts/balance` ou `GET .../ledger/balance` (`transferFee`, `maxPayoutAmount`). **O saque sai de verdade em produção** (fora dela, sempre por um provedor falso, sem variável de ambiente). O pedido é gravado (com a chave de idempotência própria do saque) e enviado ao banco na hora, sem aprovação manual, a partir da conta de recebimento da comunidade. A taxa é a taxa de saque da Memberfy (R$ 3,67 em reais), cobrada por cima do valor. O limite é o menor entre o `available` do extrato e o saldo disponível da conta de recebimento, menos os reembolsos aguardando saldo (lidos sob a mesma trava), e `amount + transferFee` precisa caber nele; acima disso, 400 traduzido com o maior valor que pode ser sacado (`maxPayoutAmount`, já sem a taxa). Estados: `PENDING` (gravado; fica assim, com `dispatchMessage`, quando o provedor da moeda ainda não faz saques), `PROCESSING` (enviado ao banco), `COMPLETED` (o banco recebeu) e `FAILED` (o valor e a taxa voltam ao saldo, com `failureMessage` traduzido). Comunidade sem conta de recebimento ativa responde 400; conta que não pode ser consultada agora responde 502. Abaixo do saque mínimo da moeda (o maior entre o mínimo do produto e o do provedor; R$ 10,00), 400 traduzido com o mínimo na mensagem.

En-têtes

NomTypeDescription
X-CommunityIdfacultatifstring (uuid)ID da comunidade em que a operação acontece. Obrigatório na maioria dos endpoints com escopo de comunidade.

Corps de la requête application/json

NomTypeDescription
amountobligatoirenumberValor que a comunidade recebe (maior que 0, no máximo 2 casas decimais: `1.005` responde 400 `payout.amountDecimals`, nunca é arredondado). A taxa de saque é somada a ele.

Réponses

StatutDescription
201Saque criado.
400Validação ou regra de saque: `amount` ausente, menor que 0,01 ou com mais de 2 casas decimais (`payout.amountDecimals`), saldo insuficiente, abaixo do mínimo, sem conta de recebimento. A mensagem vem traduzida.
401Token ausente, inválido ou expirado; token de outra comunidade (o `X-CommunityId` ou o `communityId` do corpo não é o do token); token antigo ou de uma sessão encerrada (troca de senha, convite aceito). Nesses casos a mensagem pede para entrar de novo (`auth.signInAgain`).
409Comunidade da plataforma: o saldo do recebedor da própria Memberfy não sai por saque da comunidade; nada foi gravado.
500Erro interno do servidor.
502O saldo da conta de recebimento não pôde ser consultado agora; nada foi gravado.

Exemple curl

curl -X POST "https://api.memberfy.net/api/payouts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-CommunityId: $COMMUNITY_ID" \
  -H "Content-Type: application/json" \
  -d '{"amount":10}'