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

Simulador, reajuste e prévia de preço

Simula e aplica um reajuste em massa nos preços fixos de uma tabela e confere o preço que um cliente real receberia.

Três ferramentas ajudam a mexer em preço sem susto. O simulador mostra o efeito de um reajuste (com margem) sem gravar nada. O reajuste aplica o mesmo cálculo. A prévia de preço responde a pergunta que importa de verdade: "para este cliente, neste produto e nesta quantidade, qual preço a loja vai mostrar?". Todas exigem o módulo b2b-pricing e o privilégio manage_b2b ou manage_promotions.

Os dois reajustes mexem apenas nos itens de preço fixo (price_cents). Itens de desconto (discount_bps) acompanham o preço base sozinhos e ficam de fora.

Tabelas com degraus de quantidade: reajuste com cuidado

O reajuste grava o novo preço em todas as linhas de preço fixo do mesmo produto, sem olhar o min_qty. Se um produto tem degraus (por exemplo min_qty 1 a R$ 100 e min_qty 10 a R$ 90), depois do reajuste os degraus podem ficar com o mesmo preço. O simulador mostra uma linha por degrau, mas não revela isso. Em tabelas com degraus, prefira reenviar os itens com PUT /items ou reimportar o CSV.

Simular um reajuste

Calcula o novo preço de cada item de preço fixo e a margem resultante, sem gravar. O custo vem do cadastro do produto.

POST/api/v1/admin/b2b/price-lists/{id}/simulateAdmin

Simula um reajuste em massa

Parâmetros de caminho

iduuidobrigatório
Id da tabela.

Corpo da requisição

delta_bpsintegerobrigatório
Variação em pontos-base. 600 aumenta 6%, -250 reduz 2,5%. O preço nunca fica abaixo de zero.
except_category_idsarray
Ids (UUID) de categorias que não entram no reajuste. Produtos sem categoria sempre entram.
round_to_centsinteger
Arredonda o novo preço ao múltiplo mais próximo deste valor em centavos. 100 arredonda para o real, 50 para R$ 0,50. Valores de 0 e 1 não arredondam.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/b2b/price-lists/3f0c1a52-8d7e-4c1b-9a64-2b5e7d9c1a10/simulate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "delta_bps": 600, "round_to_cents": 10 }'

Resposta

200Simulação calculada
json
{
  "items": [
    {
      "product_id": "5b6f1948-356b-4739-adfc-af8045b7b769",
      "sku": "SD-004487",
      "old_price_cents": 26250,
      "new_price_cents": 27830,
      "cost_cents": 19000,
      "margin_bps": 3172
    }
  ],
  "items_without_cost": 0
}

Campos da resposta

itemsarray
Uma linha por item de preço fixo.
product_iduuid
Produto.
skustring
SKU do produto.
old_price_centsinteger
Preço atual, em centavos.
new_price_centsinteger
Preço depois do reajuste, em centavos.
cost_centsinteger
Custo cadastrado, em centavos. Ausente quando o produto não tem custo.
margin_bpsinteger
Margem sobre o novo preço em pontos-base: (novo - custo) / novo. Ausente sem custo. 3172 é 31,72%.
items_without_costinteger
Quantos itens não têm custo e portanto ficaram sem margem.

Erros

StatusQuandoCorpo
400JSON inválido{"error":"invalid request body","detail":"..."}
500Id que não é UUID ou falha de consulta{"error":"failed to simulate","detail":"..."}
Custo zero conta como custo conhecido

Um produto com custo cadastrado como 0 aparece com cost_cents: 0 e margem de 100% (10000). Revise produtos com custo zerado antes de confiar na margem.

Aplicar o reajuste

Faz o mesmo cálculo da simulação e grava os novos preços, numa transação. Publica o evento price_list.adjusted. Vale na hora para tabelas ativas.

POST/api/v1/admin/b2b/price-lists/{id}/adjustAdmin

Aplica um reajuste em massa

Parâmetros de caminho

iduuidobrigatório
Id da tabela.

Corpo da requisição

delta_bpsintegerobrigatório
Variação em pontos-base (600 = +6%).
except_category_idsarray
Categorias (UUID) que ficam de fora.
round_to_centsinteger
Arredondamento em centavos, como no simulador.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/b2b/price-lists/3f0c1a52-8d7e-4c1b-9a64-2b5e7d9c1a10/adjust" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "delta_bps": 600, "round_to_cents": 10 }'

Resposta

200Reajuste aplicado
json
{ "items_changed": 1 }

Campos da resposta

items_changedinteger
Quantidade de linhas alteradas. Em produtos com mais de uma linha de preço fixo o número pode ser maior que a quantidade de itens simulados, porque o reajuste regrava todas as linhas do produto a cada passo.

Erros

StatusQuandoCorpo
400JSON inválido{"error":"invalid request body","detail":"..."}
500Id que não é UUID ou falha de gravação (nada é aplicado){"error":"failed to adjust price list","detail":"..."}
Não há desfazer

O reajuste sobrescreve os preços e a API não guarda o valor anterior. Rode o simulador, guarde um export da tabela e, para mudanças grandes, aplique em uma cópia antes de ativá-la.

Prévia de preço para um cliente

Pergunta à plataforma qual preço um produto teria para um cliente numa quantidade. Usa exatamente o mesmo cálculo da vitrine, do carrinho e do checkout (tabelas, degraus, regras B2B e cotações), então o número nunca diverge do que o comprador vê. O id da tabela no caminho serve para dizer se esta tabela foi a vencedora.

POST/api/v1/admin/b2b/price-lists/{id}/preview-priceAdmin

Prévia do preço de um produto para um cliente

Parâmetros de caminho

iduuidobrigatório
Id da tabela que você quer testar.

Corpo da requisição

product_iduuidobrigatório
Produto.
customer_iduuid
Cliente (usuário). Sem ele nenhuma tabela se aplica e o preço volta ao base, porque a tabela depende de empresa, grupo ou estado do comprador.
quantityintegerpadrão: 1
Quantidade comprada. Valores menores que 1 viram 1.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/b2b/price-lists/3f0c1a52-8d7e-4c1b-9a64-2b5e7d9c1a10/preview-price" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "5b6f1948-356b-4739-adfc-af8045b7b769",
    "customer_id": "220b672c-90fe-4841-ae86-bd4f1ace982e",
    "quantity": 10
  }'

Resposta

200Preço resolvido
json
{
  "list_match": true,
  "result": {
    "product_id": "5b6f1948-356b-4739-adfc-af8045b7b769",
    "quantity": 10,
    "base_price": 28990,
    "unit_price": 26250,
    "total": 262500,
    "price_list_id": "3f0c1a52-8d7e-4c1b-9a64-2b5e7d9c1a10",
    "source": "price_list",
    "min_order_qty": 1
  }
}

Campos da resposta

list_matchboolean
true quando o preço vencedor veio desta tabela. false quando outra regra ou outra tabela de prioridade maior ganhou, ou quando nenhuma tabela se aplica.
result.base_priceinteger
Preço base do produto, em centavos.
result.unit_priceinteger
Preço unitário final, em centavos.
result.totalinteger
unit_price vezes quantity, em centavos.
result.sourcestring
basetierb2b_rulequoterep_discountprice_list
De onde veio o preço: base do produto, degrau de quantidade, regra B2B avulsa, cotação aceita, desconto de representante ou tabela de preço.
result.price_list_iduuid
Tabela vencedora. Só aparece quando source é price_list.
result.discount_bpsinteger
Desconto aplicado em pontos-base, quando o preço vem de uma regra por desconto.
result.rule_idinteger
Id da regra B2B que casou, quando houver.
result.min_order_qtyinteger
Quantidade mínima de compra do produto.

Erros

StatusQuandoCorpo
400JSON inválido{"error":"invalid request body","detail":"..."}
400Sem product_id{"error":"product_id is required"}
404Tabela inexistente{"error":"price list not found"}
404Produto inexistente{"error":"product not found"}
422Falha ao calcular{"error":"failed to compute price","detail":"..."}
A prévia só enxerga tabelas em vigor

A prévia usa o cálculo real, então uma tabela em draft, archived ou fora da vigência não vence: o resultado volta com list_match: false. Para testar, ative a tabela (de preferência uma cópia, com atribuições apenas para clientes de teste) e rode a prévia para um cliente de cada alvo atribuído. Se list_match vier false com a tabela ativa, a atribuição não alcançou o cliente: confira o target_id, a vigência e se outra tabela de maior prioridade está ganhando.

Veja também

  • Itens da tabela
  • Atribuições
  • Ativar, arquivar e duplicar
Anterior
Atribuições de tabela de preço
Próxima
Pedidos programados
Nesta página
  • Simular um reajuste
  • Exemplo de requisição
  • Resposta
  • Erros
  • Aplicar o reajuste
  • Exemplo de requisição
  • Resposta
  • Erros
  • Prévia de preço para um cliente
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também