Consultar um endereço

Recupera um endereço específico pelo seu identificador público (addr_...), devolvendo o objeto completo — componentes do endereço, coordenadas, dono associado e links HATEOAS. Use quando precisar exibir, conferir ou pré-carregar os dados de um endereço antes de atualizá-lo, processar um checkout ou calcular frete.

GET /v1/addresses/{addressId}

Como funciona

Esta é uma operação de leitura (read): não altera nada no servidor, é segura e idempotente (chamar várias vezes devolve sempre o mesmo resultado, sem efeitos colaterais). Você informa o addressId no caminho da URL e a API responde com o objeto completo do endereço.

Diferentemente da listagem — que devolve projeções leves (alguns campos omitidos) dentro de um envelope paginado — a consulta individual devolve o objeto completo, no nível raiz da resposta (não dentro de data). Em especial, ela inclui os campos formatados line, line1, line2 e line3, que não aparecem nos itens da lista.

Cada resposta também traz um bloco _links (padrão HATEOAS — links que dizem ao cliente quais ações são possíveis a partir daqui). A partir de uma consulta, você descobre as URLs para atualizar (update), excluir (delete), criar (create) e listar (list) endereços sem precisar montá-las à mão.

Quando usar

• Conferir antes de atualizar: carregue o estado atual antes de enviar um PUT de atualização (que substitui o registro inteiro).
• Checkout e perfil: exibir um endereço salvo do cliente na tela de pagamento ou na área da conta.
• Logística: obter os componentes (e coordenadas, quando preenchidas) para cálculo de frete e roteirização.

Quando NÃO usar: se você precisa de vários endereços ou quer filtrar por cliente, não faça várias consultas em laço — use a listagem com o filtro customerid e paginação. A consulta individual é para quando você já tem o addressId exato.

Requisição

Headers

Por ser uma leitura sem corpo, não envie Content-Type nem X-Idempotency-Key.

Parâmetros de caminho

Exemplo curl

curl https://api.selectwin.io/v1/addresses/addr_01hqzvabc \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Resposta

200 OK — o corpo é o objeto completo do endereço no nível raiz.

{
  "id": "addr_01hqzvabc",
  "ownerType": "customer",
  "ownerId": "cus_01hqzvabc",
  "street": "Av. Paulista",
  "number": "1000",
  "complement": "Sala 1",
  "district": "Bela Vista",
  "city": "São Paulo",
  "state": "SP",
  "country": "BR",
  "postcode": "01310100",
  "latitude": null,
  "longitude": null,
  "primary": true,
  "line": "Av. Paulista, 1000 - Bela Vista, São Paulo - SP, 01310100",
  "line1": "Av. Paulista",
  "line2": "1000",
  "line3": "Bela Vista",
  "metadata": null,
  "updatedAt": "2026-04-12T17:56:33.000Z",
  "createdAt": "2026-04-12T17:56:33.000Z",
  "merchant": {
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  },
  "_links": {
    "self": {
      "href": "https://api.selectwin.io/v1/addresses/addr_01hqzvabc",
      "method": "GET",
      "description": "Read a address."
    },
    "create": {
      "href": "https://api.selectwin.io/v1/addresses",
      "method": "POST",
      "description": "Create a new address."
    },
    "update": {
      "href": "https://api.selectwin.io/v1/addresses/addr_01hqzvabc",
      "method": "PUT",
      "description": "Update the address."
    },
    "delete": {
      "href": "https://api.selectwin.io/v1/addresses/addr_01hqzvabc",
      "method": "DELETE",
      "description": "Delete the address."
    },
    "list": {
      "href": "https://api.selectwin.io/v1/addresses",
      "method": "GET",
      "description": "List all addresses."
    }
  }
}

Campos da resposta

Erros

Trate sempre pelo error.code (estável), nunca pela message. Exemplo de envelope 404:

{
  "error": {
    "code": "addressIdNotFound",
    "statusCode": 404,
    "category": "client",
    "message": "Address not found"
  }
}

Veja Tratamento de Erros e o Catálogo de Códigos de Erro.

Boas práticas

• Trate o addressId como opaco. Armazene a string inteira; não a derive de outros campos nem confie no comprimento. Veja Convenções.
• Distinga 404 de 400. addressIdNotFound (404) significa "não existe"; invalidParameters (400) significa "formato inválido". Em UI, mostre mensagens diferentes.
• Confira o dono antes de operações sensíveis. Valide ownerType/ownerId para garantir que o endereço pertence ao cliente esperado antes de cobrar ou despachar.
• Cache com prudência. Endereços mudam pouco, então cache curto é aceitável; invalide ao receber atualização ou exclusão, e use updatedAt como referência de frescor.
• Navegue pelos _links. Use _links.update/_links.delete da própria resposta em vez de montar URLs manualmente — isso mantém seu código resiliente a mudanças.
• Coordenadas podem ser null. Não assuma latitude/longitude preenchidos; trate o caso nulo antes de integrar com mapas ou cálculo de distância.
• Converta datas só na exibição. createdAt/updatedAt chegam em UTC (...Z); converta para o fuso do usuário apenas na tela.

Veja também

• Visão geral de Endereços — modelo do objeto e todas as operações.
• Listar endereços — buscar vários, com filtro por cliente e paginação.
• Atualizar endereço — substituir o registro completo (PUT).
• Criar endereço — cadastrar um novo endereço.
• Excluir endereço — remover um endereço.
• Convenções · Autenticação · Códigos de Erro