# Paginação e filtros

> **In English.** v2 listings paginate with `page` (starting at 1), `perPage`, `sortField` and
> `sortDirection` (`Asc`/`Desc`), and answer `items`, `page`, `perPage`, `count`, `totalPages` and
> the navigation flags. Each listing declares its own filters and sort fields. The deprecated v1
> listings use `pageIndex`, `pageSize`, `sortField` and `sortType`. Non-paginated lists return
> everything. Text in Brazilian Portuguese.

## O modelo da v2

As listagens da v2 (`partners_v2_documents_list`, `partners_v2_categories_list`,
`partners_v2_users_list`) recebem os parâmetros de paginação na query string:

| Parâmetro | Obrigatório | Padrão | O que faz |
|---|---|---|---|
| `page` | sim | `1` | Número da página, a partir de 1. |
| `perPage` | sim | `20` | Itens por página. |
| `sortField` | não | varia por listagem | Campo de ordenação, entre os aceitos pela listagem. |
| `sortDirection` | não | `Asc` | `Asc` ou `Desc`. |

Os nomes dos parâmetros não diferenciam maiúsculas de minúsculas: `page=2` e `Page=2` são iguais.
Enviar um `sortField` fora da lista aceita responde `422`.

A resposta traz os itens e o necessário para navegar sem contar nada do seu lado:

```json
{
  "items": [ { "id": "01991440-5a6b-7c8d-9e0f-1a2b3c4d5e6f", "name": "Contrato de locação - Apto 501" } ],
  "page": 1,
  "perPage": 20,
  "count": 48,
  "totalPages": 3,
  "hasPreviousPage": false,
  "hasNextPage": true,
  "nextPage": 2
}
```

- `count` é o total de registros para o filtro informado; `totalPages` é o total de páginas.
- `hasNextPage`, `nextPage`, `hasPreviousPage` e `previousPage` são a forma recomendada de
  percorrer: peça `nextPage` enquanto `hasNextPage` for verdadeiro. `previousPage` e `nextPage` são
  omitidos quando não existem (propriedades nulas não entram na resposta).

Para percorrer uma listagem inteira:

```bash
curl -H "Authorization: SUA_CHAVE" \
  "https://api.letssign.com.br/partners/v2/accounts/0199143a-7c2e-7b1a-9f2d-3c4b5a6d7e8f/documents?page=1&perPage=50&sortField=CreatedAt&sortDirection=Desc"
```

e repita com `page=2`, `page=3`... até `hasNextPage` ser falso. A ordem entre chamadas só é estável
se nada for criado ou alterado no meio; para exportações, ordene por `CreatedAt` e filtre por
`CreatedTo` na data de início da exportação.

## Filtros de cada listagem

Filtros são parâmetros de query, combináveis entre si (a semântica é **E** entre filtros e **OU**
dentro de um filtro de lista). Datas vão no formato `AAAA-MM-DD`; parâmetros de lista são repetidos
na query (`documentStatus=Finished&documentStatus=Draft`).

### Documentos (`partners_v2_documents_list`)

| Filtro | Tipo | O que faz |
|---|---|---|
| `documentId` | UUID | Um documento específico. |
| `name` | texto | Nome contém o texto. |
| `categories` | lista de UUID | Documentos em qualquer das categorias. |
| `documentStatus` | lista de `EDocumentStatus` | Qualquer dos status: `Draft`, `Finished`, `Approved`, `Disapproved`, `NewVersionBase`, `WaitingFormFill`. |
| `documentSignatureStatus` | lista de `EDocumentSignatureStatus` | Qualquer dos status: `SignatureNotSet`, `SettingUpSignatures`, `SignaturesDeliveryScheduled`, `WaitingSignatures`, `FinalizingSignatures`, `ErrorOnFinalizingSignatures`, `Signed`. |
| `deadlineDateFrom`, `deadlineDateTo` | data | Prazo de assinatura no intervalo (inclusive). |
| `signatureDateFrom`, `signatureDateTo` | data | Data da última assinatura no intervalo (inclusive). |
| `createdFrom`, `createdTo` | data | Data de criação no intervalo (inclusive). Só existe na v2. |

Ordenação: `Name` (padrão) ou `CreatedAt`.

### Categorias (`partners_v2_categories_list`)

| Filtro | Tipo | O que faz |
|---|---|---|
| `name` | texto | Nome contém o texto. |
| `active` | booleano | `true` só ativas, `false` só inativas; omitido, ambas. |

Ordenação: `Name` (padrão), `CreatedAt` ou `Active`.

### Usuários (`partners_v2_users_list`)

| Filtro | Tipo | O que faz |
|---|---|---|
| `id` | UUID | Um usuário específico. |
| `name` | texto | Nome contém o texto. |
| `email` | texto | E-mail contém o texto. Só existe na v2. |
| `active` | booleano | Situação do usuário na conta. |
| `visible` | booleano | Visibilidade do usuário. |
| `profile` | `EProfile` | `Owner`, `Admin` ou `User`. |

Ordenação: `FirstName` (padrão), `Email`, `Profile`, `AddedAt` ou `Active`.

## O modelo legado da v1

As três listagens obsoletas da v1 (`partners_v1_documents_list`, `partners_v1_categories_list`,
`partners_v1_users_list`) continuam respondendo, mas não recebem evolução. Elas usam outro modelo:

| Parâmetro | Obrigatório | Padrão | Equivalente na v2 |
|---|---|---|---|
| `pageIndex` | sim | `1` | `page` (também a partir de 1) |
| `pageSize` | sim | `20` | `perPage` |
| `sortField` | sim | varia (`Id` em usuários) | `sortField`, com os campos declarados |
| `sortType` | sim | `asc` | `sortDirection` (`Asc`/`Desc`) |

E respondem `PagedListDeprecated`: `items`, `totalRecords` (o `count` da v2), `totalPages`,
`pageSize` e `additionalData` (sempre nulo). Não há indicadores de navegação: calcule a próxima
página comparando `pageIndex` com `totalPages`. O passo a passo da troca está em
[Migração da v1 para a v2](https://api.letssign.com.br/docs/guides/migracao-v1-para-v2).

## Listas sem paginação

Vêm completas, numa chamada: contas (`partners_v1_accounts_list`), features
(`partners_v1_features_list`), planos (`partners_v1_plans_list`), papéis de signatário
(`partners_v1_document_signature_roles_list`), pastas (`partners_v1_folders_list`), grupos
(`partners_v1_groups_list`), modelos de formulário (`partners_v1_form_templates_list`), campos de
informação (`partners_v1_information_fields_list`), webhooks (`partners_v1_webhooks_list`), campos
de informação e de formulário de um documento. Algumas respondem de cache: pastas, grupos e modelos
de formulário por até 3 horas; papéis por até 1 hora. Criar uma pasta pela API invalida o cache de
pastas da conta.