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

# Paginação

> Entenda como os endpoints de listagem funcionam: tamanho de página, ordenação e navegação entre resultados.

Todos os endpoints de listagem da API Vendaze retornam resultados paginados. A resposta sempre inclui um array `data` e um objeto `meta` com os detalhes de navegação.

## Parâmetros de consulta

| Parâmetro  | Tipo    | Padrão       | Descrição                                                     |
| ---------- | ------- | ------------ | ------------------------------------------------------------- |
| `page`     | inteiro | `1`          | Número da página. Deve ser um inteiro positivo.               |
| `per_page` | inteiro | `50`         | Quantidade de registros por página. Máximo: `100`.            |
| `order_by` | string  | `created_at` | Campo para ordenação. Os valores aceitos variam por endpoint. |
| `order`    | string  | `desc`       | Direção da ordenação. Deve ser `asc` ou `desc`.               |

### Valores aceitos para `order_by` por recurso

| Recurso         | Valores aceitos                         |
| --------------- | --------------------------------------- |
| `people`        | `created_at`, `updated_at`, `full_name` |
| `companies`     | `created_at`, `updated_at`, `full_name` |
| `deals`         | `created_at`, `updated_at`, `name`      |
| `pipelines`     | `created_at`, `name`                    |
| `tasks`         | `created_at`, `updated_at`, `due_date`  |
| `task-types`    | `created_at`, `title`                   |
| `products`      | `created_at`, `name`                    |
| `tags`          | `created_at`, `name`                    |
| `lists`         | `created_at`, `name`                    |
| `custom-fields` | `created_at`, `label`                   |

## Estrutura da resposta

```json theme={null}
{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "full_name": "Maria Silva",
      "emails": [{ "email": "maria@empresa.com", "type": "work" }],
      "phones": [{ "phone": "+5511999990001", "type": "mobile" }],
      "owner": {
        "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "email": "joao@empresa.com",
        "name": "João Silva"
      },
      "avatar_url": null,
      "entity_id": "g7wwkh0",
      "created_at": "2026-01-15T10:30:00Z",
      "updated_at": "2026-01-15T10:30:00Z",
      "custom_fields": []
    }
  ],
  "meta": {
    "total": 120,
    "page": 1,
    "per_page": 50,
    "has_more": true
  }
}
```

### Campos do `meta`

| Campo      | Tipo     | Descrição                                                    |
| ---------- | -------- | ------------------------------------------------------------ |
| `total`    | inteiro  | Total de registros no workspace que correspondem à consulta. |
| `page`     | inteiro  | Número da página atual.                                      |
| `per_page` | inteiro  | Quantidade de registros retornados nesta página.             |
| `has_more` | booleano | `true` quando há páginas adicionais após esta.               |

## Listagem vs. detalhe

Os endpoints de listagem retornam um objeto compacto por registro. Relações embutidas (`company`, `tags`, `lists`) não são incluídas nas respostas de listagem. Use o endpoint `GET /:id` para obter um registro com todos os dados embutidos.

| Campo           | Listagem |  Detalhe (`GET /:id`) |
| --------------- | :------: | :-------------------: |
| Campos base     |    Sim   |          Sim          |
| `custom_fields` |    Sim   |          Sim          |
| `company`       |    Não   | Sim (somente pessoas) |
| `tags`          |    Não   |          Sim          |
| `lists`         |    Não   |          Sim          |

## Percorrendo todas as páginas

```javascript theme={null}
async function buscarTodasAsPessoas(accessToken) {
  const resultados = [];
  let pagina = 1;
  let temMais = true;

  while (temMais) {
    const res = await fetch(
      `https://api.vendaze.com/v1/people?page=${pagina}&per_page=50&order_by=created_at&order=asc`,
      { headers: { Authorization: `Bearer ${accessToken}` } },
    );

    if (!res.ok) throw new Error(`Requisição falhou: ${res.status}`);

    const { data, meta } = await res.json();
    resultados.push(...data);

    temMais = meta.has_more;
    pagina += 1;
  }

  return resultados;
}
```

## Erros de validação

Enviar parâmetros de paginação inválidos retorna um `422` com os erros por campo:

```json theme={null}
{
  "error": {
    "code": "validation_error",
    "message": "Validation failed.",
    "fields": {
      "per_page": "Must be between 1 and 50.",
      "order_by": "Must be one of: created_at, updated_at, full_name."
    },
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```