VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Comissões

Regras de comissão

Define quanto a loja retém de cada item vendido por um seller, por seller, categoria e faixa de valor.

Uma regra de comissão diz quanto do valor de um item vendido fica com a loja (a comissão) e quanto vai para o seller. Tudo é calculado por item dos pedidos dos sellers, e o resultado vira uma linha do razão de comissões.

Listar regras

Devolve todas as regras de comissão da loja, sem paginação.

GET/api/v1/admin/commission-rulesAdmin

Lista as regras de comissão

Autenticação: Authorization: Bearer <token> de um administrador com o privilégio view_vendors ou manage_vendors (as escritas exigem manage_vendors). O módulo commissions precisa estar ativo na loja; com o módulo desligado a resposta é 403.

Sem parâmetros.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/commission-rules" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Regras devolvidas
json
{
  "rules": [
    {
      "id": "c962f0d4-b899-4055-b156-e559873970eb",
      "name": "Comissão padrão 10%",
      "rule_type": "percentage",
      "vendor_id": null,
      "category_id": null,
      "rate": 1000,
      "min_order_value": 0,
      "max_order_value": 0,
      "priority": 0,
      "status": "active",
      "created_at": "2026-03-16T15:27:29.907292Z",
      "updated_at": "2026-03-16T15:27:29.907292Z"
    }
  ],
  "total": 1
}

Campos da resposta

rulesarray
Regras cadastradas.
rules[].iduuid
Identificador da regra.
rules[].namestring
Nome interno da regra.
rules[].rule_typestring
percentagefixed
percentage (taxa em pontos-base) ou fixed (valor fixo em centavos por item). O valor tiered aparece no modelo, mas nenhuma conta o aplica.
rules[].vendor_iduuid | null
Seller dono da regra. null vale para todos os sellers.
rules[].vendor_namestring
Razão social do seller, resolvida pelo servidor. Só aparece quando vendor_id está preenchido.
rules[].category_iduuid | null
Categoria à qual a regra se limita. null vale para todas.
rules[].rateinteger
Para percentage: pontos-base (1000 = 10%). Para fixed: centavos (500 = R$ 5,00).
rules[].min_order_valueinteger
Valor mínimo da linha do pedido, em centavos, para a regra valer. 0 = sem mínimo.
rules[].max_order_valueinteger
Valor máximo da linha do pedido, em centavos. 0 = sem máximo.
rules[].priorityinteger
Quanto maior, mais cedo a regra é escolhida.
rules[].statusstring
activeinactive
active ou inactive.
rules[].created_atstring
Criação, RFC 3339 em UTC.
rules[].updated_atstring
Última alteração, RFC 3339 em UTC.
totalinteger
Quantidade de regras.

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":"commissions"} / {"error":"insufficient privileges","required":"manage_vendors"}
Há dois lugares com o mesmo nome

Estas são as regras do razão de comissões (uma linha por item vendido). Os planos de seller têm uma taxa própria, que alimenta o fluxo de comissões por plano.

Criar regra

Cria uma regra. A partir daí, todo item vendido depois que casar com ela gera uma entrada no razão com essa taxa. Entradas já gravadas não são recalculadas.

POST/api/v1/admin/commission-rulesAdmin

Cria uma regra de comissão

Autenticação: Authorization: Bearer <token> de um administrador com o privilégio view_vendors ou manage_vendors (as escritas exigem manage_vendors). O módulo commissions precisa estar ativo na loja; com o módulo desligado a resposta é 403.

Corpo da requisição

namestringobrigatório
Nome da regra. Obrigatório.
rule_typestringobrigatório
percentagefixed
percentage ou fixed. Qualquer outro valor é recusado.
rateintegerobrigatório
Maior que zero. percentage: pontos-base (1000 = 10%); fixed: centavos.
vendor_iduuid
Limita a regra a um seller. Omita para valer para todos.
category_iduuid
Limita a uma categoria. Só é considerada se a opção de comissão por categoria estiver ligada na loja.
min_order_valueintegerpadrão: 0
Centavos, valor mínimo da linha do pedido. Padrão 0 (sem mínimo).
max_order_valueintegerpadrão: 0
Centavos, valor máximo da linha do pedido. Padrão 0 (sem máximo).
priorityintegerpadrão: 0
Prioridade. Padrão 0.
statusstringpadrão: active
activeinactive
active ou inactive. Se omitido, a regra nasce ativa.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/commission-rules" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Seller Loja Otávio, 8%",
    "rule_type": "percentage",
    "rate": 800,
    "vendor_id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
    "priority": 10
  }'

Resposta

201Regra criada
json
{
  "id": "0a6c7f5e-3b1d-4c55-9a7e-2d1f4b8a9c01",
  "name": "Seller Loja Otávio, 8%",
  "rule_type": "percentage",
  "vendor_id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
  "category_id": null,
  "rate": 800,
  "min_order_value": 0,
  "max_order_value": 0,
  "priority": 10,
  "status": "active",
  "created_at": "2026-03-16T15:27:29.907292Z",
  "updated_at": "2026-03-16T15:27:29.907292Z",
  "vendor_name": "Loja Otávio"
}

Campos da resposta

iduuid
Identificador da regra.
namestring
Nome interno da regra.
rule_typestring
percentagefixed
percentage (taxa em pontos-base) ou fixed (valor fixo em centavos por item). O valor tiered aparece no modelo, mas nenhuma conta o aplica.
vendor_iduuid | null
Seller dono da regra. null vale para todos os sellers.
vendor_namestring
Razão social do seller, resolvida pelo servidor. Só aparece quando vendor_id está preenchido.
category_iduuid | null
Categoria à qual a regra se limita. null vale para todas.
rateinteger
Para percentage: pontos-base (1000 = 10%). Para fixed: centavos (500 = R$ 5,00).
min_order_valueinteger
Valor mínimo da linha do pedido, em centavos, para a regra valer. 0 = sem mínimo.
max_order_valueinteger
Valor máximo da linha do pedido, em centavos. 0 = sem máximo.
priorityinteger
Quanto maior, mais cedo a regra é escolhida.
statusstring
activeinactive
active ou inactive.
created_atstring
Criação, RFC 3339 em UTC.
updated_atstring
Última alteração, RFC 3339 em UTC.

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":"commissions"} / {"error":"insufficient privileges","required":"manage_vendors"}
400Corpo inválido, name vazio, rule_type diferente de percentage/fixed ou rate menor ou igual a zero{"error":"rate is required and must be greater than zero"}
500vendor_id ou category_id que não é UUID, ou falha ao gravar{"error":"failed to create commission rule","detail":"..."}
Como a regra é escolhida

Para cada item vendido vale uma só regra: entre as ativas que cobrem o seller, a categoria e o valor da linha, ganha a de maior priority. No empate, vence a mais específica (com vendor_id preenchido, depois com category_id) e, persistindo o empate, a mais antiga. Sem nenhuma regra, a comissão é zero e o seller fica com o valor cheio. O intervalo min_order_value/max_order_value é comparado com o valor da linha do item, não com o total do pedido.

Alterar regra

Altera só os campos enviados (alteração parcial, apesar do PUT). Campos omitidos mantêm o valor atual.

PUT/api/v1/admin/commission-rules/{id}Admin

Altera uma regra de comissão

Autenticação: Authorization: Bearer <token> de um administrador com o privilégio view_vendors ou manage_vendors (as escritas exigem manage_vendors). O módulo commissions precisa estar ativo na loja; com o módulo desligado a resposta é 403.

Parâmetros de caminho

iduuidobrigatório
Identificador da regra.

Corpo da requisição

Todos os campos são opcionais. Envie só o que quer mudar.

namestring
Novo nome da regra.
rule_typestring
percentagefixed
percentage ou fixed. A atualização não valida este valor, então envie apenas um dos dois.
rateinteger
Maior que zero, quando enviado. percentage: pontos-base (1000 = 10%); fixed: centavos.
vendor_iduuid
Limita a regra a um seller. Campo omitido mantém o valor atual.
category_iduuid
Limita a uma categoria. Só é considerada se a opção de comissão por categoria estiver ligada na loja.
min_order_valueinteger
Centavos, valor mínimo da linha do pedido. 0 significa sem mínimo.
max_order_valueinteger
Centavos, valor máximo da linha do pedido. 0 significa sem máximo.
priorityinteger
Nova prioridade.
statusstring
activeinactive
active ou inactive.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/admin/commission-rules/d5ccd9e1-dd21-458c-90a5-4a7f3c2b9e10" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rate": 900,
    "priority": 20
  }'

Resposta

200Regra alterada
json
{
  "id": "c962f0d4-b899-4055-b156-e559873970eb",
  "name": "Comissão padrão 10%",
  "rule_type": "percentage",
  "vendor_id": null,
  "category_id": null,
  "rate": 900,
  "min_order_value": 0,
  "max_order_value": 0,
  "priority": 20,
  "status": "active",
  "created_at": "2026-03-16T15:27:29.907292Z",
  "updated_at": "2026-03-16T15:27:29.907292Z"
}

Campos da resposta

iduuid
Identificador da regra.
namestring
Nome interno da regra.
rule_typestring
percentagefixed
percentage (taxa em pontos-base) ou fixed (valor fixo em centavos por item). O valor tiered aparece no modelo, mas nenhuma conta o aplica.
vendor_iduuid | null
Seller dono da regra. null vale para todos os sellers.
vendor_namestring
Razão social do seller, resolvida pelo servidor. Só aparece quando vendor_id está preenchido.
category_iduuid | null
Categoria à qual a regra se limita. null vale para todas.
rateinteger
Para percentage: pontos-base (1000 = 10%). Para fixed: centavos (500 = R$ 5,00).
min_order_valueinteger
Valor mínimo da linha do pedido, em centavos, para a regra valer. 0 = sem mínimo.
max_order_valueinteger
Valor máximo da linha do pedido, em centavos. 0 = sem máximo.
priorityinteger
Quanto maior, mais cedo a regra é escolhida.
statusstring
activeinactive
active ou inactive.
created_atstring
Criação, RFC 3339 em UTC.
updated_atstring
Última alteração, RFC 3339 em UTC.

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":"commissions"} / {"error":"insufficient privileges","required":"manage_vendors"}
400Corpo inválido ou rate menor ou igual a zero{"error":"rate is required and must be greater than zero"}
500id que não é UUID, regra inexistente (o servidor não distingue) ou falha ao gravar{"error":"failed to update commission rule","detail":"..."}
O que a alteração não faz

A nova taxa vale para vendas futuras. As entradas do razão já gravadas guardam o valor calculado no dia e não mudam. Aqui rule_type não passa pela validação do cadastro: enviar um valor diferente de percentage/fixed deixa a regra sem efeito (comissão zero).

Excluir regra

Remove a regra de vez. O histórico não é afetado: as entradas do razão já criadas continuam, apenas deixam de apontar para uma regra existente.

DELETE/api/v1/admin/commission-rules/{id}Admin

Exclui uma regra de comissão

Autenticação: Authorization: Bearer <token> de um administrador com o privilégio view_vendors ou manage_vendors (as escritas exigem manage_vendors). O módulo commissions precisa estar ativo na loja; com o módulo desligado a resposta é 403.

Parâmetros de caminho

iduuidobrigatório
Identificador da regra.

Exemplo de requisição

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

Resposta

200Regra excluída
json
{
  "status": "deleted"
}

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":"commissions"} / {"error":"insufficient privileges","required":"manage_vendors"}
500Regra inexistente ou id que não é UUID (não há 404 nesta rota){"error":"failed to delete commission rule","detail":"commission rule not found: ..."}
Prefira desativar

Para parar de aplicar uma regra sem perder o registro de como a taxa era, envie PUT com "status": "inactive" em vez de excluir.

Veja também

  • Razão de comissões
  • Comissões por plano
  • IDs, dinheiro e datas
Anterior
Comissões
Próxima
Razão de comissões
Nesta página
  • Listar regras
  • Exemplo de requisição
  • Resposta
  • Erros
  • Criar regra
  • Exemplo de requisição
  • Resposta
  • Erros
  • Alterar regra
  • Exemplo de requisição
  • Resposta
  • Erros
  • Excluir regra
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também