Documentação Guias Paginação e filtros

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:

{
  "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:

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.

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.

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