---
title: "Listar clientes"
description: "GET /v1/customers — listagem paginada de clientes do estabelecimento."
method: "GET"
path: "/v1/customers"
url: "https://developer.beefood.com.br/docs/clientes/listar"
group: "Clientes"
scope: "customers:read"
lang: "pt"
---
# Listar clientes

`GET /v1/customers`

- Produção: `https://api.beefood.app/v1/customers`
- Sandbox: `https://api-sandbox.beefood.app/v1/customers`

Retorna os clientes do estabelecimento.

## Autenticação

Envie o access token no header `Authorization: Bearer <accessToken>`. Escopo necessário: `customers:read`. Limite: 300 requisições a cada 3 minutos.



## Parâmetros de query

- `page` *integer* — Página atual da lista. Exemplo: `1`.

- `limit` *integer* — Quantidade de itens por página. Exemplo: `20`.

- `sort` *string* — Ordem da lista: mais recentes (desc) ou mais antigos (asc). Exemplo: `"desc"`.
  - *Valores:* `asc`, `desc`

- `active` *boolean* — Filtra clientes ativos ou inativos. Exemplo: `true`.

- `customerName` *string* — Filtra pelos clientes cujo nome contém o texto informado. Exemplo: `"Cliente Exemplo"`.

- `email` *string* — Filtra pelo e-mail do cliente. Exemplo: `"cliente@exemplo.com"`.

- `documentNumber` *string* — Filtra pelo CPF ou CNPJ exato do cliente (somente dígitos). Exemplo: `"12345678900"`.

- `phone` *string* — Filtra pelos clientes cujo telefone contém os dígitos informados. Exemplo: `"11999990000"`.




## Exemplos de requisição

### cURL

```bash
curl -X GET "https://api.beefood.app/v1/customers?page=1&limit=20&sort=desc" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```


## Exemplos de resposta

### 200 OK

```json
{
  "items": [
    {
      "customerId": "13188863",
      "customerName": "Simone Costa"
    },
    {
      "customerId": "13188849",
      "customerName": "Rafael Lima"
    }
  ],
  "page": 1,
  "limit": 2,
  "total": 471,
  "pages": 236
}
```


## Campos da resposta

- `items[].customerId` *string* — ID do cliente.

- `items[].customerName` *string* — Nome do cliente.

- `items[].documentNumber` *string* — CPF ou CNPJ.

- `items[].email` *string* — E-mail.

- `items[].phone` *object* — Telefone.

- `items[].birthDate` *string* — Data de nascimento.

- `items[].averageTicket` *number* — Ticket médio do cliente.

- `items[].averageRating` *number* — Nota média nas avaliações.

- `items[].firstOrderDate` *string* — Data do primeiro pedido.

- `items[].origin` *string* — Origem do cadastro/cliente.
  - *Valores:* `DIGITAL_MENU`, `DIGITAL_MENU_DELIVERY`, `DIGITAL_MENU_LOCAL`, `DELIVERY`, `TABLE`, `OTHER`

- `page` *number* — Página atual da lista.

- `limit` *number* — Quantidade de itens por página.

- `total` *number* — Total de registros encontrados.

- `pages` *number* — Total de páginas.



## Erros

| Status | Mensagem |
| --- | --- |
| 400 | 'page' must be an integer >= 1 |
| 400 | 'limit' must be an integer between 1 and 100 |
| 400 | 'sort' must be asc or desc |
| 401 | Authentication token is missing |
| 401 | Invalid or expired access token |
| 403 | This credential does not include the customers:read scope |
| 500 | Database error when trying to … |


## Vocabulários usados neste endpoint

## Clientes · origin

| Valor | Significado | Uso |
| --- | --- | --- |
| `DIGITAL_MENU` | Cardápio digital | Clientes |
| `DIGITAL_MENU_DELIVERY` | Cardápio digital delivery | Clientes |
| `DIGITAL_MENU_LOCAL` | Cardápio digital presencial | Clientes |
| `DELIVERY` | Delivery | Clientes |
| `TABLE` | Mesa / comanda | Clientes |
| `OTHER` | Outro | Clientes |

## Listagens · sort

| Valor | Significado | Uso |
| --- | --- | --- |
| `asc` | Crescente | Todas as listagens |
| `desc` | Decrescente (padrão) | Todas as listagens |