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

Dívidas de sellers

Registra o que um seller deve à loja e acompanha o abatimento automático nos saques.

Uma dívida de seller é um valor que o seller deve à loja: uma cobrança paga em duplicidade, uma devolução que a loja bancou, uma multa, ou uma antecipação. Em vez de cobrar à parte, a plataforma abate a dívida dos saques seguintes do próprio seller.

Listar dívidas

Lista as dívidas dos sellers com a loja, da mais recente para a mais antiga.

GET/api/v1/admin/vendor-debtsAdmin

Lista as dívidas dos 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-debts ativo e a opção de dívidas/repasses ligada nas configurações da loja; com a opção desligada a resposta é 404.

Parâmetros de consulta

vendor_iduuid
Filtra por seller (UUID completo).
statusstring
activependingpaidcancelledAPCI
active, pending, paid, cancelled ou a letra A, P, C, I.
searchstring
Trecho do nome (razão social) do seller.
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-debts?status=active" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Dívidas devolvidas
json
{
  "debts": [
    {
      "id": "5b1e7a2c-4f3d-4c8a-9d21-6e0f1a2b3c4d",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "amount": 50000,
      "reason": "overcharge",
      "description": "Cobrança duplicada em setembro",
      "status": "A",
      "deducted_total": 0,
      "deduction_rate": 5000,
      "created_by": "67bf291c-0846-4053-9528-8cfd5ab0ebf1",
      "created_at": "2026-10-11T12:00:00Z",
      "updated_at": "2026-10-11T12:00:00Z",
      "remaining": 50000
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

debtsarray
Dívidas da página.
debts[].iduuid
Identificador da dívida.
debts[].vendor_iduuid
Seller devedor.
debts[].amountinteger
Valor original, em centavos.
debts[].reasonstring
overchargereturnpenaltyadvanceother
Motivo: overcharge, return, penalty, advance ou other.
debts[].descriptionstring
Descrição livre.
debts[].statusstring
APCI
Letra: A ativa, P pendente, C quitada, I cancelada.
debts[].deducted_totalinteger
Quanto já foi descontado de repasses, em centavos.
debts[].deduction_rateinteger
Fatia de cada saque que vai para a dívida, em pontos-base (10000 = 100%).
debts[].created_bystring
Administrador que criou.
debts[].created_atstring
Criação, RFC 3339 em UTC.
debts[].updated_atstring
Última alteração.
debts[].remaininginteger
amount - deducted_total, em centavos.
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-debts"} / {"error":"insufficient privileges","required":"manage_vendors"}
404Opção de dívidas desligada nas configurações da loja{"error":"vendor_debt_payout feature is not enabled","detail":"enable via admin settings"}
500vendor_id que não é UUID ou falha na consulta{"error":"failed to list debts","detail":"..."}

Criar dívida

Registra um valor que o seller deve à loja (uma cobrança em duplicidade, uma devolução assumida, uma multa). A dívida nasce ativa e passa a ser abatida dos próximos saques do seller.

POST/api/v1/admin/vendor-debtsAdmin

Registra uma dívida de um seller

Autenticação: Authorization: Bearer <token> de um administrador com view_vendors ou manage_vendors (as escritas exigem manage_vendors). Requer o módulo vendor-debts ativo e a opção de dívidas/repasses ligada nas configurações da loja; com a opção desligada a resposta é 404.

Corpo da requisição

vendor_iduuidobrigatório
Seller devedor.
amountintegerobrigatório
Valor em centavos, maior que zero.
reasonstringpadrão: other
overchargereturnpenaltyadvanceother
Motivo. Se omitido, other.
descriptionstring
Descrição livre.
deduction_rateintegerpadrão: 10000
Pontos-base de cada saque que vão para a dívida, de 1 a 10000. Se omitido (ou 0), 10000 (tudo).

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/vendor-debts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
    "amount": 50000,
    "reason": "overcharge",
    "description": "Cobrança duplicada em setembro",
    "deduction_rate": 5000
  }'

Resposta

201Dívida criada
json
{
  "id": "5b1e7a2c-4f3d-4c8a-9d21-6e0f1a2b3c4d",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "amount": 50000,
  "reason": "overcharge",
  "description": "Cobrança duplicada em setembro",
  "status": "A",
  "deducted_total": 0,
  "deduction_rate": 5000,
  "created_by": "67bf291c-0846-4053-9528-8cfd5ab0ebf1",
  "created_at": "2026-10-11T12:00:00Z",
  "updated_at": "2026-10-11T12:00:00Z",
  "remaining": 50000
}

Campos da resposta

iduuid
Identificador da dívida.
vendor_iduuid
Seller devedor.
amountinteger
Valor original, em centavos.
reasonstring
overchargereturnpenaltyadvanceother
Motivo: overcharge, return, penalty, advance ou other.
descriptionstring
Descrição livre.
statusstring
APCI
Letra: A ativa, P pendente, C quitada, I cancelada.
deducted_totalinteger
Quanto já foi descontado de repasses, em centavos.
deduction_rateinteger
Fatia de cada saque que vai para a dívida, em pontos-base (10000 = 100%).
created_bystring
Administrador que criou.
created_atstring
Criação, RFC 3339 em UTC.
updated_atstring
Última alteração.
remaininginteger
amount - deducted_total, em centavos.

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-debts"} / {"error":"insufficient privileges","required":"manage_vendors"}
404Opção de dívidas desligada nas configurações da loja{"error":"vendor_debt_payout feature is not enabled","detail":"enable via admin settings"}
400vendor_id vazio, amount menor ou igual a zero, reason fora da lista, deduction_rate acima de 10000, ou seller inexistente{"error":"amount must be positive (in centavos)"} / {"error":"failed to create debt","detail":"invalid reason: x (valid: overcharge, return, penalty, advance, other)"}
Como o desconto funciona

Quando um pedido de saque é concluído, cada dívida ativa, da mais antiga para a mais nova, retém valor do saque * deduction_rate / 10000, no máximo o que falta da dívida. Com deduction_rate 5000, metade de cada saque abate a dívida até ela zerar; quando zera, vira quitada (C).

Consultar uma dívida

Devolve a dívida e a lista de descontos já aplicados a ela.

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

Consulta uma dívida e seus descontos

Autenticação: Authorization: Bearer <token> de um administrador com view_vendors ou manage_vendors (as escritas exigem manage_vendors). Requer o módulo vendor-debts ativo e a opção de dívidas/repasses ligada nas configurações da loja; com a opção desligada a resposta é 404.

Parâmetros de caminho

iduuidobrigatório
Identificador da dívida.

Exemplo de requisição

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

Resposta

200Dívida devolvida
json
{
  "debt": {
    "id": "5b1e7a2c-4f3d-4c8a-9d21-6e0f1a2b3c4d",
    "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
    "amount": 50000,
    "reason": "overcharge",
    "description": "Cobrança duplicada em setembro",
    "status": "A",
    "deducted_total": 25000,
    "deduction_rate": 5000,
    "created_by": "67bf291c-0846-4053-9528-8cfd5ab0ebf1",
    "created_at": "2026-10-11T12:00:00Z",
    "updated_at": "2026-10-11T12:00:00Z",
    "remaining": 25000
  },
  "deductions": [
    {
      "id": "c0ffee00-1111-4222-8333-444455556666",
      "debt_id": "5b1e7a2c-4f3d-4c8a-9d21-6e0f1a2b3c4d",
      "payout_id": "a1f2c3d4-0b1c-4d2e-8f30-5a6b7c8d9e01",
      "amount": 25000,
      "created_at": "2026-10-12T12:00:00Z"
    }
  ]
}

Campos da resposta

debtobject
A dívida, com os mesmos campos da lista.
debt.iduuid
Identificador da dívida.
debt.vendor_iduuid
Seller devedor.
debt.amountinteger
Valor original, em centavos.
debt.reasonstring
overchargereturnpenaltyadvanceother
Motivo: overcharge, return, penalty, advance ou other.
debt.descriptionstring
Descrição livre.
debt.statusstring
APCI
Letra: A ativa, P pendente, C quitada, I cancelada.
debt.deducted_totalinteger
Quanto já foi descontado de repasses, em centavos.
debt.deduction_rateinteger
Fatia de cada saque que vai para a dívida, em pontos-base (10000 = 100%).
debt.created_bystring
Administrador que criou.
debt.created_atstring
Criação, RFC 3339 em UTC.
debt.updated_atstring
Última alteração.
debt.remaininginteger
amount - deducted_total, em centavos.
deductionsarray
Descontos aplicados, um por saque que abateu a dívida.
deductions[].iduuid
Identificador do desconto.
deductions[].debt_iduuid
Dívida abatida.
deductions[].payout_iduuid
Repasse do histórico em que o desconto ocorreu.
deductions[].amountinteger
Valor descontado, em centavos.
deductions[].created_atstring
Quando foi descontado.

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-debts"} / {"error":"insufficient privileges","required":"manage_vendors"}
404Opção de dívidas desligada nas configurações da loja{"error":"vendor_debt_payout feature is not enabled","detail":"enable via admin settings"}
404Dívida inexistente{"error":"debt not found"}
500id que não é UUID{"error":"failed to get debt","detail":"..."}

Cancelar dívida

Passa a dívida para I (cancelada), sem corpo. Serve para desfazer um lançamento errado.

PATCH/api/v1/admin/vendor-debts/{id}/cancelAdmin

Cancela uma dívida que ainda não teve desconto

Autenticação: Authorization: Bearer <token> de um administrador com view_vendors ou manage_vendors (as escritas exigem manage_vendors). Requer o módulo vendor-debts ativo e a opção de dívidas/repasses ligada nas configurações da loja; com a opção desligada a resposta é 404.

Parâmetros de caminho

iduuidobrigatório
Identificador da dívida.

Exemplo de requisição

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

Resposta

200Dívida cancelada
json
{
  "id": "5b1e7a2c-4f3d-4c8a-9d21-6e0f1a2b3c4d",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "amount": 50000,
  "reason": "overcharge",
  "description": "Cobrança duplicada em setembro",
  "status": "I",
  "deducted_total": 0,
  "deduction_rate": 5000,
  "created_by": "67bf291c-0846-4053-9528-8cfd5ab0ebf1",
  "created_at": "2026-10-11T12:00:00Z",
  "updated_at": "2026-10-11T12:00:00Z",
  "remaining": 50000
}

Campos da resposta

iduuid
Identificador da dívida.
vendor_iduuid
Seller devedor.
amountinteger
Valor original, em centavos.
reasonstring
overchargereturnpenaltyadvanceother
Motivo: overcharge, return, penalty, advance ou other.
descriptionstring
Descrição livre.
statusstring
APCI
Letra: A ativa, P pendente, C quitada, I cancelada.
deducted_totalinteger
Quanto já foi descontado de repasses, em centavos.
deduction_rateinteger
Fatia de cada saque que vai para a dívida, em pontos-base (10000 = 100%).
created_bystring
Administrador que criou.
created_atstring
Criação, RFC 3339 em UTC.
updated_atstring
Última alteração.
remaininginteger
amount - deducted_total, em centavos.

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-debts"} / {"error":"insufficient privileges","required":"manage_vendors"}
404Opção de dívidas desligada nas configurações da loja{"error":"vendor_debt_payout feature is not enabled","detail":"enable via admin settings"}
400Dívida inexistente, já paga, já cancelada ou com desconto já aplicado{"error":"failed to cancel debt","detail":"cannot cancel a debt with existing deductions (25000 centavos deducted)"}
Dívida com desconto não se cancela

Se qualquer valor já foi descontado, o cancelamento é recusado. Para corrigir, lance outra dívida de ajuste ou trate o estorno fora da plataforma.

Veja também

  • Pedidos de saque
  • Antecipações
  • Repasses
Anterior
Repasses
Próxima
Antecipações
Nesta página
  • Listar dívidas
  • Exemplo de requisição
  • Resposta
  • Erros
  • Criar dívida
  • Exemplo de requisição
  • Resposta
  • Erros
  • Consultar uma dívida
  • Exemplo de requisição
  • Resposta
  • Erros
  • Cancelar dívida
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também