Financeiro do seller

Em um marketplace a loja recebe o pagamento do cliente, retém uma comissão e repassa o resto ao seller. Esta seção mostra ao seller (lojista) essa conta: quanto já ganhou, quanto pode sacar, o que já recebeu, o que deve à loja e como os pagamentos diretos foram divididos.

Como funciona

1. A venda gera entradas

   Cada item vendido em sub-pedido gera uma entrada no razão, com a parte da loja (comissão) e a parte do seller. Nasce P (pendente).

2. Passam 72 horas

   A entrada vira A (confirmada) e entra em available_cents. A confirmação roda sozinha e também é feita ao ler saldo ou extrato.

3. O seller pede saque

   POST /vendor/commissions/payout-request reserva o valor. A loja aprova, processa e paga; as entradas passam a S (liquidada).

4. A loja gera o repasse

   O lote do período aparece em GET /vendor/payouts. Dívidas ativas são descontadas dele.

Conceitos-chave

Quem é o seller e o que o token permite

O seller (lojista) é descoberto pelo token; nenhuma rota recebe vendor_id. Sub-contas (funcionários) precisam de um privilégio financeiro (vendor_financial ou um dos específicos como vendor_view_commissions). O dono da loja passa sempre. Um token de administrador responde 403.

Dinheiro

Tudo em centavos inteiros (125000 = R$ 1.250,00). Taxas em pontos-base (300 = 3%). Não existe decimal em nenhum campo desta seção.

Dois razões de comissão

A comissão por pedido (/commissions, /commissions/summary) guarda, por pedido, o percentual e a taxa fixa do plano do seller. O razão por item (/commissions/entries, saldo, extrato, saques) guarda, por item vendido, a comissão e o valor do seller. O saque e o saldo usam sempre o segundo.

Pedido de saque versus repasse

Pedido de saque é a solicitação do seller (/commissions/payout-request). Repasse é o lote de pagamento que a loja gera (/payouts). Não há rota de seller para ler o pedido de saque pelo id.

Status em letra

Estas rotas devolvem o status como letra (P, A, O...), não por extenso, com exceção de antecipações e divisões de pagamento, que saem por extenso. A tabela acima resume as letras.

Endpoints

Erros comuns

• Esperar o saldo parado. balance e statement completam e confirmam o razão ao serem lidos, então o valor pode mudar entre chamadas.
• Tentar um segundo pedido de saque com um aberto: 409 open_request_exists.
• Mandar bank_info incompleto achando que a API valida. Ela grava o que receber.
• Passar um id que não é UUID em /payouts/{id}: volta 500, não 400.
• Usar pending_splits do /payment-splits/stats como verdade. Hoje ele vem sempre zerado.
• Pedir mais que o máximo na antecipação e não conferir requested_cents: o valor é reduzido sem erro.
• Esquecer de tratar 403 module_disabled. Dívidas, divisões e várias outras rotas dependem de módulos que a loja pode desligar.

Próximos passos