# Cadastrar cliente

> Cria um cliente pessoa física, jurídica ou do exterior; se o CPF/CNPJ ou e-mail já existir, devolve o cliente existente (HTTP 409).

Fonte: https://api.viashopmoda.com.br/docs-api/?p=recursos/cliente/cadastrar · Atualizado em 18/11/2026


## O que faz

Cadastra um cliente na loja. Antes, procura duplicidade por **CPF/CNPJ ou e-mail**: se encontrar, não cadastra e devolve o `cod_cliente` existente.

## Requisição

| | |
|---|---|
| **Método** | `POST` |
| **URL** | `https://api.viashopmoda.com.br/via/cliente/cadastrar/{TOKEN}` |
| **Corpo** | Objeto JSON `{ ... }`, cabeçalho `Content-Type: application/json` |
| **Token** | Substitua `{TOKEN}` pelo token da loja. Ele vai no caminho da URL, não em cabeçalho. |


## Campos

| Campo | Tipo | Obrigatório | Limites | Descrição |
|---|---|---|---|---|
| `tipo_pessoa` | string | **sim** | máx. 1 | 'F' = pessoa física: , 'J' = pessoa jurídica e 'E' = cliente do exterior. |
| `email` | string | **sim** | mín. 5, máx. 150 | Usado como contato e para acessar a loja virtual. |
| `senha` | string | **sim** | mín. 4 | Senha para acessar a loja virtual. |
| `tipo_cliente` | string | **sim** | máx. 100 | Sempre se 'tipo_pessoa'=F será 'Revendedor' e 'tipo_pessoa'=J será 'Lojista'. Somente será alterado se enviado como 'Consignado' e o 'compra_maxima_atacado' passa a ser necessário o envio. |
| `cpf` | numeric | **sim** | mín. 11, máx. 11 | Somente números. Obrigatório quando pessoa física. |
| `nome_completo` | string | **sim** | máx. 150 | Nome completo do cliente. Obrigatório quando pessoa física. |
| `rg` | string | não | máx. 25 | Caso inexistente enviar 'Isento'. Obrigatório quando pessoa física. |
| `data_nascimento` | date | **sim** | máx. 10 | Formato 'aaaa-mm-dd'. Obrigatório quando pessoa física. |
| `sexo` | string | **sim** |  | 'Masculino', 'Feminino' ou 'Nenhum'. Obrigatório quando pessoa física. |
| `cnpj` | string | **sim** | mín. 14, máx. 14 | Somente números. Obrigatório quando pessoa jurísica. |
| `nome_empresa` | string | **sim** | máx. 150 | Nome fantasia da empresa. Obrigatório quando pessoa jurídica. |
| `responsavel_empresa` | string | **sim** | máx. 150 | Nome do responsável pela empresa. Obrigatório quando pessoa jurídica. |
| `ie` | string | **sim** | máx. 25 | Caso inexistente enviar 'Isento'. Obrigatório quando pessoa jurídica. |
| `moeda` | string | não | máx. 3 | Para os clientes do exterior, é possível alterar sua moeda enviando o código no padrão ISO 4217. USD para dolar, EUR para euro e etc. |
| `condicao_diferenciada` | double | não | máx. 11 | Representa a porcentagem de acréscimo ou desconto nos preços dos produtos. |
| `compra_minima_atacado` | double | não | máx. 11 | Valor minimo para compra de atacado. |
| `compra_maxima_atacado` | double | não | máx. 11 | Usado para quando tipo_cliente=Consignado, limitando o valor máximo a ser comprado. Se não enviado será zero. |
| `cep` | numeric | **sim** | mín. 8, máx. 8 | Somente números no formato '37001000'. |
| `endereco` | string | **sim** | máx. 150 | Caso cliente do exterior, será usado como endereço completo. |
| `numero` | string | **sim** | máx. 10 | Não utilizado para clientes do exterior. |
| `complemento` | string | não | máx. 50 | Não utilizado para clientes do exterior. |
| `bairro` | string | **sim** | máx. 50 | Não utilizado para clientes do exterior. |
| `cidade` | string | **sim** | máx. 50 |  |
| `estado` | string | **sim** | máx. 2 | Sigla do estado com dois caracteres. Não utilizado para clientes do exterior. |
| `pais` | string | não | máx. 50 | Para países diferente de 'Brasil' usar o campo cod_pais. |
| `cod_pais` | string | não | máx. 2 | Código do país no padrão ISO-2, se não enviado será utilizado 'BR'. |
| `codigo_ddi` | string | não | mín. 1, aceita null | Se não enviado sempre será 55. |
| `telefone_celular` | string | **sim** | máx. 50 | Se não enviado no formato: '+{CODIGO_DDI}{NUMERO_TELEFONE}' será acrescentado o DDI (relativo ao cod_pais) ao número enviado. |
| `operadora_celular` | string | não | máx. 20 | Nome da operadora de telefonia. Se não enviado será cadastrado 'Outras' |
| `utm_source` | string | não | máx. 70 | Se enviado é necessário enviar utm_medium e utm_campaign |
| `utm_medium` | string | não | máx. 70 | Se enviado é necessário enviar utm_source e utm_campaign |
| `utm_campaign` | string | não | máx. 70 | Se enviado é necessário enviar utm_source e utm_medium |
| `crm` | array | não |  | Frases relacionadas ao CRM do cliente |
| `assinar_newsletter` | string | não | máx. 1 | 'S' ou 'N', se não enviado será cadastrado 'N'. |
| `data_cadastro` | datetime | não | máx. 19 | Data de cadastro do cliente. Padrão DATETIME 'aaaa-mm-dd hh:mm:ss'. |
| `liberado_para_comprar` | string | não | máx. 1 | Padrão 'N'. Podendo ser 'S' ou 'N'. Onde 'S' está liberado e 'N' NÃO está liberado. Observações: (1) O 'N' não signifca bloqueio algum, mas a não possibilidade de login. (2) Se não enviado será cadastrado como 'N'. (3) Se enviado como 'S' poderá ser alterado caso a cidade ou o estado enviado for considerado uma região exclusiva. |
| `vendedor` | object | não |  | Objeto para consulta do vendedor. Poderá ser usado: vendedor.id, vendedor.email ou vendedor.whatsapp para localizar o vendedor a ser atrelado ao cliente. Para consultar o vendedor [vendedores/consultar](https://api.viashopmoda.com.br/docs-api/?p=recursos/vendedores/consultar&formato=md). Se enviar 'sortear' será sorteado entre os vendedores habilitados. Se não existir, cadastro não será vinculado a nenhum vendedor. |


## Regras (valem acima da tabela)

**Obrigatórios conforme `tipo_pessoa`:**

| `tipo_pessoa` | Exige | Dispensa | `tipo_cliente` padrão |
|---|---|---|---|
| `F` (física) | `cpf`, `nome_completo`, `data_nascimento`, `sexo` (`rg` pode ser `"Isento"`) | dados da empresa | `Revendedor` |
| `J` (jurídica) | `cnpj`, `nome_empresa`, `responsavel_empresa` (`ie` pode ser `"Isento"`) | dados pessoais | `Lojista` |
| `E` (exterior) | — | CPF, CNPJ, RG, CEP, número, complemento, bairro, estado | `Lojista` |

Sempre obrigatórios: `tipo_pessoa`, `email`, `senha`, `endereco`, `cidade`, `telefone_celular`. Para `F` e `J`, também `cep`, `numero`, `bairro` e `estado`. `tipo_cliente` pode ser omitido (a loja usa o padrão da tabela acima).

- `tipo_cliente: "Consignado"` exige `compra_maxima_atacado`.
- `liberado_para_comprar`: `"S"` libera o login. Qualquer outro valor (ou ausente) deixa aguardando liberação da loja. Em cidade/estado com cliente exclusivo, o `S` vira "aguardando" com aviso em `msg_alerta`.
- `vendedor`: objeto com **um** de `id`, `email` ou `whatsapp` de um vendedor ([`vendedores/consultar`](https://api.viashopmoda.com.br/docs-api/?p=recursos/vendedores/consultar&formato=md)), ou o texto `"sortear"` (rodízio entre os vendedores habilitados). Não encontrado → cliente sem vendedor, com aviso.
- UTM só é gravado se vierem os três: `utm_source`, `utm_medium`, `utm_campaign`.
- Telefone de cliente do exterior: com o código do país, ex.: `+11234567890`.
- Nome gravado em MAIÚSCULAS.

## Exemplo

```json
{
  "tipo_pessoa": "F",
  "nome_completo": "Maria José da Silva",
  "cpf": "12345678909",
  "data_nascimento": "1986-02-15",
  "sexo": "Feminino",
  "rg": "Isento",
  "email": "maria@exemplo.com.br",
  "senha": "troque123",
  "cep": "37002000",
  "endereco": "Avenida Imigrantes",
  "numero": "10",
  "bairro": "Centro",
  "cidade": "Varginha",
  "estado": "MG",
  "telefone_celular": "35988887777",
  "liberado_para_comprar": "S",
  "vendedor": { "email": "vendedora@loja.com.br" }
}
```

## Respostas

Cadastrado (HTTP 200):

```json
{ "retorno": true, "cadastro": true, "msg": "...", "cod_cliente": "MTIz", "cod_vendedor": "Mg" }
```

Já existia (HTTP 409 — não é falha):

```json
{ "retorno": true, "status": 409, "cadastro": false, "cod_cliente": "MTIz", "cod_vendedor": "Mg" }
```

`cod_cliente` e `cod_vendedor` são textos codificados: guarde e use como recebidos.

Erros de validação vêm em `msg_erro` com o nome do campo (ex.: tamanho, formato).

## Pode reenviar?

Sim: o reenvio devolve `409` com o mesmo `cod_cliente`. Os dados enviados no reenvio **não** atualizam o cadastro — use [`cliente/atualizar`](https://api.viashopmoda.com.br/docs-api/?p=recursos/cliente/atualizar&formato=md).

## Onde entra no processo

Guia [Clientes](https://api.viashopmoda.com.br/docs-api/?p=guias/clientes&formato=md).
