> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fastpaybrasil.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Listar clientes

> Busca os clientes cadastrados na sua conta, com filtro por nome, e-mail, documento ou telefone e paginação.

Esta rota devolve, página a página, os clientes (objeto `customer`) cadastrados na sua conta. Use para montar uma tela de clientes no seu sistema, para encontrar o `id` de um cliente antes de cobrar ou registrar um cartão e para conferir se uma pessoa já tem cadastro antes de criar outro.

## Quando usar

| Situação | Como usar esta rota |
| - | - |
| Tela de busca de clientes no seu painel | `search` com o termo digitado pelo operador |
| Descobrir se um e-mail já tem cadastro antes de criar o cliente | `email` com o endereço exato |
| Localizar o cliente pelo CPF ou CNPJ | `documentId` com o número do documento |
| Exportar ou sincronizar a base de clientes | Percorra as páginas com `page` e `size` até o valor de `pages` |
| Ver os dados de um cliente cujo `id` você já tem | Use [Consultar cliente](https://docs.fastpaybrasil.com/referencia/clientes/consultar.md) |

## Antes de chamar

* Tenha uma chave secreta (`sk_`) válida ([Credenciais e ambientes](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md)).
* A rota lista os clientes da conta dona da chave. Com a chave de teste, você vê os clientes do ambiente de testes.

## Parâmetros de consulta

Todos os parâmetros são opcionais. Sem nenhum filtro, a rota devolve a primeira página com até 10 clientes, dos mais recentes para os mais antigos.

**search** `string`

Busca por nome, e-mail, documento ou telefone. Ex.: `joao`.

**email** `string`

Filtra pelo e-mail **exato**. Ex.: `joao@email.com`.

**documentId** `string`

Filtra pelo número do documento. Ex.: `52998224725`.

**page** `integer` (default: 1)

Número da página. Começa em `1`. Valor menor que 1 ou não numérico volta ao padrão.

**size** `integer` (default: 10)

Quantidade de itens por página. Valor menor que 1 ou não numérico volta ao padrão.

> [!WARNING]
>
> O tamanho da página vai em `size`. Um parâmetro `limit` é ignorado sem erro: `limit=50` continua devolvendo 10 itens.

> [!TIP]
>
> **Para o desenvolvedor:** `search` serve para busca livre (uma caixa de pesquisa, por exemplo). Para checar se um cliente já existe antes de criar outro, prefira `email` ou `documentId`, que são filtros diretos. As regras gerais de paginação estão em [Paginação, ordenação e idempotência](https://docs.fastpaybrasil.com/primeiros-passos/paginacao-ordenacao-idempotencia.md).

## Respostas

A resposta usa o mesmo envelope plano das outras listagens paginadas da API.

**data** `object[]`

Clientes da página atual.

**total** `integer`

Total de clientes encontrados com os filtros enviados.

**page** `integer`

Página atual.

**size** `integer`

Itens por página.

**pages** `integer`

Total de páginas.

**Em validação (V-37):** os campos de cada cliente em `data` e o exemplo de resposta estão retidos até a correção desta listagem pelo time técnico.

| HTTP | Significado | Corpo |
| - | - | - |
| `200` | Lista devolvida | `data`, `total`, `page`, `size` e `pages` |
| `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` |

> [!NOTE]
>
> **Para o negócio:** um cliente pode nascer de duas formas: pelo cadastro direto em [Criar cliente](https://docs.fastpaybrasil.com/referencia/clientes/criar.md) ou automaticamente, quando uma cobrança ou assinatura recebe nome e e-mail sem um `id`. Esta rota é a forma de a equipe encontrar um cadastro e recuperar o identificador dele para as operações seguintes, como registrar um cartão.

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| `401 Unauthorized` | Chave ausente, inválida ou codificada errado no Basic | Codifique em Base64 a chave seguida de `:` e envie no cabeçalho `Authorization` |
| Lista vazia com chave de teste | Os clientes foram criados com a chave de produção (ou o contrário) | Use a chave do mesmo ambiente em que o cliente foi criado |
| A página sempre volta com 10 itens | Parâmetro de tamanho enviado como `limit` | Envie `size` |
| Filtro por e-mail não encontra o cliente | `email` faz comparação exata | Confira o endereço completo ou use `search` para busca livre |

```http REST (JSON) theme={null}
GET /v1/customers?search=joao&page=1&size=10 HTTP/1.1
Host: api-global.fastpaybrasil.com
Authorization: Basic <base64 de "SUA_CHAVE_SECRETA:">
```

```bash cURL theme={null}
curl -X GET "https://api-global.fastpaybrasil.com/v1/customers?search=joao&page=1&size=10" \
  -u "$FINVIA_API_KEY:"
```

```javascript Node.js theme={null}
const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');

const params = new URLSearchParams({ email: 'joao@email.com', page: '1', size: '10' });

const response = await fetch(`https://api-global.fastpaybrasil.com/v1/customers?${params}`, {
  headers: { Authorization: `Basic ${credentials}` },
});

const { data, total, pages } = await response.json();
console.log(`${total} cliente(s) em ${pages} página(s)`);
```

```python Python theme={null}
import os

import requests

response = requests.request(
    "GET",
    "https://api-global.fastpaybrasil.com/v1/customers?search=joao&page=1&size=10",
    auth=(os.environ["FINVIA_API_KEY"], ""),
    timeout=30,
)

print(response.status_code)
if response.content:
    print(response.json())
```

```php PHP theme={null}
<?php

$ch = curl_init('https://api-global.fastpaybrasil.com/v1/customers?search=joao&page=1&size=10');

curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':',
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status, PHP_EOL;
print_r(json_decode($body, true));
```

```java Java theme={null}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Base64;

public class Exemplo {
    public static void main(String[] args) throws Exception {
        String credentials = Base64.getEncoder()
            .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes());

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api-global.fastpaybrasil.com/v1/customers?search=joao&page=1&size=10"))
            .header("Authorization", "Basic " + credentials)
            .method("GET", HttpRequest.BodyPublishers.noBody())
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());

        System.out.println(response.statusCode());
        System.out.println(response.body());
    }
}
```

```csharp C# theme={null}
using System.Net.Http.Headers;
using System.Text;

var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY");
var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:"));

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials);

var request = new HttpRequestMessage(HttpMethod.Get, "https://api-global.fastpaybrasil.com/v1/customers?search=joao&page=1&size=10");

var response = await client.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

```go Go theme={null}
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api-global.fastpaybrasil.com/v1/customers?search=joao&page=1&size=10", nil)
	if err != nil {
		panic(err)
	}
	req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	body, _ := io.ReadAll(res.Body)
	fmt.Println(res.StatusCode)
	fmt.Println(string(body))
}
```

```ruby Ruby theme={null}
require "net/http"
require "uri"

uri = URI("https://api-global.fastpaybrasil.com/v1/customers?search=joao&page=1&size=10")
request = Net::HTTP::Get.new(uri)
request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "")

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts response.code
puts response.body
```

```json 401 theme={null}
{
  "statusCode": 401,
  "message": "Unauthorized"
}
```

## Veja também

> [card] [Guia de clientes](https://docs.fastpaybrasil.com/guias/clientes.md)
>
> Quando cadastrar clientes e como eles se ligam a cartões e assinaturas.

> [card] [Criar cliente](https://docs.fastpaybrasil.com/referencia/clientes/criar.md)
>
> Cadastro com nome, e-mail e documento.

> [card] [Consultar cliente](https://docs.fastpaybrasil.com/referencia/clientes/consultar.md)
>
> Dados de um cliente pelo `id`.

> [card] [Visão geral de assinaturas](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md)
>
> O cliente como primeiro passo da cobrança recorrente.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.