# Migração da v1 para a v2

> **In English.** v2 replaces four v1 endpoints: the paginated listings of documents, categories and
> users, and the download of a document with attachments. Everything else stays in v1, and both
> versions share the key, the accounts and the error format, so you can migrate one call at a time.
> This guide maps parameters and responses between the versions. Text in Brazilian Portuguese.

## O que a v2 é

A [Partners API v2](https://api.letssign.com.br/docs/partners/v2) não é uma reescrita. Ela contém **quatro endpoints**, que
substituem quatro da v1; tudo o mais continua na [v1](https://api.letssign.com.br/docs/partners/v1). As duas versões usam a mesma
chave, as mesmas contas e o mesmo formato de erro, e podem ser chamadas na mesma integração. A
regra é simples: quando o endpoint existir na v2, use a v2.

Os endpoints substituídos da v1 aparecem como `deprecated` no OpenAPI e começam a descrição com
"Obsoleto". Eles continuam respondendo e não têm data de desligamento anunciada, mas não recebem
evolução: filtros e campos novos entram só na v2.

| v1 (obsoleto) | v2 | O que mudou |
|---|---|---|
| `GET /partners/v1/accounts/{accountId}/documents` (`partners_v1_documents_list`) | `GET /partners/v2/accounts/{accountId}/documents` (`partners_v2_documents_list`) | Paginação nova, filtro por data de criação, ordenação declarada. |
| `GET /partners/v1/accounts/{accountId}/categories` (`partners_v1_categories_list`) | `GET /partners/v2/accounts/{accountId}/categories` (`partners_v2_categories_list`) | Paginação nova, ordenação declarada. |
| `GET /partners/v1/accounts/{accountId}/users` (`partners_v1_users_list`) | `GET /partners/v2/accounts/{accountId}/users` (`partners_v2_users_list`) | Paginação nova, filtro por e-mail, ordenação declarada. |
| `GET /partners/v1/accounts/{accountId}/documents/{id}/download/with-atachments` (`partners_v1_documents_download_with_attachments`) | `GET /partners/v2/accounts/{accountId}/documents/{id}/download/with-attachments` (`partners_v2_documents_download_with_attachments`) | Grafia da rota corrigida. Mesma resposta. |

## Listagens: parâmetros

| v1 | v2 | Observação |
|---|---|---|
| `pageIndex` (a partir de 1) | `page` (a partir de 1) | Mesma base; só o nome muda. |
| `pageSize` | `perPage` | |
| `sortField` (texto livre, obrigatório) | `sortField` (opcional, entre os campos declarados) | Cada listagem aceita um conjunto fechado: documentos `Name` e `CreatedAt`; categorias `Name`, `CreatedAt` e `Active`; usuários `FirstName`, `Email`, `Profile`, `AddedAt` e `Active`. Valor fora da lista responde `422`. |
| `sortType` (`asc`/`desc`, obrigatório) | `sortDirection` (`Asc`/`Desc`, opcional) | Padrão `Asc`. |

Os filtros de negócio mantêm o nome e o significado (`name`, `active`, `documentStatus`,
`categories`, datas de prazo e de assinatura, `profile`, `visible`). A v2 acrescenta `createdFrom`
e `createdTo` em documentos e `email` em usuários. A lista completa está em
[Paginação e filtros](https://api.letssign.com.br/docs/guides/paginacao-e-filtros).

## Listagens: resposta

| v1 (`PagedListDeprecated`) | v2 (`PagedList`) | Observação |
|---|---|---|
| `items` | `items` | Mesmos DTOs de item. |
| `totalRecords` | `count` | Total de registros para o filtro. |
| `totalPages` | `totalPages` | |
| `pageSize` | `perPage` | |
| (não há) | `page` | Página atual. |
| (não há) | `hasPreviousPage`, `previousPage`, `hasNextPage`, `nextPage` | Navegação pronta; `previousPage` e `nextPage` são omitidos quando não existem. |
| `additionalData` | (removido) | Era sempre nulo. |

Antes, para saber se havia próxima página, era preciso comparar `pageIndex` com `totalPages`.
Agora basta `hasNextPage` e `nextPage`.

## Passo a passo

1. Troque o prefixo `/partners/v1` por `/partners/v2` nas quatro rotas acima e corrija
   `with-atachments` para `with-attachments`.
2. Renomeie os parâmetros de paginação: `pageIndex` para `page`, `pageSize` para `perPage`,
   `sortType` para `sortDirection` com `Asc`/`Desc`. Confira se o `sortField` que você envia está
   entre os aceitos pela listagem.
3. Ajuste a leitura da resposta: `totalRecords` para `count`, `pageSize` para `perPage`; remova o
   uso de `additionalData`; passe a percorrer por `hasNextPage`/`nextPage`.
4. Mantenha as demais chamadas na v1. Não há mudança em autenticação, contas, erros ou webhooks.
5. Se quiser, aproveite os filtros novos: `createdFrom`/`createdTo` em documentos e `email` em
   usuários.

O documento OpenAPI da v2 está em `https://api.letssign.com.br/docs/partners-v2/openapi.json` e pode ser usado para gerar o cliente.