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

Resumo da conta

Os números do cabeçalho do painel, a receita entregue de um intervalo e o saldo financeiro do seller.

Estas quatro leituras respondem às perguntas mais básicas do seller: quanto vendi, quanto tenho a receber e quantos pedidos esperam por mim. Todas valem para o seller do token.

Resumo do painel

Devolve cinco números para o cabeçalho do painel do seller. GET /api/v1/vendor/stats é a mesma operação com outro nome: mesma resposta, mesmo código.

GET/api/v1/vendor/dashboardSeller

Resumo do painel

Cabeçalhos

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

Exemplo de requisição

bash
curl -X GET "$BASE_URL/api/v1/vendor/dashboard" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Resumo
json
{
  "product_count": 4987,
  "order_count": 43965,
  "total_revenue": 2966332400,
  "pending_orders": 142,
  "avg_rating": 0,
  "review_count": 0
}

Campos da resposta

product_countinteger
Produtos do seller que não foram apagados.
order_countinteger
Sub-pedidos do seller. Conta todos os status, inclusive cancelados, a não ser que o seller tenha configurado included_statuses.
total_revenueinteger
Soma do total dos mesmos sub-pedidos, em centavos.
pending_ordersinteger
Sub-pedidos no status inicial O (pendente).
avg_ratingnumber
Nota média (0 a 5) das avaliações aprovadas dos produtos do seller. 0 quando não há avaliação.
review_countinteger
Quantidade de avaliações aprovadas.
included_statusesstring[]
Só aparece quando o seller tem uma lista própria de status contados (veja Configuração de métricas).

Erros

StatusQuandoCorpo de exemplo
401Token ausente, inválido, expirado ou revogado.invalid or expired token
403O token não é de um usuário seller, ou a loja ainda está em análise de cadastro.{"error":"vendor_pending_review"}
404O usuário não está vinculado a nenhum seller.{"error":"vendor profile not found"}
Não é a receita realizada

total_revenue soma o total de todos os sub-pedidos, cancelados e reembolsados inclusos. Para a receita que a plataforma considera realizada use Análises (analytics/stats) ou GET /vendor/revenue.

Resumo do painel (alias)

Alias de GET /api/v1/vendor/dashboard. A resposta e os campos são idênticos aos descritos acima.

GET/api/v1/vendor/statsSeller

Resumo do painel (alias)

Cabeçalhos

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

Exemplo de requisição

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

Resposta

200Resumo
json
{
  "product_count": 4987,
  "order_count": 43965,
  "total_revenue": 2966332400,
  "pending_orders": 142,
  "avg_rating": 0,
  "review_count": 0
}

Erros

StatusQuandoCorpo de exemplo
401Token ausente, inválido, expirado ou revogado.invalid or expired token
403O token não é de um usuário seller, ou a loja ainda está em análise de cadastro.{"error":"vendor_pending_review"}
404O usuário não está vinculado a nenhum seller.{"error":"vendor profile not found"}

Receita entregue do intervalo

Soma o total dos sub-pedidos enviados ou entregues (letras S e C) criados dentro do intervalo. Pedidos pendentes, em processamento, cancelados ou reembolsados ficam de fora.

GET/api/v1/vendor/revenueSeller

Receita entregue do intervalo

Cabeçalhos

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

Parâmetros de consulta

fromstringobrigatório
Primeiro dia, YYYY-MM-DD.
tostringobrigatório
Último dia, YYYY-MM-DD. O dia inteiro entra. Não pode ser anterior a from; a janela é de no máximo 366 dias.

Exemplo de requisição

bash
curl -X GET "$BASE_URL/api/v1/vendor/revenue?from=2026-10-01&to=2026-10-11" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Receita do intervalo
json
{
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "total_revenue": 0,
  "order_count": 0,
  "from": "2026-10-01",
  "to": "2026-10-11"
}

Campos da resposta

vendor_iduuid
Id do seller (UUID).
total_revenueinteger
Soma em centavos.
order_countinteger
Sub-pedidos somados.
fromstring
Início devolvido como foi enviado.
tostring
Fim devolvido como foi enviado.

Erros

StatusQuandoCorpo de exemplo
400from ou to ausente, data inválida, from depois de to ou janela maior que 1 ano.{"error":"from and to date parameters are required (YYYY-MM-DD)"}
401Token ausente, inválido, expirado ou revogado.invalid or expired token
403O token não é de um usuário seller, ou a loja ainda está em análise de cadastro.{"error":"vendor_pending_review"}
404O usuário não está vinculado a nenhum seller.{"error":"vendor profile not found"}
As letras são as de uma loja padrão

O filtro usa as letras fixas S (enviado) e C (entregue). Uma loja que renomeou ou recriou seus status pode ter outras letras para essas etapas; nesse caso compare com analytics/orders-by-status.

Saldo financeiro

Devolve o resumo financeiro do seller a partir do livro de comissões: quanto vendeu, quanto a plataforma reteve, quanto já foi repassado e quanto pode ser sacado agora. Exige o privilégio financeiro (vendor_financial ou equivalente).

GET/api/v1/vendor/balanceSeller

Saldo financeiro

Cabeçalhos

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

Exemplo de requisição

bash
curl -X GET "$BASE_URL/api/v1/vendor/balance" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Saldo
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:02:32.621375044Z"
}

Campos da resposta

vendor_iduuid
Id do seller (UUID).
total_gross_salesinteger
Vendas brutas desde sempre, antes da comissão, em centavos.
total_commissioninteger
Comissão total retida pela plataforma, em centavos.
total_vendor_earningsinteger
Ganhos do seller: vendas brutas menos comissão, em centavos.
total_paid_outinteger
Total já repassado ao seller, em centavos.
pending_payoutinteger
Valor reservado por pedidos de repasse ainda abertos, em centavos.
available_balanceinteger
Pode ser sacado agora: já confirmado, fora do período de retenção e sem reserva de repasse. Em centavos.
pending_settlementinteger
Ganhos ainda não confirmados (a venda ainda não liquidou), em centavos.
confirmed_settlementinteger
Soma bruta dos lançamentos confirmados, antes de descontar retenção e reservas, em centavos.
held_balanceinteger
Valor ainda dentro do período de retenção, em centavos.
updated_atstring
Momento do cálculo, RFC 3339 em UTC.

Erros

StatusQuandoCorpo de exemplo
401Token ausente, inválido, expirado ou revogado.invalid or expired token
403Sem o privilégio financeiro, loja em análise de cadastro ou usuário sem seller.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_financial","vendor_view_financial","vendor_request_payouts","vendor_view_commissions","vendor_view_debts","vendor_view_referrals"]}
500Falha ao calcular o saldo.{"error":"failed to calculate balance","detail":"..."}
Repasse e saldo disponível

Mostre ao usuário available_balance, não confirmed_settlement: o segundo ainda inclui valores retidos e reservados por repasses abertos.

Veja também

  • Análises
  • Relatórios
  • Ids, dinheiro e datas
Anterior
Indicadores e relatórios
Próxima
Análises por período
Nesta página
  • Resumo do painel
  • Exemplo de requisição
  • Resposta
  • Erros
  • Resumo do painel (alias)
  • Exemplo de requisição
  • Resposta
  • Erros
  • Receita entregue do intervalo
  • Exemplo de requisição
  • Resposta
  • Erros
  • Saldo financeiro
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também