# Clientes

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

Fonte: https://api.viashopmoda.com.br/docs-api/?p=guias/clientes · Atualizado em 16/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`](https://api.viashopmoda.com.br/docs-api/?p=recursos/cliente/associar_codexterno&formato=md).
- Cliente novo no ERP → [`cliente/cadastrar`](https://api.viashopmoda.com.br/docs-api/?p=recursos/cliente/cadastrar&formato=md). 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`](https://api.viashopmoda.com.br/docs-api/?p=recursos/cliente/atualizar&formato=md), enviando só os campos que mudaram.

## Fluxo: cliente se cadastra na loja

```text
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

```text
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`](https://api.viashopmoda.com.br/docs-api/?p=recursos/vendedores/consultar&formato=md)), 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`](https://api.viashopmoda.com.br/docs-api/?p=recursos/cliente/atualizar_consignado&formato=md) define o valor máximo de compra.
- **Etiquetas de CRM:** [`cliente/etiquetas`](https://api.viashopmoda.com.br/docs-api/?p=recursos/cliente/etiquetas&formato=md), com os ids de [`etiquetas/consultar`](https://api.viashopmoda.com.br/docs-api/?p=recursos/etiquetas/consultar&formato=md).

## 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`](https://api.viashopmoda.com.br/docs-api/?p=recursos/leads/consultar&formato=md) e cadastrar com [`leads/cadastrar`](https://api.viashopmoda.com.br/docs-api/?p=recursos/leads/cadastrar&formato=md) (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...`).
