# V2 Partners API

Versão `v2`. Referência completa em Markdown; o mesmo contrato está em [OpenAPI 3.1 JSON](https://api.letssign.com.br/docs/partners-v2/openapi.json) e em [página navegável](https://api.letssign.com.br/docs/partners/v2). Servidor: `https://api.letssign.com.br`.

A Partners API permite que sistemas parceiros operem contas do LetsSign: enviar documentos para
assinatura eletrônica, acompanhar o andamento, baixar os arquivos assinados, manter contatos,
pastas, categorias e usuários, e receber notificações por webhook.

Esta é a **v2**. Ela substitui endpoints específicos da v1: as listagens paginadas de documentos,
categorias e usuários (novo formato de paginação) e o download do documento com anexos. Todo o
restante continua na [Partners API v1](https://api.letssign.com.br/docs/partners/v1), que compartilha autenticação, contas e
formato de erro com esta. Use a v2 sempre que o endpoint existir aqui, e a v1 para o restante.

## Ambiente

| | |
|---|---|
| URL base | `https://api.letssign.com.br/` |
| Documento OpenAPI (v1) | `https://api.letssign.com.br/docs/partners-v1/openapi.json` |
| Documento OpenAPI (v2) | `https://api.letssign.com.br/docs/partners-v2/openapi.json` |
| Coleção Postman (v1) | `https://api.letssign.com.br/docs/partners/v1.postman_collection.json` |
| Coleção Postman (v2) | `https://api.letssign.com.br/docs/partners/v2.postman_collection.json` |

Sandbox e produção têm hosts e chaves distintos. A URL base acima é a do ambiente que serviu este documento.

## Guias

Para começar, leia o [Quickstart](https://api.letssign.com.br/docs/guides/quickstart). Os demais guias cobrem
[autenticação e contas](https://api.letssign.com.br/docs/guides/autenticacao-e-contas), [webhooks](https://api.letssign.com.br/docs/guides/webhooks),
[erros](https://api.letssign.com.br/docs/guides/erros), [paginação e filtros](https://api.letssign.com.br/docs/guides/paginacao-e-filtros),
[limites e features](https://api.letssign.com.br/docs/guides/limites-e-features),
[ferramentas e agentes de IA](https://api.letssign.com.br/docs/guides/ferramentas-e-agentes) (Postman, MCP e sandbox), a
[migração da v1 para a v2](https://api.letssign.com.br/docs/guides/migracao-v1-para-v2) e o [changelog](https://api.letssign.com.br/docs/guides/changelog).
Cada guia também existe em Markdown, na mesma URL com `.md` no fim.

## Autenticação

Toda requisição leva a chave de integração do parceiro no header `Authorization`, **sem prefixo**
(não use `Bearer`):

```http
GET /partners/v1/accounts HTTP/1.1
Host: api.letssign.com.br
Authorization: 3f9c0a1b2c3d4e5f6a7b8c9d0e1f2a3b
```

- A chave é emitida no cadastro do parceiro pela equipe LetsSign ou gerada pela própria conta na
  área de integrações do aplicativo (https://app.letssign.com.br/). Regenerar a chave invalida a anterior na hora.
- A chave identifica o **parceiro**; a **conta** vem no caminho da rota (`accountId`). Um parceiro
  pode operar várias contas: comece por `GET /partners/v1/accounts` (`partners_v1_accounts_list`)
  para descobrir os identificadores.
- `401`: chave ausente ou inválida, conta não vinculada ao parceiro, período de teste da conta
  expirado ou grupo de faturamento da conta sem plano ativo. Nos dois últimos casos o corpo é um
  Problem Details com o motivo em `detail`.
- `403`: o plano da conta não inclui uma feature exigida pela operação. Cada operação lista as
  features exigidas na descrição e na extensão `x-required-features`; consulte
  `GET /partners/v1/accounts/{accountId}/features` (`partners_v1_features_list`) para saber o que a
  conta tem.

## Conceitos

- **Conta**: espaço de uma empresa ou pessoa no LetsSign. Documentos, contatos, pastas,
  categorias, usuários e webhooks pertencem a uma conta.
- **Documento**: arquivo PDF, DOC ou DOCX enviado para assinatura, com status do documento
  (`EDocumentStatus`) e status de assinatura (`EDocumentSignatureStatus`).
- **Signatário**: quem assina, identificado por e-mail, com método de autenticação
  (`EAuthenticationMethod`: e-mail, SMS, WhatsApp, certificado digital, entre outros) e métodos
  adicionais opcionais (`EAdditionalAuthenticationMethod`). O link de assinatura pode ir por e-mail,
  SMS ou WhatsApp (`ESignatureLinkMethod`).
- **Áreas de assinatura**: página e coordenadas onde assinatura e rubrica são carimbadas no PDF.
- **Campos de informação**: dados adicionais gravados no documento, como um número de contrato.
- **Modelos de formulário**: modelos que geram documentos a partir de campos preenchidos.
- **Webhook**: URL da conta que recebe um `POST` a cada evento (documento enviado, signatário
  assinou, assinaturas concluídas, status alterado, documento removido, formulário preenchido).

## Fluxo típico

1. Liste as contas do parceiro e escolha o `accountId`.
2. Confira as features da conta.
3. Crie o documento e solicite as assinaturas em uma única chamada
   (`POST /partners/v1/accounts/{accountId}/document-signatures`,
   `partners_v1_document_signatures_create_from_file`): o arquivo vai em base64 no campo
   `contentFile`, junto da lista de signatários. A resposta traz o `id` do documento.
4. Acompanhe por webhook (recomendado) ou por
   `GET /partners/v1/accounts/{accountId}/document-signatures/{documentId}/status`.
5. Ao concluir, obtenha a URL de download do arquivo assinado
   (`GET /partners/v1/accounts/{accountId}/documents/{id}/download/signed`) ou com anexos
   (`partners_v2_documents_download_with_attachments`). A resposta traz `name` e `url`; a URL é
   temporária, então baixe logo após obtê-la.

## Convenções

- **Formato**: JSON em UTF-8, propriedades em `camelCase`. Enums são strings com os nomes exatos do
  schema (ex.: `"Email"`, `"WhatsApp"`). Propriedades nulas são omitidas nas respostas.
- **Datas**: ISO 8601 em UTC (`2026-09-03T14:05:00Z`). Envie sempre o fuso explícito.
- **Identificadores**: UUID.
- **Arquivos**: enviados como string base64 dentro do JSON; downloads devolvem uma URL temporária,
  não o binário.
- **Paginação (v2)**: parâmetros `page` (a partir de 1), `perPage`, `sortField` e `sortDirection`
  (`Asc` ou `Desc`); cada listagem declara os campos de ordenação aceitos e o padrão. A resposta
  traz `items`, `page`, `perPage`, `count` (total de registros), `totalPages`, `hasPreviousPage`,
  `hasNextPage`, `previousPage` e `nextPage`. As listagens obsoletas da v1 usam `pageIndex`,
  `pageSize`, `sortField` e `sortType`, e respondem `totalRecords`, `totalPages` e `pageSize`.
- **Idioma**: mensagens de erro e comunicações com signatários em português do Brasil.
- **Limites**: não há limite de requisições por chave hoje. Prefira webhooks a consultas repetidas.
  O corpo de uma requisição aceita até 70 MB.
- **Cache**: as listagens de pastas, grupos e modelos de formulário podem responder de um cache de
  até 3 horas; criar uma pasta pela API invalida o cache de pastas da conta.

## Erros

Erros seguem o padrão Problem Details (RFC 9457), com `Content-Type: application/problem+json`.

| Status | Quando acontece |
|---|---|
| 400 | Regra de negócio não satisfeita: recurso inexistente na conta, documento em estado que não permite a operação, recurso do plano ausente, cota atingida. `errors` lista as mensagens. |
| 401 | Ver Autenticação. Corpo vazio, exceto trial expirado e grupo sem plano ativo. |
| 403 | Plano da conta sem a feature exigida. Corpo vazio. |
| 404 | Recurso não encontrado, nas consultas por identificador que declaram 404. |
| 422 | Payload rejeitado: JSON malformado ou campos que não passaram na validação (obrigatórios, tamanhos, formatos, combinações). `errors` lista as mensagens e `problems` aponta o campo de cada uma. |
| 500 | Erro interno. Informe `requestId` e `traceId` ao suporte. |

O corpo de erro (`ProblemDetailsResult`) tem `title`, `status`, `detail`, `instance` (método e
caminho), `errors` (lista de mensagens), `problems` (mensagem e `propertyName`) e os campos de
rastreio `traceId`, `spanId` e `requestId`. Trate 400 e 422 como definitivos: repetir a mesma
requisição produz o mesmo erro.

## Webhooks

Cadastre URLs em `POST /partners/v1/accounts/{accountId}/webhooks` (`partners_v1_webhooks_create`).
Cada evento é um `POST` JSON com `event`, `accountId`, `occurredAt` e `entity`. Os dez eventos,
com schema, exemplo e o que dispara cada um, estão no objeto `webhooks` deste documento e na
[página inicial da documentação](https://api.letssign.com.br/docs).

- Sem cabeçalho de assinatura: valide a origem pelo `accountId` e, se preciso, por um segredo na
  própria URL.
- Responda 2xx (200 ou 202) em até 20 segundos; falhas são repetidas em seguida, até 5
  tentativas.
- `occurredAt` é o instante da tentativa de envio e não há identificador de entrega: trate
  repetições pelo conteúdo de `entity`. Não há garantia de ordem entre eventos.
- No cadastro, um evento `Test` é enviado de imediato; o resultado fica em `available`.

## Versões e obsolescência

Endpoints obsoletos continuam respondendo, aparecem marcados como `deprecated` e indicam o
substituto na descrição. Consulte a [Partners API v1](https://api.letssign.com.br/docs/partners/v1) e a
[Partners API v2](https://api.letssign.com.br/docs/partners/v2).

## Esquemas de autenticação

### ApiKey

Tipo: chave no header `Authorization`.

Chave de integração do parceiro, enviada **sem prefixo** no header `Authorization`
(não use `Bearer`):

```
Authorization: 3f9c0a1b2c3d4e5f6a7b8c9d0e1f2a3b
```

A chave identifica o parceiro; a conta operada vem no `accountId` da rota e precisa estar
vinculada a ele. A chave é emitida no cadastro do parceiro pela equipe LetsSign ou
gerada pela própria conta na área de integrações do aplicativo; regenerá-la invalida a
anterior na hora.

Respostas `401`: chave ausente ou inválida, conta não vinculada ao parceiro, período de teste
expirado ou grupo de faturamento sem plano ativo. Respostas `403`: o plano da conta não inclui
uma feature exigida pela operação (ver `x-required-features`).

### Bearer

Tipo: HTTP `Bearer`, formato `{access_token}`.

JWT emitido pela API de identidade para usuários do aplicativo. Não se aplica às APIs de parceiros.

## Índice de operações

Uma linha por operação, na ordem das seções abaixo. O `operationId` é estável e identifica a operação em SDKs, ferramentas e nas descrições que apontam substitutos.

| Operação | Método e caminho | operationId |
| --- | --- | --- |
| Lista paginada de documentos da conta | `GET /partners/v2/accounts/{accountId}/documents` | `partners_v2_documents_list` |
| Info para download do documento com anexos | `GET /partners/v2/accounts/{accountId}/documents/{id}/download/with-attachments` | `partners_v2_documents_download_with_attachments` |
| Lista paginada de categorias da conta | `GET /partners/v2/accounts/{accountId}/categories` | `partners_v2_categories_list` |
| Lista paginada de usuários da conta | `GET /partners/v2/accounts/{accountId}/users` | `partners_v2_users_list` |

## Endpoints

### Documents

Documentos da conta: listagem, URLs de download (original, assinado, com anexos, com certificado digital), campos de informação, campos de formulário, mapeamento de assinaturas e solicitação de assinaturas para um documento já existente.

#### Lista paginada de documentos da conta

`GET /partners/v2/accounts/{accountId}/documents`

- operationId: `partners_v2_documents_list`
- Autenticação: `ApiKey`

Lista os documentos da conta com paginação e filtros por identificador, nome, categorias, status,
status de assinatura, prazo, data da última assinatura e data de criação.

- `page` começa em 1; `perPage` define o tamanho da página. Ordene por `Name` (padrão) ou
  `CreatedAt`, com `sortDirection` `Asc` ou `Desc`.
- A resposta traz `items`, `count` (total de registros), `totalPages` e os indicadores de
  navegação (`hasNextPage`, `nextPage`, `hasPreviousPage`, `previousPage`).
- Substitui `partners_v1_documents_list`. Somente leitura.

**Features exigidas no plano da conta:** `documents`.

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- | --- |
| `accountId` | path | string (uuid) | sim | Identificador da conta operada. Obtenha a lista em `partners_v1_accounts_list`. |
| `DocumentId` | query | string (uuid) | não | Filtra por um documento específico. Exemplo: `"01991440-5a6b-7c8d-9e0f-1a2b3c4d5e6f"`. |
| `Name` | query | string | não | Filtra documentos cujo nome contém o texto. Exemplo: `"Contrato"`. |
| `DeadlineDateFrom` | query | string (date) | não | Prazo de assinatura a partir desta data (inclusive). Exemplo: `"2026-09-01"`. |
| `DeadlineDateTo` | query | string (date) | não | Prazo de assinatura até esta data (inclusive). Exemplo: `"2026-09-30"`. |
| `SignatureDateFrom` | query | string (date) | não | Data da última assinatura a partir desta data (inclusive). Exemplo: `"2026-08-01"`. |
| `SignatureDateTo` | query | string (date) | não | Data da última assinatura até esta data (inclusive). Exemplo: `"2026-08-31"`. |
| `Categories` | query | string (uuid)[] | não | Filtra documentos em qualquer das categorias informadas. Exemplo: `["0199143b-1d2e-7f3a-8b4c-5d6e7f8a9b0c"]`. |
| `DocumentStatus` | query | [EDocumentStatus](#edocumentstatus)[] | não | Filtra por status do documento (qualquer dos informados). Exemplo: `["Finished"]`. |
| `DocumentSignatureStatus` | query | [EDocumentSignatureStatus](#edocumentsignaturestatus)[] | não | Filtra por status de assinatura (qualquer dos informados). Exemplo: `["WaitingSignatures"]`. |
| `CreatedFrom` | query | string (date) | não | Criados a partir desta data (inclusive). Exemplo: `"2026-08-01"`. |
| `CreatedTo` | query | string (date) | não | Criados até esta data (inclusive). Exemplo: `"2026-08-31"`. |
| `Page` | query | integer (int32) | sim | Número da página, a partir de 1. Padrão: `1`. |
| `PerPage` | query | integer (int32) | sim | Quantidade de itens por página. Padrão: `20`. |
| `SortField` | query | `"Name"` \| `"CreatedAt"` | não | Campo de ordenação. Aceita `Name`, `CreatedAt`; padrão `Name`. |
| `SortDirection` | query | `"Asc"` \| `"Desc"` | não | Sentido da ordenação. |

**Respostas**

| Status | Descrição | Corpo |
| --- | --- | --- |
| `200` | OK | [PagedListOfDocumentDto](#pagedlistofdocumentdto) (`application/json`) |
| `401` | Chave ausente ou inválida, conta não vinculada ao parceiro, período de teste expirado ou grupo de faturamento sem plano ativo. Nos dois últimos casos o corpo é um Problem Details com o motivo em `detail`. | sem corpo |
| `403` | O plano da conta não inclui alguma das features exigidas: `documents`. | sem corpo |

Exemplo de resposta `200`:

```json
{
  "items": [
    {
      "id": "01991440-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
      "name": "Contrato de locação - Apto 501",
      "statusId": "Finished",
      "status": "Pronto para assinar",
      "signatureStatusId": "WaitingSignatures",
      "signatureStatus": "Aguardando assinaturas",
      "endDate": "2026-09-30T23:59:59Z",
      "deadlineForSignature": "2026-09-30T12:00:00Z",
      "categories": [
        {
          "id": "0199143b-1d2e-7f3a-8b4c-5d6e7f8a9b0c",
          "name": "Contratos de locação"
        }
      ],
      "groups": [
        {
          "id": "0199143d-3f40-7b5c-8d6e-7f8a9b0c1d2e",
          "name": "Jurídico"
        }
      ],
      "reminderFrequency": "ThreeDays",
      "createdAt": "2026-08-20T14:05:00Z"
    }
  ],
  "hasPreviousPage": false,
  "hasNextPage": true,
  "nextPage": 2,
  "page": 1,
  "perPage": 20,
  "count": 48,
  "totalPages": 3
}
```

#### Info para download do documento com anexos

`GET /partners/v2/accounts/{accountId}/documents/{id}/download/with-attachments`

- operationId: `partners_v2_documents_download_with_attachments`
- Autenticação: `ApiKey`

Devolve uma URL temporária para baixar o PDF do documento com os anexos incorporados.

- Sem anexos, devolve o arquivo original. Responde `400` quando o documento não existe na conta
  ou não tem arquivo disponível.
- A URL é pré-assinada e vale por 5 minutos; cada chamada gera uma URL nova. `name` é o nome do
  documento, sem extensão.
- Substitui `partners_v1_documents_download_with_attachments`.

**Features exigidas no plano da conta:** `documents`.

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | sim | Identificador do documento, devolvido na criação (`id`) e nas listagens. |
| `accountId` | path | string (uuid) | sim | Identificador da conta operada. Obtenha a lista em `partners_v1_accounts_list`. |

**Respostas**

| Status | Descrição | Corpo |
| --- | --- | --- |
| `200` | OK | [DocumentUrlInfoDto](#documenturlinfodto) (`application/json`) |
| `401` | Chave ausente ou inválida, conta não vinculada ao parceiro, período de teste expirado ou grupo de faturamento sem plano ativo. Nos dois últimos casos o corpo é um Problem Details com o motivo em `detail`. | sem corpo |
| `403` | O plano da conta não inclui alguma das features exigidas: `documents`. | sem corpo |

Exemplo de resposta `200`:

```json
{
  "name": "Contrato de locação - Apto 501",
  "url": "https://s3.sa-east-1.amazonaws.com/documents/0199143a-7c2e-7b1a-9f2d-3c4b5a6d7e8f/01991440-5a6b-7c8d-9e0f-1a2b3c4d5e6f-attachments.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=300&X-Amz-Signature=3f9c0a1b2c3d4e5f"
}
```

### Categories

Categorias que classificam os documentos da conta.

#### Lista paginada de categorias da conta

`GET /partners/v2/accounts/{accountId}/categories`

- operationId: `partners_v2_categories_list`
- Autenticação: `ApiKey`

Lista as categorias da conta com paginação e filtros por nome e situação.

- `page` começa em 1; `perPage` define o tamanho da página. Ordene por `Name` (padrão),
  `CreatedAt` ou `Active`, com `sortDirection` `Asc` ou `Desc`.
- A resposta traz `items`, `count` (total de registros), `totalPages` e os indicadores de
  navegação (`hasNextPage`, `nextPage`, `hasPreviousPage`, `previousPage`).
- Substitui `partners_v1_categories_list`. Somente leitura.

**Features exigidas no plano da conta:** `categories`.

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- | --- |
| `accountId` | path | string (uuid) | sim | Identificador da conta operada. Obtenha a lista em `partners_v1_accounts_list`. |
| `Name` | query | string | não | Filtra categorias cujo nome contém o texto. Exemplo: `"Contratos"`. |
| `Active` | query | boolean | não | Filtra por situação: `true` só ativas, `false` só inativas. Sem valor, ambas. Exemplo: `true`. |
| `Page` | query | integer (int32) | sim | Número da página, a partir de 1. Padrão: `1`. |
| `PerPage` | query | integer (int32) | sim | Quantidade de itens por página. Padrão: `20`. |
| `SortField` | query | `"Name"` \| `"CreatedAt"` \| `"Active"` | não | Campo de ordenação. Aceita `Name`, `CreatedAt`, `Active`; padrão `Name`. |
| `SortDirection` | query | `"Asc"` \| `"Desc"` | não | Sentido da ordenação. |

**Respostas**

| Status | Descrição | Corpo |
| --- | --- | --- |
| `200` | OK | [PagedListOfCategoryDto](#pagedlistofcategorydto) (`application/json`) |
| `401` | Chave ausente ou inválida, conta não vinculada ao parceiro, período de teste expirado ou grupo de faturamento sem plano ativo. Nos dois últimos casos o corpo é um Problem Details com o motivo em `detail`. | sem corpo |
| `403` | O plano da conta não inclui alguma das features exigidas: `categories`. | sem corpo |

Exemplo de resposta `200`:

```json
{
  "items": [
    {
      "id": "0199143b-1d2e-7f3a-8b4c-5d6e7f8a9b0c",
      "name": "Contratos de locação",
      "accountId": "0199143a-7c2e-7b1a-9f2d-3c4b5a6d7e8f",
      "createdAt": "2025-03-12T13:45:10Z",
      "active": true
    }
  ],
  "hasPreviousPage": false,
  "hasNextPage": false,
  "page": 1,
  "perPage": 20,
  "count": 1,
  "totalPages": 1
}
```

### Users

Usuários vinculados à conta.

#### Lista paginada de usuários da conta

`GET /partners/v2/accounts/{accountId}/users`

- operationId: `partners_v2_users_list`
- Autenticação: `ApiKey`

Lista os usuários da conta com paginação e filtros por identificador, nome, e-mail, situação,
visibilidade e perfil.

- `page` começa em 1; `perPage` define o tamanho da página. Ordene por `FirstName` (padrão),
  `Email`, `Profile`, `AddedAt` ou `Active`, com `sortDirection` `Asc` ou `Desc`.
- A resposta traz `items`, `count` (total de registros), `totalPages` e os indicadores de
  navegação (`hasNextPage`, `nextPage`, `hasPreviousPage`, `previousPage`).
- Substitui `partners_v1_users_list`. Somente leitura.

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- | --- |
| `accountId` | path | string (uuid) | sim | Identificador da conta operada. Obtenha a lista em `partners_v1_accounts_list`. |
| `Id` | query | string (uuid) | não | Filtra por um usuário específico. Exemplo: `"0199143f-5b6c-7d7e-8f80-9a0b1c2d3e4f"`. |
| `Name` | query | string | não | Filtra usuários cujo nome contém o texto. Exemplo: `"Ana"`. |
| `Active` | query | boolean | não | Filtra por situação: `true` só ativos, `false` só inativos. Sem valor, ambos. Exemplo: `true`. |
| `Visible` | query | boolean | não | Filtra por visibilidade na conta. Sem valor, todos. Exemplo: `true`. |
| `Profile` | query | [EProfile](#eprofile) | não | Filtra por perfil na conta. Exemplo: `"Admin"`. |
| `Email` | query | string | não | Filtra usuários cujo e-mail contém o texto. Exemplo: `"ana.pereira"`. |
| `Page` | query | integer (int32) | sim | Número da página, a partir de 1. Padrão: `1`. |
| `PerPage` | query | integer (int32) | sim | Quantidade de itens por página. Padrão: `20`. |
| `SortField` | query | `"FirstName"` \| `"Email"` \| `"Profile"` \| `"AddedAt"` \| `"Active"` | não | Campo de ordenação. Aceita `FirstName`, `Email`, `Profile`, `AddedAt`, `Active`; padrão `FirstName`. |
| `SortDirection` | query | `"Asc"` \| `"Desc"` | não | Sentido da ordenação. |

**Respostas**

| Status | Descrição | Corpo |
| --- | --- | --- |
| `200` | OK | [PagedListOfPartnerUserAccountDto](#pagedlistofpartneruseraccountdto) (`application/json`) |
| `401` | Chave ausente ou inválida, conta não vinculada ao parceiro, período de teste expirado ou grupo de faturamento sem plano ativo. Nos dois últimos casos o corpo é um Problem Details com o motivo em `detail`. | sem corpo |
| `403` | O plano da conta não inclui uma feature exigida por esta operação. | sem corpo |

Exemplo de resposta `200`:

```json
{
  "items": [
    {
      "id": "0199143f-5b6c-7d7e-8f80-9a0b1c2d3e4f",
      "firstName": "Ana",
      "lastName": "Pereira",
      "fullName": "Ana Pereira",
      "email": "ana.pereira@exemplo.com.br",
      "addedAt": "2026-08-20T14:05:00Z",
      "active": true,
      "profile": "Admin",
      "profileDescription": "Administrador"
    },
    {
      "id": "0199144d-a7b8-7c9d-9e0f-1a2b3c4d5e6f",
      "firstName": "Bruno",
      "lastName": "Costa",
      "fullName": "Bruno Costa",
      "email": "bruno.costa@exemplo.com.br",
      "addedAt": "2026-08-20T14:05:00Z",
      "active": true,
      "profile": "User",
      "profileDescription": "Usuário"
    }
  ],
  "hasPreviousPage": false,
  "hasNextPage": false,
  "page": 1,
  "perPage": 20,
  "count": 2,
  "totalPages": 1
}
```

## Eventos de webhook

Cada evento abaixo é um `POST` que a plataforma envia às URLs cadastradas na conta. O contrato de entrega (resposta esperada, tempo limite e retentativas) está na descrição de cada evento.

### Enviado no cadastro de uma URL de webhook, para verificar a disponibilidade

`POST` enviado à URL cadastrada na conta, com `event` igual a `Test`.

- operationId: `webhook_test`

Enviado uma única vez, no cadastro da URL por `partners_v1_webhooks_create`, para verificar a
disponibilidade. O resultado fica em `available` do webhook; a URL é gravada mesmo quando o
teste falha. `entity.test` é sempre `true`. Não é reenviado antes das demais entregas.

**Entrega**

- `POST` com `Content-Type: application/json; charset=utf-8`, sem cabeçalho de autenticação ou
  assinatura. Valide a origem pelo `accountId` e, se precisar, por um segredo na própria URL.
- Responda qualquer status 2xx (200 ou 202 recomendados) em até 20 segundos. Outro status,
  timeout ou erro de rede contam como falha; a entrega é repetida em seguida, até 5 tentativas.
- `occurredAt` é o instante desta tentativa de envio, não o do evento, e muda a cada
  retentativa. Não há identificador de entrega no payload: trate repetições pelo conteúdo de
  `entity`.
- Não há garantia de ordem entre eventos, mesmo do mesmo documento. Para o estado atual, consulte
  `partners_v1_document_signatures_status`.
- Cada URL cadastrada na conta recebe todos os eventos; não há filtro por evento.

**Payload** (`application/json`, obrigatório)

| Propriedade | Tipo | Obrigatória | Descrição |
| --- | --- | --- | --- |
| `occurredAt` | string (date-time) | sim | Instante (UTC) desta tentativa de envio. Muda a cada retentativa; não é a data do evento. |
| `accountId` | string (uuid) | sim | Conta à qual o evento pertence. |
| `event` | `"Test"` | sim | Nome do evento, que define o formato de `entity`. |
| `entity` | [TestWebHookDto](#testwebhookdto) | sim | Dados do evento, no formato do schema referenciado; qual schema vem em `event`. |

```json
{
  "occurredAt": "2026-08-21T10:12:45Z",
  "accountId": "0199143a-7c2e-7b1a-9f2d-3c4b5a6d7e8f",
  "event": "Test",
  "entity": {
    "test": true
  }
}
```

**Resposta esperada da sua URL**

| Status | Descrição |
| --- | --- |
| `2XX` | Entrega confirmada. Qualquer status 2xx serve; 200 e 202 são os recomendados. O corpo é ignorado. |
| `default` | Outro status, timeout de 20 segundos ou erro de rede: a entrega conta como falha e é repetida em seguida, até 5 tentativas. |

### Documento enviado para assinatura

`POST` enviado à URL cadastrada na conta, com `event` igual a `DocumentSentToSignature`.

- operationId: `webhook_document_sent_to_signature`

Um documento foi enviado para assinatura: na criação por
`partners_v1_document_signatures_create_from_file`, em `partners_v1_documents_request_signatures`
ou pelo aplicativo. Com envio agendado (`scheduledTo`), o evento sai no momento da criação, não
na data agendada.

`entity.signers` traz os signatários no momento do envio, com o `id` da assinatura (o
`signatureId` das operações de editar, remover e reenviar), papel, método de autenticação, e-mail
e nome.

**Entrega**

- `POST` com `Content-Type: application/json; charset=utf-8`, sem cabeçalho de autenticação ou
  assinatura. Valide a origem pelo `accountId` e, se precisar, por um segredo na própria URL.
- Responda qualquer status 2xx (200 ou 202 recomendados) em até 20 segundos. Outro status,
  timeout ou erro de rede contam como falha; a entrega é repetida em seguida, até 5 tentativas.
- `occurredAt` é o instante desta tentativa de envio, não o do evento, e muda a cada
  retentativa. Não há identificador de entrega no payload: trate repetições pelo conteúdo de
  `entity`.
- Não há garantia de ordem entre eventos, mesmo do mesmo documento. Para o estado atual, consulte
  `partners_v1_document_signatures_status`.
- Cada URL cadastrada na conta recebe todos os eventos; não há filtro por evento.

**Payload** (`application/json`, obrigatório)

| Propriedade | Tipo | Obrigatória | Descrição |
| --- | --- | --- | --- |
| `occurredAt` | string (date-time) | sim | Instante (UTC) desta tentativa de envio. Muda a cada retentativa; não é a data do evento. |
| `accountId` | string (uuid) | sim | Conta à qual o evento pertence. |
| `event` | `"DocumentSentToSignature"` | sim | Nome do evento, que define o formato de `entity`. |
| `entity` | [DocumentSentToSignWebHookDto](#documentsenttosignwebhookdto) | sim | Dados do evento, no formato do schema referenciado; qual schema vem em `event`. |

```json
{
  "occurredAt": "2026-08-21T10:12:45Z",
  "accountId": "0199143a-7c2e-7b1a-9f2d-3c4b5a6d7e8f",
  "event": "DocumentSentToSignature",
  "entity": {
    "documentId": "01991440-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
    "sentAt": "2026-08-20T14:05:00Z",
    "signers": [
      {
        "id": "01991441-0a1b-7c2d-8e3f-4a5b6c7d8e9f",
        "role": "Parte",
        "authenticationMethod": "Email",
        "email": "maria.silva@exemplo.com.br",
        "name": "Maria da Silva"
      },
      {
        "id": "01991441-9f8e-7d6c-8b5a-4c3d2e1f0a9b",
        "role": "Testemunha",
        "authenticationMethod": "Email",
        "email": "joao.souza@exemplo.com.br",
        "name": "João de Souza"
      }
    ]
  }
}
```

**Resposta esperada da sua URL**

| Status | Descrição |
| --- | --- |
| `2XX` | Entrega confirmada. Qualquer status 2xx serve; 200 e 202 são os recomendados. O corpo é ignorado. |
| `default` | Outro status, timeout de 20 segundos ou erro de rede: a entrega conta como falha e é repetida em seguida, até 5 tentativas. |

### Novo signatário adicionado ao documento

`POST` enviado à URL cadastrada na conta, com `event` igual a `SignerAddedToDocument`.

- operationId: `webhook_signer_added_to_document`

Um signatário foi adicionado a um documento que já estava em assinatura, por
`partners_v1_document_signatures_add_signer` ou pelo aplicativo. `entity.signer.id` é o
`signatureId` da nova assinatura.

**Entrega**

- `POST` com `Content-Type: application/json; charset=utf-8`, sem cabeçalho de autenticação ou
  assinatura. Valide a origem pelo `accountId` e, se precisar, por um segredo na própria URL.
- Responda qualquer status 2xx (200 ou 202 recomendados) em até 20 segundos. Outro status,
  timeout ou erro de rede contam como falha; a entrega é repetida em seguida, até 5 tentativas.
- `occurredAt` é o instante desta tentativa de envio, não o do evento, e muda a cada
  retentativa. Não há identificador de entrega no payload: trate repetições pelo conteúdo de
  `entity`.
- Não há garantia de ordem entre eventos, mesmo do mesmo documento. Para o estado atual, consulte
  `partners_v1_document_signatures_status`.
- Cada URL cadastrada na conta recebe todos os eventos; não há filtro por evento.

**Payload** (`application/json`, obrigatório)

| Propriedade | Tipo | Obrigatória | Descrição |
| --- | --- | --- | --- |
| `occurredAt` | string (date-time) | sim | Instante (UTC) desta tentativa de envio. Muda a cada retentativa; não é a data do evento. |
| `accountId` | string (uuid) | sim | Conta à qual o evento pertence. |
| `event` | `"SignerAddedToDocument"` | sim | Nome do evento, que define o formato de `entity`. |
| `entity` | [SignerAddedToDocumentWebHookDto](#signeraddedtodocumentwebhookdto) | sim | Dados do evento, no formato do schema referenciado; qual schema vem em `event`. |

```json
{
  "occurredAt": "2026-08-21T10:12:45Z",
  "accountId": "0199143a-7c2e-7b1a-9f2d-3c4b5a6d7e8f",
  "event": "SignerAddedToDocument",
  "entity": {
    "documentId": "01991440-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
    "signer": {
      "id": "01991441-9f8e-7d6c-8b5a-4c3d2e1f0a9b",
      "role": "Testemunha",
      "authenticationMethod": "Email",
      "email": "joao.souza@exemplo.com.br",
      "name": "João de Souza"
    }
  }
}
```

**Resposta esperada da sua URL**

| Status | Descrição |
| --- | --- |
| `2XX` | Entrega confirmada. Qualquer status 2xx serve; 200 e 202 são os recomendados. O corpo é ignorado. |
| `default` | Outro status, timeout de 20 segundos ou erro de rede: a entrega conta como falha e é repetida em seguida, até 5 tentativas. |

### Signatário assinou o documento

`POST` enviado à URL cadastrada na conta, com `event` igual a `DocumentSignatureMember`.

- operationId: `webhook_document_signature_member`

Um signatário assinou o documento. `entity` traz o documento, o papel, o e-mail, o nome informado
na assinatura e `signedAt`. Chega uma vez por signatário; quando o último assina, também é
enviado `DocumentSignatureFinished`.

**Entrega**

- `POST` com `Content-Type: application/json; charset=utf-8`, sem cabeçalho de autenticação ou
  assinatura. Valide a origem pelo `accountId` e, se precisar, por um segredo na própria URL.
- Responda qualquer status 2xx (200 ou 202 recomendados) em até 20 segundos. Outro status,
  timeout ou erro de rede contam como falha; a entrega é repetida em seguida, até 5 tentativas.
- `occurredAt` é o instante desta tentativa de envio, não o do evento, e muda a cada
  retentativa. Não há identificador de entrega no payload: trate repetições pelo conteúdo de
  `entity`.
- Não há garantia de ordem entre eventos, mesmo do mesmo documento. Para o estado atual, consulte
  `partners_v1_document_signatures_status`.
- Cada URL cadastrada na conta recebe todos os eventos; não há filtro por evento.

**Payload** (`application/json`, obrigatório)

| Propriedade | Tipo | Obrigatória | Descrição |
| --- | --- | --- | --- |
| `occurredAt` | string (date-time) | sim | Instante (UTC) desta tentativa de envio. Muda a cada retentativa; não é a data do evento. |
| `accountId` | string (uuid) | sim | Conta à qual o evento pertence. |
| `event` | `"DocumentSignatureMember"` | sim | Nome do evento, que define o formato de `entity`. |
| `entity` | [DocumentSignatureMemberWebHookDto](#documentsignaturememberwebhookdto) | sim | Dados do evento, no formato do schema referenciado; qual schema vem em `event`. |

```json
{
  "occurredAt": "2026-08-21T10:12:45Z",
  "accountId": "0199143a-7c2e-7b1a-9f2d-3c4b5a6d7e8f",
  "event": "DocumentSignatureMember",
  "entity": {
    "documentId": "01991440-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
    "role": "Parte",
    "email": "maria.silva@exemplo.com.br",
    "name": "Maria da Silva",
    "signedAt": "2026-08-21T10:12:45Z"
  }
}
```

**Resposta esperada da sua URL**

| Status | Descrição |
| --- | --- |
| `2XX` | Entrega confirmada. Qualquer status 2xx serve; 200 e 202 são os recomendados. O corpo é ignorado. |
| `default` | Outro status, timeout de 20 segundos ou erro de rede: a entrega conta como falha e é repetida em seguida, até 5 tentativas. |

### Todos signatários assinaram o documento

`POST` enviado à URL cadastrada na conta, com `event` igual a `DocumentSignatureFinished`.

- operationId: `webhook_document_signature_finished`

O último signatário assinou: `entity.signatureStatus` é `Signed` e `entity.status` é o status do
documento na conclusão (em geral `Finished`). A partir daqui o PDF assinado está disponível em
`partners_v1_documents_download_signed` e, havendo signatário com certificado digital, em
`partners_v1_documents_download_digital_certificate`.

**Entrega**

- `POST` com `Content-Type: application/json; charset=utf-8`, sem cabeçalho de autenticação ou
  assinatura. Valide a origem pelo `accountId` e, se precisar, por um segredo na própria URL.
- Responda qualquer status 2xx (200 ou 202 recomendados) em até 20 segundos. Outro status,
  timeout ou erro de rede contam como falha; a entrega é repetida em seguida, até 5 tentativas.
- `occurredAt` é o instante desta tentativa de envio, não o do evento, e muda a cada
  retentativa. Não há identificador de entrega no payload: trate repetições pelo conteúdo de
  `entity`.
- Não há garantia de ordem entre eventos, mesmo do mesmo documento. Para o estado atual, consulte
  `partners_v1_document_signatures_status`.
- Cada URL cadastrada na conta recebe todos os eventos; não há filtro por evento.

**Payload** (`application/json`, obrigatório)

| Propriedade | Tipo | Obrigatória | Descrição |
| --- | --- | --- | --- |
| `occurredAt` | string (date-time) | sim | Instante (UTC) desta tentativa de envio. Muda a cada retentativa; não é a data do evento. |
| `accountId` | string (uuid) | sim | Conta à qual o evento pertence. |
| `event` | `"DocumentSignatureFinished"` | sim | Nome do evento, que define o formato de `entity`. |
| `entity` | [DocumentSignatureStatusWebHookDto](#documentsignaturestatuswebhookdto) | sim | Dados do evento, no formato do schema referenciado; qual schema vem em `event`. |

```json
{
  "occurredAt": "2026-08-21T10:12:45Z",
  "accountId": "0199143a-7c2e-7b1a-9f2d-3c4b5a6d7e8f",
  "event": "DocumentSignatureFinished",
  "entity": {
    "id": "01991440-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
    "status": "Finished",
    "signatureStatus": "Signed"
  }
}
```

**Resposta esperada da sua URL**

| Status | Descrição |
| --- | --- |
| `2XX` | Entrega confirmada. Qualquer status 2xx serve; 200 e 202 são os recomendados. O corpo é ignorado. |
| `default` | Outro status, timeout de 20 segundos ou erro de rede: a entrega conta como falha e é repetida em seguida, até 5 tentativas. |

### Documento teve status alterado

`POST` enviado à URL cadastrada na conta, com `event` igual a `DocumentStatusChanged`.

- operationId: `webhook_document_status_changed`

O status do documento em `entity.id` mudou. Dois casos hoje:

- `entity.status` = `Finished`: o conteúdo do documento ficou pronto (documentos gerados no
  editor ou a partir de formulário).
- `entity.status` = `NewVersionBase`: o documento virou base de uma nova versão, criada no
  aplicativo; `entity.newVersionId` identifica a nova versão, que segue o fluxo normal.

**Entrega**

- `POST` com `Content-Type: application/json; charset=utf-8`, sem cabeçalho de autenticação ou
  assinatura. Valide a origem pelo `accountId` e, se precisar, por um segredo na própria URL.
- Responda qualquer status 2xx (200 ou 202 recomendados) em até 20 segundos. Outro status,
  timeout ou erro de rede contam como falha; a entrega é repetida em seguida, até 5 tentativas.
- `occurredAt` é o instante desta tentativa de envio, não o do evento, e muda a cada
  retentativa. Não há identificador de entrega no payload: trate repetições pelo conteúdo de
  `entity`.
- Não há garantia de ordem entre eventos, mesmo do mesmo documento. Para o estado atual, consulte
  `partners_v1_document_signatures_status`.
- Cada URL cadastrada na conta recebe todos os eventos; não há filtro por evento.

**Payload** (`application/json`, obrigatório)

| Propriedade | Tipo | Obrigatória | Descrição |
| --- | --- | --- | --- |
| `occurredAt` | string (date-time) | sim | Instante (UTC) desta tentativa de envio. Muda a cada retentativa; não é a data do evento. |
| `accountId` | string (uuid) | sim | Conta à qual o evento pertence. |
| `event` | `"DocumentStatusChanged"` | sim | Nome do evento, que define o formato de `entity`. |
| `entity` | [DocumentStatusChangedWebHookDto](#documentstatuschangedwebhookdto) | sim | Dados do evento, no formato do schema referenciado; qual schema vem em `event`. |

```json
{
  "occurredAt": "2026-08-21T10:12:45Z",
  "accountId": "0199143a-7c2e-7b1a-9f2d-3c4b5a6d7e8f",
  "event": "DocumentStatusChanged",
  "entity": {
    "status": "NewVersionBase",
    "newVersionId": "0199144e-b8c9-7d0e-8f1a-2b3c4d5e6f7a",
    "id": "01991440-5a6b-7c8d-9e0f-1a2b3c4d5e6f"
  }
}
```

**Resposta esperada da sua URL**

| Status | Descrição |
| --- | --- |
| `2XX` | Entrega confirmada. Qualquer status 2xx serve; 200 e 202 são os recomendados. O corpo é ignorado. |
| `default` | Outro status, timeout de 20 segundos ou erro de rede: a entrega conta como falha e é repetida em seguida, até 5 tentativas. |

### Documento foi removido

`POST` enviado à URL cadastrada na conta, com `event` igual a `DocumentRemoved`.

- operationId: `webhook_document_removed`

O documento em `entity.id` foi excluído, por `partners_v1_documents_delete` ou pelo aplicativo.
Ao excluir um envelope, este evento sai uma vez, com o id do envelope; quem lista os documentos
atingidos é o `DocumentSignaturesCanceled` da mesma exclusão, enviado quando o documento estava
aguardando assinaturas — parte das exclusões feitas no aplicativo não o envia. Depois deste evento,
as operações sobre o documento respondem `400`.

**Entrega**

- `POST` com `Content-Type: application/json; charset=utf-8`, sem cabeçalho de autenticação ou
  assinatura. Valide a origem pelo `accountId` e, se precisar, por um segredo na própria URL.
- Responda qualquer status 2xx (200 ou 202 recomendados) em até 20 segundos. Outro status,
  timeout ou erro de rede contam como falha; a entrega é repetida em seguida, até 5 tentativas.
- `occurredAt` é o instante desta tentativa de envio, não o do evento, e muda a cada
  retentativa. Não há identificador de entrega no payload: trate repetições pelo conteúdo de
  `entity`.
- Não há garantia de ordem entre eventos, mesmo do mesmo documento. Para o estado atual, consulte
  `partners_v1_document_signatures_status`.
- Cada URL cadastrada na conta recebe todos os eventos; não há filtro por evento.

**Payload** (`application/json`, obrigatório)

| Propriedade | Tipo | Obrigatória | Descrição |
| --- | --- | --- | --- |
| `occurredAt` | string (date-time) | sim | Instante (UTC) desta tentativa de envio. Muda a cada retentativa; não é a data do evento. |
| `accountId` | string (uuid) | sim | Conta à qual o evento pertence. |
| `event` | `"DocumentRemoved"` | sim | Nome do evento, que define o formato de `entity`. |
| `entity` | [DocumentRemovedWebHookDto](#documentremovedwebhookdto) | sim | Dados do evento, no formato do schema referenciado; qual schema vem em `event`. |

```json
{
  "occurredAt": "2026-08-21T10:12:45Z",
  "accountId": "0199143a-7c2e-7b1a-9f2d-3c4b5a6d7e8f",
  "event": "DocumentRemoved",
  "entity": {
    "id": "01991440-5a6b-7c8d-9e0f-1a2b3c4d5e6f"
  }
}
```

**Resposta esperada da sua URL**

| Status | Descrição |
| --- | --- |
| `2XX` | Entrega confirmada. Qualquer status 2xx serve; 200 e 202 são os recomendados. O corpo é ignorado. |
| `default` | Outro status, timeout de 20 segundos ou erro de rede: a entrega conta como falha e é repetida em seguida, até 5 tentativas. |

### Formulário foi preenchido

`POST` enviado à URL cadastrada na conta, com `event` igual a `FormFilled`.

- operationId: `webhook_form_filled`

Um formulário criado por `partners_v1_forms_create` foi preenchido por completo e o documento
correspondente foi gerado. `entity.formId` e `entity.documentId` identificam formulário e
documento. Em seguida, solicite as assinaturas com `partners_v1_documents_request_signatures`.

**Entrega**

- `POST` com `Content-Type: application/json; charset=utf-8`, sem cabeçalho de autenticação ou
  assinatura. Valide a origem pelo `accountId` e, se precisar, por um segredo na própria URL.
- Responda qualquer status 2xx (200 ou 202 recomendados) em até 20 segundos. Outro status,
  timeout ou erro de rede contam como falha; a entrega é repetida em seguida, até 5 tentativas.
- `occurredAt` é o instante desta tentativa de envio, não o do evento, e muda a cada
  retentativa. Não há identificador de entrega no payload: trate repetições pelo conteúdo de
  `entity`.
- Não há garantia de ordem entre eventos, mesmo do mesmo documento. Para o estado atual, consulte
  `partners_v1_document_signatures_status`.
- Cada URL cadastrada na conta recebe todos os eventos; não há filtro por evento.

**Payload** (`application/json`, obrigatório)

| Propriedade | Tipo | Obrigatória | Descrição |
| --- | --- | --- | --- |
| `occurredAt` | string (date-time) | sim | Instante (UTC) desta tentativa de envio. Muda a cada retentativa; não é a data do evento. |
| `accountId` | string (uuid) | sim | Conta à qual o evento pertence. |
| `event` | `"FormFilled"` | sim | Nome do evento, que define o formato de `entity`. |
| `entity` | [FormFilledWebhookDto](#formfilledwebhookdto) | sim | Dados do evento, no formato do schema referenciado; qual schema vem em `event`. |

```json
{
  "occurredAt": "2026-08-21T10:12:45Z",
  "accountId": "0199143a-7c2e-7b1a-9f2d-3c4b5a6d7e8f",
  "event": "FormFilled",
  "entity": {
    "formId": "01991443-7d8e-7f9a-8b1c-2d3e4f5a6b7c",
    "documentId": "01991440-5a6b-7c8d-9e0f-1a2b3c4d5e6f"
  }
}
```

**Resposta esperada da sua URL**

| Status | Descrição |
| --- | --- |
| `2XX` | Entrega confirmada. Qualquer status 2xx serve; 200 e 202 são os recomendados. O corpo é ignorado. |
| `default` | Outro status, timeout de 20 segundos ou erro de rede: a entrega conta como falha e é repetida em seguida, até 5 tentativas. |

### Prazo de assinatura do documento venceu

`POST` enviado à URL cadastrada na conta, com `event` igual a `DocumentSignaturesExpired`.

- operationId: `webhook_document_signatures_expired`

O prazo de assinatura venceu e as assinaturas foram canceladas pelo processo automático, que roda
uma vez por dia. `entity.deadlineForSignature` é o prazo que venceu.

`entity.id` é o envelope a que os documentos pertencem, ou o próprio documento quando ele não está
em um envelope. `entity.documents` traz somente os documentos cancelados — em um envelope o
vencimento pode atingir parte deles, porque o prazo é por documento — e, em cada um,
`pendingSigners` com os signatários que ainda não tinham assinado, no mesmo formato de
`webhook_document_sent_to_signature`.

Guarde `pendingSigners`: o cancelamento apaga as assinaturas do documento, então quem não assinou
não aparece mais em `partners_v1_document_signatures_status`. Os documentos ficam com o status de
assinatura `SignatureNotSet` e aceitam uma nova solicitação por
`partners_v1_documents_request_signatures`, com um prazo novo.

**Entrega**

- `POST` com `Content-Type: application/json; charset=utf-8`, sem cabeçalho de autenticação ou
  assinatura. Valide a origem pelo `accountId` e, se precisar, por um segredo na própria URL.
- Responda qualquer status 2xx (200 ou 202 recomendados) em até 20 segundos. Outro status,
  timeout ou erro de rede contam como falha; a entrega é repetida em seguida, até 5 tentativas.
- `occurredAt` é o instante desta tentativa de envio, não o do evento, e muda a cada
  retentativa. Não há identificador de entrega no payload: trate repetições pelo conteúdo de
  `entity`.
- Não há garantia de ordem entre eventos, mesmo do mesmo documento. Para o estado atual, consulte
  `partners_v1_document_signatures_status`.
- Cada URL cadastrada na conta recebe todos os eventos; não há filtro por evento.

**Payload** (`application/json`, obrigatório)

| Propriedade | Tipo | Obrigatória | Descrição |
| --- | --- | --- | --- |
| `occurredAt` | string (date-time) | sim | Instante (UTC) desta tentativa de envio. Muda a cada retentativa; não é a data do evento. |
| `accountId` | string (uuid) | sim | Conta à qual o evento pertence. |
| `event` | `"DocumentSignaturesExpired"` | sim | Nome do evento, que define o formato de `entity`. |
| `entity` | [DocumentSignaturesExpiredWebHookDto](#documentsignaturesexpiredwebhookdto) | sim | Dados do evento, no formato do schema referenciado; qual schema vem em `event`. |

```json
{
  "occurredAt": "2026-08-21T10:12:45Z",
  "accountId": "0199143a-7c2e-7b1a-9f2d-3c4b5a6d7e8f",
  "event": "DocumentSignaturesExpired",
  "entity": {
    "deadlineForSignature": "2026-09-08T00:00:00Z",
    "id": "01991447-3c4d-7e5f-8a6b-7c8d9e0f1a2b",
    "documents": [
      {
        "id": "01991440-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
        "pendingSigners": [
          {
            "id": "01991441-0a1b-7c2d-8e3f-4a5b6c7d8e9f",
            "role": "Parte",
            "authenticationMethod": "Email",
            "email": "maria.silva@exemplo.com.br",
            "name": "Maria da Silva"
          },
          {
            "id": "01991441-9f8e-7d6c-8b5a-4c3d2e1f0a9b",
            "role": "Testemunha",
            "authenticationMethod": "Email",
            "email": "joao.souza@exemplo.com.br",
            "name": "João de Souza"
          }
        ]
      }
    ]
  }
}
```

**Resposta esperada da sua URL**

| Status | Descrição |
| --- | --- |
| `2XX` | Entrega confirmada. Qualquer status 2xx serve; 200 e 202 são os recomendados. O corpo é ignorado. |
| `default` | Outro status, timeout de 20 segundos ou erro de rede: a entrega conta como falha e é repetida em seguida, até 5 tentativas. |

### Assinaturas do documento foram canceladas

`POST` enviado à URL cadastrada na conta, com `event` igual a `DocumentSignaturesCanceled`.

- operationId: `webhook_document_signatures_canceled`

As assinaturas foram canceladas a pedido, por `partners_v1_document_signatures_cancel`,
`partners_v1_documents_delete` ou pelo aplicativo. Uma exclusão só envia este evento se o documento
estava aguardando assinaturas, e parte das exclusões feitas no aplicativo envia somente o
`DocumentRemoved`. Para o cancelamento automático no vencimento do prazo, o evento é
`webhook_document_signatures_expired`.

`entity.id` é o envelope a que os documentos pertencem, ou o próprio documento quando ele não está
em um envelope. `entity.documents` traz somente os documentos cancelados — em um envelope o
cancelamento pode atingir parte deles — e, em cada um, `pendingSigners` com os signatários que ainda
não tinham assinado, no mesmo formato de `webhook_document_sent_to_signature`.

Guarde `pendingSigners`: o cancelamento apaga as assinaturas do documento, então quem não assinou
não aparece mais em `partners_v1_document_signatures_status`. Os documentos ficam com o status de
assinatura `SignatureNotSet` e aceitam uma nova solicitação por
`partners_v1_documents_request_signatures`. Quando o cancelamento vem de uma exclusão, o
`DocumentRemoved` do documento excluído também é enviado.

**Entrega**

- `POST` com `Content-Type: application/json; charset=utf-8`, sem cabeçalho de autenticação ou
  assinatura. Valide a origem pelo `accountId` e, se precisar, por um segredo na própria URL.
- Responda qualquer status 2xx (200 ou 202 recomendados) em até 20 segundos. Outro status,
  timeout ou erro de rede contam como falha; a entrega é repetida em seguida, até 5 tentativas.
- `occurredAt` é o instante desta tentativa de envio, não o do evento, e muda a cada
  retentativa. Não há identificador de entrega no payload: trate repetições pelo conteúdo de
  `entity`.
- Não há garantia de ordem entre eventos, mesmo do mesmo documento. Para o estado atual, consulte
  `partners_v1_document_signatures_status`.
- Cada URL cadastrada na conta recebe todos os eventos; não há filtro por evento.

**Payload** (`application/json`, obrigatório)

| Propriedade | Tipo | Obrigatória | Descrição |
| --- | --- | --- | --- |
| `occurredAt` | string (date-time) | sim | Instante (UTC) desta tentativa de envio. Muda a cada retentativa; não é a data do evento. |
| `accountId` | string (uuid) | sim | Conta à qual o evento pertence. |
| `event` | `"DocumentSignaturesCanceled"` | sim | Nome do evento, que define o formato de `entity`. |
| `entity` | [DocumentSignaturesCanceledWebHookDto](#documentsignaturescanceledwebhookdto) | sim | Dados do evento, no formato do schema referenciado; qual schema vem em `event`. |

```json
{
  "occurredAt": "2026-08-21T10:12:45Z",
  "accountId": "0199143a-7c2e-7b1a-9f2d-3c4b5a6d7e8f",
  "event": "DocumentSignaturesCanceled",
  "entity": {
    "id": "01991447-3c4d-7e5f-8a6b-7c8d9e0f1a2b",
    "documents": [
      {
        "id": "01991440-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
        "pendingSigners": [
          {
            "id": "01991441-0a1b-7c2d-8e3f-4a5b6c7d8e9f",
            "role": "Parte",
            "authenticationMethod": "Email",
            "email": "maria.silva@exemplo.com.br",
            "name": "Maria da Silva"
          },
          {
            "id": "01991441-9f8e-7d6c-8b5a-4c3d2e1f0a9b",
            "role": "Testemunha",
            "authenticationMethod": "Email",
            "email": "joao.souza@exemplo.com.br",
            "name": "João de Souza"
          }
        ]
      }
    ]
  }
}
```

**Resposta esperada da sua URL**

| Status | Descrição |
| --- | --- |
| `2XX` | Entrega confirmada. Qualquer status 2xx serve; 200 e 202 são os recomendados. O corpo é ignorado. |
| `default` | Outro status, timeout de 20 segundos ou erro de rede: a entrega conta como falha e é repetida em seguida, até 5 tentativas. |

## Schemas

Objetos e enums referenciados acima, em ordem alfabética. Enums são strings com os valores listados; propriedades nulas são omitidas nas respostas.

### CategoryDto

| Propriedade | Tipo | Obrigatória | Descrição |
| --- | --- | --- | --- |
| `id` | string (uuid) | não | ID da categoria Exemplo: `"0199143b-1d2e-7f3a-8b4c-5d6e7f8a9b0c"`. |
| `name` | string | não | Nome da categoria Exemplo: `"Contratos de locação"`. |
| `accountId` | string (uuid) | não | ID da conta Exemplo: `"0199143a-7c2e-7b1a-9f2d-3c4b5a6d7e8f"`. |
| `createdAt` | string (date-time) | não | Data de criação da categoria Exemplo: `"2025-03-12T13:45:10Z"`. |
| `active` | boolean | não | Categoria está ativa? Exemplo: `true`. |

### DocumentCategoryDto

| Propriedade | Tipo | Obrigatória | Descrição |
| --- | --- | --- | --- |
| `id` | string (uuid) | não | Identificador da categoria. Exemplo: `"0199143b-1d2e-7f3a-8b4c-5d6e7f8a9b0c"`. |
| `name` | string | não | Nome da categoria. Exemplo: `"Contratos de locação"`. |

### DocumentDto

| Propriedade | Tipo | Obrigatória | Descrição |
| --- | --- | --- | --- |
| `id` | string (uuid) | não | Identificador do documento. Exemplo: `"01991440-5a6b-7c8d-9e0f-1a2b3c4d5e6f"`. |
| `name` | string | não | Nome do documento. Exemplo: `"Contrato de locação - Apto 501"`. |
| `statusId` | [EDocumentStatus](#edocumentstatus) | não | Status do documento (código). Exemplo: `"Finished"`. |
| `status` | string \| null | não | Status do documento, por extenso em português. Exemplo: `"Pronto para assinar"`. |
| `signatureStatusId` | [EDocumentSignatureStatus](#edocumentsignaturestatus) | não | Status de assinatura do documento (código). Exemplo: `"WaitingSignatures"`. |
| `signatureStatus` | string \| null | não | Status de assinatura, por extenso em português. Exemplo: `"Aguardando assinaturas"`. |
| `endDate` | string (date-time) \| null | não | Fim da vigência do documento, quando definido. Campo legado, não preenchido em documentos criados pela API; o prazo de assinatura é `deadlineForSignature`. Exemplo: `"2026-09-30T23:59:59Z"`. |
| `deadlineForSignature` | string (date-time) \| null | não | Prazo de assinatura definido no envio, quando há. Somente a data é considerada: o cancelamento automático ocorre no decorrer do dia informado, em horário de Brasília. Exemplo: `"2026-09-30T12:00:00Z"`. |
| `fullSignedAt` | string (date-time) \| null | não | Data e hora em que o último signatário assinou. Nulo enquanto há assinaturas pendentes. |
| `categories` | [DocumentCategoryDto](#documentcategorydto)[] | não | Categorias associadas ao documento. |
| `groups` | [DocumentGroupDto](#documentgroupdto)[] | não | Grupos de acesso vinculados ao documento. Vazio quando quem vê o documento é decidido pelos grupos da pasta. |
| `reminderFrequency` | [EReminderFrequency](#ereminderfrequency) \| null | não | Frequência dos lembretes automáticos, quando configurada. Exemplo: `"ThreeDays"`. |
| `createdAt` | string (date-time) | não | Data e hora de criação do documento. Exemplo: `"2026-08-20T14:05:00Z"`. |

### DocumentGroupDto

| Propriedade | Tipo | Obrigatória | Descrição |
| --- | --- | --- | --- |
| `id` | string (uuid) | não | Identificador do grupo de acesso. Exemplo: `"0199143d-3f40-7b5c-8d6e-7f8a9b0c1d2e"`. |
| `name` | string | não | Nome do grupo de acesso. Exemplo: `"Jurídico"`. |

### DocumentRemovedWebHookDto

Dados do evento `DocumentRemoved`.

| Propriedade | Tipo | Obrigatória | Descrição |
| --- | --- | --- | --- |
| `id` | string (uuid) | não | Identificador do documento excluído. Exemplo: `"01991440-5a6b-7c8d-9e0f-1a2b3c4d5e6f"`. |

### DocumentSentToSignWebHookDto

Dados do evento `DocumentSentToSignature`.

| Propriedade | Tipo | Obrigatória | Descrição |
| --- | --- | --- | --- |
| `documentId` | string (uuid) | sim | Identificador do documento enviado para assinatura. |
| `sentAt` | string (date-time) | sim | Data e hora (UTC) do envio da solicitação. |
| `signers` | object[] | sim | Signatários do documento no momento do envio. |

### DocumentSignatureMemberWebHookDto

Dados do evento `DocumentSignatureMember`: um signatário assinou.

| Propriedade | Tipo | Obrigatória | Descrição |
| --- | --- | --- | --- |
| `documentId` | string (uuid) | não | Identificador do documento assinado. Exemplo: `"01991440-5a6b-7c8d-9e0f-1a2b3c4d5e6f"`. |
| `role` | string | não | Papel com que o signatário assinou. Exemplo: `"Parte"`. |
| `email` | string | não | E-mail do signatário. Exemplo: `"maria.silva@exemplo.com.br"`. |
| `name` | string | não | Nome informado pelo signatário ao assinar. Exemplo: `"Maria da Silva"`. |
| `signedAt` | string (date-time) \| null | não | Data e hora (UTC) da assinatura. Exemplo: `"2026-08-21T10:12:45Z"`. |

### DocumentSignatureStatusWebHookDto

Dados do evento `DocumentSignatureFinished`: o último signatário assinou.

| Propriedade | Tipo | Obrigatória | Descrição |
| --- | --- | --- | --- |
| `id` | string (uuid) | não | Identificador do documento. Exemplo: `"01991440-5a6b-7c8d-9e0f-1a2b3c4d5e6f"`. |
| `status` | `"Draft"` \| `"Finished"` \| `"Approved"` \| `"Disapproved"` \| `"NewVersionBase"` \| `"WaitingFormFill"` | não | `Draft` (Rascunho), `Finished` (Pronto para assinar), `Approved` (Aprovado), `Disapproved` (Reprovado), `NewVersionBase` (Base para nova versão), `WaitingFormFill` (Aguardando Preenchimento). |
| `signatureStatus` | `"SignatureNotSet"` \| `"SettingUpSignatures"` \| `"SignaturesDeliveryScheduled"` \| `"WaitingSignatures"` \| `"FinalizingSignatures"` \| `"ErrorOnFinalizingSignatures"` \| `"Signed"` | não | `SignatureNotSet` (Assinatura não configurada), `SettingUpSignatures` (Configurando assinaturas), `SignaturesDeliveryScheduled` (Envio de assinaturas agendada), `WaitingSignatures` (Aguardando assinaturas), `FinalizingSignatures` (Finalizando assinaturas), `ErrorOnFinalizingSignatures` (Erro finalizando assinaturas), `Signed` (Assinado). |

### DocumentSignaturesCanceledWebHookDto

Dados do evento `DocumentSignaturesCanceled`: um evento por envelope, com os documentos que
tiveram as assinaturas canceladas.

| Propriedade | Tipo | Obrigatória | Descrição |
| --- | --- | --- | --- |
| `id` | string (uuid) | não | Identificador do envelope a que os documentos cancelados pertencem, ou do próprio documento quando ele não está em um envelope. Exemplo: `"01991447-3c4d-7e5f-8a6b-7c8d9e0f1a2b"`. |
| `documents` | object[] | não | Documentos cancelados. Em um envelope, apenas os que foram cancelados: o cancelamento pode atingir parte deles. |

### DocumentSignaturesExpiredWebHookDto

Dados do evento `DocumentSignaturesExpired`: o mesmo do cancelamento, mais o prazo que
venceu.

| Propriedade | Tipo | Obrigatória | Descrição |
| --- | --- | --- | --- |
| `deadlineForSignature` | string (date-time) \| null | não | Prazo de assinatura que venceu, como valia no instante do cancelamento. Exemplo: `"2026-09-08T00:00:00Z"`. |
| `id` | string (uuid) | não | Identificador do envelope a que os documentos cancelados pertencem, ou do próprio documento quando ele não está em um envelope. Exemplo: `"01991447-3c4d-7e5f-8a6b-7c8d9e0f1a2b"`. |
| `documents` | object[] | não | Documentos cancelados. Em um envelope, apenas os que foram cancelados: o cancelamento pode atingir parte deles. |

### DocumentStatusChangedWebHookDto

Dados do evento `DocumentStatusChanged`.

| Propriedade | Tipo | Obrigatória | Descrição |
| --- | --- | --- | --- |
| `status` | `"Draft"` \| `"Finished"` \| `"Approved"` \| `"Disapproved"` \| `"NewVersionBase"` \| `"WaitingFormFill"` | não | `Draft` (Rascunho), `Finished` (Pronto para assinar), `Approved` (Aprovado), `Disapproved` (Reprovado), `NewVersionBase` (Base para nova versão), `WaitingFormFill` (Aguardando Preenchimento). |
| `newVersionId` | string (uuid) \| null | não | Identificador da nova versão, presente quando `status` é `NewVersionBase`. Exemplo: `"0199144e-b8c9-7d0e-8f1a-2b3c4d5e6f7a"`. |
| `id` | string (uuid) | não | Identificador do documento excluído. Exemplo: `"01991440-5a6b-7c8d-9e0f-1a2b3c4d5e6f"`. |

### DocumentUrlInfoDto

| Propriedade | Tipo | Obrigatória | Descrição |
| --- | --- | --- | --- |
| `name` | string | não | Nome do documento, sem extensão. Exemplo: `"Contrato de locação - Apto 501"`. |
| `url` | string | não | URL pré-assinada para download (GET), válida por 5 minutos. |

### EDocumentSignatureStatus

Valores:

- `SignatureNotSet`: Assinatura não configurada
- `SettingUpSignatures`: Configurando assinaturas
- `SignaturesDeliveryScheduled`: Envio de assinaturas agendada
- `WaitingSignatures`: Aguardando assinaturas
- `FinalizingSignatures`: Finalizando assinaturas
- `ErrorOnFinalizingSignatures`: Erro finalizando assinaturas
- `Signed`: Assinado

### EDocumentStatus

Valores:

- `Draft`: Rascunho
- `Finished`: Pronto para assinar
- `Approved`: Aprovado
- `Disapproved`: Reprovado
- `NewVersionBase`: Base para nova versão
- `WaitingFormFill`: Aguardando Preenchimento

### EProfile

Valores:

- `Owner`: Dono
- `Admin`: Administrador
- `User`: Usuário

### EReminderFrequency

Valores:

- `OneDay`: Lembrete a cada 1 dia
- `TwoDays`: Lembrete a cada 2 dias
- `ThreeDays`: Lembrete a cada 3 dias
- `SevenDays`: Lembrete a cada 7 dias
- `FourteenDays`: Lembrete a cada 14 dias

### FormFilledWebhookDto

Dados do evento `FormFilled`: um formulário foi preenchido por completo.

| Propriedade | Tipo | Obrigatória | Descrição |
| --- | --- | --- | --- |
| `formId` | string (uuid) | não | Identificador do formulário. Exemplo: `"01991443-7d8e-7f9a-8b1c-2d3e4f5a6b7c"`. |
| `documentId` | string (uuid) | não | Identificador do documento gerado a partir do formulário. Exemplo: `"01991440-5a6b-7c8d-9e0f-1a2b3c4d5e6f"`. |

### PagedListOfCategoryDto

| Propriedade | Tipo | Obrigatória | Descrição |
| --- | --- | --- | --- |
| `items` | [CategoryDto](#categorydto)[] | não |  |
| `hasPreviousPage` | boolean | não |  |
| `hasNextPage` | boolean | não |  |
| `previousPage` | integer (int32) \| null | não |  |
| `nextPage` | integer (int32) \| null | não |  |
| `page` | integer (int32) | não |  |
| `perPage` | integer (int32) | não |  |
| `count` | integer (int32) | não |  |
| `totalPages` | integer (int32) | não |  |

### PagedListOfDocumentDto

| Propriedade | Tipo | Obrigatória | Descrição |
| --- | --- | --- | --- |
| `items` | [DocumentDto](#documentdto)[] | não |  |
| `hasPreviousPage` | boolean | não |  |
| `hasNextPage` | boolean | não |  |
| `previousPage` | integer (int32) \| null | não |  |
| `nextPage` | integer (int32) \| null | não |  |
| `page` | integer (int32) | não |  |
| `perPage` | integer (int32) | não |  |
| `count` | integer (int32) | não |  |
| `totalPages` | integer (int32) | não |  |

### PagedListOfPartnerUserAccountDto

| Propriedade | Tipo | Obrigatória | Descrição |
| --- | --- | --- | --- |
| `items` | [PartnerUserAccountDto](#partneruseraccountdto)[] | não |  |
| `hasPreviousPage` | boolean | não |  |
| `hasNextPage` | boolean | não |  |
| `previousPage` | integer (int32) \| null | não |  |
| `nextPage` | integer (int32) \| null | não |  |
| `page` | integer (int32) | não |  |
| `perPage` | integer (int32) | não |  |
| `count` | integer (int32) | não |  |
| `totalPages` | integer (int32) | não |  |

### PartnerUserAccountDto

| Propriedade | Tipo | Obrigatória | Descrição |
| --- | --- | --- | --- |
| `id` | string (uuid) | não | Identificador do usuário. Exemplo: `"0199143f-5b6c-7d7e-8f80-9a0b1c2d3e4f"`. |
| `firstName` | string | não | Primeiro nome. Exemplo: `"Ana"`. |
| `lastName` | string \| null | não | Sobrenome. Exemplo: `"Pereira"`. |
| `fullName` | string \| null | não | Nome completo. Exemplo: `"Ana Pereira"`. |
| `email` | string | não | E-mail de acesso. Exemplo: `"ana.pereira@exemplo.com.br"`. |
| `addedAt` | string (date-time) | não | Data e hora em que o usuário foi adicionado à conta. Exemplo: `"2026-08-20T14:05:00Z"`. |
| `active` | boolean | não | Verdadeiro quando o usuário está ativo na conta. Exemplo: `true`. |
| `profile` | [EProfile](#eprofile) | não | Perfil na conta (código). Exemplo: `"Admin"`. |
| `profileDescription` | string \| null | não | Perfil por extenso em português. Exemplo: `"Administrador"`. |

### SignerAddedToDocumentWebHookDto

Dados do evento `SignerAddedToDocument`.

| Propriedade | Tipo | Obrigatória | Descrição |
| --- | --- | --- | --- |
| `documentId` | string (uuid) | sim | Identificador do documento que recebeu o signatário. |
| `signer` | object | sim | Signatário como aparece nos eventos de webhook. |

### TestWebHookDto

Dados do evento `Test`, enviado no cadastro de uma URL de webhook.

| Propriedade | Tipo | Obrigatória | Descrição |
| --- | --- | --- | --- |
| `test` | boolean | não | Sempre verdadeiro; marca a notificação de teste. Exemplo: `true`. |