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 não é uma reescrita. Ela contém quatro endpoints, que substituem quatro da v1; tudo o mais continua na 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.

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

Troque o prefixo /partners/v1 por /partners/v2 nas quatro rotas acima e corrija with-atachments para with-attachments.
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.
Ajuste a leitura da resposta: totalRecords para count, pageSize para perPage; remova o uso de additionalData; passe a percorrer por hasNextPage/nextPage.
Mantenha as demais chamadas na v1. Não há mudança em autenticação, contas, erros ou webhooks.
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.

Este guia também existe em Markdown, e o conjunto completo da documentação em llms.txt.