VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa

Repasses e dívidas

Como o seller recebe o que vendeu: pedidos de saque, repasses, dívidas descontadas e antecipação de recebíveis.

Depois que a comissão separa a parte da loja da parte do seller (lojista), o seller precisa receber a parte dele. Esta área cobre esse caminho: o seller pede o saque, o financeiro aprova e paga, a plataforma registra o repasse e desconta eventuais dívidas do seller. Uma antecipação permite receber antes do ciclo normal.

São as rotas do administrador da loja. O pedido de saque e o pedido de antecipação nascem no painel do seller.

Pontos principais
  • Valores são inteiros em centavos (4990 = R$ 49,90). Taxas e descontos em pontos-base (1000 = 10%).
  • Os módulos commissions (pedidos de saque), vendor-payouts (repasses) e vendor-debts (dívidas) precisam estar ativos. Com módulo desligado a resposta é 403. As dívidas ainda exigem a opção própria ligada nas configurações (senão 404).
  • Leitura exige view_vendors ou manage_vendors; escrita exige manage_vendors. As antecipações exigem apenas um administrador.
  • O estado vem como letra na resposta, e cada lista tem um alfabeto próprio. As tabelas abaixo trazem todos.
  • A plataforma não transfere dinheiro. Ela registra o estado e o comprovante; a transferência bancária é feita fora.

Como funciona

O caminho do saque

Pedido aberto→Aprovado→Em processamento→Pago
LetraEstado do pedido de saqueSignificado
OabertoO seller pediu. O valor fica reservado no saldo dele.
AaprovadoO financeiro aprovou.
Pem processamentoA transferência foi enviada ao banco.
CpagoConcluído: o saldo foi liquidado e o repasse entrou no histórico.
RrecusadoRecusado enquanto estava aberto. O saldo reservado volta.

O repasse

Cada pagamento concluído fica registrado como um repasse. Há também o repasse gerado por período, usado quando o financeiro paga todos os sellers em ciclos.

LetraEstado do repasseSignificado
OpendenteCriado, aguardando pagamento.
Pem processamentoPagamento em andamento.
CconcluídoPago. Final.
FfalhouO pagamento falhou. Pode voltar para P.
IcanceladoCancelado. Final.

A dívida

LetraEstado da dívidaSignificado
AativaEstá sendo abatida dos saques.
PpendenteRegistrada, ainda não ativa.
CquitadaTotalmente abatida.
IcanceladaCancelada antes de qualquer desconto.

Conceitos-chave

Saldo disponível

Só as entradas confirmadas do razão formam saldo disponível. As pendentes ainda estão na janela de retenção de 72 horas. Um pedido de saque reserva o valor pedido, então o seller não consegue pedir duas vezes o mesmo saldo.

Dívida e desconto

Uma dívida é abatida quando um pedido de saque é concluído: cada dívida ativa retém a sua deduction_rate do valor pedido, da mais antiga à mais nova. O repasse do histórico guarda o líquido. O repasse gerado por período não faz esse desconto.

Antecipação

A antecipação é um empréstimo curto sobre o saldo do próprio seller. Ela vira uma dívida, pelo valor cheio, e é quitada pelos saques seguintes.

Endpoints

MétodoCaminhoPara que servePágina
GET/api/v1/admin/payout-requestsListar pedidos de saquePedidos de saque
POST/api/v1/admin/payout-requests/{id}/approveAprovarPedidos de saque
POST/api/v1/admin/payout-requests/{id}/rejectRecusarPedidos de saque
POST/api/v1/admin/payout-requests/{id}/processMarcar em processamentoPedidos de saque
POST/api/v1/admin/payout-requests/{id}/completeConcluir com o comprovantePedidos de saque
GET/api/v1/admin/vendor-payoutsListar repassesRepasses
GET/api/v1/admin/vendor-payouts/{id}Consultar um repasseRepasses
POST/api/v1/admin/vendor-payouts/generateGerar repasse por períodoRepasses
PATCH/api/v1/admin/vendor-payouts/{id}/statusAlterar o estadoRepasses
GET/api/v1/admin/vendor-debtsListar dívidasDívidas
POST/api/v1/admin/vendor-debtsCriar dívidaDívidas
GET/api/v1/admin/vendor-debts/{id}Consultar dívida e descontosDívidas
PATCH/api/v1/admin/vendor-debts/{id}/cancelCancelar dívidaDívidas
GET/api/v1/admin/vendor-advancesListar antecipaçõesAntecipações
POST/api/v1/admin/vendor-advances/{id}/approveAprovar antecipaçãoAntecipações
POST/api/v1/admin/vendor-advances/{id}/disburseRegistrar o envioAntecipações
PUT/api/v1/admin/vendor-advances/settingsDefinir a políticaAntecipações

Erros comuns

  • Transferir o valor pedido em vez do líquido. Com dívida ativa, o valor a transferir é o líquido do repasse do histórico.
  • Concluir sem passar por processamento. complete só funciona a partir de P; process só a partir de A.
  • Recusar um pedido já aprovado. Só pedidos abertos podem ser recusados.
  • Filtrar repasses por status=pending. O filtro de repasses usa um mapa genérico em que pending vira P (processamento). Use a letra O.
  • Esperar 404 por UUID inexistente ou malformado. Várias rotas respondem 500 nesses casos.
  • PUT parcial na política de antecipação. O corpo substitui tudo; campos omitidos viram zero.
  • Cancelar uma dívida já abatida. Qualquer desconto aplicado bloqueia o cancelamento.

Próximos passos

Pedidos de saque
Conduza a fila de saques até o pagamento.
Dívidas de sellers
Registre o que o seller deve e deixe a plataforma abater.
Antecipações
Aprove e acompanhe a antecipação de recebíveis.
Anterior
Preencher histórico
Próxima
Pedidos de saque
Nesta página
  • Como funciona
  • O caminho do saque
  • O repasse
  • A dívida
  • Conceitos-chave
  • Saldo disponível
  • Dívida e desconto
  • Antecipação
  • Endpoints
  • Erros comuns
  • Próximos passos