Consultar um endereço

Visão Geral

Este endpoint permite consultar informações detalhadas sobre um endereço específico armazenado na plataforma. Facilita a verificação e utilização de dados de endereço em processos de checkout, gestão de clientes e operações logísticas.

Precauções

ATENÇÃO! Por favor, leia estas informações importantes antes de usar este endpoint.

• ID do Endereço: Certifique-se de utilizar um ID de endereço válido e existente no sistema.
• Permissões: Verifique se você possui as permissões necessárias para acessar os dados do endereço.
• Cache: Considere implementar cache para endereços frequentemente acessados, a fim de reduzir a carga em sua aplicação.

Descrição

O endpoint Consultar Endereço permite obter informações detalhadas de um endereço específico a partir do seu ID de maneira rápida e eficiente.

Requisição

GET /v1/addresses/{addressId}

Parâmetros da Requisição

Resposta - 200 OK

Se a requisição for bem-sucedida, o servidor retornará um código de status HTTP 200 OK e um objeto JSON com as informações completas do endereço.

Exemplo de Resposta

Resposta root-level (mesmo shape de create/read via mount).

{
  "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": {
    "source": "checkout"
  },
  "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."
    }
  }
}

Atributos da Resposta

Respostas de Erro

400 Bad Request

Esta resposta ocorre quando o ID do endereço fornecido é inválido.

{
  "error": {
    "status": "Bad Request",
    "statusCode": 400,
    "category": "validation",
    "message": "Validation errors occurred.",
    "params": [
      {
        "addressId": "The provided address ID is invalid. Please check the ID and try again."
      }
    ]
  }
}

404 Not Found

Ocorre quando o addressId não existe ou não pertence à sua conta (addressIdNotFound).

{
  "error": {
    "status": "Not Found",
    "statusCode": 404,
    "category": "resource",
    "message": "Address not found."
  }
}

Casos de Uso

1. Checkout em E-commerce: Exibição de endereços salvos durante o processo de checkout
2. Perfil de Cliente: Visualização de detalhes de endereço na área do cliente
3. Gestão Logística: Consulta de endereços para cálculo de frete e planejamento de entregas
4. Validação de Dados: Verificação de informações de endereço antes de processar uma transação

Melhores Práticas

1. Cache de Resultados: Considere armazenar em cache os resultados desta chamada para endereços frequentemente acessados
2. Tratamento de Erros: Implemente tratamento adequado para todos os códigos de erro possíveis
3. Validação Visual: Se exibir o endereço para o usuário, considere utilizar um mapa para validação visual
4. Associação com Cliente: Verifique se o endereço pertence ao cliente correto antes de utilizar em operações sensíveis
5. Integração com Outros Serviços: Utilize as coordenadas geográficas (latitude e longitude) para integração com serviços de geolocalização

Integração com Outros Endpoints

• Use Listar Endereços para obter todos os endereços de um cliente
• Use Excluir Endereço para remover o endereço após a consulta, se necessário
• Use Criar Endereço para adicionar um novo endereço com base em um existente