Listar clientes

Este endpoint permite recuperar uma lista paginada de clientes, com opções de filtragem e ordenação, facilitando a busca e visualização de múltiplos registros de clientes. É especialmente útil para in

Visão Geral

Precauções

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

Paginação: Utilizar os parâmetros de paginação para limitar o volume de dados retornados por requisição.
Filtros: Aplicar filtros específicos para reduzir o conjunto de resultados e melhorar a performance.
Volume de Dados: Este endpoint pode retornar grandes volumes de dados, o que pode impactar o desempenho da aplicação.

Descrição

O endpoint Listar Clientes permite recuperar uma coleção paginada de clientes registrados no sistema. Os resultados podem ser filtrados por diversos parâmetros como e-mail ou documento, e ordenados conforme necessário.

Requisição

GET /v1/customers

Parâmetros de Consulta (Query)

Parâmetro	Tipo	Obrigatório	Descrição	Exemplo	Localização
`limit`	integer	Não	Número máximo de registros (1–100, padrão: 20)	`20`	Query
`offset`	integer	Não	Posição inicial para retornar registros (padrão: 0)	`0`	Query
`sort`	string	Não	Expressão de ordenação (ex.: `-createdAt`)	`-createdAt`	Query
`id`	string	Não	Filtra clientes pelo ID específico (`cus_*`)	`cus_01hqzvabc`	Query
`name`	string	Não	Filtra clientes pelo nome ou sobrenome (busca parcial)	`joão`	Query
`email`	string	Não	Filtra clientes pelo endereço de e-mail	`[email protected]`	Query
`document`	string	Não	Filtra clientes pelo número do documento (11–20 dígitos)	`12345678900`	Query
`telephoneline`	string	Não	Filtra clientes pela linha de telefone (7–20 dígitos, sem formatação)	`11987654321`	Query
`externalreference`	string	Não	Filtra clientes pela referência externa	`CUSTOMER_ID_12345`	Query

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

Resposta - 200 OK

Se a requisição for bem-sucedida, o servidor retornará um código de status HTTP 200 OK e uma lista paginada de clientes.

Exemplo de Resposta

{
  "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",
      "email": "[email protected]",
      "document": {
        "type": "cpf",
        "number": "12345678900"
      },
      "telephone": {
        "countryCode": "55",
        "areaCode": "11",
        "number": "987654321",
        "line": "11987654321"
      },
      "birthdate": "1990-05-15",
      "gender": "male",
      "available": true,
      "delinquent": false,
      "externalReference": "CRM-98765",
      "additionalEmails": ["[email protected]"],
      "metadata": { "source": "website" },
      "createdAt": "2026-04-12T17:56:33.000Z",
      "updatedAt": "2026-04-12T17:56:33.000Z",
      "_links": {
        "self": { "href": "https://api.selectwin.io/v1/customers/cus_01hqzvabc", "method": "GET", "description": "Read a customer." }
      }
    }
  ],
  "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."
    }
  }
}

Atributos da Resposta Paginada (lista de customers)

Atributo	Tipo	Descrição
`offset`	integer	Posição inicial dos resultados retornados
`limit`	integer	Quantidade máxima de registros retornados
`total`	integer	Total de registros disponíveis para a consulta
`hasMore`	boolean	Indica se existem mais resultados além dos retornados
`page.current`	integer	Número da página atual
`page.total`	integer	Total de páginas disponíveis
`page.offset.first` / `.prev` / `.next` / `.last`	integer \| null	Offsets de navegação
`data`	array	Lista de clientes — cada item é o objeto completo do cliente (sem os embeds `transactions`/`subscriptions`/`addresses`/`cards`), com seu próprio `_links`
`merchant`	object	`{ name, merchantId, isSubAccount }`
`_links`	object	Links HATEOAS da listagem (self, create)

Respostas de Erro

400 Bad Request

Ocorre quando a requisição contém parâmetros inválidos ou está mal formatada.

{
  "error": {
    "status": "Bad Request",
    "statusCode": 400,
    "category": "validation",
    "message": "Validation errors occurred.",
    "params": [
      {
        "limit": "O limite deve ser um número entre 1 e 100."
      }
    ]
  }
}

Casos de Uso

Interfaces Administrativas: Exibir lista de clientes em painéis de controle
Relatórios: Gerar relatórios de clientes com base em filtros específicos
Busca de Clientes: Permitir que operadores busquem clientes por e-mail ou documento
Exportação de Dados: Base para extração de dados de clientes para sistemas externos

Melhores Práticas

Implementar Paginação Eficiente: Sempre utilize os parâmetros limit e offset para controlar o volume de dados
Utilizar Filtros: Aproveite os filtros disponíveis para reduzir o conjunto de resultados
Cache de Resultados: Implemente cache nos resultados que não mudam com frequência
Evitar Listagens Completas: Sempre inclua algum filtro ao buscar clientes em bases muito grandes

Integração com Outros Endpoints

Use Consultar Cliente para obter detalhes completos de um cliente específico após encontrá-lo na lista
Use Atualizar Cliente para modificar informações de clientes encontrados na listagem
Use Excluir Cliente para remover clientes identificados através da listagem

Listar clientes

On this page