Casos de uso
Varejo complexo e B2B2C: o caminho típico pela API
Cenário
Uma rede vende para empresa e para consumidor final ao mesmo tempo, com lojas em várias praças, balcão, vendedor externo e estoque local. Por fora parece varejo; por dentro há grupo de clientes, crédito faturado e preço que muda por região.
A unidade que organiza a integração é o depósito. O mesmo produto pode ter preço e quantidade diferentes em cada depósito, o frete parte do endereço do depósito de origem, e cada depósito decide para quem os seus produtos aparecem.
Os canais convivem em vez de competir. O balcão e o vendedor externo atendem dentro do portal, com as condições do cliente, e a venda feita fora da plataforma pode gerar cashback para uso no canal digital, o que traz o cliente do balcão para o portal próprio.
As dores que levam a esta integração
O mesmo produto aparece com três preços diferentes nos canais
Como aparece
"O mesmo produto aparece com três preços diferentes: no meu portal, na minha venda direta e no marketplace."
Por que acontece
Vários canais (indústria, distribuidor, representante, loja, marketplace e venda direta) disputam o mesmo cliente e o mesmo produto sem governança de preço e de comissionamento.
Uso quatro ou cinco sistemas para um único atendimento complexo
Como aparece
"Para fechar um pedido complexo eu abro cinco sistemas."
Por que acontece
A operação é fragmentada entre ERP, catálogo, portal, crédito e fiscal, sem uma orquestração unificada.
Simplificamos o preço porque o sistema não aguenta
Como aparece
"A gente nivelou a tabela porque manter preço diferente por filial e por cliente virou impossível de administrar."
Por que acontece
O sistema de origem não sustenta preço por depósito cruzado com o preço de cada cliente, de cada categoria e de cada condição, e a empresa achata a política para conseguir administrar.
O que normalmente se integra
| Entidade | Sentido | Frequência típica | Endpoints e eventos |
|---|---|---|---|
| Estoque e preço por loja e depósito O depósito é criado antes de preço e quantidade, e cada par de produto e depósito tem o seu estoque. | Seu sistema para a CWS Platform | Contínua, em lotes pequenos | |
| Clientes e grupos de clientes É o grupo que separa a revenda do consumidor final no mesmo portal: as regras de preço e as condições de pagamento usam o grupo como critério. | Nos dois sentidos | Carga inicial e a cada alteração de cadastro | |
| Regras de preço por grupo e por região Uma regra pode ser elegível por tipo de cliente, por contribuinte de ICMS e pelo par UF do depósito e UF do destinatário. | Seu sistema para a CWS Platform | Quando a política comercial muda |
|
| Limite de crédito do cliente empresa O limite de crédito pode ser combinado com cartão ou com boleto no mesmo pedido. | Seu sistema para a CWS Platform | A cada evento financeiro que altera o limite | |
| Vendedores de balcão e externos | Seu sistema para a CWS Platform | Quando a equipe ou a carteira muda | |
| Cashback da venda feita fora da plataforma O seu sistema informa quem comprou, o número do pedido e os itens; o programa calcula quanto cada item rende. A data de liberação é programável, e o crédito pode ser cancelado enquanto não foi liberado. Depende de ativação. | Seu sistema para a CWS Platform | A cada venda de balcão que gera cashback | |
| Pedidos | CWS Platform para o seu sistema | Por evento (webhook) ou por consulta periódica | |
| Status, nota fiscal e rastreio A plataforma não emite a nota fiscal: recebe os dados e o XML da nota já emitida. O fluxo de status é de mão única. | Seu sistema para a CWS Platform | A cada mudança de etapa do pedido | |
| Retirada na loja, frete e pagamento no caixa Cada endereço de retirada é ligado aos depósitos que o abastecem, e as tabelas de frete são por transportadora e depósito. A base de conhecimento também descreve a gestão de pagamento no caixa por API: não está na coleção pública. | Configuração no painel | Na implantação e quando a operação muda | |
Fluxo típico
- 1
Autenticar
O integrador obtém o token de acesso com o usuário de integração da loja e o envia como Bearer nas demais chamadas. O token vale 12 horas; ao expirar, a resposta é 401 e basta autenticar de novo.
- 2
Enviar estoque e preço por depósito
O seu sistema envia estoque e preço de cada depósito, em lotes de 1 a 50 itens. Quando uma matriz integra pelas lojas, a loja vai na rota.
- 3
Carregar clientes e grupos
O seu sistema cria os clientes, cria os grupos que separam os públicos e vincula cada cliente ao grupo dele.
- 4
Publicar as regras de preço
As regras de preço sobem com os critérios de cada público e de cada região. Entre as regras não cumulativas vale a de maior prioridade, e as cumulativas se aplicam sobre o resultado.
- POST Criar Regra de Preço
- 5
Informar o crédito do cliente empresa
O seu sistema informa o limite de crédito de quem compra faturado. O pedido com saldo suficiente é aprovado automaticamente.
- 6
Cadastrar os vendedores
O seu sistema cadastra os vendedores de balcão e externos e vincula os clientes de cada um. No atendimento valem os endereços, o limite de crédito, os preços de contrato e as regras de preço do cliente.
- 7
Receber o pedido e devolver o andamento
Um pedido com itens de lojas ou depósitos diferentes se divide em um pedido por loja e por depósito, cada um com frete e nota fiscal próprios. A plataforma avisa por webhook, e o seu sistema devolve o status de cada um.
- 8
Registrar a venda feita fora da plataforma
Quando o programa de cashback está ativo, o seu sistema informa a venda de balcão e o programa registra o crédito do cliente, para uso no portal. Se a venda for desfeita, o seu sistema cancela a concessão enquanto ela não foi liberada.
Variações
Preço da região, estoque de outro lugar
A plataforma pode cobrar o preço da loja mais próxima do endereço de entrega mesmo quando o pedido sai de um centro de distribuição, com recálculo e alerta quando o cliente troca o endereço. É configuração, sem rota na API.
Uma loja ou um depósito por pedido
Depende de ativação
A loja pode restringir cada pedido a um único depósito ou a uma única loja, para os casos em que crédito e faturamento precisam sair em uma só nota. Com a restrição, a integração recebe um pedido só.
Pagamento no caixa
Depende de ativação
No pagamento no caixa o cliente divide o valor entre várias formas e condições. O pedido nasce com um status inicial próprio de pagamento na loja, gerado pela plataforma, e a aprovação do pagamento é feita pela loja.
Matriz com lojas
Quando uma matriz integra pelas lojas, os contratos de cada loja têm rotas próprias, com a loja na rota. Grupos de clientes criados na matriz podem ser usados pelas filiais nas regras delas.
Marketplaces de terceiros como canal
Depende de ativação
A loja pode gerar um feed do catálogo para marketplaces e outros canais de terceiros, e usá-los como canal de demanda. Não está na coleção pública.
Impostos calculados no ERP
Depende de ativação
Quando a regra fiscal mora no ERP, a plataforma chama o endpoint de tributos do ERP antes de fechar o pedido e usa os valores devolvidos, por item. É uma chamada síncrona, e o seu tempo de resposta entra no tempo do carrinho.
- Callback Callback de cálculo de impostos
Quadro de possibilidades
Este é um caminho comum, não o único.
A CWS Platform chega ao mesmo objetivo por configuração, por API ou pela combinação das duas, e a melhor forma depende da sua operação, do seu ERP e das suas regras. Converse com um arquiteto da CWS Platform para desenhar a integração do seu caso.
Conversar com um arquitetoMódulos da plataforma envolvidos
- Varejo Complexo: empresa e consumidor final no mesmo portal
- Inventory Hub: o estoque por loja e depósito
- Pricing Engine: regras de preço por grupo e por região
- Logistics Engine: frete por depósito e retirada na loja
- Checkout & Payments: crédito, multipagamento e pagamento no caixa
- Marketing Suite: o programa de cashback
- Sales Hub: o balcão e o vendedor externo no portal
Gerado a partir da coleção pública da API, publicada em 04/09/2026: api-docs.cws.digital.