Pular para o conteúdo
platform
PT EN

Casos de uso

Marketplace B2B: o caminho típico pela API

Cenário

Um operador reúne várias lojas no mesmo portal: filiais próprias, franquias ou sellers convidados. Cada loja vende com o próprio estoque, preço, frete e pagamento, dentro dos critérios gerais definidos pelo dono do portal.

O marketplace costuma ser consequência de digitalizar uma operação que já existe. As lojas e os estoques já estão lá, e é a integração de cada loja que os coloca no canal. Por isso a qualidade do dado que cada loja envia (estoque, preço e andamento do pedido) é uma das condições de que a operação depende.

Na API há dois papéis. A loja integra o que é dela: envia estoque e preço e atende os pedidos em que é a fornecedora. A loja de origem do pedido, que no marketplace é o operador, consulta os pedidos que nasceram nela por rotas próprias. O pedido do cliente se divide em um pedido por loja, e também por depósito da mesma loja.

As dores que levam a esta integração

Perco venda por falta de sortimento e não consigo ampliar sem comprar estoque

Como aparece

"O cliente pede, a gente não tem, e ele compra do concorrente. O item existe no meu fornecedor, mas não tem como eu vender."

Por que acontece

O portal e o ERP assumem que só se vende o que está no estoque próprio. Vender estoque de terceiro exige que o parceiro configure preço, frete e disponibilidade dentro das regras da companhia, e falta a camada que permita isso sem abrir mão da governança.

O preço negociado de cada cliente não cabe no portal

Como aparece

"Cada cliente tem o preço dele, ninguém consegue colocar isso no site."

Por que acontece

A transação B2B move cinco variáveis ao mesmo tempo (preço, entrega, pagamento, quantidade e composição), e plataformas de e-commerce tratam isso como campos estáticos de formulário.

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 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.

O que normalmente se integra

EntidadeSentidoFrequência típicaEndpoints e eventos
Estoque e preço de cada loja A mesma loja pode vender o mesmo produto em depósitos diferentes, com preço e quantidade diferentes, e o frete é calculado a partir do endereço do depósito de origem. Seu sistema para a CWS Platform Contínua, em lotes pequenos
Clientes O marketplace pode ocultar o e-mail e o telefone do cliente para os sellers; nesse caso a API devolve os dados mascarados. Depende de ativação. Nos dois sentidos Carga inicial e a cada alteração de cadastro
Contratos e regras de preço por loja Um contrato pode ser limitado por marketplace, por UF de destino e por filiais. Seu sistema para a CWS Platform Por vigência do contrato e quando a política muda
Limite de crédito O limite pode valer por loja ou para a matriz inteira. No segundo caso o cliente usa o limite em qualquer filial, e cada loja recebe o débito separado para conciliação. Seu sistema para a CWS Platform A cada evento financeiro que altera o limite
Pedidos da loja fornecedora CWS Platform para o seu sistema Por evento (webhook) ou por consulta periódica
Status, nota fiscal e acompanhamento dos itens Cada pedido de loja tem produtos, valor, frete, prazo de preparo e nota fiscal próprios. Seu sistema para a CWS Platform A cada mudança de etapa do pedido
Pedidos originados no marketplace É a visão da loja de origem: os pedidos que os clientes dela fizeram, incluindo os atendidos por outras lojas. CWS Platform para o seu sistema Por consulta periódica
Saldo de cashback O programa de cashback depende de ativação. As rotas devolvem o saldo consolidado, o saldo por cliente e o extrato de um cliente. CWS Platform para o seu sistema Por consulta, para conciliação
Comissão e divisão do pagamento O contrato de cada loja define o percentual do marketplace por cenário de venda, e o valor do pedido é dividido por loja. Não está na coleção pública. Configuração no painel No contrato de cada loja com o marketplace
Produtos e frete de cada loja Cada loja mantém os próprios produtos e as próprias tabelas de frete no painel. A base de conhecimento também descreve criação de produto por API: não está na coleção pública. Configuração no painel Na entrada da loja e quando o sortimento muda

Fluxo típico

  1. 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. 2

    Enviar estoque e preço de cada loja

    Cada loja envia o próprio estoque e preço, por depósito, em lotes de 1 a 50 itens. Uma matriz pode enviar em nome das filiais vinculadas a ela, com a filial na rota.

  3. 3

    Publicar a condição comercial de cada loja

    Contratos e regras de preço sobem por loja. O contrato fixa o preço do item para os clientes vinculados e pode ser limitado por marketplace, por UF de destino e por filiais.

  4. 4

    Receber o pedido de cada loja

    Itens de lojas diferentes ficam no mesmo carrinho, cada loja com as próprias opções de frete. Fechada a compra, o pedido do cliente se divide em um pedido por loja, e a plataforma avisa cada loja por webhook. A loja busca o detalhe do pedido em que é a fornecedora.

  5. 5

    Devolver o andamento por loja

    A loja fornecedora move o próprio pedido: pronto para envio, enviado com o rastreio, e a nota fiscal já emitida. Cada pedido de loja tem a sua nota.

  6. 6

    Acompanhar o conjunto

    O operador lista os pedidos originados no marketplace e, a partir do pedido do cliente, vê os pedidos de loja em que ele foi dividido.

  7. 7

    Reconciliar

    Uma consulta periódica da listagem por data de alteração confere se cada loja tem tudo o que a plataforma gerou, e recupera o que o webhook não entregou.

Variações

A loja de origem move o pedido

Depende de ativação

A coleção traz rotas para a loja de origem atualizar o status, anexar a nota e informar o acompanhamento de um pedido que nasceu nela. A atualização pela loja de origem depende de uma configuração da própria loja, liberada pela CWS Platform; sem ela a resposta é 422.

Cancelamento pela loja fornecedora

Quando o pedido nasceu em outra loja, o cancelamento pela fornecedora depende de a loja de origem ter habilitado essa permissão. Enquanto ela não liberar, o cancelamento responde 422, e quem cancela é a loja de origem.

O mesmo produto em várias lojas

Depende de ativação

Quando várias lojas vendem o mesmo produto, a página mostra uma oferta principal e as demais ofertas. A oferta principal sai pelo menor preço ou pela loja mais próxima do cliente, conforme a configuração do marketplace. Para a integração nada muda: cada loja segue enviando o próprio estoque e preço.

Matriz com filiais

Quando o marketplace é uma matriz com filiais, 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.

Orçamento respondido pela loja

Depende de ativação

Com o orçamento ativo no marketplace, cada loja lista as solicitações pendentes para os produtos que vende e responde com preço e prazo, ou recusa. A recusa não se desfaz.

Sem webhook, só por consulta

A loja que 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.

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 arquiteto

Módulos da plataforma envolvidos

Gerado a partir da coleção pública da API, publicada em 04/09/2026: api-docs.cws.digital.