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

Dívidas e divisão de pagamentos

Dívidas do seller com a loja e como os pagamentos diretos foram divididos.

Duas visões do lado "o que sai" do dinheiro: as dívidas que a loja desconta dos repasses e as divisões de pagamento (split) quando o cliente paga direto ao seller. Cada par de rotas depende de um módulo diferente da loja.

Módulos e recurso

Dívidas exigem o módulo vendor-debts e o recurso vendor_debt_payout ligados (403 module_disabled ou 404). Divisões exigem o módulo direct-payments. O seller só lê; quem lança e cancela dívidas é a loja.

Listar dívidas

Uma dívida é um valor que o seller deve à loja (estorno, devolução, multa, adiantamento). Enquanto não quitada, uma parte de cada repasse é descontada (deduction_rate) até zerar. Lista todas, da mais nova para a mais antiga, sem paginação.

GET/api/v1/vendor/debtsSeller

Dívidas do seller com a loja

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).

Parâmetros de consulta

statusstring
activependingpaidcancelledAPCI
Filtra por situação. Aceita o nome ou a letra.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/vendor/debts?status=active" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Dívidas
json
{
  "debts": [
    {
      "id": "6f9c61b0-39cf-4577-a9e4-dc8b4fc5c8b8",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "amount": 200000,
      "reason": "advance",
      "description": "Antecipa Venddor advance 1c8bb5d2-ce76-4856-8763-83ed95dbe294",
      "status": "A",
      "deducted_total": 50000,
      "deduction_rate": 10000,
      "created_by": "b00d3e7c-d5b4-4942-827a-06e2c43645af",
      "created_at": "2026-10-01T13:04:16Z",
      "updated_at": "2026-10-05T10:00:00Z",
      "remaining": 150000
    }
  ]
}

Campos da resposta

debtsobject[]

Dívidas.

iduuid
Id da dívida.
vendor_iduuid
Seller.
amountinteger
Valor original, em centavos.
reasonstring
overchargereturnpenaltyadvanceother
Motivo curto.
descriptionstring
Descrição detalhada.
statusstring
APCI
Letra: A ativa (já descontando), P pendente, C quitada, I cancelada.
deducted_totalinteger
Quanto já foi descontado, em centavos.
deduction_rateinteger
Fatia de cada repasse tomada para esta dívida, em pontos-base (10000 = 100%).
created_byuuid
Usuário da loja que lançou a dívida.
created_atstring
Criação, RFC 3339.
updated_atstring
Última alteração, RFC 3339.
remaininginteger
Quanto falta: amount menos deducted_total.

Erros

StatusQuandoCorpo de exemplo
401Token ausente, inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.{"error":"insufficient permissions"}
403Sub-conta do seller sem nenhum dos privilégios financeiro (a lista completa vem em privilege_required_any; o exemplo está cortado). O dono da loja passa sempre.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_financial","vendor_view_financial"]}
403O módulo vendor-debts está desligado nesta loja.{"error":"module_disabled","module":"vendor-debts"}
404O recurso de dívidas (vendor_debt_payout) está desligado nas configurações da loja.{"error":"vendor_debt_payout feature is not enabled","detail":"enable via admin settings"}
403O usuário não está vinculado a nenhum seller.{"error":"no vendor profile found for this user"}

Resumo das dívidas

Totais e contagens das dívidas do seller.

GET/api/v1/vendor/debts/summarySeller

Totais das dívidas do seller

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/vendor/debts/summary" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Resumo
json
{
  "total_debt": 200000,
  "total_deducted": 50000,
  "total_remaining": 150000,
  "active_debts": 1,
  "pending_debts": 0,
  "paid_debts": 3
}

Campos da resposta

total_debtinteger
Soma das dívidas ativas e pendentes, em centavos.
total_deductedinteger
Soma já descontada.
total_remaininginteger
total_debt menos total_deducted.
active_debtsinteger
Quantidade de dívidas ativas.
pending_debtsinteger
Quantidade de dívidas pendentes.
paid_debtsinteger
Quantidade de dívidas quitadas.

Erros

StatusQuandoCorpo de exemplo
401Token ausente, inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.{"error":"insufficient permissions"}
403Sub-conta do seller sem nenhum dos privilégios financeiro (a lista completa vem em privilege_required_any; o exemplo está cortado). O dono da loja passa sempre.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_financial","vendor_view_financial"]}
403O módulo vendor-debts está desligado nesta loja.{"error":"module_disabled","module":"vendor-debts"}
404O recurso de dívidas (vendor_debt_payout) está desligado nas configurações da loja.{"error":"vendor_debt_payout feature is not enabled","detail":"enable via admin settings"}
403O usuário não está vinculado a nenhum seller.{"error":"no vendor profile found for this user"}

Listar divisões de pagamento

Quando o pagamento é feito direto ao seller (módulo direct-payments), a plataforma divide o valor do pedido entre o seller e a loja. Cada divisão é um registro com o valor bruto e a comissão. Lista as divisões do seller, da mais nova para a mais antiga.

GET/api/v1/vendor/payment-splitsSeller

Como cada pagamento foi dividido

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).

Parâmetros de consulta

statusstring
pendingprocessingcompletedfailedrefunded
Filtra por situação. pending e processing são o mesmo grupo e devolvem as mesmas divisões.
pageintegerpadrão: 1
Página, a partir de 1.
per_pageintegerpadrão: 20
Itens por página, de 1 a 100. Fora disso vale 20.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/vendor/payment-splits?status=pending&page=1&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Divisões
json
{
  "splits": [
    {
      "id": "e596dfec-f18d-4946-9950-9199b26e5516",
      "order_id": "a8a3c7a3-5f15-45a8-a385-4f20fbf8b722",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "vendor_name": "Loja Exemplo",
      "order_number": "VND-20261010-0004",
      "recipient_type": "vendor",
      "amount": 27300,
      "commission_amount": 2700,
      "status": "pending",
      "payment_method": "pix",
      "created_at": "2026-10-11T02:56:38Z",
      "updated_at": "2026-10-11T02:56:38Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

splitsobject[]

Divisões da página.

iduuid
Id da divisão.
order_iduuid
Pedido.
vendor_iduuid
Seller.
vendor_namestring
Nome do seller.
order_numberstring
Número do pedido para exibição.
recipient_typestring
vendormarketplace
Quem recebe esta fatia.
amountinteger
Valor bruto, em centavos, antes da comissão.
commission_amountinteger
Comissão da loja, em centavos.
statusstring
pendingcompletedfailedrefunded
Situação por extenso.
payment_methodstring
Forma de pagamento (por exemplo pix). Omitido se vazio.
payment_refstring
Referência no gateway. Omitido se vazio.
error_messagestring
Motivo da falha. Omitido se não houve.
processed_atstring
Quando foi processada. Omitido antes.
created_atstring
Criação, RFC 3339.
updated_atstring
Última alteração, RFC 3339.
totalinteger
Total de registros.
pageinteger
Página devolvida.
per_pageinteger
Tamanho da página aplicado.
total_pagesinteger
Número de páginas.

Erros

StatusQuandoCorpo de exemplo
401Token ausente, inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.{"error":"insufficient permissions"}
403O módulo direct-payments está desligado nesta loja.{"error":"module_disabled","module":"direct-payments"}
403O usuário não está vinculado a nenhum seller.{"error":"vendor not found for user"}

Totais das divisões

Totais das divisões do seller.

GET/api/v1/vendor/payment-splits/statsSeller

Totais das divisões de pagamento

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/vendor/payment-splits/stats" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Totais
json
{
  "total_splits": 37648,
  "pending_splits": 0,
  "completed_splits": 0,
  "failed_splits": 0,
  "total_amount": 2284420857,
  "total_commission": 253823873
}

Campos da resposta

total_splitsinteger
Quantidade de divisões.
pending_splitsinteger
Quantidade pendente. Veja o aviso: hoje vem sempre 0.
completed_splitsinteger
Quantidade concluída. Hoje vem sempre 0.
failed_splitsinteger
Quantidade com falha. Hoje vem sempre 0.
total_amountinteger
Soma bruta, em centavos.
total_commissioninteger
Soma das comissões, em centavos.
Contadores por status zerados

Na loja de teste os três contadores por status (pending_splits, completed_splits, failed_splits) voltam 0 mesmo com milhares de divisões pending na listagem: o cálculo compara com o nome por extenso, mas o banco guarda a letra. Só total_splits, total_amount e total_commission são confiáveis. Para contar por status, use GET /payment-splits?status=... e leia total.

Erros

StatusQuandoCorpo de exemplo
401Token ausente, inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.{"error":"insufficient permissions"}
403O módulo direct-payments está desligado nesta loja.{"error":"module_disabled","module":"direct-payments"}
403O usuário não está vinculado a nenhum seller.{"error":"vendor not found for user"}

Veja também

  • Antecipação
  • Saques e repasses
  • Visão geral
Anterior
Antecipação (Antecipa Venddor)
Próxima
Pagar.me, chargebacks e disputas
Nesta página
  • Listar dívidas
  • Exemplo de requisição
  • Resposta
  • Erros
  • Resumo das dívidas
  • Exemplo de requisição
  • Resposta
  • Erros
  • Listar divisões de pagamento
  • Exemplo de requisição
  • Resposta
  • Erros
  • Totais das divisões
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também