> For the complete documentation index, see [llms.txt](https://apidoc.toplojas.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidoc.toplojas.com.br/clientes/listar-clientes.md).

# Listar Clientes

Retorna a **listagem de clientes** da loja, com suporte a busca e paginação.

```
GET /clientes/
```

## 🔎 Filtros disponíveis

Os filtros são enviados na **Query** da requisição. Todos são opcionais e podem ser combinados.

| Parâmetro      | Tipo    | Descrição                                                         |
| -------------- | ------- | ----------------------------------------------------------------- |
| `ChaveBusca`   | texto   | Pesquisa por **Nome**, **CPF**, **CNPJ** ou **E-mail** do cliente |
| `Status`       | texto   | Situação do cadastro: `A` (Ativado) ou `D` (Desativado)           |
| `Pagina`       | inteiro | Página desejada (paginação)                                       |
| `QtdPorPagina` | inteiro | Registros por página (máx. **100**)                               |

{% hint style="info" %}
O filtro `ChaveBusca` é o mais prático para localizar um cliente: basta informar parte do nome, o CPF, o CNPJ ou o e-mail e a API retorna os clientes correspondentes.
{% endhint %}

## 📥 Exemplo de requisição

Buscando clientes pelo nome, 50 por página:

```bash
curl -X GET "https://api.toplojas.com.br/clientes/?ChaveBusca=Paloma&QtdPorPagina=50" \
  -H "Authorization: Bearer [Token]" \
  -H "Loja: [Identificador de Sua Loja]"
```

## 📤 Exemplo de resposta

A resposta segue o padrão de paginação (`Dados` + `Paginacao`):

```json
{
  "Dados": [
    {
      "Codigo": "679695",
      "IsPessoa": "F",
      "Nome_RazaoSocial": "Paloma Macetko",
      "CPF_CNPJ": "999.999.99-99",
      "RG_IE": "",
      "DataNascimento": "2024-01-01",
      "ObsStaff": "",
      "Email": "suporte2@web4business.com.br",
      "Telefone01": "(47) 11111111",
      "Telefone03": "(47) 22222222",
      "Telefone02": "(47) 33333333",
      "Endereco": {
        "End_Estado": "SC",
        "End_Cidade": "Brusque",
        "End_Bairro": "Centro",
        "End_Endereco": "Rua Central",
        "End_Numero": "99",
        "End_Complemento": "",
        "End_CEP": "88350-000"
      }
    }
  ],
  "Paginacao": {
    "PaginaAtual": 1,
    "QtdPaginas": 1,
    "QtdRegistros": 1
  }
}
```

{% hint style="info" %}
Consulte a descrição de cada campo na referência:

{% embed url="<https://api.toplojas.com.br/doc/#/Clientes>" %}
{% endhint %}

Para entender o funcionamento da paginação, veja:

{% content-ref url="/pages/-MObwaEfNJbBvr8ZSK0U" %}
[Paginação](/funcionamento/paginacao.md)
{% endcontent-ref %}