Listar clientes

Recupera uma coleção paginada de clientes cadastrados na sua conta, com busca, filtros e ordenação. É o ponto de partida para telas administrativas, sincronização de CRM, relatórios e para encontrar o id de um cliente quando você só conhece o e-mail, o documento ou a sua referência externa.

GET /v1/customers

Como funciona

O endpoint devolve um objeto paginado: em vez de despejar todos os clientes de uma vez, a API retorna uma "fatia" controlada por limit (tamanho da página) e offset (quantos registros pular). Junto vêm metadados de navegação (total, hasMore, page) e links HATEOAS (_links) para a próxima ação possível.

Pontos importantes do mecanismo:

• Projeção leve. Cada item em data[] é uma versão resumida do cliente — só os campos mais usados para listar (nome, e-mail, documento, telefone, situação e timestamps). Campos pesados como endereços, cartões e transações não vêm na listagem. Para a ficha completa, use Consultar cliente com o id retornado aqui.
• Filtros combinam com E (AND). Se você enviar email e document ao mesmo tempo, só voltam clientes que casem com ambos.
• Filtros de data. A família daterange* filtra pelo campo de data do cliente (data de cadastro). daterange isola um único dia; os sufixos gt/gte/lt/lte definem limites inferiores/superiores, exclusivos ou inclusivos.
• Operação somente-leitura. Listar não altera nada, não consome idempotência e pode ser repetida à vontade (respeitando os limites de uso).

Quando usar (e quando não)

Use para encontrar clientes por critério (e-mail, documento, nome, referência externa), para alimentar listagens administrativas e para sincronização incremental por intervalo de datas.

Evite usar a listagem como banco de dados espelho: percorrer toda a base página a página em tempo real é caro e lento. Se você já tem o id, vá direto em Consultar cliente. Se você sincroniza um sistema externo, prefira filtrar por daterangegte a partir do último ponto sincronizado, em vez de varrer tudo.

Requisição

Headers

Resumo das Convenções:

Não há corpo de requisição neste endpoint, então Content-Type é dispensável.

Parâmetros de consulta (query)

Todos opcionais. Sem filtros, a API retorna a primeira página de todos os clientes.

Os nomes de filtro são minúsculos sem separador (telephoneline, externalreference), mesmo que o campo correspondente no objeto seja camelCase (telephone.line, externalReference).

Exemplos curl

Primeira página, 20 itens, mais recentes primeiro:

curl "https://api.selectwin.io/v1/customers?limit=20&offset=0&sort=descending" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Buscar por documento (encontrar o id a partir do CPF):

curl "https://api.selectwin.io/v1/customers?document=12345678901" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Sincronização incremental: clientes cadastrados a partir de uma data:

curl "https://api.selectwin.io/v1/customers?daterangegte=2026-04-01T00:00:00Z&limit=100" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Resposta

200 OK — objeto paginado. Cada item em data[] é uma projeção leve do cliente.

{
  "offset": 0,
  "limit": 20,
  "total": 142,
  "hasMore": true,
  "page": {
    "current": 1,
    "total": 8,
    "offset": { "first": 0, "prev": null, "next": 20, "last": 140 }
  },
  "data": [
    {
      "id": "cus_01hqzvabc",
      "firstName": "João",
      "lastName": "Silva",
      "document": "12345678900",
      "documentType": "cpf",
      "email": "[email protected]",
      "telephone": "5511987654321",
      "delinquent": false,
      "available": true,
      "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/customers",
      "method": "GET",
      "description": "List all customers."
    },
    "create": {
      "href": "https://api.selectwin.io/v1/customers",
      "method": "POST",
      "description": "Create a new customer."
    }
  }
}

Campos da página

Campos de cada item em data[]

Como paginar

1. Comece com offset=0 e um limit (ex.: 100).
2. Processe data[].
3. Se hasMore for true, faça offset += limit e repita; ou use page.offset.next diretamente.
4. Pare quando hasMore for false.

Detalhes e exemplos em Paginação.

Erros

A resposta de erro usa o envelope padrão com error.code estável — trate sempre pelo code, nunca pela message. Veja Tratamento de erros e o Catálogo de códigos de erro.

Exemplo de 400 por limit inválido:

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

Boas práticas

• Filtre antes de paginar. Em bases grandes, sempre restrinja com email, document, externalreference ou um intervalo de datas — varrer tudo é lento e custa cota de requisições.
• Use daterangegte para sincronizar. Guarde o updatedAt/createdAt mais recente já processado e, na próxima rodada, filtre a partir dele, em vez de reler a coleção inteira.
• Trate data[] como resumo. Não tente extrair endereço, cartões ou transações daqui; busque a ficha individual em Read quando precisar dos detalhes.
• IDs são opacos. Armazene a string id inteira; não interprete o prefixo nem o comprimento. Veja Convenções.
• Pagine com hasMore/page.offset.next, não com cálculos próprios de "última página".
• Respeite os limites de uso. Em 429, aplique backoff honrando error.retryAfterMinutes (veja API Limits).
• Datas em UTC. Envie os filtros daterange* em ISO 8601 com sufixo Z; converta para o fuso do usuário só na exibição.

Veja também

• Visão geral de Clientes — o objeto, seus estados e todas as operações.
• Criar cliente — cadastrar um novo cliente.
• Consultar cliente — a ficha completa a partir do id encontrado aqui.
• Atualizar cliente — alterar dados de um cliente da lista.
• Excluir cliente — remover um cliente.
• Paginação · Convenções · Autenticação · Catálogo de códigos de erro