Resumo em 30 segundos #
- Clientes podem nascer na loja (o próprio cliente se cadastra) ou no ERP.
- Cliente novo na loja → a ViaShopModa avisa o ERP por webhook. O ERP cria o cliente e informa o código dele com
cliente/associar_codexterno. - Cliente novo no ERP →
cliente/cadastrar. Se o CPF, CNPJ ou e-mail já existir, a loja não cadastra de novo e devolve ocod_clienteexistente (HTTP 409). - Alterações →
cliente/atualizar, enviando só os campos que mudaram.
Fluxo: cliente se cadastra na loja #
Cliente Loja (ViaShopModa) ERP
| cadastra-se | |
|-------------------->| |
| |-- webhook: cliente novo ----------->| cria o cliente
| |<-- POST cliente/associar_codexterno-| {"email":"...", "cod_externo":"C-1020"}Fluxo: cliente nasce no ERP #
ERP Loja (ViaShopModa)
|-- POST cliente/cadastrar ------------------>|
|<-- 200 {cod_cliente:"MTIz", cadastro:true} -| cliente novo
|<-- 409 {cod_cliente:"MTIz", cadastro:false}-| já existia (mesmo CPF/CNPJ ou e-mail)Nos dois casos, guarde o cod_cliente devolvido.
Regras importantes #
- Identidade: o cliente é único por CPF/CNPJ e por e-mail.
- Tipo de pessoa:
Fexige CPF e dados pessoais;Jexige CNPJ e dados da empresa;E(exterior) dispensa documento e endereço brasileiro. - Liberação:
liberado_para_comprar: "S"libera o login. Sem isso, o cadastro fica aguardando a loja liberar. Em cidades ou estados com cliente exclusivo, oSpode ser trocado por "aguardando", com aviso. - Vendedor: envie
vendedorcomid,emailouwhatsappde um vendedor (vejavendedores/consultar), ou"sortear"para a loja escolher em rodízio. - O que a atualização não muda: tipo de pessoa, nome, empresa, responsável, IE, CPF, CNPJ, condição diferenciada, compra mínima, origem e moeda. Esses só mudam pelo painel da loja.
- Consignado:
cliente/atualizar_consignadodefine o valor máximo de compra. - Etiquetas de CRM:
cliente/etiquetas, com os ids deetiquetas/consultar.
Leads #
Lead é quem deixou nome e e-mail ou WhatsApp, mas ainda não tem cadastro. A loja avisa por webhook; também é possível consultar com leads/consultar e cadastrar com leads/cadastrar (ex.: formulário de landing page).
Erros comuns de integração #
- Tratar o
409decliente/cadastrarcomo falha. É o aviso de que o cliente já existe — use ocod_clienteda resposta. - Usar
cliente/cadastrarpara atualizar. Usecliente/atualizar. - Converter
cod_clientepara número. É um texto codificado; use como recebido. - Enviar telefone de cliente do exterior sem o código do país (
+1...).