API atual/Referência completa/Conta do cliente

Endereços

Caderno de endereços do cliente: listar, criar, alterar e apagar.

O caderno de endereços é a lista de endereços que o cliente salva para não digitar tudo a cada compra. No checkout, o app mostra essa lista e manda o id escolhido em billing_address_id e shipping_address_id (Criar pedido). Cada cliente só enxerga e altera os seus endereços. O CPF/CNPJ não fica no endereço: ele é do perfil e é copiado para o endereço do pedido na compra.

GET/api/v1/storefront/addressesCliente

Lista os endereços do cliente

bash

curl "$BASE_URL/api/v1/storefront/addresses" \
  -H "Authorization: Bearer $TOKEN"

200Endereços

json

{
  "addresses": [
    {
      "id": "04d6da67-1f55-427c-885d-0a30bdbf264d",
      "address_id": "04d6da67-1f55-427c-885d-0a30bdbf264d",
      "user_id": "264a70c1-9c69-458d-ac73-838543f87da2",
      "label": "Casa",
      "is_default": true,
      "first_name": "Maria",
      "last_name": "Souza",
      "address_line1": "Avenida Paulista, 1000",
      "address_line2": "Apto 52",
      "district": "Bela Vista",
      "district_id": "e471b959-3334-4bcb-93e4-45609cc40fc0",
      "city": "São Paulo",
      "city_id": "3d899205-1b71-4f09-8bbf-2c62bcefc2e5",
      "state": "SP",
      "postal_code": "01310-100",
      "country": "BR",
      "phone": "11987654321",
      "type": "D",
      "created_at": "2026-10-11T20:54:49.755615Z",
      "updated_at": "2026-10-11T20:54:49.755615Z"
    }
  ],
  "total": 1
}

Campos da resposta

addressesarray

Endereços do cliente. Vem null (e total: 0) quando não há nenhum: trate os dois.

addresses[].iduuid

Id do endereço. address_id repete o valor.

addresses[].is_defaultboolean

true no endereço padrão. Só um endereço é padrão por vez.

addresses[].typestring

Campo duplicado (D, S...). Ignore-o.

totalinteger

Quantidade de endereços.

Além dos campos acima, cada endereço traz cópias com nomes alternativos (b_address, b_city, b_zipcode, s_address, s_city...); um app novo deve usar só os campos principais.

Status	Quando	Corpo
401	Sem token, ou token inválido ou expirado	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
500	Falha ao listar	`{"error":"failed to list addresses","detail":"..."}`

POST/api/v1/storefront/addressesCliente

Cria um endereço

Corpo da requisição

first_namestring

Nome de quem recebe. last_name é o sobrenome.

address_line1string

Rua e número (Avenida Paulista, 1000). Se você mandar number separado, ele é anexado à rua.

address_line2string

Complemento (apartamento, bloco). Em lojas que exigem o número no campo próprio, number ou address2 preenchem este campo.

districtstring

Bairro. neighborhood é aceito como sinônimo. district_id aponta o bairro do catálogo da loja.

citystring

Cidade. city_id aponta a cidade do catálogo da loja e é preferido para a área de entrega.

statestring

UF, duas letras (SP).

postal_codestring

CEP, com ou sem hífen. Sinônimos aceitos: zipcode, zip_code, post_code.

countrystringpadrão: BR

País, código ISO de 2 letras.

phonestring

Telefone de contato da entrega.

labelstring

Apelido ("Casa", "Trabalho").

is_defaultboolean

true torna este o endereço padrão e tira a marca do anterior. O primeiro endereço do cliente é sempre o padrão.

complementstring

Complemento extra ("Casa 10", "Bloco B").

bash

curl -X POST "$BASE_URL/api/v1/storefront/addresses" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "first_name": "Maria",
  "last_name": "Souza",
  "address_line1": "Avenida Paulista, 1000",
  "address_line2": "Apto 52",
  "district": "Bela Vista",
  "city": "São Paulo",
  "state": "SP",
  "postal_code": "01310-100",
  "country": "BR",
  "phone": "11987654321",
  "label": "Casa",
  "is_default": true
}'

201Endereço criado

json

{
  "id": "04d6da67-1f55-427c-885d-0a30bdbf264d",
  "address_id": "04d6da67-1f55-427c-885d-0a30bdbf264d",
  "user_id": "264a70c1-9c69-458d-ac73-838543f87da2",
  "label": "Casa",
  "is_default": true,
  "first_name": "Maria",
  "last_name": "Souza",
  "address_line1": "Avenida Paulista, 1000",
  "address_line2": "Apto 52",
  "district": "Bela Vista",
  "district_id": "e471b959-3334-4bcb-93e4-45609cc40fc0",
  "city": "São Paulo",
  "city_id": "3d899205-1b71-4f09-8bbf-2c62bcefc2e5",
  "state": "SP",
  "postal_code": "01310-100",
  "country": "BR",
  "phone": "11987654321",
  "type": "D",
  "created_at": "2026-10-11T20:54:49.755615Z",
  "updated_at": "2026-10-11T20:54:49.755615Z"
}

A resposta é o endereço criado. A plataforma tenta ligar a cidade e o bairro ao catálogo da loja e preenche city_id e district_id quando encontra.

Status	Quando	Corpo
400	Corpo que não é JSON	`{"error":"invalid request body","detail":"..."}`
401	Sem token, ou token inválido ou expirado	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
403	A loja bloqueou a edição de endereço para este tipo de conta	`{"error":"address_edit_blocked","detail":"Address create/edit/delete is disabled for your account type"}`
422	Política de endereço da loja	`{"error":"address_number_required","message":"..."}`
500	Falha ao gravar	`{"error":"failed to create address","detail":"..."}`

PUT/api/v1/storefront/addresses/{id}Cliente

Altera um endereço

Altera só os campos enviados. Aceita os mesmos campos e sinônimos do corpo de criar (todos opcionais, listados na rota POST acima). Mandar is_default: true passa o padrão para este endereço.

Parâmetros de caminho

iduuidobrigatório

Id do endereço. Um texto que não é UUID responde 400 invalid id.

bash

curl -X PUT "$BASE_URL/api/v1/storefront/addresses/$ADDRESS_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "Trabalho",
  "is_default": false
}'

A resposta 200 é o endereço atualizado.

Status	Quando	Corpo
400	`id` que não é UUID, ou corpo que não é JSON	`{"error":"invalid id","detail":"id must be a valid UUID"}`
401	Sem token, ou token inválido ou expirado	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
403	Edição de endereço bloqueada pela loja	`{"error":"address_edit_blocked"}`
422	Política de endereço da loja (só quando um campo de endereço foi alterado)	`{"error":"address_cep_mismatch","message":"..."}`
500	Falha ao gravar	`{"error":"failed to update address","detail":"..."}`

DELETE/api/v1/storefront/addresses/{id}Cliente

Apaga um endereço

Remove o endereço do caderno. Pedidos já feitos com ele não mudam, porque guardam a sua própria cópia. Se o endereço apagado era o padrão, o cliente fica sem padrão até marcar outro.

Parâmetros de caminho

iduuidobrigatório

Id do endereço.

bash

curl -X DELETE "$BASE_URL/api/v1/storefront/addresses/$ADDRESS_ID" \
  -H "Authorization: Bearer $TOKEN"

200Endereço apagado

json

{ "message": "address deleted" }

Status	Quando	Corpo
400	`id` que não é UUID	`{"error":"invalid id"}`
401	Sem token, ou token inválido ou expirado	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
403	Edição de endereço bloqueada pela loja	`{"error":"address_edit_blocked"}`
500	Endereço inexistente ou de outro cliente (a plataforma devolve 500 em vez de 404), ou falha interna	`{"error":"failed to delete address","detail":"address 1111... not found for user ..."}`

Veja também

Endereços

Caderno de endereços do cliente: listar, criar, alterar e apagar.

GET/api/v1/storefront/addressesCliente

Lista os endereços do cliente

bash

curl "$BASE_URL/api/v1/storefront/addresses" \
  -H "Authorization: Bearer $TOKEN"

200Endereços

json

{
  "addresses": [
    {
      "id": "04d6da67-1f55-427c-885d-0a30bdbf264d",
      "address_id": "04d6da67-1f55-427c-885d-0a30bdbf264d",
      "user_id": "264a70c1-9c69-458d-ac73-838543f87da2",
      "label": "Casa",
      "is_default": true,
      "first_name": "Maria",
      "last_name": "Souza",
      "address_line1": "Avenida Paulista, 1000",
      "address_line2": "Apto 52",
      "district": "Bela Vista",
      "district_id": "e471b959-3334-4bcb-93e4-45609cc40fc0",
      "city": "São Paulo",
      "city_id": "3d899205-1b71-4f09-8bbf-2c62bcefc2e5",
      "state": "SP",
      "postal_code": "01310-100",
      "country": "BR",
      "phone": "11987654321",
      "type": "D",
      "created_at": "2026-10-11T20:54:49.755615Z",
      "updated_at": "2026-10-11T20:54:49.755615Z"
    }
  ],
  "total": 1
}

Campos da resposta

addressesarray

Endereços do cliente. Vem null (e total: 0) quando não há nenhum: trate os dois.

addresses[].iduuid

Id do endereço. address_id repete o valor.

addresses[].is_defaultboolean

true no endereço padrão. Só um endereço é padrão por vez.

addresses[].typestring

Campo duplicado (D, S...). Ignore-o.

totalinteger

Quantidade de endereços.

Além dos campos acima, cada endereço traz cópias com nomes alternativos (b_address, b_city, b_zipcode, s_address, s_city...); um app novo deve usar só os campos principais.

Status	Quando	Corpo
401	Sem token, ou token inválido ou expirado	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
500	Falha ao listar	`{"error":"failed to list addresses","detail":"..."}`

POST/api/v1/storefront/addressesCliente

Cria um endereço

Corpo da requisição

first_namestring

Nome de quem recebe. last_name é o sobrenome.

address_line1string

Rua e número (Avenida Paulista, 1000). Se você mandar number separado, ele é anexado à rua.

address_line2string

Complemento (apartamento, bloco). Em lojas que exigem o número no campo próprio, number ou address2 preenchem este campo.

districtstring

Bairro. neighborhood é aceito como sinônimo. district_id aponta o bairro do catálogo da loja.

citystring

Cidade. city_id aponta a cidade do catálogo da loja e é preferido para a área de entrega.

statestring

UF, duas letras (SP).

postal_codestring

CEP, com ou sem hífen. Sinônimos aceitos: zipcode, zip_code, post_code.

countrystringpadrão: BR

País, código ISO de 2 letras.

phonestring

Telefone de contato da entrega.

labelstring

Apelido ("Casa", "Trabalho").

is_defaultboolean

true torna este o endereço padrão e tira a marca do anterior. O primeiro endereço do cliente é sempre o padrão.

complementstring

Complemento extra ("Casa 10", "Bloco B").

bash

curl -X POST "$BASE_URL/api/v1/storefront/addresses" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "first_name": "Maria",
  "last_name": "Souza",
  "address_line1": "Avenida Paulista, 1000",
  "address_line2": "Apto 52",
  "district": "Bela Vista",
  "city": "São Paulo",
  "state": "SP",
  "postal_code": "01310-100",
  "country": "BR",
  "phone": "11987654321",
  "label": "Casa",
  "is_default": true
}'

201Endereço criado

json

{
  "id": "04d6da67-1f55-427c-885d-0a30bdbf264d",
  "address_id": "04d6da67-1f55-427c-885d-0a30bdbf264d",
  "user_id": "264a70c1-9c69-458d-ac73-838543f87da2",
  "label": "Casa",
  "is_default": true,
  "first_name": "Maria",
  "last_name": "Souza",
  "address_line1": "Avenida Paulista, 1000",
  "address_line2": "Apto 52",
  "district": "Bela Vista",
  "district_id": "e471b959-3334-4bcb-93e4-45609cc40fc0",
  "city": "São Paulo",
  "city_id": "3d899205-1b71-4f09-8bbf-2c62bcefc2e5",
  "state": "SP",
  "postal_code": "01310-100",
  "country": "BR",
  "phone": "11987654321",
  "type": "D",
  "created_at": "2026-10-11T20:54:49.755615Z",
  "updated_at": "2026-10-11T20:54:49.755615Z"
}

A resposta é o endereço criado. A plataforma tenta ligar a cidade e o bairro ao catálogo da loja e preenche city_id e district_id quando encontra.

Status	Quando	Corpo
400	Corpo que não é JSON	`{"error":"invalid request body","detail":"..."}`
401	Sem token, ou token inválido ou expirado	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
403	A loja bloqueou a edição de endereço para este tipo de conta	`{"error":"address_edit_blocked","detail":"Address create/edit/delete is disabled for your account type"}`
422	Política de endereço da loja	`{"error":"address_number_required","message":"..."}`
500	Falha ao gravar	`{"error":"failed to create address","detail":"..."}`

PUT/api/v1/storefront/addresses/{id}Cliente

Altera um endereço

Altera só os campos enviados. Aceita os mesmos campos e sinônimos do corpo de criar (todos opcionais, listados na rota POST acima). Mandar is_default: true passa o padrão para este endereço.

Parâmetros de caminho

iduuidobrigatório

Id do endereço. Um texto que não é UUID responde 400 invalid id.

bash

curl -X PUT "$BASE_URL/api/v1/storefront/addresses/$ADDRESS_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "Trabalho",
  "is_default": false
}'

A resposta 200 é o endereço atualizado.

Status	Quando	Corpo
400	`id` que não é UUID, ou corpo que não é JSON	`{"error":"invalid id","detail":"id must be a valid UUID"}`
401	Sem token, ou token inválido ou expirado	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
403	Edição de endereço bloqueada pela loja	`{"error":"address_edit_blocked"}`
422	Política de endereço da loja (só quando um campo de endereço foi alterado)	`{"error":"address_cep_mismatch","message":"..."}`
500	Falha ao gravar	`{"error":"failed to update address","detail":"..."}`

DELETE/api/v1/storefront/addresses/{id}Cliente

Apaga um endereço

Remove o endereço do caderno. Pedidos já feitos com ele não mudam, porque guardam a sua própria cópia. Se o endereço apagado era o padrão, o cliente fica sem padrão até marcar outro.

Parâmetros de caminho

iduuidobrigatório

Id do endereço.

bash

curl -X DELETE "$BASE_URL/api/v1/storefront/addresses/$ADDRESS_ID" \
  -H "Authorization: Bearer $TOKEN"

200Endereço apagado

json

{ "message": "address deleted" }

Status	Quando	Corpo
400	`id` que não é UUID	`{"error":"invalid id"}`
401	Sem token, ou token inválido ou expirado	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
403	Edição de endereço bloqueada pela loja	`{"error":"address_edit_blocked"}`
500	Endereço inexistente ou de outro cliente (a plataforma devolve 500 em vez de 404), ou falha interna	`{"error":"failed to delete address","detail":"address 1111... not found for user ..."}`