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

Repasses

O histórico de repasses aos sellers, a geração por período e o acompanhamento do estado de cada repasse.

O repasse é o registro de uma transferência do valor devido ao seller. Pode nascer de dois jeitos: o financeiro gera um repasse para um período (abaixo), ou ele é registrado ao concluir um pedido de saque (veja Pedidos de saque). Os valores são inteiros em centavos.

Listar repasses

Lista o histórico de repasses: tanto os gerados por período (veja Gerar repasse, abaixo) quanto os registrados ao concluir um pedido de saque.

GET/api/v1/admin/vendor-payoutsAdmin

Lista os repasses aos sellers

Autenticação: Authorization: Bearer <token> de um administrador com view_vendors ou manage_vendors (as escritas exigem manage_vendors). Requer o módulo vendor-payouts ativo.

Parâmetros de consulta

vendor_iduuid
Filtra por seller (UUID completo).
statusstring
OPCFI
Use a letra: O, P, C, F, I. As palavras passam por um mapa genérico em que pending vira P (que aqui é em processamento).
searchstring
Trecho do nome (razão social) do seller, sem diferenciar maiúsculas.
pageintegerpadrão: 1
Página, a partir de 1.
per_pageintegerpadrão: 20
De 1 a 100. Fora disso vale 20.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/vendor-payouts?status=O&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Repasses devolvidos
json
{
  "payouts": [
    {
      "id": "a1f2c3d4-0b1c-4d2e-8f30-5a6b7c8d9e01",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "amount": 99816,
      "commission": 0,
      "net_amount": 99816,
      "status": "O",
      "payout_method": "pix",
      "period_start": "2026-09-01",
      "period_end": "2026-09-30",
      "created_at": "2026-10-01T12:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

payoutsarray
Repasses da página, do mais recente ao mais antigo.
payouts[].iduuid
Identificador do repasse.
payouts[].vendor_iduuid
Seller que recebe.
payouts[].amountinteger
Valor bruto, em centavos: net_amount + commission.
payouts[].commissioninteger
Comissão descontada neste repasse, em centavos. Os repasses gerados por esta API gravam 0, porque a comissão já foi abatida em cada entrada do razão.
payouts[].net_amountinteger
Valor líquido a transferir, em centavos.
payouts[].statusstring
OPCFI
Letra: O pendente, P em processamento, C concluído, F falhou, I cancelado.
payouts[].payout_methodstring
Forma de pagamento do seller: pix ou bank_transfer.
payouts[].referencestring | null
Comprovante da transferência.
payouts[].period_startstring
Início do período do repasse, YYYY-MM-DD.
payouts[].period_endstring
Fim do período, YYYY-MM-DD.
payouts[].notesstring | null
Observações. Omitido quando vazio.
payouts[].created_atstring
Criação, RFC 3339 em UTC.
payouts[].completed_atstring
Quando foi concluído. Só nos concluídos.
totalinteger
Total com o filtro.
pageinteger
Página devolvida.
per_pageinteger
Tamanho de página usado.
total_pagesinteger
Total de páginas.

Erros

StatusQuandoCorpo
401Sem token ou token inválido{"error":"missing authorization header"}
403Sem o privilégio exigido, ou módulo desligado{"error":"module_disabled","module":"vendor-payouts"} / {"error":"insufficient privileges","required":"manage_vendors"}
500vendor_id que não é UUID ou falha na consulta{"error":"failed to list payouts","detail":"..."}

Consultar um repasse

Devolve um repasse pelo identificador.

GET/api/v1/admin/vendor-payouts/{id}Admin

Consulta um repasse

Autenticação: Authorization: Bearer <token> de um administrador com view_vendors ou manage_vendors (as escritas exigem manage_vendors). Requer o módulo vendor-payouts ativo.

Parâmetros de caminho

iduuidobrigatório
Identificador do repasse.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/vendor-payouts/d5ccd9e1-dd21-458c-90a5-4a7f3c2b9e10" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Repasse devolvido
json
{
  "id": "a1f2c3d4-0b1c-4d2e-8f30-5a6b7c8d9e01",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "amount": 99816,
  "commission": 0,
  "net_amount": 99816,
  "status": "O",
  "payout_method": "pix",
  "period_start": "2026-09-01",
  "period_end": "2026-09-30",
  "created_at": "2026-10-01T12:00:00Z"
}

Campos da resposta

iduuid
Identificador do repasse.
vendor_iduuid
Seller que recebe.
amountinteger
Valor bruto, em centavos: net_amount + commission.
commissioninteger
Comissão descontada neste repasse, em centavos. Os repasses gerados por esta API gravam 0, porque a comissão já foi abatida em cada entrada do razão.
net_amountinteger
Valor líquido a transferir, em centavos.
statusstring
OPCFI
Letra: O pendente, P em processamento, C concluído, F falhou, I cancelado.
payout_methodstring
Forma de pagamento do seller: pix ou bank_transfer.
referencestring | null
Comprovante da transferência.
period_startstring
Início do período do repasse, YYYY-MM-DD.
period_endstring
Fim do período, YYYY-MM-DD.
notesstring | null
Observações. Omitido quando vazio.
created_atstring
Criação, RFC 3339 em UTC.
completed_atstring
Quando foi concluído. Só nos concluídos.

Erros

StatusQuandoCorpo
401Sem token ou token inválido{"error":"missing authorization header"}
403Sem o privilégio exigido, ou módulo desligado{"error":"module_disabled","module":"vendor-payouts"} / {"error":"insufficient privileges","required":"manage_vendors"}
404Repasse inexistente{"error":"payout not found"}
500id que não é UUID{"error":"failed to get payout","detail":"..."}

Gerar repasse

Soma as entradas confirmadas do seller criadas no período, cria um repasse pendente (O) com o total do seller e marca essas entradas como liquidadas, tudo na mesma transação. É o caminho "por período", usado quando o financeiro paga todos os seller em ciclos (por exemplo, quinzenal), sem esperar o seller pedir.

POST/api/v1/admin/vendor-payouts/generateAdmin

Gera o repasse de um seller para um período

Autenticação: Authorization: Bearer <token> de um administrador com view_vendors ou manage_vendors (as escritas exigem manage_vendors). Requer o módulo vendor-payouts ativo.

Corpo da requisição

vendor_iduuidobrigatório
Seller a pagar.
period_startstringobrigatório
Primeiro dia, YYYY-MM-DD.
period_endstringobrigatório
Último dia, YYYY-MM-DD, inclusive. Não pode ser anterior ao início.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/vendor-payouts/generate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
    "period_start": "2026-09-01",
    "period_end": "2026-09-30"
  }'

Resposta

201Repasse gerado
json
{
  "payout_id": "a1f2c3d4-0b1c-4d2e-8f30-5a6b7c8d9e01",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "period_start": "2026-09-01",
  "period_end": "2026-09-30",
  "entries_settled": 22,
  "gross_amount": 110907,
  "commission_amount": 11091,
  "vendor_amount": 99816
}

Campos da resposta

payout_iduuid
Repasse criado. Consulte-o em Consultar um repasse.
vendor_iduuid
Seller.
period_startstring
Início, YYYY-MM-DD.
period_endstring
Fim, YYYY-MM-DD.
entries_settledinteger
Quantidade de entradas liquidadas.
gross_amountinteger
Soma do valor dos itens, em centavos.
commission_amountinteger
Parte da loja, em centavos.
vendor_amountinteger
Parte do seller, em centavos. É o valor do repasse.

Erros

StatusQuandoCorpo
401Sem token ou token inválido{"error":"missing authorization header"}
403Sem o privilégio exigido, ou módulo desligado{"error":"module_disabled","module":"vendor-payouts"} / {"error":"insufficient privileges","required":"manage_vendors"}
400vendor_id, period_start ou period_end ausentes; data fora de YYYY-MM-DD; fim antes do início; nenhuma entrada confirmada no período; seller inexistente{"error":"failed to generate payout","detail":"no confirmed commission entries found for vendor ... in the given period"}
Esta rota não desconta dívidas

O desconto de dívidas do seller ocorre quando um pedido de saque é concluído. Um repasse gerado por período grava o valor cheio do seller; se ele tem dívida ativa, o desconto precisa ser feito por fora ou o repasse deve seguir pelo pedido de saque.

Backfill e confirmação automáticos

Antes de somar, a rota cria as entradas que faltam para pedidos concluídos do período e confirma as pendentes que já passaram da retenção de 72 horas. Por isso gerar um repasse de um período antigo funciona sem preparo.

Alterar o estado de um repasse

Conduz o repasse pelo ciclo de pagamento. As transições permitidas são fixas; qualquer outra é recusada.

PATCH/api/v1/admin/vendor-payouts/{id}/statusAdmin

Altera o estado de um repasse

Autenticação: Authorization: Bearer <token> de um administrador com view_vendors ou manage_vendors (as escritas exigem manage_vendors). Requer o módulo vendor-payouts ativo.

Parâmetros de caminho

iduuidobrigatório
Identificador do repasse.

Corpo da requisição

statusstringobrigatório
processingcompletedfailedcancelledPCFI
Novo estado: processing, completed, failed, cancelled (ou pending), ou a letra.
referencestring
Comprovante da transferência. Guardado em reference.

Exemplo de requisição

bash
curl -X PATCH "$BASE_URL/api/v1/admin/vendor-payouts/d5ccd9e1-dd21-458c-90a5-4a7f3c2b9e10/status" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "processing"
  }'

Resposta

200Estado alterado
json
{
  "id": "a1f2c3d4-0b1c-4d2e-8f30-5a6b7c8d9e01",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "amount": 99816,
  "commission": 0,
  "net_amount": 99816,
  "status": "P",
  "payout_method": "pix",
  "period_start": "2026-09-01",
  "period_end": "2026-09-30",
  "created_at": "2026-10-01T12:00:00Z"
}

Campos da resposta

iduuid
Identificador do repasse.
vendor_iduuid
Seller que recebe.
amountinteger
Valor bruto, em centavos: net_amount + commission.
commissioninteger
Comissão descontada neste repasse, em centavos. Os repasses gerados por esta API gravam 0, porque a comissão já foi abatida em cada entrada do razão.
net_amountinteger
Valor líquido a transferir, em centavos.
statusstring
OPCFI
Letra: O pendente, P em processamento, C concluído, F falhou, I cancelado.
payout_methodstring
Forma de pagamento do seller: pix ou bank_transfer.
referencestring | null
Comprovante da transferência.
period_startstring
Início do período do repasse, YYYY-MM-DD.
period_endstring
Fim do período, YYYY-MM-DD.
notesstring | null
Observações. Omitido quando vazio.
created_atstring
Criação, RFC 3339 em UTC.
completed_atstring
Quando foi concluído. Só nos concluídos.

Erros

StatusQuandoCorpo
401Sem token ou token inválido{"error":"missing authorization header"}
403Sem o privilégio exigido, ou módulo desligado{"error":"module_disabled","module":"vendor-payouts"} / {"error":"insufficient privileges","required":"manage_vendors"}
400Corpo inválido ou status vazio{"error":"status is required"}
404Repasse inexistente (às vezes 500, veja a nota){"error":"payout not found"}
500Transição inválida ou estado desconhecido (devia ser 400){"error":"failed to update payout status","detail":"invalid status transition: C -> P (allowed from C: [])"}
Transições permitidas

O (pendente) vai para P ou I. P (em processamento) vai para C ou F. F (falhou) volta para P para nova tentativa. C (concluído) e I (cancelado) são finais. Uma transição fora dessa lista responde 500 com a explicação em detail, e o repasse inexistente também cai em 500, porque o serviço o trata como erro.

Mudar o estado não movimenta dinheiro

Marcar completed só registra o estado. A transferência bancária acontece fora da plataforma.

Veja também

  • Pedidos de saque
  • Razão de comissões
  • Dívidas de sellers
Anterior
Pedidos de saque
Próxima
Dívidas de sellers
Nesta página
  • Listar repasses
  • Exemplo de requisição
  • Resposta
  • Erros
  • Consultar um repasse
  • Exemplo de requisição
  • Resposta
  • Erros
  • Gerar repasse
  • Exemplo de requisição
  • Resposta
  • Erros
  • Alterar o estado de um repasse
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também