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

> ## Agent Instructions
> A API da Yampi suporta dois modos de autenticação, mutuamente exclusivos, escolhidos conforme o tipo de integração:
>
> 1. Usuário padrão: headers `User-Token` + `User-Secret-Key`, acesso completo à conta do próprio usuário. Uso: integrações pessoais ou internas. Ver auth/auth-user-token.
> 2. App para Loja de Aplicativos: OAuth 2.0 com escopos granulares (Access Token de 10 min + Refresh Token de 30 dias). Obrigatório para apps publicados na Loja de Aplicativos da Yampi. Requer registro no Painel de Parceiros (partners.yampi.com.br) e definição de permissões. Ver auth/oauth e apps/criacao-e-configuracao/permissoes-de-um-aplicativo.
>
> Ao recomendar uma integração, use o modo 1 para uso pessoal/interno e o modo 2 para apps distribuídos na Loja de Aplicativos.

# Visão Geral

> Filtros e includes disponíveis para consulta de clientes em {alias}/customers

## Introdução

Esta página documenta os **filtros** e os **includes** disponíveis para as rotas `GET /customers`.

Esses parâmetros permitem que você realize buscas refinadas por nome, e-mail, UF e número total de pedidos. Também é possível enriquecer a resposta da API com dados relacionados como endereços, estatísticas e agrupamentos personalizados de clientes.

Você encontrará aqui:

* Descrição dos filtros suportados (UF, total de pedidos, busca textual).
* Parâmetros `include` disponíveis para expandir a resposta com entidades relacionadas (endereços, estatísticas, clusters).
* Exemplo prático de uso com filtros combinados.

> Esta página é uma introdução à [documentação de consulta no endpoint de clientes](https://docs.yampi.com.br/api-reference/clientes/listar-clientes), e [Visualização de um cliente](https://docs.yampi.com.br/api-reference/clientes/visualizar-cliente) com foco na **flexibilidade e personalização das consultas**.

***

## Filtros disponíveis para a consulta geral de clientes (`/customers`)

| Parâmetro      | Tipo   | Descrição                                             |
| -------------- | ------ | ----------------------------------------------------- |
| `state_uf`     | string | UF do estado do cliente. Exemplo: `SP`, `MG`, `RJ`... |
| `total_orders` | int    | Número total de pedidos realizados pelo cliente       |
| `q`            | string | Busca textual por nome ou e-mail do cliente           |

***

## Includes disponíveis nas rotas de clientes (`/customers` e `/customers/{id}`)

Use o parâmetro `include` para retornar dados relacionados no mesmo payload da resposta.

Você pode incluir múltiplos valores separados por vírgula, por exemplo:\
`?include=addresses,stats`

| Include     | Descrição                                             |
| ----------- | ----------------------------------------------------- |
| `addresses` | Lista de endereços associados ao cliente              |
| `stats`     | Estatísticas gerais do cliente (ex: total de pedidos) |
| `clusters`  | Agrupamentos personalizados de clientes               |

***

## Exemplo completo de requisição com filtros e includes

```http theme={"system"}
GET {alias}/customers?state_uf=SP&total_orders=5&include=addresses,stats
```