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

Comissões e saldo

Saldo, extrato, razão por item e comissões por pedido do seller.

Cada venda do seller gera dinheiro dividido em duas partes: a comissão que fica com a loja e o valor do seller. Estas cinco rotas mostram essa conta de ângulos diferentes. As rotas usam dois razões distintos, explicados na visão geral.

Ler pode escrever

/commissions/balance e /commissions/statement completam o razão antes de responder (criam entradas faltantes e confirmam as com mais de 72 horas). Duas chamadas seguidas podem devolver números diferentes, e em lojas grandes a primeira pode demorar.

Dois razões, duas tabelas de status

entries usa P, A, S, C. As comissões por pedido usam O, A, C, I. A letra A e a letra C significam coisas parecidas, mas não são intercambiáveis. A API devolve a letra, não o nome.

Saldo do seller

Devolve quanto o seller pode sacar agora e como o restante do dinheiro está distribuído. Atenção: apesar de ser um GET, a leitura primeiro gera as entradas de comissão que faltam (pedidos concluídos ainda sem lançamento) e confirma as que já passaram da janela de 72 horas. Chamar essa rota pode alterar o razão.

GET/api/v1/vendor/commissions/balanceSeller

Saldo disponível, pendente e retido

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/commissions/balance" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Saldo
json
{
  "id": "",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "available_cents": 125000,
  "pending_cents": 9293,
  "held_cents": 0,
  "total_earned_cents": 250000,
  "total_paid_cents": 115707,
  "gross_cents": 277778,
  "commission_cents": 27778,
  "confirmed_cents": 126000,
  "reserved_cents": 1000,
  "updated_at": "2026-10-11T21:24:44Z"
}

Campos da resposta

idstring
Sempre vazio. Ignore.
vendor_iduuid
Seller do token.
available_centsinteger
Pode sacar agora: entradas confirmadas, menos as retidas, menos o que já está reservado por pedidos de saque abertos. Nunca negativo.
pending_centsinteger
Ainda na janela de confirmação (entradas P). Não é sacável.
held_centsinteger
Confirmado, mas retido até uma data de liberação.
total_earned_centsinteger
Tudo que o seller ganhou desde sempre, em qualquer status (já sem a comissão da loja).
total_paid_centsinteger
Total já liquidado ou pago ao seller.
gross_centsinteger
Vendas brutas acumuladas (antes da comissão).
commission_centsinteger
Comissão acumulada retida pela loja.
confirmed_centsinteger
Soma bruta das entradas confirmadas, antes de descontar retido e reservado.
reserved_centsinteger
Valor reservado por pedidos de saque abertos (O, A ou P).
updated_atstring
Momento do cálculo, RFC 3339.

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 usuário não está vinculado a nenhum seller.{"error":"no vendor account associated with this user"}

Extrato

Extrato em ordem cronológica: cada comissão ganha entra como crédito e cada saque como débito, com os saldos de abertura e fechamento do período. Sem from/to devolve os últimos 30 dias. Como o saldo, esta leitura gera e confirma entradas pendentes no período antes de responder.

GET/api/v1/vendor/commissions/statementSeller

Extrato do seller por período

Cabeçalhos

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

Parâmetros de consulta

fromstring
Primeiro dia, YYYY-MM-DD. Padrão: um mês atrás.
tostring
Último dia, inclusive, YYYY-MM-DD. Padrão: hoje.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/vendor/commissions/statement?from=2026-09-01&to=2026-09-30" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Extrato
json
{
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "period_start": "2026-09-01",
  "period_end": "2026-09-30",
  "opening_balance": 100000,
  "closing_balance": 116000,
  "total_credits": 21000,
  "total_debits": 5000,
  "entries": [
    {
      "id": "eedb4d02-57da-467b-b5fd-e553fbe5476a",
      "type": "commission",
      "description": "order_commission",
      "order_id": "1c56dcf8-3ed2-4166-b02f-cd917fb0e90a",
      "credit": 21000,
      "debit": 0,
      "balance": 121000,
      "status": "A",
      "date": "2026-09-08T03:04:21Z"
    },
    {
      "id": "ff4e3984-349f-49e4-9398-3232a4e35ec7",
      "type": "payout",
      "description": "vendor_payout",
      "credit": 0,
      "debit": 5000,
      "balance": 116000,
      "status": "C",
      "date": "2026-09-20T10:00:00Z"
    }
  ]
}

Campos da resposta

vendor_iduuid
Seller do token.
period_startstring
Início do período, YYYY-MM-DD.
period_endstring
Fim do período, YYYY-MM-DD.
opening_balanceinteger
Saldo antes do período, em centavos: ganhos confirmados menos saques concluídos.
closing_balanceinteger
Saldo ao fim do período, em centavos.
total_creditsinteger
Soma dos créditos do período.
total_debitsinteger
Soma dos débitos do período.
entriesobject[]

Linhas do extrato.

iduuid
Id da entrada ou do saque.
typestring
commissionpayoutadjustment
Natureza da linha.
descriptionstring
Código estável, não é texto para exibir: order_commission ou vendor_payout. Traduza no seu cliente.
order_iduuid
Pedido de origem. Só em linhas de comissão.
creditinteger
Centavos creditados ao seller.
debitinteger
Centavos debitados (saques).
balanceinteger
Saldo corrente após a linha.
statusstring
Status em letra da entrada ou do saque. Veja a tabela da página inicial.
datestring
Data da linha, RFC 3339 em UTC.

Erros

StatusQuandoCorpo de exemplo
400from ou to fora do formato YYYY-MM-DD (o texto de detail vem em inglês).{"error":"invalid 'from' date, expected YYYY-MM-DD","detail":"parsing time \"2026-13-01\": month out of range"}
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 usuário não está vinculado a nenhum seller.{"error":"no vendor account associated with this user"}

Razão por item

É o razão detalhado: uma entrada por item vendido em sub-pedido, mostrando quanto fica para a loja e quanto para o seller. Da mais recente para a mais antiga. Este é o razão que alimenta saldo, extrato e saques.

GET/api/v1/vendor/commissions/entriesSeller

Entradas de comissão por item vendido

Cabeçalhos

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

Parâmetros de consulta

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/commissions/entries?page=1&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Entradas
json
{
  "entries": [
    {
      "id": "9c37d00c-d9f7-4c0e-9826-1ed655d812bd",
      "order_id": "18566b6e-7857-4f00-9e62-52f644c2e78e",
      "order_item_id": "ccb748c1-a2a4-49a8-b52e-a6db1a989147",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "rule_id": "c962f0d4-b899-4055-b156-e559873970eb",
      "item_amount": 8194,
      "commission_amount": 819,
      "vendor_amount": 7375,
      "status": "P",
      "created_at": "2026-10-09T06:30:57Z"
    }
  ],
  "total": 56197,
  "page": 1,
  "per_page": 20,
  "total_pages": 2810
}

Campos da resposta

entriesobject[]

Entradas da página.

iduuid
Id da entrada.
order_iduuid
Sub-pedido (pedido filho do seller) que gerou a entrada.
order_item_iduuid|null
Item do pedido a que a entrada se refere.
vendor_iduuid
Seller dono da entrada.
rule_iduuid|null
Regra de comissão aplicada.
item_amountinteger
Valor da linha vendida, em centavos.
commission_amountinteger
Parte que fica com a loja, em centavos.
vendor_amountinteger
Parte que cabe ao seller, em centavos (item_amount menos commission_amount).
statusstring
PASC
Situação em letra.
created_atstring
Criação, RFC 3339 em UTC.
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"}
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 usuário não está vinculado a nenhum seller.{"error":"no vendor account associated with this user"}

Comissões por pedido

Lista a comissão que a loja cobra em cada pedido do seller, calculada com o percentual e a taxa fixa do plano do seller. Existe um segundo razão, por item, em /commissions/entries. Não filtre por status aqui: só page e per_page são aceitos.

GET/api/v1/vendor/commissionsSeller

Comissões do plano, uma por pedido

Cabeçalhos

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

Parâmetros de consulta

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/commissions?page=1&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Comissões
json
{
  "commissions": [
    {
      "id": 36975,
      "order_id": "4d4d79f4-f71b-4706-a303-bc79d48df101",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "vendor_name": "Loja Exemplo",
      "plan_id": 8,
      "order_amount": 129990,
      "commission_bps": 700,
      "fixed_fee_cents": 0,
      "commission_amount": 9099,
      "status": "O",
      "created_at": "2026-10-11T21:02:32Z",
      "updated_at": "2026-10-11T21:02:32Z"
    }
  ],
  "total": 36926,
  "page": 1,
  "per_page": 20,
  "total_pages": 1847
}

Campos da resposta

commissionsobject[]

Comissões da página.

idinteger
Id da comissão (inteiro).
order_iduuid
Pedido de origem.
vendor_iduuid
Seller.
vendor_namestring
Nome do seller. Omitido se vazio.
plan_idinteger
Plano do seller no momento do pedido. Omitido se não havia plano.
order_amountinteger
Parte do pedido que é do seller, em centavos.
commission_bpsinteger
Percentual do plano gravado no pedido, em pontos-base (700 = 7%).
fixed_fee_centsinteger
Taxa fixa do plano, em centavos.
commission_amountinteger
Comissão da loja nesse pedido, em centavos: order_amount x commission_bps / 10000 + fixed_fee_cents.
statusstring
OACI
Situação em letra.
paid_atstring
Quando foi marcada como paga. Omitido antes disso.
created_atstring
Criação, RFC 3339 em UTC.
updated_atstring
Última alteração, RFC 3339 em UTC.
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"}
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 usuário não está vinculado a nenhum seller.{"error":"no vendor account associated with this user"}

Resumo das comissões

Soma as comissões por pedido (as de /commissions) por status. Comissões canceladas (I) ficam fora de todos os totais.

GET/api/v1/vendor/commissions/summarySeller

Totais das comissões do plano por status

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/commissions/summary" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Resumo
json
{
  "total_pending": 7793179,
  "total_approved": 0,
  "total_paid": 1041,
  "total_all_time": 7794220,
  "pending_count": 36925,
  "approved_count": 0,
  "paid_count": 1
}

Campos da resposta

total_pendinginteger
Centavos de comissão O (pendente).
total_approvedinteger
Centavos de comissão A (aprovada).
total_paidinteger
Centavos de comissão C (paga).
total_all_timeinteger
Soma de tudo, exceto canceladas.
pending_countinteger
Quantidade pendente.
approved_countinteger
Quantidade aprovada.
paid_countinteger
Quantidade paga.

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 usuário não está vinculado a nenhum seller.{"error":"no vendor account associated with this user"}

Veja também

  • Saques
  • Antecipação
  • Visão geral
Anterior
Financeiro do seller
Próxima
Saques e repasses
Nesta página
  • Saldo do seller
  • Exemplo de requisição
  • Resposta
  • Erros
  • Extrato
  • Exemplo de requisição
  • Resposta
  • Erros
  • Razão por item
  • Exemplo de requisição
  • Resposta
  • Erros
  • Comissões por pedido
  • Exemplo de requisição
  • Resposta
  • Erros
  • Resumo das comissões
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também