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

Saldo, extrato e receita do seller

Consulta o saldo do seller, o extrato do período, a receita por intervalo de datas e a completude do cadastro.

Leituras financeiras e de qualidade de cadastro de um seller. Todas exigem view_vendors ou manage_vendors e só leem. O saldo e o extrato são os mesmos que o seller vê no painel dele. Valores em centavos.

Saldo

Resume quanto o seller vendeu, quanto a plataforma reteve, quanto já foi repassado e quanto está disponível.

GET/api/v1/admin/vendors/{id}/balanceAdmin

Saldo financeiro de um seller

Parâmetros de caminho

iduuidobrigatório
Id do seller.
200Saldo

Campos da resposta

total_gross_salesinteger
Vendas brutas acumuladas (antes da comissão), em centavos.
total_commissioninteger
Comissão retida pela plataforma, acumulada.
total_vendor_earningsinteger
Ganhos do seller, acumulados (bruto menos comissão).
total_paid_outinteger
Total já repassado ao seller.
pending_payoutinteger
Reservado em pedidos de repasse ainda abertos.
available_balanceinteger
Disponível para pedir repasse agora.
pending_settlementinteger
Ainda em liquidação (aguardando confirmar).
confirmed_settlementinteger
Liquidação confirmada, antes de descontar retenções e reservas.
held_balanceinteger
Retido dentro do período de segurança.
updated_atstring
Quando o saldo foi calculado (RFC 3339).

Extrato

GET/api/v1/admin/vendors/{id}/statementAdmin

Extrato do seller em um período

Parâmetros de caminho

iduuidobrigatório
Id do seller.

Parâmetros de consulta

fromstringpadrão: um mês atrás
Início do período, YYYY-MM-DD.
tostringpadrão: hoje
Fim do período, YYYY-MM-DD.
200Extrato

Campos da resposta

period_startstring
Início aplicado (YYYY-MM-DD).
period_endstring
Fim aplicado.
opening_balanceinteger
Saldo no início do período, em centavos.
closing_balanceinteger
Saldo no fim do período.
total_creditsinteger
Soma dos créditos do período.
total_debitsinteger
Soma dos débitos do período.
entriesarray
Lançamentos do período.
entries[].typestring
Tipo do lançamento (por exemplo commission).
entries[].creditinteger
Crédito, em centavos (0 se for débito).
entries[].debitinteger
Débito, em centavos.
entries[].balanceinteger
Saldo depois deste lançamento.
entries[].statusstring
Status do lançamento, em letra.
entries[].order_idstring
Pedido de origem, quando há.
entries[].datestring
Data do lançamento (RFC 3339).

Receita por período

Soma a receita dos pedidos enviados ou entregues do seller, deixando de fora os demais status (cancelados, reembolsados, aguardando pagamento).

GET/api/v1/admin/vendors/{id}/revenueAdmin

Receita de um seller em um intervalo de datas

Parâmetros de caminho

iduuidobrigatório
Id do seller.

Parâmetros de consulta

fromstringobrigatório
Início, YYYY-MM-DD.
tostringobrigatório
Fim, YYYY-MM-DD, inclusive (até 23:59:59 do dia).
200Receita

Campos da resposta

total_revenueinteger
Receita no período, em centavos.
order_countinteger
Pedidos somados.
fromstring
Início aplicado.
tostring
Fim aplicado.

Completude do cadastro

Diz quanto do cadastro do seller está preenchido e o que falta.

GET/api/v1/admin/vendors/{id}/completenessAdmin

Percentual de completude do cadastro de um seller

Parâmetros de caminho

iduuidobrigatório
Id do seller.
200Completude

Campos da resposta

percentageinteger
De 0 a 100.
missing_fieldsarray
Nomes dos campos do cadastro que ainda estão vazios.

Erros

StatusQuandoCorpo de exemplo
400revenue sem from ou to.{"error":"from and to date parameters are required (YYYY-MM-DD)"}
400Data em formato errado, from depois de to, ou intervalo maior que 1 ano.{"error":"date range must not exceed 1 year"}
400statement com data em formato errado.{"error":"invalid 'from' date, expected YYYY-MM-DD","detail":"..."}
404completeness de seller que não existe.{"error":"vendor not found"}
500id que não é UUID.{"error":"failed to calculate balance","detail":"..."}
401 / 403Sem token ou sem privilégio.{"error":"missing authorization header"}
Seller inexistente no saldo e na receita dá 200 com zeros

balance e revenue não conferem se o seller existe: um UUID válido que não é de nenhum seller devolve zeros. Confirme o seller com GET /vendors/{id} quando isso importar.

Veja também

  • Consultar e editar o seller
  • Visão geral
Anterior
Status e candidatura do seller
Próxima
Equipe do seller
Nesta página
  • Saldo
  • Extrato
  • Receita por período
  • Completude do cadastro
  • Erros
  • Veja também
json
{
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "total_gross_sales": 2494786460,
  "total_commission": 249478645,
  "total_vendor_earnings": 2245307815,
  "total_paid_out": 588919064,
  "pending_payout": 1000,
  "available_balance": 1656378458,
  "pending_settlement": 9293,
  "confirmed_settlement": 1656379458,
  "held_balance": 0,
  "updated_at": "2026-10-11T21:27:29Z"
}
json
{
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "period_start": "2026-10-01",
  "period_end": "2026-10-11",
  "opening_balance": 1658191594,
  "closing_balance": 1658200887,
  "total_credits": 9293,
  "total_debits": 0,
  "entries": [
    {
      "id": "463bdf21-c5ad-409d-9392-fcbbad20bf98",
      "type": "commission",
      "description": "order_commission",
      "order_id": "1115a56b-7e0b-4ba7-9940-2f5d79210602",
      "credit": 1918,
      "debit": 0,
      "balance": 1658193512,
      "status": "P",
      "date": "2026-10-09T06:08:11Z"
    }
  ]
}
json
{
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "total_revenue": 21545514,
  "order_count": 349,
  "from": "2026-09-01",
  "to": "2026-10-01"
}
json
{ "percentage": 84, "missing_fields": ["cnpj", "bank_code"] }
bash
curl "$BASE_URL/api/v1/admin/vendors/94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36/revenue?from=2026-09-01&to=2026-10-01" \
  -H "Authorization: Bearer $TOKEN"