🏠 Endereços do Cliente

📋 Visão Geral

O módulo de Endereços do Cliente permite que o cliente autenticado gerencie seus endereços de entrega e cobrança de forma autônoma, sem necessidade de intervenção administrativa.

Os endereços são utilizados em todos os fluxos que envolvem entrega física, como pedidos, fretes e cotações logísticas. Manter os dados atualizados garante precisão no cálculo de frete e na comunicação com transportadoras.

Cada cliente pode cadastrar múltiplos endereços e definir um endereço principal, que será usado como padrão sempre que nenhum endereço específico for informado em uma operação.

🔄 Entidades Envolvidas

O módulo opera sobre uma única entidade principal:

Endereço do Cliente (CustomerAddress)

Representa um local físico vinculado ao cliente autenticado. Os campos que compõem um endereço são:

id — identificador único gerado automaticamente pela plataforma
main — indica se este é o endereço principal do cliente, usado como padrão em entregas e cobranças
identification — apelido livre definido pelo cliente (ex: "Casa", "Trabalho"), não precisa ser único
zipCode — CEP ou código postal
street, number, complement, district, city — campos do logradouro; complement é obrigatório na requisição mas aceita string vazia quando não houver complemento
state — nome completo do estado
stateCode — código do estado no formato alpha-2 prefixado pelo país (ex: BR-SP), deve ser válido e pertencer ao país informado
countryCode — código do país no formato alpha-3 (ex: BRA, USA, PRT)
recipient — nome do destinatário que receberá no endereço (limite de 255 caracteres)
createdAt e updatedAt — datas de criação e última atualização, gerenciadas pela plataforma

Todos os campos de texto, exceto recipient, têm limite máximo de 100 caracteres.

O primeiro endereço cadastrado é definido automaticamente como principal. Ao definir um novo endereço como principal, o anterior perde o status automaticamente — apenas um endereço pode ser principal por vez. O cliente é identificado pelo token de autenticação — customerId, main, createdAt e updatedAt não devem ser enviados nas requisições.

📌 Notas e Considerações

A exclusão de um endereço é permanente e irreversível — os dados não podem ser recuperados após a remoção.
countryCode deve estar no formato alpha-3 (3 letras). Caso o país não seja encontrado, a API retorna o erro UAPPI_STORE_CUSTOMER_ADDRESS_COUNTRY_NOT_FOUND.
stateCode deve ser um código válido pertencente ao país informado. Caso o estado não seja encontrado, a API retorna UAPPI_STORE_CUSTOMER_ADDRESS_STATE_NOT_FOUND.

🏠 Listagem de Endereços do Cliente

GET /customer/address

Lista todos os endereços cadastrados do cliente autenticado

📋 Descrição

Endpoint responsável por listar todos os endereços cadastrados do cliente autenticado.

Permite ao cliente visualizar seus endereços registrados, identificar o endereço principal e gerenciar suas opções de entrega de forma organizada.

🔐 Permissão

CustomerAuth — autenticação do cliente via token JWT

📝 Parâmetros

🏷️ Headers Obrigatórios

Header	Valor	Descrição
`Authorization`	Bearer {token}	Token de autenticação do cliente

📊 Campos de Condição Disponíveis

Campo	Tipo	Descrição
`id`	integer	Filtrar por ID do endereço
`main`	boolean	Filtrar pelo endereço principal (`true`) ou secundários (`false`)
`zipCode`	string	Filtrar pelo CEP do endereço

📊 Campos de Ordenação Disponíveis

Campo	Descrição
`id`	Ordenar pelo identificador do endereço

💡 Exemplo de Requisição

1curl --request GET \
2  --url '{{MAIN_URL}}/customer/address' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI'
curl --request GET \
  --url '{{MAIN_URL}}/customer/address' \
  --header 'Authorization: Bearer SEU_TOKEN_AQUI'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "registers": [
5      {
6        "id": 456,
7        "main": true,
8        "zipCode": "01310100",
9        "identification": "Casa",
10        "street": "Av. Paulista",
11        "number": "1000",
12        "city": "São Paulo",
13        "complement": "Apto 101",
14        "district": "Bela Vista",
15        "state": "São Paulo",
16        "recipient": "João Silva",
17        "stateCode": "BR-SP",
18        "countryCode": "BRA",
19        "createdAt": "2026-01-10 10:30:00",
20        "updatedAt": "2026-01-15 14:20:00"
21      }
22    ],
23    "pagination": {
24      "limit": 10,
25      "offset": 0,
26      "pages": 1,
27      "registers": 1
28    }
29  }
30}
{
  "status": true,
  "data": {
    "registers": [
      {
        "id": 456,
        "main": true,
        "zipCode": "01310100",
        "identification": "Casa",
        "street": "Av. Paulista",
        "number": "1000",
        "city": "São Paulo",
        "complement": "Apto 101",
        "district": "Bela Vista",
        "state": "São Paulo",
        "recipient": "João Silva",
        "stateCode": "BR-SP",
        "countryCode": "BRA",
        "createdAt": "2026-01-10 10:30:00",
        "updatedAt": "2026-01-15 14:20:00"
      }
    ],
    "pagination": {
      "limit": 10,
      "offset": 0,
      "pages": 1,
      "registers": 1
    }
  }
}

⚠️ 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.

> Este endpoint não possui erros específicos da aplicação além dos erros padrão de autenticação.

🏠 Detalhe de Endereço do Cliente

GET /customer/address/{addressId}

Retorna os detalhes completos de um endereço específico do cliente autenticado

📋 Descrição

Endpoint responsável por retornar todos os dados de um endereço específico do cliente autenticado.

Útil para pré-preenchimento de formulários de edição e para exibição detalhada de um endereço selecionado.

🔐 Permissão

CustomerAuth — autenticação do cliente via token JWT

📝 Parâmetros

🏷️ Headers Obrigatórios

Header	Valor	Descrição
`Authorization`	Bearer {token}	Token de autenticação do cliente

🔗 Parâmetros de URL

Parâmetro	Tipo	Obrigatório	Descrição
`addressId`	integer	✅ Sim	ID do endereço a ser consultado

💡 Exemplo de Requisição

1curl --request GET \
2  --url '{{MAIN_URL}}/customer/address/456' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI'
curl --request GET \
  --url '{{MAIN_URL}}/customer/address/456' \
  --header 'Authorization: Bearer SEU_TOKEN_AQUI'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "id": 456,
5    "main": true,
6    "zipCode": "01310100",
7    "identification": "Casa",
8    "street": "Av. Paulista",
9    "number": "1000",
10    "city": "São Paulo",
11    "complement": "Apto 101",
12    "district": "Bela Vista",
13    "state": "São Paulo",
14    "recipient": "João Silva",
15    "stateCode": "BR-SP",
16    "countryCode": "BRA",
17    "createdAt": "2026-01-10 10:30:00",
18    "updatedAt": "2026-01-15 14:20:00"
19  }
20}
{
  "status": true,
  "data": {
    "id": 456,
    "main": true,
    "zipCode": "01310100",
    "identification": "Casa",
    "street": "Av. Paulista",
    "number": "1000",
    "city": "São Paulo",
    "complement": "Apto 101",
    "district": "Bela Vista",
    "state": "São Paulo",
    "recipient": "João Silva",
    "stateCode": "BR-SP",
    "countryCode": "BRA",
    "createdAt": "2026-01-10 10:30:00",
    "updatedAt": "2026-01-15 14:20:00"
  }
}

⚠️ 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 Erro	HTTP	Descrição
`UAPPI_STORE_INVALID_ADDRESS`	404	Endereço não encontrado

🏠 Criar Endereço do Cliente

POST /customer/address

Cria um novo endereço para o cliente autenticado

📋 Descrição

Endpoint responsável por criar um novo endereço vinculado ao cliente autenticado.

Quando se trata do primeiro endereço cadastrado, ele é automaticamente definido como endereço principal (main: true), garantindo um padrão inicial para operações de entrega e cobrança.

🔐 Permissão

CustomerAuth — autenticação do cliente via token JWT

📝 Parâmetros

🏷️ Headers Obrigatórios

Header	Valor	Descrição
`Authorization`	Bearer {token}	Token de autenticação do cliente
`Content-Type`	application/json	Tipo de conteúdo

📦 Parâmetros do Corpo

Campo	Tipo	Obrigatório	Descrição
`zipCode`	string	✅ Sim	CEP ou código postal (máx. 100 caracteres)
`identification`	string	✅ Sim	Apelido do endereço — ex: "Casa", "Trabalho" (máx. 100 caracteres)
`countryCode`	string	✅ Sim	Código do país no formato alpha-3 — ex: `BRA` (exatamente 3 caracteres)
`stateCode`	string	✅ Sim	Código do país no formato alpha-2 + código do estado — ex: `BR-SP` (máx. 10 caracteres)
`state`	string	✅ Sim	Nome completo do estado — ex: "São Paulo" (máx. 100 caracteres)
`city`	string	✅ Sim	Nome da cidade (máx. 100 caracteres)
`street`	string	✅ Sim	Nome da rua ou logradouro (máx. 100 caracteres)
`number`	string	✅ Sim	Número do imóvel (máx. 100 caracteres)
`complement`	string	✅ Sim	Complemento — enviar string vazia `""` se não houver (máx. 100 caracteres)
`district`	string	✅ Sim	Bairro (máx. 100 caracteres)
`recipient`	string	✅ Sim	Nome completo do destinatário que receberá no endereço (máx. 255 caracteres)

💡 Exemplo de Requisição

1curl --request POST \
2  --url '{{MAIN_URL}}/customer/address' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6    "zipCode": "01310100",
7    "identification": "Casa",
8    "countryCode": "BRA",
9    "stateCode": "BR-SP",
10    "state": "São Paulo",
11    "city": "São Paulo",
12    "street": "Av. Paulista",
13    "number": "1000",
14    "complement": "Apto 101",
15    "district": "Bela Vista",
16    "recipient": "João Silva"
17  }'
curl --request POST \
  --url '{{MAIN_URL}}/customer/address' \
  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
  --header 'Content-Type: application/json' \
  --data '{
    "zipCode": "01310100",
    "identification": "Casa",
    "countryCode": "BRA",
    "stateCode": "BR-SP",
    "state": "São Paulo",
    "city": "São Paulo",
    "street": "Av. Paulista",
    "number": "1000",
    "complement": "Apto 101",
    "district": "Bela Vista",
    "recipient": "João Silva"
  }'

✅ Resposta de Sucesso

HTTP Status: 201 Created

1{
2  "status": true,
3  "data": {
4    "id": 456,
5    "main": false,
6    "zipCode": "01310100",
7    "identification": "Casa",
8    "street": "Av. Paulista",
9    "number": "1000",
10    "city": "São Paulo",
11    "complement": "Apto 101",
12    "district": "Bela Vista",
13    "state": "São Paulo",
14    "recipient": "João Silva",
15    "stateCode": "BR-SP",
16    "countryCode": "BRA",
17    "createdAt": "2026-04-23 10:00:00",
18    "updatedAt": "2026-04-23 10:00:00"
19  }
20}
{
  "status": true,
  "data": {
    "id": 456,
    "main": false,
    "zipCode": "01310100",
    "identification": "Casa",
    "street": "Av. Paulista",
    "number": "1000",
    "city": "São Paulo",
    "complement": "Apto 101",
    "district": "Bela Vista",
    "state": "São Paulo",
    "recipient": "João Silva",
    "stateCode": "BR-SP",
    "countryCode": "BRA",
    "createdAt": "2026-04-23 10:00:00",
    "updatedAt": "2026-04-23 10:00:00"
  }
}

⚠️ 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 Erro	HTTP	Descrição
`UAPPI_STORE_CUSTOMER_ADDRESS_COUNTRY_NOT_FOUND`	404	País informado não encontrado
`UAPPI_STORE_CUSTOMER_ADDRESS_STATE_NOT_FOUND`	404	Estado informado não encontrado ou não pertence ao país informado

🏠 Atualizar Endereço do Cliente

PUT /customer/address/{addressId}

Atualiza os dados de um endereço existente do cliente autenticado

📋 Descrição

Endpoint responsável por atualizar todas as informações de um endereço existente do cliente autenticado.

Permite corrigir ou alterar qualquer campo do endereço, como CEP, logradouro, complemento ou destinatário, garantindo que os dados de entrega permaneçam precisos e atualizados.

🔐 Permissão

CustomerAuth — autenticação do cliente via token JWT

📝 Parâmetros

🏷️ Headers Obrigatórios

Header	Valor	Descrição
`Authorization`	Bearer {token}	Token de autenticação do cliente
`Content-Type`	application/json	Tipo de conteúdo

🔗 Parâmetros de URL

Parâmetro	Tipo	Obrigatório	Descrição
`addressId`	integer	✅ Sim	ID do endereço a ser atualizado

📦 Parâmetros do Corpo

Campo	Tipo	Obrigatório	Descrição
`zipCode`	string	✅ Sim	CEP ou código postal (máx. 100 caracteres)
`identification`	string	✅ Sim	Apelido do endereço — ex: "Casa", "Trabalho" (máx. 100 caracteres)
`countryCode`	string	✅ Sim	Código do país no formato alpha-3 — ex: `BRA` (exatamente 3 caracteres)
`stateCode`	string	✅ Sim	Código do país no formato alpha-2 + código do estado — ex: `BR-SP` (máx. 10 caracteres)
`state`	string	✅ Sim	Nome completo do estado — ex: "São Paulo" (máx. 100 caracteres)
`city`	string	✅ Sim	Nome da cidade (máx. 100 caracteres)
`street`	string	✅ Sim	Nome da rua ou logradouro (máx. 100 caracteres)
`number`	string	✅ Sim	Número do imóvel (máx. 100 caracteres)
`complement`	string	✅ Sim	Complemento — enviar string vazia `""` se não houver (máx. 100 caracteres)
`district`	string	✅ Sim	Bairro (máx. 100 caracteres)
`recipient`	string	✅ Sim	Nome completo do destinatário que receberá no endereço (máx. 255 caracteres)

💡 Exemplo de Requisição

1curl --request PUT \
2  --url '{{MAIN_URL}}/customer/address/456' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6    "zipCode": "01310100",
7    "identification": "Trabalho",
8    "countryCode": "BRA",
9    "stateCode": "BR-SP",
10    "state": "São Paulo",
11    "city": "São Paulo",
12    "street": "Av. Paulista",
13    "number": "2000",
14    "complement": "Sala 501",
15    "district": "Bela Vista",
16    "recipient": "João Silva"
17  }'
curl --request PUT \
  --url '{{MAIN_URL}}/customer/address/456' \
  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
  --header 'Content-Type: application/json' \
  --data '{
    "zipCode": "01310100",
    "identification": "Trabalho",
    "countryCode": "BRA",
    "stateCode": "BR-SP",
    "state": "São Paulo",
    "city": "São Paulo",
    "street": "Av. Paulista",
    "number": "2000",
    "complement": "Sala 501",
    "district": "Bela Vista",
    "recipient": "João Silva"
  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "id": 456,
5    "main": false,
6    "zipCode": "01310100",
7    "identification": "Trabalho",
8    "street": "Av. Paulista",
9    "number": "2000",
10    "city": "São Paulo",
11    "complement": "Sala 501",
12    "district": "Bela Vista",
13    "state": "São Paulo",
14    "recipient": "João Silva",
15    "stateCode": "BR-SP",
16    "countryCode": "BRA",
17    "createdAt": "2026-01-10 10:30:00",
18    "updatedAt": "2026-04-23 10:00:00"
19  }
20}
{
  "status": true,
  "data": {
    "id": 456,
    "main": false,
    "zipCode": "01310100",
    "identification": "Trabalho",
    "street": "Av. Paulista",
    "number": "2000",
    "city": "São Paulo",
    "complement": "Sala 501",
    "district": "Bela Vista",
    "state": "São Paulo",
    "recipient": "João Silva",
    "stateCode": "BR-SP",
    "countryCode": "BRA",
    "createdAt": "2026-01-10 10:30:00",
    "updatedAt": "2026-04-23 10:00:00"
  }
}

⚠️ 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 Erro	HTTP	Descrição
`UAPPI_STORE_INVALID_ADDRESS`	404	Endereço não encontrado
`UAPPI_STORE_CUSTOMER_ADDRESS_COUNTRY_NOT_FOUND`	404	País informado não encontrado
`UAPPI_STORE_CUSTOMER_ADDRESS_STATE_NOT_FOUND`	404	Estado informado não encontrado ou não pertence ao país informado

🗑️ Remover Endereço do Cliente

DELETE /customer/address/{addressId}

Remove permanentemente um endereço do cliente autenticado

📋 Descrição

Endpoint responsável por remover permanentemente um endereço do cliente autenticado.

A exclusão é definitiva e irreversível — o endereço não pode ser recuperado após a remoção. Essa operação deve ser realizada com atenção, pois impacta dados utilizados em processos como entrega e cobrança.

🔐 Permissão

CustomerAuth — autenticação do cliente via token JWT

📝 Parâmetros

🏷️ Headers Obrigatórios

Header	Valor	Descrição
`Authorization`	Bearer {token}	Token de autenticação do cliente

🔗 Parâmetros de URL

Parâmetro	Tipo	Obrigatório	Descrição
`addressId`	integer	✅ Sim	ID do endereço a ser removido

💡 Exemplo de Requisição

1curl --request DELETE \
2  --url '{{MAIN_URL}}/customer/address/456' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI'
curl --request DELETE \
  --url '{{MAIN_URL}}/customer/address/456' \
  --header 'Authorization: Bearer SEU_TOKEN_AQUI'

✅ Resposta de Sucesso

HTTP Status: 200 OK

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

⚠️ 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 Erro	HTTP	Descrição
`UAPPI_STORE_INVALID_ADDRESS`	404	Endereço não encontrado

📍 Definir Endereço Principal do Cliente

PUT /customer/address/main/{addressId}

Define um endereço como o endereço principal do cliente autenticado

📋 Descrição

Endpoint responsável por definir qual endereço será o endereço principal do cliente autenticado.

O endereço principal é utilizado como padrão em operações de entrega e cobrança, impactando diretamente o fluxo de pedidos quando nenhum endereço específico é selecionado pelo cliente.

Ao definir um novo endereço como principal, as seguintes regras são aplicadas automaticamente:

O endereço anteriormente principal perde o status de principal (main: false)
O endereço informado passa a ser o principal (main: true)
Apenas um endereço permanece como principal por vez, garantindo consistência nos dados

🔐 Permissão

CustomerAuth — autenticação do cliente via token JWT

📝 Parâmetros

🏷️ Headers Obrigatórios

Header	Valor	Descrição
`Authorization`	Bearer {token}	Token de autenticação do cliente

🔗 Parâmetros de URL

Parâmetro	Tipo	Obrigatório	Descrição
`addressId`	integer	✅ Sim	ID do endereço que será definido como principal

💡 Exemplo de Requisição

1curl --request PUT \
2  --url '{{MAIN_URL}}/customer/address/main/456' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI'
curl --request PUT \
  --url '{{MAIN_URL}}/customer/address/main/456' \
  --header 'Authorization: Bearer SEU_TOKEN_AQUI'

✅ Resposta de Sucesso

HTTP Status: 200 OK

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

⚠️ 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 Erro	HTTP	Descrição
`UAPPI_STORE_INVALID_ADDRESS`	404	Endereço não encontrado

Começando

Store Theme

Customização de Interface

Consumo de Dados

Tracking e SEO

Checkout

Consumo de Dados

Tracking e SEO

Ambiente de Pagamento

Área Restrita (Minha Conta)

Consumo de Dados

Tracking e SEO

SDK Público (public-sdk)

Modules

Api

Tracking

API Pública

Área Restrita (Minha Conta)

Carrinho de Compras

API Privada

Apps

Configurações Gerais

Clientes

Template

Avaliações

Notificações

ERPs

Filas

Grupo de Pedidos

Pedidos

Carrinhos

Pagamentos

Anti-Fraude

Produtos

Inteligência Artificial

Marcas

Categorias

Filtros

Atributos

Url

Relatórios

Render

Fretes

Usuários

Promocionais

Marketplace

Third Party

Datalogic

Busca

MCP

🏠 Endereços do Cliente

📋 Visão Geral

🔄 Entidades Envolvidas

📌 Notas e Considerações

🏠 Listagem de Endereços do Cliente

📋 Descrição

🔐 Permissão

📝 Parâmetros

🏷️ Headers Obrigatórios

📊 Campos de Condição Disponíveis

📊 Campos de Ordenação Disponíveis

💡 Exemplo de Requisição

✅ Resposta de Sucesso

⚠️ Possíveis Erros

🏠 Detalhe de Endereço do Cliente

📋 Descrição

🔐 Permissão

📝 Parâmetros

🏷️ Headers Obrigatórios

🔗 Parâmetros de URL

💡 Exemplo de Requisição

✅ Resposta de Sucesso

⚠️ Possíveis Erros

🏠 Criar Endereço do Cliente

📋 Descrição

🔐 Permissão

📝 Parâmetros

🏷️ Headers Obrigatórios

📦 Parâmetros do Corpo

💡 Exemplo de Requisição