Casos de uso
Integração ERP: o caminho típico pela API
Cenário
A empresa já tem um ERP, e é nele que moram o cadastro, o estoque, o fiscal e o financeiro. A CWS Platform entra como a camada em que o cliente e o vendedor negociam e fecham o pedido. A integração existe para que os dois lados trabalhem com o mesmo dado sem redigitação.
No desenho mais comum o ERP continua sendo o sistema de registro. Ele envia para a plataforma o que o canal precisa mostrar (estoque, preço, clientes, limite de crédito, contratos) e recebe de volta o que o canal produz (pedidos), devolvendo depois o andamento de cada pedido: status, nota fiscal e rastreio.
A plataforma não emite a nota fiscal. Ela recebe do ERP os dados e o XML da nota já emitida.
As dores que levam a esta integração
O portal mostra estoque e preço que divergem do ERP
Como aparece
"O portal mostra estoque que já não existe."
Por que acontece
O ERP trabalha em janelas de processamento, e a verdade do sistema de registro não chega ao canal de venda no ritmo em que o cliente compra.
O ERP é forçado a atender o canal de venda em tempo real
Como aparece
"Cada mudança simples vira um projeto de TI."
Por que acontece
O ERP foi desenhado para registrar. Quando ele também precisa responder ao cliente na hora, cada regra comercial nova vira desenvolvimento dentro do sistema que guarda o fiscal e o contábil.
Cada mudança na política comercial vira um projeto do integrador
Como aparece
"Para criar uma regra nova de desconto eu abro um chamado, o integrador orça, desenvolve e testa, e a campanha já passou."
Por que acontece
O preço de cada cliente, a alçada, o crédito e a regra fiscal são desenvolvidos no projeto, fora do produto, e cada customização precisa ser mantida e retestada a cada mudança de política.
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 Duas possibilidades: a rota da coleção, de 1 a 50 itens com resposta por item, para a atualização contínua; e POST /api/v1/stocks/batch, até 200 itens em fila assíncrona, para a carga grande. A segunda não está na coleção pública. Fonte da segunda rota: base de conhecimento da CWS Platform, confirmada pelo time de tecnologia em 06/10/2026. | ERP para a CWS Platform | Contínua, em lotes pequenos; carga grande em fila | |
| Clientes e endereços | Nos dois sentidos | Carga inicial e a cada alteração de cadastro | |
| Grupos de clientes | ERP para a CWS Platform | Quando a segmentação comercial muda | |
| Limite de crédito Na plataforma o limite é uma conta corrente do cliente, com saldo e extrato. | ERP para a CWS Platform | A cada evento financeiro que altera o limite | |
| Contratos de preço O contrato fixa o preço do item para os clientes vinculados; fora das condições do contrato vale o preço padrão da loja. | ERP para a CWS Platform | Por vigência do contrato | |
| Regras de preço | ERP para a CWS Platform | Quando a política comercial muda |
|
| Pedidos | CWS Platform para o ERP | Por evento (webhook) ou por consulta periódica | |
| Status, nota fiscal e rastreio Pronto para envio exige o número do pedido no ERP; os dados da nota podem ir junto, e a operação pode configurá-la como obrigatória no processo de venda; enviado leva o rastreio; cancelado exige o motivo do cancelamento. | ERP para a CWS Platform | A cada mudança de etapa do pedido no ERP | |
| Impostos por item | CWS Platform para o ERP | A cada cálculo, antes de fechar o pedido (depende de ativação) |
|
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
Carregar clientes e grupos
O ERP cria os clientes na plataforma, com os endereços, e os vincula aos grupos que a política comercial usa. O documento do cliente é a chave nas chamadas seguintes.
- 3
Enviar estoque e preço
Para a atualização contínua, o ERP envia estoque e preço em lotes de 1 a 50 itens. A resposta traz o resultado de cada item, então o integrador lê o corpo e reprocessa só o que foi recusado. Para a carga grande existe uma segunda rota,
POST /api/v1/stocks/batch, com até 200 itens por requisição e processamento em fila assíncrona; ela não está na coleção pública. Estoque enviado pela API reativa automaticamente o produto que estava fora de venda. - 4
Publicar a condição comercial
O ERP informa o limite de crédito de cada cliente e os contratos de preço, com os clientes e os produtos de cada contrato. A partir daí o pedido com saldo suficiente é aprovado automaticamente, e o preço de contrato vale para quem está vinculado a ele.
- 5
Receber o pedido
Depois que o pedido é gerado, a plataforma avisa o seu endpoint por webhook. O ERP busca o pedido completo pelo identificador recebido e o registra. Os status iniciais do pedido são gerados pela plataforma, e a integração move o pedido a partir deles.
- GET Buscar Detalhes do Pedido - Loja
- Webhook Webhook de pedidos
- 6
Devolver o andamento
Conforme o pedido anda no ERP, o integrador atualiza o status na plataforma: pronto para envio, com o número do pedido no ERP, e enviado, com o rastreio. O cancelamento exige o motivo. O fluxo é de mão única: um pedido enviado não volta para pronto para envio. O XML da nota emitida é enviado pelo endpoint de nota fiscal.
- 7
Reconciliar
Uma consulta periódica da listagem de pedidos por data de alteração confere se o ERP tem tudo o que a plataforma gerou, e recupera o que o webhook não entregou.
Variações
Matriz com filiais
Quando uma matriz integra por várias filiais, o estoque e os contratos de cada filial têm rotas próprias, com a filial na rota. A filial precisa estar vinculada à matriz do token; sem o vínculo a resposta é 403.
Operação de marketplace
Em um marketplace, a loja que vendeu é quem atualiza o status do próprio pedido, e o operador do marketplace consulta todos os pedidos do seu ambiente por rotas próprias. Um pedido do cliente pode gerar mais de um pedido de fornecedor.
Sem webhook, só por consulta
Quem ainda não tem um endpoint para receber webhooks integra pedidos só por consulta: lista os pedidos por status e por data de alteração e busca o detalhe de cada um.
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
Orçamento respondido pelo ERP
Quando o cliente pede orçamento, o integrador lista os orçamentos pendentes, responde com preço e condição a partir do ERP e acompanha o orçamento que virou pedido.
Prazo de entrega sob consulta
Para itens com prazo sob consulta, o integrador lista os itens do pedido que esperam prazo e informa o lead time de cada um a partir do ERP.
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
- Inventory Hub: o estoque por depósito que a integração alimenta
- Pricing Engine: contratos e regras de preço
- Checkout & Payments: limite de crédito como meio de pagamento
- OMS: os status do pedido e a nota fiscal
- CDL Workspace: onde a regra comercial é configurada
- APIs e Integrações: a visão geral de integração
Gerado a partir da coleção pública da API, publicada em 04/09/2026: api-docs.cws.digital.