Pular para o conteúdo
platform
PT EN

Referência da API · Clientes · Gestão de Clientes

Criar Novo Cliente

Método
POST
Rota
/v1/customer
URL base
https://ws.autorei.net
Token
Exige token Bearer
Testar no Postman

Abre esta requisição na documentação pública da API, a fonte oficial da referência.

Descrição

Cadastra um cliente na sua loja, com o endereço e, opcionalmente, os vínculos de tipo, grupo e tag de preço. O cliente criado já pode acessar a loja com o username e a senha informados.

Corpo da Requisição (JSON)

Campo Tipo Obrigatório Descrição
documentType string Sim cpf ou pf para pessoa física; cnpj ou pj para jurídica. Nenhum outro valor é aceito.
document string Sim CPF ou CNPJ, válido e coerente com o documentType. CNPJ alfanumérico é aceito.
username string Sim E-mail de acesso do cliente. Precisa ser um e-mail válido.
phone string Sim Telefone do cliente.
password string Sim Senha de acesso do cliente.
customerRegistrationAddress objeto Condicional Endereço de cadastro do cliente. Campos na tabela de endereço. Ver a regra abaixo.
addressList array Condicional Endereços de entrega do cliente. Campos na tabela de endereço. Ver a regra abaixo.
name string Não Nome ou razão social.
tradingName string Não Nome fantasia.
contactName string Não Nome do contato.
stateRegistration string Não Inscrição estadual.
cnae string Não CNAE do cliente.
paysIcms boolean Não Se é contribuinte de ICMS.
politicallyExposedPerson boolean Não Se é pessoa politicamente exposta.
federalEmployee boolean Não Se é servidor público federal.
optinTracking boolean Não Aceite de acompanhamento por mensagem.
trackingPhone string Não Telefone do acompanhamento.
forceChangePassword boolean Não Exige troca de senha no primeiro acesso.
passwordExpired boolean Não Marca a senha como expirada. Ausente vale false.
sendEmailNewCustomer boolean Não true dispara o e-mail de primeiro acesso ao cliente. A senha que você enviou nunca vai nesse e-mail.
ssoConfigId integer Não Configuração de SSO. Validada contra a sua loja.
priceRuleTags array Não Tags de preço, por nome.
customerTypeList array Não Tipos de cliente, por name ou externalId.
customerGroupList array Não Grupos de cliente, por name ou externalId.

Endereço (customerRegistrationAddress e cada item de addressList):

Campo Tipo Obrigatório Descrição
zipcode string Sim CEP do endereço. É o que resolve rua e bairro, ver a regra dos Correios.
number string Sim Número.
complement string Não Complemento.
street string Condicional Rua. Ver a regra dos Correios.
quarter string Condicional Bairro. Ver a regra dos Correios.
city string Não Cidade.
state string Não UF.
addressType string Não RESIDENTIAL ou BUSINESS. Não diferencia maiúsculas.
farmerStateRegistration string Não Inscrição estadual de produtor rural.
principal boolean Não Marca o endereço como principal.
name string Não Nome do endereço.
lat · lng number Não Coordenadas. Só aceitas se a sua loja tiver a funcionalidade de latitude/longitude habilitada.

Regras de negócio

customerRegistrationAddress e addressList guardam coisas diferentes

Os dois são endereço, mas vão para lugares distintos e enviar só um tem efeitos diferentes:

O que você envia O que o cliente recebe
Só customerRegistrationAddress Endereço de cadastro preenchido, e nenhum endereço de entrega, a lista fica vazia.
Só addressList, com um item principal: true Os endereços de entrega da lista, e o endereço de cadastro copiado do item principal.
Os dois Os endereços de entrega da lista e o endereço de cadastro que você informou.
Só addressList sem nenhum principal: true Recusado, não há endereço de cadastro a determinar.
Nenhum dos dois Recusado.

A recusa é Property [address] with value [] does not pass validation.

O CEP manda no endereço

O endereço é resolvido pelos Correios a partir do zipcode, e o que os Correios devolvem substitui o que você enviou em street, quarter, city e state. Do seu payload sobrevivem apenas number e complement, que os Correios não têm.

Os campos que você envia funcionam como reserva: cada um é usado só quando os Correios não trazem aquele dado para o CEP. Depois do merge, street e quarter não podem ficar vazios, se ficarem, a criação é recusada.

CEP não encontrado também é recusado, a menos que a sua loja tenha a validação de CEP desabilitada.

addressType inválido não é recusado

Um valor fora de RESIDENTIAL/BUSINESS cai no padrão RESIDENTIAL, sem erro.

Resposta · 200

O cliente criado, na raiz (sem o envelope customer). O código é 200, não 201.

Campo Tipo Descrição
id integer Id do cliente na CWS.
document string CPF ou CNPJ do cliente.
documentType string pf ou pj.
name string Nome ou razão social.
tradingName string Nome fantasia.
contactName string Nome do contato.
email string E-mail de acesso do cliente.
phone string Telefone, já formatado ((31) 99999-9999).
dateCreated string Data e hora do cadastro.
active boolean Se o cliente está ativo.
passwordExpired boolean Se a senha está marcada como expirada.
stateRegistration string Inscrição estadual. Vem "isento" quando não informada.
cnae string CNAE do cliente.
paysIcms boolean Se é contribuinte de ICMS.
genre string Gênero.
birthdate string Data de nascimento.
politicallyExposedPerson boolean Se é pessoa politicamente exposta.
federalEmployee boolean Se é servidor público federal.
optinTracking boolean Se aceita acompanhamento por mensagem.
trackingPhone string Telefone do acompanhamento.
optinPath string Origem do consentimento.
address array Endereços do cliente, no mesmo formato de GET /customer/addresses/:document.
customerRegistrationAddress objeto Endereço de cadastro.
priceRuleTag array Tags de preço do cliente. Vem null quando não há vínculo.
customerTypeList array Tipos de cliente vinculados. null quando não há vínculo.
customerGroupList array Grupos de cliente vinculados. null quando não há vínculo.

Erros

Código Quando
422 Falha de validação: {"status":"UNPROCESSABLE_ENTITY","message":"Property [campo] with value [x] does not pass validation"}. A mensagem nomeia o campo recusado, documentType, username, document, phone, password, ssoConfigId ou address.
401 Token ausente, malformado ou expirado.
400 Corpo não parseável, ou e-mail ou documento já cadastrado na sua loja.
401 Token ausente, malformado ou expirado.

Exemplo de requisição

curl --request POST 'https://ws.autorei.net/v1/customer' \
  --header 'Authorization: Bearer {{access_token}}' \
  --header 'Content-Type: application/json' \
  --data '{
  "documentType": "cpf",
  "document": "70041364856",
  "username": "ana.ribeiro@exemplo.com.br",
  "name": "Ana Paula Ribeiro",
  "contactName": "Ana Paula Ribeiro",
  "phone": "11987654321",
  "password": "sua-senha",
  "optinTracking": true,
  "trackingPhone": "11987654321",
  "customerRegistrationAddress": {
    "zipcode": "01310-100",
    "street": "Avenida Paulista",
    "number": "1578",
    "complement": "Conjunto 42",
    "quarter": "Bela Vista",
    "city": "São Paulo",
    "state": "SP",
    "addressType": "RESIDENTIAL",
    "principal": true
  }
}'

Respostas de exemplo

200Sucesso: pessoa física

{
  "id": 4470601,
  "document": "700.413.648-56",
  "documentType": "pf",
  "name": "Ana Paula Ribeiro",
  "tradingName": null,
  "contactName": "Ana Paula Ribeiro",
  "email": "ana.ribeiro@exemplo.com.br",
  "phone": "(11) 98765-4321",
  "dateCreated": "2026-09-01T13:42:07Z",
  "active": true,
  "passwordExpired": false,
  "stateRegistration": "isento",
  "cnae": null,
  "paysIcms": false,
  "genre": "F",
  "birthdate": "1988-04-12",
  "politicallyExposedPerson": false,
  "federalEmployee": false,
  "optinTracking": true,
  "trackingPhone": "(11) 98765-4321",
  "optinPath": "API",
  "address": [
    {
      "id": 4470701,
      "name": "Endereço de cadastro",
      "zipcode": "01310-100",
      "street": "Avenida Paulista",
      "number": "1578",
      "complement": "Conjunto 42",
      "quarter": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "principal": true,
      "addressType": "RESIDENTIAL",
      "farmerStateRegistration": null,
      "howToReachLocationDescription": null,
      "responsibleContact": null,
      "attributes": {},
      "dateCreated": "2026-09-01T13:42:07Z",
      "lastUpdated": "2026-09-01T13:42:07Z"
    }
  ],
  "customerRegistrationAddress": {
    "id": 4470701,
    "name": "Endereço de cadastro",
    "zipcode": "01310-100",
    "street": "Avenida Paulista",
    "number": "1578",
    "complement": "Conjunto 42",
    "quarter": "Bela Vista",
    "city": "São Paulo",
    "state": "SP",
    "principal": true,
    "addressType": "RESIDENTIAL",
    "farmerStateRegistration": null,
    "howToReachLocationDescription": null,
    "responsibleContact": null,
    "attributes": {},
    "dateCreated": "2026-09-01T13:42:07Z",
    "lastUpdated": "2026-09-01T13:42:07Z"
  },
  "priceRuleTag": null,
  "customerTypeList": null,
  "customerGroupList": null
}

200Sucesso: pessoa jurídica

{
  "id": 4470602,
  "document": "29.893.264/0001-01",
  "documentType": "pj",
  "name": "Comercial Aurora Ltda",
  "tradingName": "Aurora Distribuidora",
  "contactName": "Marcos Aurélio",
  "email": "compras@auroradistribuidora.com.br",
  "phone": "(11) 98765-4321",
  "dateCreated": "2026-09-01T13:42:07Z",
  "active": true,
  "passwordExpired": false,
  "stateRegistration": "123456789",
  "cnae": "4530703",
  "paysIcms": true,
  "genre": null,
  "birthdate": null,
  "politicallyExposedPerson": false,
  "federalEmployee": false,
  "optinTracking": true,
  "trackingPhone": "(11) 98765-4321",
  "optinPath": "API",
  "address": [
    {
      "id": 4470701,
      "name": "Endereço de cadastro",
      "zipcode": "01310-100",
      "street": "Avenida Paulista",
      "number": "1578",
      "complement": "Conjunto 42",
      "quarter": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "principal": true,
      "addressType": "RESIDENTIAL",
      "farmerStateRegistration": null,
      "howToReachLocationDescription": null,
      "responsibleContact": null,
      "attributes": {},
      "dateCreated": "2026-09-01T13:42:07Z",
      "lastUpdated": "2026-09-01T13:42:07Z"
    }
  ],
  "customerRegistrationAddress": {
    "id": 4470701,
    "name": "Endereço de cadastro",
    "zipcode": "01310-100",
    "street": "Avenida Paulista",
    "number": "1578",
    "complement": "Conjunto 42",
    "quarter": "Bela Vista",
    "city": "São Paulo",
    "state": "SP",
    "principal": true,
    "addressType": "RESIDENTIAL",
    "farmerStateRegistration": null,
    "howToReachLocationDescription": null,
    "responsibleContact": null,
    "attributes": {},
    "dateCreated": "2026-09-01T13:42:07Z",
    "lastUpdated": "2026-09-01T13:42:07Z"
  },
  "priceRuleTag": null,
  "customerTypeList": null,
  "customerGroupList": null
}

Usado em

Endpoints relacionados

← Ver o grupo: Clientes

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