Skip to content

👤 Documentação de Gerenciamento de Cliente

📋 Visão Geral

O Gerenciamento de Cliente agrupa as operações sobre o ciclo de vida do cadastro do cliente na loja — desde a criação da conta até o seu encerramento definitivo.

Cada operação atua sobre o mesmo recurso (/customer) e exige o nível de autenticação adequado: o cadastro é público, enquanto consulta, atualização e encerramento exigem o cliente autenticado via token JWT.

🔄 Entidades Envolvidas

Perfil do cliente (Customer)

Armazena os dados cadastrais do cliente: nome, e-mail, telefone, gênero, data de nascimento, nacionalidade, tipo de pessoa (física ou jurídica) e origem do cadastro.

Os campos walletAmount, pointSystemAmount, orderQuantity e orderValue são calculados — refletem o estado atual do cliente na plataforma e não podem ser definidos diretamente.

Campos relacionais

Por padrão, os campos relacionais são retornados como null na consulta (GET /customer). Para carregá-los, informe o parâmetro fields na requisição:

CampoDescrição
addressesEndereços cadastrados pelo cliente
documentsDocumentos cadastrados (CPF, RG, CNPJ etc.)
flagsPreferências de comunicação (sendPromotionalEmail, sendPromotionalSms, sendOrderEmail, sendOrderSms)
additionalFieldsCampos adicionais configurados pela loja
O parâmetro fields pode ser enviado como array no corpo JSON ou como query string (fields[]=addresses&fields[]=documents).

🛡️ Validações Aplicadas

Validação de idade mínima

A configuração customers/validation/minimum-age define a idade mínima para cadastro. Quando o valor é 0, a regra é desativada e qualquer idade é aceita.

Validação do domínio do e-mail

A configuração customers/validation/email-domain bloqueia o cadastro e a troca de e-mail quando o domínio do e-mail não possui registros MX válidos. Quando o valor é false, que é o padrão, qualquer domínio é aceito.

Validação externa

Quando customers/validation/external-url está preenchida com uma URL válida, o cadastro e a atualização são submetidos ao serviço externo antes de serem persistidos. O serviço pode rejeitar a operação com regra de negócio própria.

Unicidade de e-mail

Um e-mail já associado a outro cliente no mesmo canal de venda é rejeitado tanto na criação quanto na atualização.

🗑️ Encerramento de Conta

O encerramento é irreversível. Ao excluir a conta, o sistema:

  • Anonimiza os dados pessoais do cliente (nome, e-mail, telefone, data de nascimento)
  • Remove os endereços e documentos vinculados
  • Preserva o histórico de pedidos, com dados anonimizados, para integridade do histórico
  • Invalida o token JWT ativo — o cliente é deslogado no mesmo ciclo da requisição

    • O campo requestedAt é obrigatório e registra a data em que o cliente solicitou o encerramento, para fins de auditoria e conformidade com boas práticas de privacidade.

    📌 Notas e Considerações

  • O cadastro (POST /customer) é o único endpoint público desta seção — não exige Authorization header.
  • Os campos id, salesChannelId, nationality, birthdate, origin, active e createdAt são protegidos e ignorados se enviados na atualização.
  • A resposta de atualização (PUT /customer) retorna sempre os campos relacionais como null — utilize GET /customer com fields para consultá-los após a atualização.
  • Quando o cliente está sujeito ao mascaramento de dados (masked: true), campos sensíveis como e-mail, nome, telefone, números de documentos e CEPs de endereços são retornados parcialmente ocultados.

👤 Cadastro de Cliente

POST /customer

Cria um novo cliente com dados pessoais e documentos

📋 Descrição

Endpoint responsável por criar um novo cliente na loja.

A criação contempla o envio de dados pessoais, documentos e configurações iniciais, garantindo que o cliente esteja apto para autenticação e utilização da plataforma.

A validação de idade mínima é aplicada conforme a configuração customers/validation/minimum-age (valor 0 desativa a regra), e a validação externa é executada quando customers/validation/external-url está preenchida com URL válida.

📝 Parâmetros

🏷️ Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo

📦 Parâmetros do Corpo

ParâmetroTipoObrigatórioDescrição
emailstring⚠️ CondicionalE-mail do cliente — máximo 255 caracteres. Obrigatório, exceto quando socialLoginToken for informado (nesse caso o e-mail vem do token e não pode ser enviado)
nameCorporateNamestring✅ SimNome completo (pessoa física) ou razão social (pessoa jurídica)
isCorporateboolean✅ Simtrue para pessoa jurídica, false para pessoa física
genderstring✅ SimGênero: male, female ou undefined
nationalitystring✅ SimCódigo do país no formato alpha-3 — ex: BRA, USA
phonestring✅ SimTelefone no formato internacional
originstring✅ SimOrigem do cadastro: frontend, api ou admin
birthdatestring✅ SimData de nascimento no formato YYYY-MM-DD
tradeNamestring⚠️ CondicionalNome fantasia — obrigatório quando isCorporate for true
passwordstring❌ NãoSenha do cliente — entre 8 e 64 caracteres. Não pode ser enviada junto com socialLoginToken
socialLoginTokenstring❌ NãoToken do login social (Google ou Facebook), recebido na URL de cadastro após o login. Vale 30 minutos. Veja [Cadastro a partir do login social](#-cadastro-a-partir-do-login-social)
documentsarray✅ SimLista de documentos do cliente
documents[].typestring✅ SimTipo do documento: cpf, cnpj, ie, rg, document1, document2, document3
documents[].documentstring✅ SimNúmero do documento — máximo 100 caracteres
additionalFieldsarray❌ NãoCampos adicionais da loja — máximo 100 itens
additionalFields[].codestring⚠️ CondicionalCódigo do campo — obrigatório quando additionalFields for informado
additionalFields[].valuemixed⚠️ CondicionalValor do campo — obrigatório quando additionalFields for informado

💡 Exemplo de Requisição

1curl --request POST \
2  --url '{{MAIN_URL}}/customer' \
3  --header 'Content-Type: application/json' \
4  --data '{
5    "email": "cliente@exemplo.com",
6    "nameCorporateName": "João Silva",
7    "isCorporate": false,
8    "gender": "male",
9    "nationality": "BRA",
10    "birthdate": "1990-05-15",
11    "phone": "+5511999887766",
12    "origin": "api",
13    "password": "senhaSegura123",
14    "documents": [
15      {
16        "type": "cpf",
17        "document": "12345678900"
18      }
19    ]
20  }'

🔐 Cadastro a partir do login social

Quando o cliente faz login com Google ou Facebook e ainda não existe na loja, o redirecionamento para a URL de cadastro traz o parâmetro socialLoginToken. Esse token prova o e-mail confirmado pelo provedor.

Para concluir o cadastro, envie o formulário normal a este mesmo endpoint, com estas diferenças:

  • Envie socialLoginToken.
  • Não envie email nem password. O e-mail vem do token.
  • O cliente é criado sem senha e recebe o e-mail para definir a senha.
  • A sessão do cliente é aberta e o cookie de autenticação é gravado na resposta, como no login. A resposta tem o mesmo formato do cadastro normal.

1curl --request POST \
2  --url '{{MAIN_URL}}/customer' \
3  --header 'Content-Type: application/json' \
4  --data '{
5    "socialLoginToken": "<token recebido na URL de cadastro>",
6    "nameCorporateName": "João Silva",
7    "isCorporate": false,
8    "gender": "undefined",
9    "nationality": "BRA",
10    "birthdate": "1990-05-15",
11    "phone": "+5511999887766",
12    "documents": [
13      { "type": "cpf", "document": "12345678900" }
14    ]
15  }'

✅ Resposta de Sucesso

HTTP Status: 201 Created

1{
2  "status": true,
3  "data": {
4    "id": 12345,
5    "salesChannelId": 1,
6    "tradePolicyId": 1,
7    "email": "cliente@exemplo.com",
8    "dealerGroupId": null,
9    "nameCorporateName": "João Silva",
10    "tradeName": "",
11    "isCorporate": false,
12    "gender": "male",
13    "nationality": "BRA",
14    "birthdate": "1990-05-15",
15    "phone": "+5511999887766",
16    "walletAmount": 0,
17    "pointSystemAmount": 0,
18    "orderQuantity": 0,
19    "cancelledOrderQuantity": 0,
20    "orderValue": 0,
21    "lastOrder": null,
22    "origin": "api",
23    "createdAt": "2025-01-15 10:30:00",
24    "active": true,
25    "deleted": false,
26    "masked": false,
27    "addresses": null,
28    "documents": [
29      {
30        "type": "cpf",
31        "document": "12345678900"
32      }
33    ],
34    "flags": null,
35    "additionalFields": null
36  }
37}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

Código do ErroHTTPDescrição
UAPPI_SOCIAL_LOGIN_INVALID_CUSTOMER_TOKEN400Token do login social inválido ou expirado
UAPPI_STORE_CUSTOMER_EMAIL_ALREADY_IN_USE409E-mail já em uso por outro cliente
UAPPI_STORE_ALREADY_USED_CUSTOMER_DOCUMENT409Documento já em uso por outro cliente
UAPPI_CORE_INVALID_DOCUMENT_TYPE400Tipo de documento inválido
UAPPI_CORE_EMPTY_DOCUMENT400Documento não pode estar vazio
UAPPI_CORE_INVALID_CPF400CPF inválido
UAPPI_CORE_INVALID_CNPJ400CNPJ inválido
UAPPI_STORE_INVALID_PASSWORD_LENGTH400Senha com tamanho inválido — deve ter entre 8 e 64 caracteres
UAPPI_STORE_CUSTOMER_MINIMUM_AGE_NOT_REACHED400Idade mínima não atingida conforme configuração da loja
UAPPI_STORE_CUSTOMER_INVALID_EMAIL_DOMAIN400Domínio do e-mail inválido — não possui registros para receber e-mails
UAPPI_STORE_CUSTOMER_EXTERNAL_VALIDATION_REJECTED422Serviço externo rejeitou o cadastro com regra de negócio
UAPPI_STORE_CUSTOMER_EXTERNAL_VALIDATION_INVALID_CONTRACT502Serviço externo respondeu com contrato inválido
UAPPI_STORE_CUSTOMER_EXTERNAL_VALIDATION_UNAVAILABLE502Serviço externo indisponível
UAPPI_STORE_CUSTOMER_EXTERNAL_VALIDATION_TIMEOUT504Timeout no serviço externo de validação

👤 Consultar Perfil do Cliente

GET /customer

Retorna os dados do perfil do cliente autenticado

📋 Descrição

Endpoint utilizado para consultar o perfil do cliente autenticado, com suporte a campos relacionais carregados sob demanda.

A resposta base inclui todos os campos escalares do cadastro. Os campos relacionais (addresses, documents, flags, additionalFields) retornam como null por padrão e devem ser solicitados explicitamente via parâmetro fields.

Quando o cliente está sujeito ao mascaramento de dados (masked: true), campos sensíveis como e-mail, nome, telefone, números de documentos e CEPs de endereços são retornados parcialmente ocultados.

🔐 Permissão

  • CustomerAuth — autenticação do cliente via token JWT

📝 Parâmetros

🏷️ Headers Obrigatórios

HeaderValorDescrição
AuthorizationBearer {token}Token de autenticação do cliente
Content-Typeapplication/jsonTipo de conteúdo

🗂️ Campos Disponíveis (fields)

CampoDescrição
addressesLista de endereços cadastrados pelo cliente
documentsDocumentos cadastrados (CPF, RG, CNPJ etc.)
flagsPreferências de comunicação do cliente
additionalFieldsCampos adicionais configurados pela loja

💡 Exemplo de Requisição

> Nota: esta API aceita corpo JSON em requisições GET, seguindo a convenção da plataforma. Utilize o header Content-Type: application/json e envie os parâmetros no corpo da requisição.

1curl --request GET \
2  --url '{{MAIN_URL}}/customer' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6    "fields": ["addresses", "documents", "flags", "additionalFields"]
7  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "id": 3,
5    "salesChannelId": 1,
6    "tradePolicyId": 1,
7    "email": "customeruappi@email.com",
8    "dealerGroupId": 0,
9    "nameCorporateName": "Customer teste",
10    "tradeName": "",
11    "isCorporate": false,
12    "gender": "male",
13    "nationality": "BRA",
14    "birthdate": "2000-01-01",
15    "phone": "+12345678912",
16    "walletAmount": 323,
17    "pointSystemAmount": 0,
18    "orderQuantity": 1,
19    "cancelledOrderQuantity": 0,
20    "orderValue": 0,
21    "lastOrder": null,
22    "origin": "frontend",
23    "createdAt": "2026-04-09 17:09:10",
24    "active": true,
25    "deleted": false,
26    "masked": false,
27    "addresses": [
28      {
29        "id": 1,
30        "main": false,
31        "zipCode": "1600000",
32        "identification": "Casa",
33        "street": "Rua xxxxxx",
34        "number": "1111",
35        "city": "Birigui",
36        "complement": "Casa verde",
37        "district": "Centro",
38        "state": "São Paulo",
39        "recipient": "Destinatário",
40        "stateCode": "BR-SP",
41        "countryCode": "BRA",
42        "createdAt": "2026-04-23 13:48:03",
43        "updatedAt": "2026-04-23 14:12:55"
44      }
45    ],
46    "documents": [
47      {
48        "type": "cpf",
49        "document": "20431311099"
50      }
51    ],
52    "flags": {
53      "sendPromotionalEmail": true,
54      "sendPromotionalSms": true,
55      "sendOrderEmail": true,
56      "sendOrderSms": true
57    },
58    "additionalFields": []
59  }
60}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

Código do ErroHTTPDescrição
UAPPI_STORE_CUSTOMER_NOT_FOUND404Cliente não encontrado

✏️ Atualizar Perfil do Cliente

PUT /customer

Atualiza os dados do perfil do cliente autenticado

📋 Descrição

Endpoint utilizado para atualizar os dados de perfil do cliente autenticado: nome, e-mail, gênero, telefone e nome fantasia.

Os campos id, salesChannelId, nationality, birthdate, origin, active e createdAt são protegidos — se enviados na requisição, serão ignorados.

Quando o e-mail informado for diferente do atual, o sistema verifica se já existe outro cliente cadastrado com o mesmo e-mail no canal de venda. Em caso positivo, a requisição é rejeitada.

Quando a configuração customers/validation/external-url estiver preenchida, a atualização é submetida ao serviço externo antes de ser persistida. O serviço externo pode rejeitar a operação com regra de negócio própria.

A resposta retorna o objeto completo do cliente após a atualização. Os campos relacionais (addresses, documents, flags, additionalFields) são sempre retornados como null — para consultá-los, utilize GET /customer com o parâmetro fields.

🔐 Permissão

  • CustomerAuth — autenticação do cliente via token JWT

📝 Parâmetros

🏷️ Headers Obrigatórios

HeaderValorDescrição
AuthorizationBearer {token}Token de autenticação do cliente
Content-Typeapplication/jsonTipo de conteúdo

📦 Parâmetros do Corpo

CampoTipoObrigatórioDescrição
emailstring✅ SimE-mail válido (máx. 255 caracteres)
nameCorporateNamestring✅ SimNome completo ou razão social (máx. 255 caracteres)
isCorporateboolean✅ SimDefine se é pessoa jurídica
genderstring✅ SimGênero: male, female ou undefined
phonestring✅ SimTelefone no formato internacional
tradeNamestring✅ SimSobrenome ou nome fantasia — pode ser vazio (máx. 255 caracteres)

💡 Exemplo de Requisição

1curl --request PUT \
2  --url '{{MAIN_URL}}/customer' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6    "email": "customeruappi@email.com",
7    "nameCorporateName": "Customer teste",
8    "tradeName": "",
9    "isCorporate": false,
10    "gender": "male",
11    "phone": "+12345678912"
12  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "id": 3,
5    "salesChannelId": 1,
6    "tradePolicyId": 1,
7    "email": "customeruappi@email.com",
8    "dealerGroupId": 0,
9    "nameCorporateName": "Customer teste",
10    "tradeName": "",
11    "isCorporate": false,
12    "gender": "male",
13    "nationality": "BRA",
14    "birthdate": "2000-01-01",
15    "phone": "+12345678912",
16    "walletAmount": 323,
17    "pointSystemAmount": 0,
18    "orderQuantity": 0,
19    "cancelledOrderQuantity": 0,
20    "orderValue": 0,
21    "lastOrder": null,
22    "origin": "frontend",
23    "createdAt": "2026-04-09 17:09:10",
24    "active": true,
25    "deleted": false,
26    "masked": false,
27    "addresses": null,
28    "documents": null,
29    "flags": null,
30    "additionalFields": null
31  }
32}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

Código do ErroHTTPDescrição
UAPPI_STORE_CUSTOMER_NOT_FOUND404Cliente não encontrado
UAPPI_STORE_CUSTOMER_EMAIL_ALREADY_IN_USE409E-mail já em uso por outro cliente
UAPPI_STORE_CUSTOMER_INVALID_EMAIL_DOMAIN400Domínio do e-mail inválido — não possui registros para receber e-mails
UAPPI_STORE_CUSTOMER_EXTERNAL_VALIDATION_REJECTED422Serviço externo rejeitou a atualização com regra de negócio
UAPPI_STORE_CUSTOMER_EXTERNAL_VALIDATION_INVALID_CONTRACT502Serviço externo respondeu com contrato inválido
UAPPI_STORE_CUSTOMER_EXTERNAL_VALIDATION_UNAVAILABLE502Serviço externo indisponível
UAPPI_STORE_CUSTOMER_EXTERNAL_VALIDATION_TIMEOUT504Timeout no serviço externo de validação

🗑️ Encerrar Conta do Cliente

DELETE /customer

Encerra a conta do cliente autenticado

📋 Descrição

Endpoint utilizado para encerrar a conta do cliente autenticado de forma definitiva e irreversível.

O processo anonimiza os dados pessoais do cliente (nome, e-mail, telefone, data de nascimento), remove os endereços e documentos vinculados, e marca o registro como inativo e excluído.

Os pedidos anteriores são preservados com dados anonimizados para manutenção da integridade histórica.

Ao concluir a operação, o token de autenticação ativo é invalidado — o cliente é deslogado no mesmo ciclo da requisição.

O campo requestedAt é obrigatório e deve conter a data em que o cliente solicitou o encerramento. O valor é registrado no histórico de exclusão para fins de auditoria e conformidade com boas práticas de privacidade.

🔐 Permissão

  • CustomerAuth — autenticação do cliente via token JWT

📝 Parâmetros

🏷️ Headers Obrigatórios

HeaderValorDescrição
AuthorizationBearer {token}Token de autenticação do cliente
Content-Typeapplication/jsonTipo de conteúdo

📦 Parâmetros do Corpo

CampoTipoObrigatórioDescrição
requestedAtdate✅ SimData da solicitação de encerramento (ex: 2025-01-01)

💡 Exemplo de Requisição

1curl --request DELETE \
2  --url '{{MAIN_URL}}/customer' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6    "requestedAt": "2025-01-01"
7  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": true
4}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

Código do ErroHTTPDescrição
UAPPI_STORE_CUSTOMER_NOT_FOUND404Cliente não encontrado

Uappi é a melhor opção para o crescimento da sua loja!

Institucional

;