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

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"
}

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

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"
    }
  ]
}

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).

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"

200Receita

json

{
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "total_revenue": 21545514,
  "order_count": 349,
  "from": "2026-09-01",
  "to": "2026-10-01"
}

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

json

{ "percentage": 84, "missing_fields": ["cnpj", "bank_code"] }

Campos da resposta

percentageinteger

De 0 a 100.

missing_fieldsarray

Nomes dos campos do cadastro que ainda estão vazios.

Erros

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

Veja também

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.

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

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"
}

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

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"
    }
  ]
}

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).

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"

200Receita

json

{
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "total_revenue": 21545514,
  "order_count": 349,
  "from": "2026-09-01",
  "to": "2026-10-01"
}

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

json

{ "percentage": 84, "missing_fields": ["cnpj", "bank_code"] }

Campos da resposta

percentageinteger

De 0 a 100.

missing_fieldsarray

Nomes dos campos do cadastro que ainda estão vazios.

Erros

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