Listar endereços

Visão Geral

Este endpoint permite recuperar uma lista paginada de endereços, com opções de filtragem e ordenação. É especialmente útil para implementação de interfaces de seleção de endereço em processos de checkout, perfis de usuário e painéis administrativos.

Precauções

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

• Filtro por Cliente: O parâmetro customerid é opcional. Quando informado, filtra os endereços pelo dono e valida que o cliente existe (caso contrário retorna 404). Sem ele, são listados os endereços da sua conta.
• Paginação: Este endpoint retorna resultados paginados. Utilize os parâmetros limit e offset para navegar entre as páginas.
• Volume de Dados: Para muitos endereços, considere implementar paginação eficiente para melhor desempenho.

Descrição

O endpoint Listar Endereços permite consultar a lista de endereços cadastrados, com suporte a paginação, ordenação e filtragem por cliente.

Requisição

GET /v1/addresses

Parâmetros da Requisição

Também são aceitos os filtros de intervalo de data: daterange, daterangegt, daterangegte, daterangelt, daterangelte.

Atenção: o parâmetro é customerid (tudo minúsculo) e não existe filtro isPrimary nesta rota.

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 a lista paginada de endereços.

Exemplo de Resposta

{
  "offset": 0,
  "limit": 20,
  "total": 42,
  "hasMore": true,
  "page": {
    "current": 1,
    "total": 3,
    "offset": { "first": 0, "prev": null, "next": 20, "last": 40 }
  },
  "data": [
    {
      "id": "addr_01hqzvabc",
      "ownerType": "customer",
      "ownerId": "cus_01hqzvabc",
      "street": "Av. Paulista",
      "number": "1000",
      "complement": null,
      "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 BR 01310100",
      "line1": "Av. Paulista, 1000",
      "line2": "Bela Vista",
      "line3": "São Paulo SP BR 01310100",
      "metadata": { "source": "checkout" },
      "createdAt": "2026-04-12T17:56:33.000Z",
      "updatedAt": "2026-04-12T17:56:33.000Z",
      "_links": {
        "self": { "href": "https://api.selectwin.io/v1/addresses/addr_01hqzvabc", "method": "GET", "description": "Read a address." }
      }
    }
  ],
  "merchant": {
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  },
  "_links": {
    "self": {
      "href": "https://api.selectwin.io/v1/addresses",
      "method": "GET",
      "description": "List all addresses."
    },
    "create": {
      "href": "https://api.selectwin.io/v1/addresses",
      "method": "POST",
      "description": "Create a new address."
    }
  }
}

Atributos da Resposta

Atributos de Paginação (resposta raiz)

Atributos de cada objeto de Endereço (array data)

Cada item de data é o objeto completo do endereço (mesmo shape do Consultar Endereço), com seu próprio _links:

Respostas de Erro

400 Bad Request

Esta resposta ocorre quando há erros nos parâmetros da requisição (ex.: customerid em formato inválido).

{
  "error": {
    "status": "Bad Request",
    "statusCode": 400,
    "category": "validation",
    "message": "Validation errors occurred.",
    "params": [
      {
        "customerid": "must be a valid cus_ id"
      }
    ]
  }
}

404 Not Found

Ocorre quando o customerid informado não corresponde a um cliente existente na sua conta (invalidCustomerId).

{
  "error": {
    "status": "Not Found",
    "statusCode": 404,
    "category": "resource",
    "message": "The provided customer id is invalid."
  }
}

Casos de Uso

1. Seleção de Endereço: Permitir que o cliente escolha entre seus endereços durante o checkout
2. Gestão de Perfil: Exibir todos os endereços cadastrados na área do cliente
3. Dashboard Administrativo: Visualizar endereços associados a um cliente específico
4. Análise Geográfica: Coletar dados de localização para análises de mercado e logística

Melhores Práticas

1. Cache de Resultados: Para clientes com muitos endereços, considere armazenar em cache os resultados desta chamada
2. Implementação de Paginação: Utilize os parâmetros offset e limit para implementar paginação eficiente
3. Filtro por Cliente: Utilize o parâmetro customerid para obter apenas os endereços de um cliente específico
4. Validação no Cliente: Valide os parâmetros de consulta no lado do cliente antes de enviar a requisição
5. Tratamento de Lista Vazia: Implemente um tratamento adequado para quando a lista de endereços estiver vazia

Integração com Outros Endpoints

• Use Consultar Endereço para obter detalhes completos de um endereço específico da lista
• Use Criar Endereço para adicionar um novo endereço quando a lista estiver vazia
• Use Excluir Endereço para remover endereços obsoletos da lista