Listar endereços

Recupere uma lista paginada de endereços cadastrados, com filtros por cliente e por intervalo de datas. Use para montar telas de seleção de endereço no checkout, exibir os endereços de um cliente no perfil ou sincronizar cadastros com o seu CRM/ERP.

GET /v1/addresses

Como funciona

Este endpoint retorna uma coleção paginada de endereços que pertencem à sua conta (merchant). Em vez de devolver tudo de uma vez, a API entrega os resultados em "páginas": você controla quantos itens vêm por vez (limit) e a partir de qual posição começar (offset).

Alguns pontos importantes sobre o comportamento:

• Projeção leve. Cada item dentro de data[] é uma projeção de listagem — uma versão enxuta do endereço, otimizada para listas. Ela já traz os campos principais (logradouro, cidade, CEP, etc.), mas para a representação individual completa (com os links de navegação de cada recurso) consulte Consultar endereço via GET /v1/addresses/{addressId}.
• Somente leitura. É uma operação GET, portanto segura e sem efeitos colaterais: pode ser repetida à vontade, não altera nada e não precisa de chave de idempotência.
• Metadados de paginação no nível raiz. O corpo da resposta é o próprio objeto paginado (offset, limit, total, hasMore, page, data, merchant, _links). Para entender esse envelope em detalhe, veja Paginação.

O fluxo típico de iterar por todas as páginas:

Quando usar (e quando não usar)

Use Listar quando você precisa descobrir ou percorrer vários endereços: popular um seletor de endereços, montar um painel administrativo, ou exportar cadastros em lote.

Quando não usar:

• Se você já tem o addr_* de um endereço específico e quer todos os detalhes, vá direto em Consultar endereço — é mais rápido e mais barato do que listar e filtrar no cliente.
• Para criar, alterar ou remover endereços, use Criar, Atualizar e Excluir.

Requisição

Headers

Por ser um GET sem corpo, não há Content-Type nem X-Idempotency-Key.

A autenticação é sempre pelo header SelectKey — nunca Authorization: Bearer ou Basic.

Parâmetros de query

Todos os parâmetros abaixo são opcionais. Sem nenhum filtro, o endpoint retorna a primeira página de todos os endereços da sua conta.

Exemplo de requisição

Primeira página de 25 endereços de um cliente, dos mais recentes para os mais antigos:

curl -G https://api.selectwin.io/v1/addresses \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  --data-urlencode "customerid=cus_01hqzvabc" \
  --data-urlencode "limit=25" \
  --data-urlencode "offset=0" \
  --data-urlencode "sort=descending"

Endereços criados em uma janela de datas, sem filtrar por cliente:

curl -G https://api.selectwin.io/v1/addresses \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  --data-urlencode "daterangegte=2026-04-01T00:00:00Z" \
  --data-urlencode "daterangelt=2026-05-01T00:00:00Z" \
  --data-urlencode "limit=100"

curl -G com --data-urlencode monta a query string com escape correto — útil para valores com : (datas) ou caracteres especiais.

Resposta

Em caso de sucesso, o servidor retorna 200 OK com o objeto paginado. O array data contém as projeções leves de cada endereço.

{
  "offset": 0,
  "limit": 25,
  "total": 42,
  "page": {
    "offset": { "first": 0, "prev": null, "next": 25, "last": 25 },
    "current": 1,
    "total": 2
  },
  "data": [
    {
      "id": "addr_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,
      "lineAddress": "Av. Paulista, 1000 - Bela Vista, São Paulo - SP, 01310100",
      "metadata": null,
      "primary": true,
      "ownerType": "customer",
      "ownerId": "cus_01hqzvabc",
      "updatedAt": "2026-04-12T17:56:33.000Z",
      "createdAt": "2026-04-12T17:56:33.000Z"
    }
  ],
  "hasMore": true,
  "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."
    }
  }
}

Campos de paginação (raiz da resposta)

Campos de cada endereço em data[]

Como percorrer todas as páginas

1. Comece com offset=0 e um limit (ex.: 25 ou 100).
2. Processe os itens de data.
3. Se hasMore for true, faça a próxima chamada usando page.offset.next como novo offset.
4. Pare quando hasMore for false.

Prefira sempre os valores de page.offset.* da própria resposta a recalcular offsets na mão — assim seu código continua correto mesmo se o limit efetivo mudar.

Erros

O envelope de erro traz um error.code estável (use-o para tratar erros — nunca a message). Veja a estrutura em Tratamento de Erros.

Exemplo de 400 por parâmetro inválido:

{
  "error": {
    "code": "invalidParameters",
    "statusCode": 400,
    "category": "validation",
    "message": "Validation errors occurred.",
    "params": [
      { "limit": "limit must be between 1 and 100" }
    ]
  }
}

Boas práticas

• Filtre no servidor, não no cliente. Passe customerid e os filtros de data na query em vez de baixar tudo e filtrar localmente — menos tráfego e menos chamadas contra o seu rate limit.
• Escolha um limit adequado. Para seletores de endereço no checkout, limit=10 costuma bastar. Para sincronização/exportação, use limit=100 e itere com page.offset.next para minimizar o número de chamadas.
• Navegue por page.offset.*. Use os offsets que a resposta entrega em vez de calcular offsets manualmente.
• Datas sempre em UTC com Z. Monte faixas com limite inferior inclusivo (daterangegte) e superior exclusivo (daterangelt) para não duplicar registros nas bordas.
• Trate data: []. Mostre um estado vazio amigável e, se fizer sentido, ofereça o fluxo de Criar endereço.
• Respeite o rate limit. Ao percorrer muitas páginas, espace as chamadas; em 429, faça backoff conforme error.retryAfterMinutes.
• IDs são opacos. Guarde o id (addr_*) inteiro; não faça parsing nem deduza nada do prefixo. Veja Convenções.

Veja também

• Visão geral de Endereços — o modelo do objeto e o ciclo de vida.
• Criar endereço · Consultar endereço · Atualizar endereço · Excluir endereço
• Paginação — o envelope offset/limit/page/hasMore em detalhe.
• Convenções · Autenticação · Catálogo de Códigos de Erro