VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Cotações e preços B2B

Regras de preço B2B

Cria e mantém regras de preço por faixa de quantidade e grupo de clientes nos produtos do seller.

Uma regra de preço B2B dá um preço ou desconto especial quando o comprador leva uma certa quantidade, opcionalmente só para um grupo de clientes (por exemplo "Atacado"). É assim que o seller monta a tabela de preços escalonada do atacado. Todas as rotas exigem o módulo b2b-pricing ligado.

Desconto e preço fixo

Se discount_bps é maior que zero, ele manda e price_cents é ignorado. Para preço fixo, envie discount_bps: 0 e um price_cents positivo.

Faixas não se validam entre si

A plataforma não impede faixas que se sobrepõem. Use priority para decidir qual vence.

Listar regras

Lista as regras de preço por quantidade e grupo de clientes dos produtos do seller. Uma regra é escopada pelo produto: a tabela de regras não guarda o seller, a posse vem do produto.

GET/api/v1/vendor/b2b/rulesSeller

Listar as regras de preço do seller

Cabeçalhos

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

Parâmetros de consulta

product_iduuid
Só as regras deste produto.
usergroup_idstring
Só as regras deste grupo de clientes.
is_activeboolean
Filtra por ativas. Só o texto true conta como verdadeiro; qualquer outro valor filtra as inativas.
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/b2b/rules?is_active=true&page=1&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Regras
json
{
  "rules": [
    {
      "id": 2,
      "product_id": "d004b341-c402-446a-95f1-791b133b810c",
      "usergroup_id": "a1111111-1111-1111-1111-111111111111",
      "min_qty": 50,
      "max_qty": 99,
      "price_cents": 0,
      "discount_bps": 1500,
      "priority": 2,
      "is_active": true,
      "created_at": "2026-10-01T01:42:06Z",
      "updated_at": "2026-10-01T01:42:06Z",
      "product_name": "Smartwatch Lite Vermelho",
      "product_sku": "SD-001939",
      "product_price": 80990,
      "usergroup_name": "Atacado"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

rulesobject[]

Regras da página.

idinteger
Id da regra (inteiro).
product_iduuid
Produto da regra. Não pode ser trocado depois.
usergroup_idstring|null
Grupo de clientes que recebe a regra. Omitido/null = todos os clientes.
min_qtyinteger
Quantidade mínima (inclusive) da faixa.
max_qtyinteger
Quantidade máxima (inclusive). 0 = sem teto.
price_centsinteger
Preço unitário fixo em centavos. Só vale quando discount_bps é 0.
discount_bpsinteger
Desconto em pontos-base (1500 = 15%). Tem precedência sobre price_cents.
priorityinteger
Prioridade. Maior vence quando várias regras casam.
is_activeboolean
Se a regra está valendo.
created_atstring
Criação, RFC 3339 em UTC.
updated_atstring
Última alteração, RFC 3339 em UTC.
product_namestring
Nome do produto (dado de apoio).
product_skustring
SKU do produto (dado de apoio).
product_priceinteger
Preço de tabela do produto em centavos (dado de apoio).
usergroup_namestring
Nome do grupo, quando há (dado de apoio).
totalinteger
Total que casa com o filtro.
pageinteger
Página devolvida.
per_pageinteger
Tamanho da página.
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"}
403O módulo b2b-pricing está desligado nesta loja.{"error":"module_disabled","module":"b2b-pricing"}

Criar regra

Cria uma regra de preço para um produto seu. Quando o carrinho de um comprador do grupo atinge a faixa de quantidade, o preço da regra substitui o de tabela. Use discount_bps para um desconto percentual ou price_cents para um preço fixo.

POST/api/v1/vendor/b2b/rulesSeller

Criar uma regra de preço B2B

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).
Content-Typestringobrigatório
application/json.

Corpo da requisição

product_iduuidobrigatório
Produto do seller. Precisa ser seu e não estar apagado.
usergroup_idstring
Grupo de clientes. Omita para valer para todos.
min_qtyintegerobrigatório
Quantidade mínima da faixa. Menor que 1 vira 1.
max_qtyintegerpadrão: 0
Quantidade máxima. 0 = sem teto. Se maior que zero, não pode ser menor que min_qty.
price_centsintegerpadrão: 0
Preço unitário fixo, em centavos. Obrigatório positivo quando discount_bps é 0.
discount_bpsintegerpadrão: 0
Desconto de 0 a 10000 pontos-base.
priorityintegerpadrão: 0
Prioridade; maior vence.
is_activebooleanpadrão: true
Regra ativa.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/vendor/b2b/rules" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "product_id": "d004b341-c402-446a-95f1-791b133b810c",
  "usergroup_id": "a1111111-1111-1111-1111-111111111111",
  "min_qty": 50,
  "max_qty": 99,
  "discount_bps": 1500,
  "priority": 2
}'

Resposta

201Regra criada
json
{
  "id": 2,
  "product_id": "d004b341-c402-446a-95f1-791b133b810c",
  "usergroup_id": "a1111111-1111-1111-1111-111111111111",
  "min_qty": 50,
  "max_qty": 99,
  "price_cents": 0,
  "discount_bps": 1500,
  "priority": 2,
  "is_active": true,
  "created_at": "2026-10-01T01:42:06Z",
  "updated_at": "2026-10-01T01:42:06Z",
  "product_name": "Smartwatch Lite Vermelho",
  "product_sku": "SD-001939",
  "product_price": 80990,
  "usergroup_name": "Atacado"
}

Campos da resposta

idinteger
Id da regra (inteiro).
product_iduuid
Produto da regra. Não pode ser trocado depois.
usergroup_idstring|null
Grupo de clientes que recebe a regra. Omitido/null = todos os clientes.
min_qtyinteger
Quantidade mínima (inclusive) da faixa.
max_qtyinteger
Quantidade máxima (inclusive). 0 = sem teto.
price_centsinteger
Preço unitário fixo em centavos. Só vale quando discount_bps é 0.
discount_bpsinteger
Desconto em pontos-base (1500 = 15%). Tem precedência sobre price_cents.
priorityinteger
Prioridade. Maior vence quando várias regras casam.
is_activeboolean
Se a regra está valendo.
created_atstring
Criação, RFC 3339 em UTC.
updated_atstring
Última alteração, RFC 3339 em UTC.
product_namestring
Nome do produto (dado de apoio).
product_skustring
SKU do produto (dado de apoio).
product_priceinteger
Preço de tabela do produto em centavos (dado de apoio).
usergroup_namestring
Nome do grupo, quando há (dado de apoio).

Erros

StatusQuandoCorpo de exemplo
400JSON inválido ou regra incoerente: max_qty menor que min_qty, discount_bps fora de 0 a 10000, ou nem price_cents nem discount_bps positivos.{"error":"failed to create price rule","detail":"either price_cents or discount_bps must be positive"}
404O produto não existe ou não é seu.{"error":"product not found"}
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"}
403O módulo b2b-pricing está desligado nesta loja.{"error":"module_disabled","module":"b2b-pricing"}

Ver uma regra

Devolve uma regra do seller, com nome, SKU e preço de tabela do produto.

GET/api/v1/vendor/b2b/rules/{id}Seller

Detalhe de uma regra de preço

Cabeçalhos

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

Parâmetros de caminho

idintegerobrigatório
Id da regra (inteiro). Letras dão 400 invalid rule id.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/vendor/b2b/rules/2" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Regra
json
{
  "id": 2,
  "product_id": "d004b341-c402-446a-95f1-791b133b810c",
  "usergroup_id": "a1111111-1111-1111-1111-111111111111",
  "min_qty": 50,
  "max_qty": 99,
  "price_cents": 0,
  "discount_bps": 1500,
  "priority": 2,
  "is_active": true,
  "created_at": "2026-10-01T01:42:06Z",
  "updated_at": "2026-10-01T01:42:06Z",
  "product_name": "Smartwatch Lite Vermelho",
  "product_sku": "SD-001939",
  "product_price": 80990,
  "usergroup_name": "Atacado"
}

Campos da resposta

idinteger
Id da regra (inteiro).
product_iduuid
Produto da regra. Não pode ser trocado depois.
usergroup_idstring|null
Grupo de clientes que recebe a regra. Omitido/null = todos os clientes.
min_qtyinteger
Quantidade mínima (inclusive) da faixa.
max_qtyinteger
Quantidade máxima (inclusive). 0 = sem teto.
price_centsinteger
Preço unitário fixo em centavos. Só vale quando discount_bps é 0.
discount_bpsinteger
Desconto em pontos-base (1500 = 15%). Tem precedência sobre price_cents.
priorityinteger
Prioridade. Maior vence quando várias regras casam.
is_activeboolean
Se a regra está valendo.
created_atstring
Criação, RFC 3339 em UTC.
updated_atstring
Última alteração, RFC 3339 em UTC.
product_namestring
Nome do produto (dado de apoio).
product_skustring
SKU do produto (dado de apoio).
product_priceinteger
Preço de tabela do produto em centavos (dado de apoio).
usergroup_namestring
Nome do grupo, quando há (dado de apoio).

Erros

StatusQuandoCorpo de exemplo
400id não é um inteiro.{"error":"invalid rule id"}
404A regra não existe ou o produto dela não é seu (a plataforma não diferencia, para não vazar regras alheias).{"error":"price rule not found"}
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"}
403O módulo b2b-pricing está desligado nesta loja.{"error":"module_disabled","module":"b2b-pricing"}

Atualizar regra

Altera só os campos enviados. O produto não muda. Diferente da criação, a atualização não revalida as faixas: a plataforma aceita max_qty menor que min_qty ou discount_bps fora do intervalo. Confira os valores antes de enviar.

PUT/api/v1/vendor/b2b/rules/{id}Seller

Alterar uma regra de preço

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).
Content-Typestringobrigatório
application/json.

Parâmetros de caminho

idintegerobrigatório
Id da regra (inteiro). Letras dão 400 invalid rule id.

Corpo da requisição

usergroup_idstring
Novo grupo de clientes.
min_qtyinteger
Nova quantidade mínima.
max_qtyinteger
Nova quantidade máxima (0 = sem teto).
price_centsinteger
Novo preço fixo em centavos.
discount_bpsinteger
Novo desconto em pontos-base.
priorityinteger
Nova prioridade.
is_activeboolean
Ativa ou desativa a regra.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/vendor/b2b/rules/2" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "discount_bps": 1800,
  "is_active": true
}'

Resposta

200Regra atualizada
json
{
  "id": 2,
  "product_id": "d004b341-c402-446a-95f1-791b133b810c",
  "usergroup_id": "a1111111-1111-1111-1111-111111111111",
  "min_qty": 50,
  "max_qty": 99,
  "price_cents": 0,
  "discount_bps": 1800,
  "priority": 2,
  "is_active": true,
  "created_at": "2026-10-01T01:42:06Z",
  "updated_at": "2026-10-01T01:42:06Z",
  "product_name": "Smartwatch Lite Vermelho",
  "product_sku": "SD-001939",
  "product_price": 80990,
  "usergroup_name": "Atacado"
}

Campos da resposta

idinteger
Id da regra (inteiro).
product_iduuid
Produto da regra. Não pode ser trocado depois.
usergroup_idstring|null
Grupo de clientes que recebe a regra. Omitido/null = todos os clientes.
min_qtyinteger
Quantidade mínima (inclusive) da faixa.
max_qtyinteger
Quantidade máxima (inclusive). 0 = sem teto.
price_centsinteger
Preço unitário fixo em centavos. Só vale quando discount_bps é 0.
discount_bpsinteger
Desconto em pontos-base (1500 = 15%). Tem precedência sobre price_cents.
priorityinteger
Prioridade. Maior vence quando várias regras casam.
is_activeboolean
Se a regra está valendo.
created_atstring
Criação, RFC 3339 em UTC.
updated_atstring
Última alteração, RFC 3339 em UTC.
product_namestring
Nome do produto (dado de apoio).
product_skustring
SKU do produto (dado de apoio).
product_priceinteger
Preço de tabela do produto em centavos (dado de apoio).
usergroup_namestring
Nome do grupo, quando há (dado de apoio).

Erros

StatusQuandoCorpo de exemplo
400id não inteiro ou JSON inválido.{"error":"invalid rule id"}
404A regra não existe ou o produto dela não é seu (a plataforma não diferencia, para não vazar regras alheias).{"error":"price rule not found"}
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"}
403O módulo b2b-pricing está desligado nesta loja.{"error":"module_disabled","module":"b2b-pricing"}

Excluir regra

Apaga a regra de vez. Não há exclusão lógica nem desfazer. Se só quer suspender, use PUT com is_active: false.

DELETE/api/v1/vendor/b2b/rules/{id}Seller

Excluir uma regra de preço

Cabeçalhos

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

Parâmetros de caminho

idintegerobrigatório
Id da regra (inteiro). Letras dão 400 invalid rule id.

Exemplo de requisição

bash
curl -X DELETE "$BASE_URL/api/v1/vendor/b2b/rules/2" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Regra excluída
json
{
  "message": "price rule deleted"
}

Erros

StatusQuandoCorpo de exemplo
400id não é um inteiro.{"error":"invalid rule id"}
404A regra não existe ou o produto dela não é seu (a plataforma não diferencia, para não vazar regras alheias).{"error":"price rule not found"}
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"}
403O módulo b2b-pricing está desligado nesta loja.{"error":"module_disabled","module":"b2b-pricing"}

Veja também

  • Cotações
  • Visão geral da seção
Anterior
Negociação em rodadas
Próxima
Financeiro do seller
Nesta página
  • Listar regras
  • Exemplo de requisição
  • Resposta
  • Erros
  • Criar regra
  • Exemplo de requisição
  • Resposta
  • Erros
  • Ver uma regra
  • Exemplo de requisição
  • Resposta
  • Erros
  • Atualizar regra
  • Exemplo de requisição
  • Resposta
  • Erros
  • Excluir regra
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também