API ViaShopModa documentação

Clientes

Como os cadastros de clientes circulam entre a loja e o ERP — cadastro, atualização, duplicidade, consignado, vendedor e etiquetas.

Ver como Markdown Atualizado em 18/11/2026

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 o cod_cliente existente (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: F exige CPF e dados pessoais; J exige 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, o S pode ser trocado por "aguardando", com aviso.
  • Vendedor: envie vendedor com id, email ou whatsapp de um vendedor (veja vendedores/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_consignado define o valor máximo de compra.
  • Etiquetas de CRM: cliente/etiquetas, com os ids de etiquetas/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 409 de cliente/cadastrar como falha. É o aviso de que o cliente já existe — use o cod_cliente da resposta.
  • Usar cliente/cadastrar para atualizar. Use cliente/atualizar.
  • Converter cod_cliente para número. É um texto codificado; use como recebido.
  • Enviar telefone de cliente do exterior sem o código do país (+1...).