B2B, preços e pedidos programados

No comércio entre empresas (B2B) o mesmo produto raramente custa o mesmo para todo mundo. Um distribuidor paga menos que um varejista, quem compra 100 unidades paga menos que quem compra 1, e um estado pode ter condição própria. Uma tabela de preço (price list) é a política que guarda essas regras: um nome, uma vigência, uma prioridade e uma lista de itens com preço fixo ou desconto, atribuída a empresas, grupos de usuários ou estados.

Estas são as rotas do administrador da loja. A vitrine, o carrinho e o checkout consultam as mesmas tabelas para calcular o preço que cada comprador enxerga. O segundo tema da seção são os pedidos programados (standing orders, também chamados de "grade de entrega"): o comprador agenda compras recorrentes e a plataforma gera um pedido real a cada data. Aqui o administrador apenas supervisiona.

Como funciona

O ciclo de uma tabela

Uma tabela arquivada pode voltar a active. Só tabelas em draft ou archived podem ser excluídas (exclusão lógica).

Fluxo típico de integração

1. Crie a tabela
   POST /price-lists com nome, código único e prioridade. Ela nasce em rascunho.
2. Preencha os itens
   PUT /price-lists/{id}/items para poucas linhas, ou POST /import com um CSV para milhares.
3. Atribua a quem vale
   POST /price-lists/{id}/assignments com uma empresa, um grupo de usuários ou um estado.
4. Ative
   POST /price-lists/{id}/activate. A partir daí vitrine, carrinho e checkout usam a tabela.
5. Confira o preço
   POST /price-lists/{id}/preview-price mostra o preço que um cliente real enxerga. A prévia só considera tabelas ativas e em vigor.

Conceitos importantes

Como o preço de um comprador é escolhido

O comprador entra em uma tabela quando existe uma atribuição que o alcança: a empresa (conta corporativa) dele, um grupo de usuários ao qual pertence ou o estado do endereço padrão. Entre as linhas das tabelas que alcançam o comprador, têm o produto e cujo min_qty cabe na quantidade comprada, vence a de tabela com maior priority; em empate de prioridade, vence o menor preço unitário. As tabelas têm precedência sobre as regras de preço B2B avulsas e sobre o preço base.

Item: preço fixo ou desconto

Cada item é um par produto e quantidade mínima (min_qty), e tem exatamente um de dois campos: price_cents (preço unitário fixo) ou discount_bps (desconto sobre o preço base do produto, de 1 a 10000). Enviar os dois, ou nenhum, é recusado. O reajuste em massa só altera itens de preço fixo, porque os de desconto acompanham o preço base sozinhos.

Atribuição

Uma atribuição liga a tabela a um alvo: corporate_account (id da conta corporativa), usergroup (id do grupo) ou state (UF com 2 letras, gravada em maiúsculas). Se você enviar o id de um usuário como corporate_account, a plataforma troca pelo id da conta corporativa dele quando existir.

Pedido programado

Um pedido programado tem frequência (weekly, biweekly ou monthly), próxima data, itens e, opcionalmente, fim ou número de ocorrências. Uma rotina diária (05:00, horário de São Paulo) gera um pedido real por data, com o preço vigente no dia (não o do dia em que a grade foi criada). Três falhas seguidas pausam a grade sozinha.

Endpoints

Erros comuns

1. Ativar uma tabela e esquecer a atribuição. Ela fica active mas ninguém recebe o preço. Confira assignment_count na listagem.
2. Enviar price_cents e discount_bps juntos. O item é recusado: cada linha leva exatamente um dos dois.
3. Enviar preço em reais. A API usa centavos: 262.50 está errado, o certo é 26250. Só o CSV usa o formato brasileiro (262,50).
4. Reutilizar o code de outra tabela. O código é único entre as tabelas não excluídas; a criação falha com 400.
5. Tentar excluir uma tabela ativa. Arquive primeiro. A exclusão só vale para rascunho ou arquivada (409).
6. Esperar que a duplicata copie atribuições. A cópia leva os itens, mas nasce como rascunho e sem atribuições.
7. Passar um id mal formado. Um id que não é UUID devolve 500 (não 404); um UUID válido que não existe devolve 404. O id 0 devolve 400 invalid id parameter.

Próximos passos