VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Guia rápido/Clientes

Endereços

Lista, cria, altera e exclui os endereços de entrega e cobrança de um cliente.

Um cliente pode ter vários endereços. Eles são usados no checkout (entrega e cobrança), na emissão da nota fiscal e no cálculo de frete. Um deles é o padrão: o que a vitrine sugere primeiro e o que os filtros por cidade e UF da lista de clientes consultam.

Use estas rotas quando o endereço nasce fora da vitrine: o ERP cadastra a filial do cliente, o atendimento corrige um CEP, uma migração traz o histórico.

Cada endereço traz, além dos campos próprios, os campos de apelido b_* (cobrança) e s_* (entrega), que repetem os campos principais para quem já lê esses nomes.

GET/api/v1/admin/users/{id}/addressesAdmin

Lista os endereços de um usuário

Exige view_users ou manage_users. Usuário sem endereços devolve lista vazia ([]).

Path parameters

iduuidobrigatório
Id do usuário.
200Endereços do usuário
json
{
  "addresses": [
    {
      "id": "d9e1749d-ae6a-4f9a-8943-22d93d90cde0",
      "user_id": "3dc023ca-3746-4b6e-8afd-686a4a9af99f",
      "label": "Matriz",
      "is_default": true,
      "first_name": "Padaria Pão Doce Ltda",
      "last_name": "",
      "address_line1": "Avenida Paulista, 1000",
      "complement": "Sala 14",
      "district": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "postal_code": "01310-100",
      "country": "BR",
      "phone": "1133334444",
      "created_at": "2026-10-11T20:56:23.338259Z",
      "updated_at": "2026-10-11T20:57:46.981711Z"
    }
  ],
  "total": 1
}

Campos do endereço

iduuid
Id do endereço. address_id repete o valor.
user_iduuid
Dono do endereço.
labelstring
Apelido ("Casa", "Matriz"). Pode ser vazio.
is_defaultboolean
Endereço padrão do usuário. Só um por usuário.
first_namestring
Nome do destinatário. Para destinatário PJ, a razão social inteira.
last_namestring
Sobrenome do destinatário. Pode ser vazio.
address_line1string
Logradouro e número (Avenida Paulista, 1000).
address_line2string
Segunda linha, quando existe (a vitrine usa para o número).
complementstring
Complemento (Sala 14, Bloco B). Campo próprio, não se mistura com address_line2.
districtstring
Bairro. district_id é o id no catálogo de bairros, quando o bairro existe lá.
citystring
Cidade. city_id é o id no catálogo de cidades, quando a cidade existe lá (usado para casar áreas de entrega).
statestring
UF (SP).
postal_codestring
CEP, como foi enviado (01310-100 ou 01310100).
countrystringpadrão: BR
País (código de 2 letras).
phonestring
Telefone do destinatário, gravado como veio (sem normalizar).
typestring
Apelido fixo (D).
s_*, b_*string
Apelidos para entrega (s_firstname, s_lastname, s_address, s_city, s_state, s_zipcode, s_country, s_phone) e cobrança (b_*, os mesmos nomes). Sempre iguais aos campos acima.
created_atstring
Criação (RFC 3339). updated_at é a última alteração.
POST/api/v1/admin/users/{id}/addressesAdmin

Cria um endereço para um usuário

Cadastra um endereço em nome do cliente. Exige manage_users. O corpo aceita os nomes dos campos e também apelidos de entrada (address, zipcode, address2, firstname...).

Esta rota não aplica as regras de endereço da vitrine (número obrigatório, conferência do CEP). Valide antes de enviar.

Path parameters

iduuidobrigatório
Id do usuário.

Corpo da requisição

first_namestringobrigatório
Nome do destinatário. Apelido: firstname.
last_namestring
Sobrenome. Apelido: lastname. Opcional: para PJ, use a razão social em first_name.
address_line1stringobrigatório
Logradouro. Apelido: address. Se você também enviar number, ele é anexado (Rua das Flores, 123) quando ainda não aparece no texto.
address_line2string
Segunda linha. Apelido: address2.
complementstring
Complemento.
districtstring
Bairro. Apelido: neighborhood.
citystringobrigatório
Cidade.
statestringobrigatório
UF.
postal_codestringobrigatório
CEP. Apelidos: zipcode, zip_code, post_code.
countrystringpadrão: BR
País.
phonestring
Telefone do destinatário.
labelstring
Apelido do endereço.
is_defaultbooleanpadrão: false
Torna este o endereço padrão (o anterior deixa de ser).
city_iduuid
Id da cidade no catálogo. Se omitido, a plataforma tenta achar pelo nome e pela UF.
district_iduuid
Id do bairro no catálogo. Se omitido, a plataforma tenta achar pelo nome.

Exemplo de requisição (criar)

bash
curl -X POST "$BASE_URL/api/v1/admin/users/3dc023ca-3746-4b6e-8afd-686a4a9af99f/addresses" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Padaria Pão Doce Ltda",
    "address_line1": "Avenida Paulista, 1000",
    "complement": "Sala 12",
    "district": "Bela Vista",
    "city": "São Paulo",
    "state": "SP",
    "postal_code": "01310-100",
    "phone": "1133334444",
    "label": "Loja",
    "is_default": true
  }'

Resposta (criar)

201Endereço criado
json
{
  "id": "d9e1749d-ae6a-4f9a-8943-22d93d90cde0",
  "user_id": "3dc023ca-3746-4b6e-8afd-686a4a9af99f",
  "label": "Loja",
  "is_default": true,
  "first_name": "Padaria Pão Doce Ltda",
  "last_name": "",
  "address_line1": "Avenida Paulista, 1000",
  "complement": "Sala 12",
  "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": "1133334444",
  "created_at": "2026-10-11T20:56:23.338259Z",
  "updated_at": "2026-10-11T20:56:23.338259Z"
}

A resposta é o endereço completo (com os apelidos s_* e b_*, omitidos aqui). Reaproveite o id para alterar ou excluir.

PUT/api/v1/admin/users/{id}/addresses/{addressId}Admin

Atualiza um endereço de um usuário

Altera apenas os campos enviados. Exige manage_users. Aceita os mesmos nomes e apelidos da criação, todos opcionais.

Path parameters

iduuidobrigatório
Id do usuário.
addressIduuidobrigatório
Id do endereço (de addresses[].id).

Corpo da requisição

first_namestring
Nome do destinatário.
last_namestring
Sobrenome.
address_line1string
Logradouro.
address_line2string
Segunda linha.
complementstring
Complemento.
districtstring
Bairro.
citystring
Cidade.
statestring
UF.
postal_codestring
CEP.
countrystring
País.
phonestring
Telefone.
labelstring
Apelido.
is_defaultboolean
true torna este o padrão.

A resposta é o endereço atualizado, no mesmo formato da criação, com status 200.

DELETE/api/v1/admin/users/{id}/addresses/{addressId}Admin

Exclui um endereço de um usuário

Remove o endereço. Exige manage_users.

Path parameters

iduuidobrigatório
Id do usuário.
addressIduuidobrigatório
Id do endereço.
200Endereço excluído
json
{ "message": "address deleted" }

Erros

StatusQuandoCorpo
400Faltam campos obrigatórios na criação{"error":"missing required address fields","detail":"first_name, address_line1, city, state, postal_code are required"}
400Corpo que não é JSON{"error":"invalid request body","detail":"..."}
400addressId que não é UUID{"error":"invalid addressId","detail":"addressId must be a valid UUID"}
401Sem credenciais ou token expirado{"error":"invalid or expired token"}
403Falta o privilégio manage_users{"error":"insufficient privileges","required":"manage_users"}
404Usuário (criação) ou endereço (alterar, excluir) inexistente{"error":"user not found"} ou {"error":"address not found"}
500Id de usuário que não é UUID, ou falha interna{"error":"failed to create address","detail":"..."}
Telefone do endereço não é o telefone da conta

O telefone do endereço é o contato de quem recebe a entrega e é gravado como você enviou. O telefone da conta (phone do usuário) é normalizado para o formato internacional (+55...). Não use um no lugar do outro ao conciliar cadastros.

Os campos `s_*` e `b_*` são só leitura

Eles existem para quem lê esses nomes. Para gravar, use first_name, address_line1, postal_code e os demais campos acima (ou os apelidos de entrada address, zipcode, firstname).

Veja também

  • Consultar cliente
  • Criar cliente
  • Pedidos
Anterior
PF e PJ
Próxima
Campos de perfil
Nesta página
  • Exemplo de requisição (criar)
  • Resposta (criar)
  • Erros
  • Veja também