# LetsSign Partners API > API REST para sistemas parceiros operarem contas do LetsSign: envio de documentos para assinatura eletrônica, acompanhamento, download dos arquivos assinados, contatos, pastas, categorias, usuários e notificações por webhook. Autenticação por chave de integração no header `Authorization`. Documentação em português do Brasil. Duas versões convivem. A v1 concentra a maior parte dos endpoints; a v2 substitui as listagens paginadas de documentos, categorias e usuários e o download do documento com anexos. Use a v2 quando o endpoint existir nela e a v1 para o restante. Os dez eventos de webhook estão descritos nos dois documentos. Cada referência existe em Markdown, para leitura direta, e em OpenAPI 3.1 JSON, para gerar clientes e ferramentas; o `operationId` de cada operação é estável e é citado nas descrições que apontam substitutos de endpoints obsoletos. As seções a seguir são os guias e, depois, a referência completa de cada documento, na mesma ordem do índice. --- # Quickstart: da chave à assinatura em cinco passos > **In English.** The shortest path through the Partners API: authenticate with the partner key, > find the account, send a PDF for electronic signature in a single request, follow the signatures > through webhooks or polling, and download the signed file. The guide is written in Brazilian > Portuguese; every step names the `operationId` you will find in the > [OpenAPI document](https://api.letssign.com.br/docs/partners-v1/openapi.json). Este guia leva do zero à primeira assinatura concluída. Cada passo cita o `operationId` da operação, que é o nome dela na [referência da v1](https://api.letssign.com.br/docs/partners/v1) e no documento OpenAPI. ## Antes de começar - **Chave de integração.** 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/). Ela identifica o parceiro e vai em toda requisição no header `Authorization`, sem prefixo. Detalhes em [Autenticação e contas](https://api.letssign.com.br/docs/guides/autenticacao-e-contas). - **Ambiente.** Sandbox e produção têm hosts e chaves distintos. A URL base deste ambiente é `https://api.letssign.com.br/`. - **Um PDF para testar** e o e-mail de quem vai assinar. Use endereços que você controla. Os exemplos usam `curl`. Troque `SUA_CHAVE` e os identificadores pelos seus. ## 1. Descubra a conta A chave identifica o **parceiro**; as operações agem sobre uma **conta**, identificada pelo `accountId` no caminho. Liste as contas que a chave pode operar (`partners_v1_accounts_list`): ```bash curl -H "Authorization: SUA_CHAVE" https://api.letssign.com.br/partners/v1/accounts ``` ```json [ { "id": "0199143a-7c2e-7b1a-9f2d-3c4b5a6d7e8f", "name": "Imobiliária Horizonte", "companyName": "Horizonte Negócios Imobiliários Ltda", "isTrial": false, "personType": "Company", "documentNumber": "12345678000195", "active": true } ] ``` Guarde o `id`: ele é o `accountId` dos próximos passos. Só contas ativas e vinculadas ao parceiro aparecem, em ordem alfabética, sem paginação. ## 2. Confira as features do plano Cada operação exige features do plano da conta; sem elas a resposta é `403`. Para enviar um documento para assinatura são necessárias `documents` e `documents_signatures`; para webhooks, `integrations` (`partners_v1_features_list`): ```bash curl -H "Authorization: SUA_CHAVE" \ https://api.letssign.com.br/partners/v1/accounts/0199143a-7c2e-7b1a-9f2d-3c4b5a6d7e8f/features ``` ```json [ { "id": "documents", "description": "Documentos" }, { "id": "documents_signatures", "description": "Assinatura de documentos" }, { "id": "integrations", "description": "Integrações" } ] ``` A relação entre features e operações está em [Limites e features](https://api.letssign.com.br/docs/guides/limites-e-features). ## 3. Envie o documento para assinatura Uma única chamada cria o documento e dispara a solicitação a cada signatário (`partners_v1_document_signatures_create_from_file`). O arquivo vai em base64 no campo `contentFile`, com o tipo MIME em `contentType`: ```bash CONTEUDO=$(base64 -i contrato.pdf) # Linux: base64 -w0 contrato.pdf curl -X POST -H "Authorization: SUA_CHAVE" -H "Content-Type: application/json" \ https://api.letssign.com.br/partners/v1/accounts/0199143a-7c2e-7b1a-9f2d-3c4b5a6d7e8f/document-signatures \ -d @- < **In English.** Every request carries the partner's integration key in the `Authorization` > header, with no scheme prefix. The key identifies the partner; the account being operated comes in > the route as `accountId`, and one key can operate several accounts. This guide covers where the > key comes from, how accounts, plans and features relate, how to manage the account's users, and > what produces `401` and `403`. Text in Brazilian Portuguese. ## A chave de integração Toda requisição leva a chave no header `Authorization`, **sem prefixo**. Não use `Bearer` nem `ApiKey` na frente: com prefixo, a chave não é reconhecida e a resposta é `401`. ```http GET /partners/v1/accounts HTTP/1.1 Host: api.letssign.com.br Authorization: 3f9c0a1b2c3d4e5f6a7b8c9d0e1f2a3b ``` - **Emissão.** A equipe LetsSign emite a chave no cadastro do parceiro, ou a própria conta a gera na área de integrações do aplicativo (https://app.letssign.com.br/). - **Rotação.** Regenerar a chave invalida a anterior na hora; não há período em que as duas valem. Atualize a configuração dos seus sistemas no mesmo instante em que regenerar. - **Guarda.** A chave dá acesso a todas as contas vinculadas ao parceiro. Mantenha-a no servidor, fora de aplicativos móveis, páginas e repositórios. Ela também não deve aparecer em URLs. - **Sandbox e produção** têm hosts e chaves distintos. A URL base deste ambiente é `https://api.letssign.com.br/`. O documento OpenAPI declara dois esquemas de segurança. `ApiKey` é este header. `Bearer` (JWT) é o esquema da API de identidade usada pelo aplicativo e **não se aplica** às APIs de parceiros. ## Parceiro, conta e usuário - **Parceiro** é quem tem a chave: o sistema que integra. - **Conta** é o espaço de uma empresa ou pessoa no LetsSign. Documentos, contatos, pastas, categorias, usuários e webhooks pertencem a uma conta. Quase todas as rotas levam o `accountId` no caminho. - **Usuário** é uma pessoa que acessa o aplicativo dentro de uma conta, com perfil `Owner`, `Admin` ou `User`. Um parceiro opera quantas contas estiverem vinculadas a ele. O ponto de partida é a lista de contas (`partners_v1_accounts_list`): só entram contas **ativas e vinculadas ao parceiro**, em ordem alfabética, sem paginação e sem exigir feature de plano. ```json [ { "id": "0199143a-7c2e-7b1a-9f2d-3c4b5a6d7e8f", "name": "Imobiliária Horizonte", "companyName": "Horizonte Negócios Imobiliários Ltda", "createdAt": "2025-03-12T13:45:10Z", "isTrial": false, "initDate": "2025-03-12T00:00:00Z", "personType": "Company", "documentNumber": "12345678000195", "active": true } ] ``` `id` é o `accountId`. `isTrial` indica conta em período de teste; `documentNumber` é o CPF ou CNPJ do titular. Uma conta que sai da lista (desativada ou desvinculada) passa a responder `401` nas rotas que a citam. ## Planos e features O que uma conta pode fazer vem do **plano do seu grupo de faturamento**, expresso em **features**. - `partners_v1_features_list` devolve as features da conta: `id` (o código usado nas descrições das operações e na extensão `x-required-features` do OpenAPI) e uma descrição legível. A lista muda quando o plano muda. - Cada operação declara as features que exige. Sem alguma delas, a resposta é `403` com corpo vazio. Consulte a lista antes de habilitar uma funcionalidade na sua integração. - `partners_v1_plans_list` lista os planos vinculados ao parceiro, isto é, os planos que a equipe LetsSign pode atribuir às contas dele. Não recebe `accountId` e é informativo: a atribuição de plano não é feita pela API. O mapa de features por operação, as cotas e os demais limites estão em [Limites e features](https://api.letssign.com.br/docs/guides/limites-e-features). ## Usuários da conta - **Adicionar** (`partners_v1_users_add`): envia a cada e-mail um convite com o código de acesso. Um e-mail que já existe em outra conta do LetsSign é reaproveitado; um novo cria o usuário. `onlyForSignature` verdadeiro cria o usuário com perfil `User` (só vê e assina os próprios documentos) e exige a feature `only_signature`; falso cria como `Admin`. O lote é atômico: se qualquer e-mail já pertence à conta, ninguém é adicionado e a resposta `400` lista os repetidos. Conta inativa ou sem plano ativo também responde `400`. - **Ativar e desativar** (`partners_v1_users_change_status`). - **Listar** (`partners_v2_users_list`): paginada, com filtros por identificador, nome, e-mail, situação, visibilidade e perfil. - **Logotipo da conta** (`partners_v1_accounts_change_logo`): imagem PNG, JPG ou JPEG em base64; substitui a anterior. ## O que responde 401 e 403 | Situação | Status | Corpo | |---|---|---| | Chave ausente, inválida ou com prefixo | `401` | vazio | | Conta não vinculada ao parceiro (ou inativa) | `401` | vazio | | Período de teste da conta expirado | `401` | Problem Details com o motivo em `detail` | | Grupo de faturamento da conta sem plano ativo | `401` | Problem Details com o motivo em `detail` | | Plano da conta sem uma feature exigida pela operação | `403` | vazio | Em algumas operações a verificação da conta acontece dentro da regra de negócio, e não na autenticação. É o caso da troca de logotipo, que responde `400` com `Conta não existe` ou `Parceiro não pode realizar operações na conta solicitada`. O formato dos erros está em [Erros](https://api.letssign.com.br/docs/guides/erros). ## Boas práticas - Trate `401` como problema de configuração (chave, ambiente, vínculo da conta), não como falha transitória: repetir a mesma requisição não muda o resultado. - Guarde `requestId` e `traceId` das respostas de erro; eles identificam a requisição no suporte. - Nos webhooks não há cabeçalho de assinatura. Valide a origem pelo `accountId` do payload e, se precisar, por um segredo na própria URL cadastrada. Veja [Webhooks](https://api.letssign.com.br/docs/guides/webhooks). --- # Webhooks > **In English.** Register one or more URLs per account and receive a JSON `POST` for each event: > document sent for signature, signer added, signer signed, all signatures finished, document status > changed, document removed, form filled, signatures expired, signatures canceled. Any 2xx within > 20 seconds confirms delivery; failures are retried up to 5 times. New events may be added, so route > by the `event` you know and discard the rest with a 2xx. There is no signature header and no > delivery id: validate the origin with `accountId` (and a secret in your URL) and treat repeats by > the content of `entity`. Text in Brazilian Portuguese. Webhooks são a forma recomendada de acompanhar documentos: em vez de consultar a situação repetidamente, sua URL recebe um `POST` a cada evento da conta. ## Cadastro Cadastre a URL com `partners_v1_webhooks_create` (exige a feature `integrations`): ```bash curl -X POST -H "Authorization: SUA_CHAVE" -H "Content-Type: application/json" \ https://api.letssign.com.br/partners/v1/accounts/0199143a-7c2e-7b1a-9f2d-3c4b5a6d7e8f/webhooks \ -d '{ "uri": "https://integracao.exemplo.com.br/letssign/webhook" }' ``` ```json { "id": "0199143e-4a5b-7c6d-9e7f-8a9b0c1d2e3f", "accountId": "0199143a-7c2e-7b1a-9f2d-3c4b5a6d7e8f", "uri": "https://integracao.exemplo.com.br/letssign/webhook", "available": true, "createdAt": "2026-08-20T14:05:00Z" } ``` - A URL precisa começar com `http://` ou `https://`, ter o host em minúsculas e um TLD de 2 a 5 letras. A mesma URL não pode ser cadastrada duas vezes na conta (`400`). - No cadastro, um evento **`Test`** é enviado de imediato. Sua URL deve responder `200` ou `202` em até 20 segundos; o resultado fica em `available`. A URL é gravada mesmo quando o teste falha, e o `Test` não é reenviado depois. - Cada URL cadastrada recebe **todos** os eventos da conta; não há filtro por evento. Para receber em mais de um sistema, cadastre mais de uma URL. - Liste com `partners_v1_webhooks_list` e remova com `partners_v1_webhooks_delete`. Depois da remoção, eventos novos deixam de ser enviados àquela URL. ## O envelope Cada entrega é um `POST` com `Content-Type: application/json; charset=utf-8` e este corpo: | Campo | Tipo | O que traz | |---|---|---| | `event` | string | Nome do evento, que define o formato de `entity`. | | `accountId` | UUID | Conta à qual o evento pertence. Use para validar a origem e rotear. | | `occurredAt` | data e hora (UTC) | Instante **desta tentativa de envio**, não do evento. Muda a cada retentativa. | | `entity` | objeto | Os dados do evento. O schema de cada um está no objeto `webhooks` do documento OpenAPI e na seção de payloads abaixo. | ```json { "occurredAt": "2026-08-21T10:12:45Z", "accountId": "0199143a-7c2e-7b1a-9f2d-3c4b5a6d7e8f", "event": "DocumentSignatureFinished", "entity": { "...": "depende do evento" } } ``` ## Os eventos | Evento | Quando | O que fazer | |---|---|---| | `Test` | Uma vez, no cadastro da URL. `entity.test` é sempre `true`. | Responder 2xx. | | `DocumentSentToSignature` | 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, sai no momento da criação. | Guardar `entity.signers[].id`: é o `signatureId` para editar, remover e reenviar. | | `SignerAddedToDocument` | Um signatário foi adicionado a um documento já em assinatura. | Guardar `entity.signer.id`. | | `DocumentSignatureMember` | Um signatário assinou. Chega uma vez por signatário, com papel, e-mail, nome informado e `signedAt`. | Atualizar o andamento. Quando é o último, também chega `DocumentSignatureFinished`. | | `DocumentSignatureFinished` | O último signatário assinou: `entity.signatureStatus` é `Signed`. | Baixar o PDF assinado (`partners_v1_documents_download_signed`) ou, com certificado digital, `partners_v1_documents_download_digital_certificate`. | | `DocumentStatusChanged` | O status do documento mudou: `Finished` (conteúdo pronto, em documentos gerados no editor ou por formulário) ou `NewVersionBase` (o documento virou base de uma nova versão, em `entity.newVersionId`). | Acompanhar a nova versão, se houver. | | `DocumentRemoved` | O documento foi excluído, pela API ou pelo aplicativo. Ao excluir um envelope, sai uma vez, com o id do envelope. | Encerrar o acompanhamento; operações sobre o documento passam a responder `400`. | | `FormFilled` | Um formulário criado por `partners_v1_forms_create` foi preenchido por completo e o documento foi gerado. | Solicitar as assinaturas com `partners_v1_documents_request_signatures`. | | `DocumentSignaturesExpired` | O prazo de assinatura venceu e as assinaturas foram canceladas pelo processo automático diário. `entity.deadlineForSignature` é o prazo que venceu. Sai uma vez por envelope, e `entity.documents` traz só os documentos atingidos. | Guardar `documents[].pendingSigners`: quem não assinou deixa de existir depois do cancelamento. Reenviar com `partners_v1_documents_request_signatures` e um prazo novo, se for o caso. | | `DocumentSignaturesCanceled` | As assinaturas foram canceladas a pedido, pela API ou pelo aplicativo. Numa exclusão só chega se o documento estava aguardando assinaturas, e parte das exclusões feitas no aplicativo não o envia. Mesmo formato do evento acima, sem o prazo. | Encerrar o acompanhamento, ou reabrir com `partners_v1_documents_request_signatures`. | ## Contrato de entrega - **Confirmação.** Qualquer status 2xx confirma a entrega; `200` ou `202` são os recomendados. O corpo da sua resposta é ignorado. - **Tempo limite.** 20 segundos. Outro status, tempo esgotado ou erro de rede contam como falha. - **Retentativas.** A entrega é repetida em seguida, até 5 tentativas, sem espera progressiva. Depois disso o evento não é reenviado. - **Sem assinatura.** Não há cabeçalho de autenticação nem assinatura HMAC no payload. Valide a origem pelo `accountId` (ele precisa ser uma conta sua) e, se quiser uma camada a mais, inclua um segredo na própria URL cadastrada (`https://.../webhook?token=...`) e confira-o a cada entrega. - **Sem identificador de entrega.** Trate repetições pelo conteúdo de `entity`: por exemplo, `event` + `entity.documentId` + `entity.signer.id` + `signedAt` identificam uma assinatura. - **Sem garantia de ordem**, mesmo entre eventos do mesmo documento. Para saber o estado atual, consulte `partners_v1_document_signatures_status`. ## Como tratar no seu lado 1. **Responda rápido.** Grave o payload numa fila e responda `202`; processe depois. Assim você fica longe dos 20 segundos mesmo em picos. 2. **Seja idempotente.** Guarde uma chave derivada do conteúdo e ignore o que já processou. 3. **Valide a origem.** Rejeite (`4xx`) payloads cujo `accountId` não seja seu ou cujo segredo na URL não bata. 4. **Reconcilie.** Como não há ordem garantida, ao receber `DocumentSignatureMember` confirme o estado com `partners_v1_document_signatures_status` antes de decisões irreversíveis. 5. **Registre.** Guarde o payload bruto e o instante de recebimento; sem identificador de entrega, é o seu registro que permite investigar. 6. **Monitore `available`.** Se o teste do cadastro falhou, corrija a URL e cadastre de novo (remova a anterior primeiro). 7. **Descarte o que você não trata.** Eventos novos podem ser criados. Faça o roteamento pelo `event` que você conhece, responda 2xx para os demais e descarte-os: um `4xx`/`5xx` num evento que você não trata só gera retentativa e ruído no seu registro. ## Payloads de exemplo Os exemplos abaixo são os mesmos do objeto `webhooks` do documento OpenAPI, com o envelope completo. ### `Test` Enviado no cadastro de uma URL de webhook, para verificar a disponibilidade. ```json { "occurredAt": "2026-08-21T10:12:45Z", "accountId": "0199143a-7c2e-7b1a-9f2d-3c4b5a6d7e8f", "event": "Test", "entity": { "test": true } } ``` ### `DocumentSentToSignature` Documento enviado para assinatura. ```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" } ] } } ``` ### `SignerAddedToDocument` Novo signatário adicionado ao documento. ```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" } } } ``` ### `DocumentSignatureMember` Signatário assinou o documento. ```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" } } ``` ### `DocumentSignatureFinished` Todos signatários assinaram o documento. ```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" } } ``` ### `DocumentStatusChanged` Documento teve status alterado. ```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" } } ``` ### `DocumentRemoved` Documento foi removido. ```json { "occurredAt": "2026-08-21T10:12:45Z", "accountId": "0199143a-7c2e-7b1a-9f2d-3c4b5a6d7e8f", "event": "DocumentRemoved", "entity": { "id": "01991440-5a6b-7c8d-9e0f-1a2b3c4d5e6f" } } ``` ### `FormFilled` Formulário foi preenchido. ```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" } } ``` ### `DocumentSignaturesExpired` Prazo de assinatura do documento venceu. ```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" } ] } ] } } ``` ### `DocumentSignaturesCanceled` Assinaturas do documento foram canceladas. ```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" } ] } ] } } ``` --- # Erros > **In English.** Errors follow RFC 9457 Problem Details (`application/problem+json`). `400` means a > business rule was not met, `422` means the payload itself was rejected (malformed JSON or failed > validation), `401` and `403` are authentication and plan features, `404` appears only where an > operation declares it, and `500` is an internal failure to report with `requestId` and `traceId`. > `400` and `422` are final: repeating the same request produces the same error. Text in Brazilian > Portuguese. ## Formato Erros vêm com `Content-Type: application/problem+json` e o corpo `ProblemDetailsResult`: | Campo | O que traz | |---|---| | `type` | URI que identifica o tipo do problema (a seção da RFC 9110 do status). | | `title` | Nome do status, em inglês (`Bad Request`, `Unprocessable Entity`). | | `status` | O status HTTP, repetido no corpo. | | `detail` | Explicação em texto, quando existe (por exemplo, nos `401` de trial expirado e de grupo sem plano). | | `instance` | Método e caminho da requisição. | | `errors` | Lista de mensagens, em português. É onde estão as mensagens de regra de negócio e de validação. | | `problems` | Uma entrada por problema, com `message` e `propertyName` (o campo do payload, quando o erro é de um campo). | | `traceId`, `spanId`, `requestId` | Identificadores de rastreio. Informe-os ao suporte. | Exemplo ilustrativo de `422`, com um campo inválido: ```json { "type": "https://tools.ietf.org/html/rfc9110#section-15.5.21", "title": "Unprocessable Entity", "status": 422, "instance": "POST /partners/v1/accounts/0199143a-7c2e-7b1a-9f2d-3c4b5a6d7e8f/document-signatures", "errors": ["O e-mail do signatário é inválido."], "problems": [ { "message": "O e-mail do signatário é inválido.", "propertyName": "signers[0].email" } ], "traceId": "00-9d5ae161cadc20cdb55a260d9f4b5453-184806a3008259ec-00", "spanId": "184806a3008259ec", "requestId": "0HNOA3C9U49GU:00000001" } ``` Exemplo ilustrativo de `400`, com uma regra de negócio: ```json { "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1", "title": "Bad Request", "status": 400, "instance": "POST /partners/v1/accounts/0199143a-7c2e-7b1a-9f2d-3c4b5a6d7e8f/document-signatures", "errors": ["Um ou mais papéis (Fiador) não existe(m)"], "problems": [], "traceId": "00-1c4f0b2d9a8e7f6c5b4a39281706f5e4-5b4a39281706f5e4-00", "spanId": "5b4a39281706f5e4", "requestId": "0HNOA3C9U49GU:00000002" } ``` As mensagens exatas variam por operação; a referência de cada operação lista as principais. ## O que cada status significa | Status | Quando acontece | Corpo | |---|---|---| | `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 (SMS, WhatsApp, biometria), cota atingida, duplicidade. | Problem Details, mensagens em `errors`. | | `401` | Chave ausente ou inválida, conta não vinculada, trial expirado, grupo de faturamento sem plano ativo. | Vazio, exceto nos dois últimos casos (motivo em `detail`). | | `403` | O plano da conta não inclui uma feature exigida pela operação. | Vazio. | | `404` | Recurso não encontrado, nas consultas por identificador que declaram `404` (por exemplo, a situação das assinaturas de um documento que não é da conta). | Problem Details. | | `422` | Payload rejeitado: JSON malformado ou campos que não passaram na validação (obrigatórios, tamanhos, formatos, combinações). | Problem Details, `errors` e `problems` com o campo. | | `500` | Erro interno. | Problem Details com `requestId` e `traceId`. | A distinção que mais importa: **`422` é sobre a forma** da requisição (o JSON e os campos) e **`400` é sobre o estado** (o que a conta, o documento ou o plano permitem agora). Os dois são definitivos para a mesma requisição. ## O que vale repetir - `400` e `422`: corrija a requisição. Repetir igual produz o mesmo erro. - `401`: confira chave, ambiente e vínculo da conta. Veja [Autenticação e contas](https://api.letssign.com.br/docs/guides/autenticacao-e-contas). - `403`: o plano não tem a feature. Confira `partners_v1_features_list`. - `404`: o identificador está errado ou pertence a outra conta. - `500`: pode repetir com espera crescente (por exemplo, três tentativas a partir de 2 segundos). Persistindo, informe `requestId` e `traceId` ao suporte. - **Tempo esgotado sem resposta**: a operação pode ter sido executada. As criações não têm chave de idempotência: `partners_v1_document_signatures_create_from_file` e `partners_v1_forms_create` criam um documento novo a cada chamada e consomem cota. Antes de repetir, confira se o recurso existe (`partners_v2_documents_list` filtrando por `Name` e `CreatedFrom`). Já os upserts de contato (`partners_v1_contacts_upsert_person`, `partners_v1_contacts_upsert_company`) são idempotentes, e criações com chave natural, como webhooks (URL) e usuários (e-mail), respondem `400` na repetição em vez de duplicar. Não há limite de requisições por chave hoje, então não existe `429`; se um dia houver, ele aparecerá neste guia e no [changelog](https://api.letssign.com.br/docs/guides/changelog). ## Mensagens frequentes | Mensagem em `errors` | Operação | Causa e saída | |---|---|---| | `Um ou mais papéis (...) não existe(m)` | criação e edição de signatários | O `role` não existe na conta. Consulte `partners_v1_document_signature_roles_list`. | | `Um ou mais grupos (...) não existe(m) ou está(ão) inativo(s)` | criação de documento, criação de formulário e atualização de grupos do documento | `422`: o id não é grupo **ativo** da conta. Consulte `partners_v1_groups_list`; grupo desativado no aplicativo deixa de ser aceito. | | `Nenhum signatário assinou o documento até o momento.` | download do assinado | Ainda não há assinatura. Aguarde `DocumentSignatureMember` ou consulte a situação. | | `A URL ... já é usada como webhook na conta` | cadastro de webhook | A URL já está cadastrada; liste com `partners_v1_webhooks_list`. | | `Conta não existe`, `Parceiro não pode realizar operações na conta solicitada` | troca de logotipo | O `id` não é de uma conta vinculada ao parceiro. | | Tags faltando no formulário | criação de formulário | Toda tag do modelo precisa estar em `fillers[].fieldsTags` ou em `filledFields`; a mensagem lista quais faltam. | --- # 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. --- # Limites e features > **In English.** What an account can do comes from the plan's features; each operation declares the > features it needs and answers `403` without them. Plans also carry quotas (documents per period, > SMS and WhatsApp messages) that answer `400` when exhausted. This guide lists the features, the > operations behind each one, the quotas, the size and time limits, and the caches. Text in > Brazilian Portuguese. ## Features do plano Features são as capacidades do plano do grupo de faturamento da conta. `partners_v1_features_list` devolve as da conta, com `id` e descrição. Cada operação da referência declara as suas na descrição e na extensão `x-required-features` do OpenAPI; sem alguma delas, a resposta é `403` com corpo vazio. Operações sem feature exigem só a chave válida e a conta vinculada. | Feature | O que libera | |---|---| | `documents` | Tudo sobre documentos: listagens, downloads, informações, campos de formulário, mapeamento de assinaturas, pasta, exclusão e solicitação de assinaturas em documento existente. | | `documents_signatures` | Criar documento para assinatura a partir de arquivo, consultar a situação, adicionar, editar, remover e reenviar signatários, cancelar assinaturas e alterar métodos adicionais de autenticação. Sempre junto de `documents`. | | `integrations` | Webhooks (listar, cadastrar, remover) e contatos (junto de `contacts`). | | `contacts` | Contatos pessoa e empresa: consultar, criar ou atualizar e remover. Junto de `integrations`. | | `categories` | Categorias: listar, criar, consultar, atualizar, remover e ativar ou desativar. | | `custom_models`, `default_models` | Modelos de formulário: listar modelos, criar formulários e consultar os campos de formulário de um documento. Modelos próprios da conta e modelos padrão, respectivamente; as operações pedem as duas. | | `folder_writer` | Criar pastas. Listar pastas não exige feature. | | `groups` | Listar grupos da conta. | | `document_informations` | Listar os campos de informação da conta. | | `only_signature` | Adicionar usuários com `onlyForSignature` verdadeiro (perfil `User`). | Sem feature: listar contas, features e planos, trocar o logotipo, listar papéis de signatário, listar pastas e adicionar, listar e alterar a situação de usuários. Além das features, o plano habilita **recursos** que aparecem só quando usados: envio por SMS e WhatsApp, biometria facial nos métodos adicionais de autenticação e campos de informação no documento. Pedir um recurso que o plano não tem responde `400`, com a mensagem em `errors`. ## Cotas - **Documentos.** Criar um documento para assinatura (`partners_v1_document_signatures_create_from_file`) ou a partir de formulário (`partners_v1_forms_create`) consome um documento da cota do plano. Cota esgotada responde `400`. - **SMS e WhatsApp.** Enviar o link ou o código por esses canais consome a cota do canal. Esgotada, a operação responde `400`. - **Lembretes.** `reminderFrequency` envia lembretes automáticos por e-mail, até 3 por signatário. As cotas não são consultáveis pela API; acompanhe pelo aplicativo. ## Tamanhos, formatos e prazos | Limite | Valor | |---|---| | Corpo da requisição | Até 70 MB. Como os arquivos vão em base64 (cerca de 33% maiores que o binário), isso acomoda arquivos de até aproximadamente 50 MB. | | Formatos de documento | PDF, DOC e DOCX. DOC e DOCX são convertidos para PDF. PDF com senha ou com edição bloqueada é recusado. | | Logotipo da conta | PNG, JPG ou JPEG, em base64. | | URL de download | Válida por 5 minutos; cada chamada gera uma URL nova. | | Webhook | Resposta 2xx em até 20 segundos; até 5 tentativas em caso de falha. | | Requisições por chave | Sem limite hoje. Prefira webhooks a consultas repetidas; se um limite for criado, ele será anunciado no [changelog](https://api.letssign.com.br/docs/guides/changelog). | Áreas de assinatura (`signatureAreas`) precisam apontar para páginas que existem no arquivo; página inexistente responde `400`. ## Caches | Listagem | Cache | |---|---| | Pastas (`partners_v1_folders_list`) | Até 3 horas. Criar uma pasta pela API invalida o cache da conta. | | Grupos (`partners_v1_groups_list`) | Até 3 horas. | | Modelos de formulário (`partners_v1_form_templates_list`) | Até 3 horas. | | Papéis de signatário (`partners_v1_document_signature_roles_list`) | Até 1 hora. | Alterações feitas no aplicativo podem demorar esse tempo para aparecer nessas listagens. ## Situação da conta - **Período de teste** (`isTrial`): ao expirar, as rotas da conta respondem `401` com o motivo em `detail`. - **Grupo de faturamento sem plano ativo**: `401` com o motivo em `detail`. - **Conta inativa ou desvinculada**: sai de `partners_v1_accounts_list` e responde `401`. Veja [Autenticação e contas](https://api.letssign.com.br/docs/guides/autenticacao-e-contas) e [Erros](https://api.letssign.com.br/docs/guides/erros). --- # Ferramentas e agentes de IA > **In English.** Everything on this page is generated from the same OpenAPI documents that power > the reference: a Postman collection per version (also importable in Bruno, Insomnia and > Hoppscotch), a Model Context Protocol (MCP) server that turns each operation into a tool, the > `llms.txt` index for language models and the sandbox environment. The last section is the > checklist an agent should follow when operating the API. Text in Brazilian Portuguese. Tudo nesta página nasce dos mesmos documentos OpenAPI que alimentam a referência ([v1](https://api.letssign.com.br/docs/partners-v1/openapi.json), [v2](https://api.letssign.com.br/docs/partners-v2/openapi.json)): nenhum formato é mantido à mão, então nenhum fica atrás do contrato. As URLs abaixo são as do ambiente que serviu esta página (`https://api.letssign.com.br`); o sandbox tem as mesmas rotas no host dele. ## Coleção Postman Cada versão tem uma coleção no formato Postman v2.1, gerada pela própria API: | Versão | Coleção | |---|---| | Partners API v1 | `https://api.letssign.com.br/docs/partners/v1.postman_collection.json` | | Partners API v2 | `https://api.letssign.com.br/docs/partners/v2.postman_collection.json` | **Importar.** No Postman: *Import*, cole a URL da coleção. No Bruno: *Import Collection* e escolha *Postman Collection* com o arquivo baixado, ou *OpenAPI V3* apontando para o documento OpenAPI. Insomnia e Hoppscotch importam tanto a coleção Postman quanto o documento OpenAPI. **O que vem pronto.** - Uma pasta por recurso (as tags do documento), com a descrição da tag. Cada requisição leva o `operationId` e a descrição completa da operação. - Autenticação no nível da coleção: header `Authorization` com o valor da variável `apiKey`, sem prefixo. Nenhuma requisição precisa de configuração própria. - Variáveis da coleção: `baseUrl` (já preenchida com `https://api.letssign.com.br`), `apiKey`, `accountId` e `webhookUrl`. O `accountId` substitui o segmento `{accountId}` de todas as rotas; os demais parâmetros de rota (`:id`, `:documentId`) ficam como variáveis da URL, com descrição. - Parâmetros de consulta declarados, com o valor padrão preenchido; os opcionais sem padrão entram desmarcados. - Corpo de exemplo em cada POST e PUT e exemplos de resposta salvos, os mesmos da referência. - Pasta **Webhooks**: um POST por evento, com o payload de exemplo, enviado a `webhookUrl` sem autenticação. Serve para testar o seu receptor antes de cadastrar a URL na conta. **Para começar.** Preencha `apiKey` e `accountId` (obtenha o segundo com a requisição *Lista as contas do parceiro*, `partners_v1_accounts_list`, na coleção da v1) e execute as consultas da pasta de contas. Faça isso primeiro no sandbox. ## Servidor MCP a partir do OpenAPI O Model Context Protocol (MCP) é o padrão com que assistentes (Claude, Cursor, VS Code e outros) recebem ferramentas. A API não expõe um servidor MCP próprio. Em vez disso, o documento OpenAPI tem o que um servidor genérico precisa para gerar uma ferramenta por operação: `operationId` estável, descrição, schemas e exemplos. A configuração abaixo usa o [`@ivotoby/openapi-mcp-server`](https://github.com/ivo-toby/mcp-openapi-server), um servidor MCP de código aberto que lê o documento na inicialização e cria uma ferramenta por operação; foi verificada com este contrato na versão indicada (49 ferramentas para a v1, chamadas chegando à API), e qualquer servidor equivalente que aceite uma URL de OpenAPI 3.1 e um header fixo funciona do mesmo jeito. ### Claude Desktop, Cursor e outros clientes com `mcpServers` Adicione ao arquivo de configuração do cliente (`claude_desktop_config.json`, `.cursor/mcp.json`): ```json { "mcpServers": { "partners-api-v1": { "command": "npx", "args": [ "-y", "@ivotoby/openapi-mcp-server@1.16.1", "--api-base-url", "https://api.letssign.com.br", "--openapi-spec", "https://api.letssign.com.br/docs/partners-v1/openapi.json", "--headers", "Authorization:SUA_CHAVE", "--disable-abbreviation", "true", "--name", "partners-api-v1" ] } } } ``` ### Claude Code ```bash claude mcp add partners-api-v1 -- npx -y @ivotoby/openapi-mcp-server@1.16.1 \ --api-base-url https://api.letssign.com.br \ --openapi-spec https://api.letssign.com.br/docs/partners-v1/openapi.json \ --headers "Authorization:SUA_CHAVE" \ --disable-abbreviation true \ --name partners-api-v1 ``` ### O que observar - **Uma versão por servidor.** Cada documento vira um servidor; para a v2, repita a configuração com `https://api.letssign.com.br/docs/partners-v2/openapi.json` e outro nome. A v1 concentra a maior parte das operações; a v2 tem as listagens paginadas e o download com anexos. - **Nome das ferramentas.** Com `--disable-abbreviation true`, cada ferramenta recebe o `operationId` da operação com hifens no lugar dos sublinhados (`partners-v1-accounts-list`, `partners-v2-documents-list`), então os nomes citados nos guias e na referência são reconhecíveis para o agente. Sem a opção, o servidor abrevia os nomes (`partners-v-1-accounts-lst`). O nome mais longo do contrato tem 62 caracteres, abaixo do limite de 64 que a abreviação existe para contornar. A descrição de cada ferramenta é a descrição da operação, e os parâmetros de rota e de consulta viram o schema de entrada, com as descrições da referência. - **Reduza a superfície.** A v1 tem dezenas de operações; um agente trabalha melhor com menos ferramentas. `--tag Documentos` (repetível) limita a um recurso; `--operation get` deixa só consultas, útil para exploração sem risco; `--tools dynamic` troca as ferramentas individuais por três meta-ferramentas (listar operações, ler o schema de uma, invocá-la), que consomem pouco contexto. As tags são as da referência (`Contas`, `Documentos`, `Webhooks` etc.). - **A chave fica no arquivo de configuração** e dá acesso a todas as contas vinculadas ao parceiro. Use uma chave do sandbox enquanto experimenta, e a de produção só em máquina e cliente de confiança. O agente age como o parceiro: criar um documento consome a cota do plano e envia e-mail, SMS ou WhatsApp aos signatários. - **Sem servidor MCP hospedado.** Não há endpoint MCP remoto nem OAuth; o servidor roda na máquina do cliente, com a chave do parceiro. Se isso mudar, o [changelog](https://api.letssign.com.br/docs/guides/changelog) anuncia. ## Formatos para modelos de linguagem Um modelo não precisa executar JavaScript para ler esta documentação: | Arquivo | Conteúdo | |---|---| | `https://api.letssign.com.br/llms.txt` | Índice curto, no formato [llmstxt.org](https://llmstxt.org): resumo da API e links para guias, referências e formatos. | | `https://api.letssign.com.br/llms-full.txt` | O índice seguido de todos os guias e da referência completa das duas versões, em um único Markdown. | | `https://api.letssign.com.br/docs/index.json` | Documentos e guias com título, versão, contagens e a URL de cada formato, para descoberta automática. | | `https://api.letssign.com.br/docs/partners/v1.md`, `https://api.letssign.com.br/docs/partners/v2.md` | A referência de cada versão em Markdown: introdução, autenticação, índice de operações, operações por tag, eventos de webhook e schemas. | As páginas HTML também negociam conteúdo: uma requisição com `Accept: text/markdown` para `https://api.letssign.com.br/docs`, para a página de uma versão ou para um guia recebe o Markdown na mesma URL. Um agente que vai integrar a API deve começar por `llms.txt`, ler o [Quickstart](https://api.letssign.com.br/docs/guides/quickstart) e a referência da versão que vai usar, e consultar o documento OpenAPI para schemas exatos. ## Sandbox Sandbox e produção são ambientes separados, com hosts, contas, parceiros e chaves distintos: uma chave do sandbox não funciona em produção, e vice-versa. Documentos, signatários e webhooks criados no sandbox ficam lá. - **Endereços.** No LetsSign, a API do sandbox está em `https://sandbox.api.letssign.com.br/`, com a documentação em `https://sandbox.api.letssign.com.br/docs`, e o aplicativo em `https://sandbox.app.letssign.com.br/`. Em outros labels, peça os endereços ao suporte. - **Chave.** A chave do sandbox é obtida como a de produção: emitida no cadastro do parceiro pela equipe LetsSign ou gerada pela própria conta na área de integrações do aplicativo do sandbox (a conta precisa da feature `integrations`). Não há chave pública compartilhada: cada parceiro usa a própria. Para conseguir uma conta no sandbox, escreva para atendimento@letssign.com.br. - **Formatos.** Cada host gera a própria documentação, então a coleção Postman e o documento OpenAPI servidos pelo sandbox já apontam para o sandbox; use-os como `baseUrl` e `--api-base-url` ao configurar ferramentas contra ele. - **Comportamento.** O sandbox roda a mesma versão da API, com as mesmas regras de plano, cotas e features. Use signatários com e-mails que você controla: as notificações são enviadas de verdade. ## Como um agente deve operar a API Orientações para um agente (ou para quem escreve o prompt de um) que vai chamar a API: 1. **Descubra antes de agir.** Liste as contas do parceiro (`partners_v1_accounts_list`) e use o `id` devolvido como `accountId`; nunca invente ou reutilize identificadores de outro ambiente. Confira as features da conta (`partners_v1_features_list`) antes de operações que exigem `documents_signatures`, `integrations` ou outras. 2. **Chame pelo `operationId`.** É o nome estável de cada operação em ferramentas, coleção e referência. Quando um endpoint existir na v2, prefira a v2; os obsoletos indicam o substituto na descrição. 3. **Trate `400` e `422` como definitivos.** Repetir a mesma requisição produz o mesmo erro; leia `errors` e `problems` do Problem Details e corrija o payload. `401` é configuração (chave, ambiente, vínculo da conta); `403` é feature ausente no plano. 4. **Criar documento não é idempotente.** Cada `POST` de envio para assinatura cria um documento novo, consome cota e notifica os signatários. Se a resposta se perder, procure o documento (`partners_v2_documents_list`, filtrando por nome e data) antes de repetir. Confirme com quem opera antes de criar, cancelar ou remover algo em produção. 5. **Arquivos vão em base64** dentro do JSON, com o `contentType`; downloads devolvem uma URL temporária, válida por poucos minutos, e não o binário. 6. **Acompanhe por webhook, não por consulta em laço.** Cadastre a URL uma vez (`partners_v1_webhooks_create`) e reaja aos eventos; use a consulta de status só para conferir. 7. **Datas em ISO 8601 com fuso explícito**, identificadores em UUID, enums pelos nomes exatos do schema (`"Email"`, `"WhatsApp"`). 8. **Comece no sandbox.** Só aponte para produção quando o fluxo estiver validado. --- # 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. --- # Changelog > **In English.** Changes to the Partners API contract and to its documentation, most recent first. > Deprecations are announced here and marked as `deprecated` in the OpenAPI documents; deprecated > endpoints keep working with no shutdown date announced. This log starts in September 2026, with > the publication of the OpenAPI contract. Text in Brazilian Portuguese. Este registro começa em setembro de 2026, com a publicação do contrato OpenAPI. Mudanças anteriores a essa data não estão listadas aqui. Para acompanhar: os endpoints obsoletos aparecem como `deprecated` nos documentos OpenAPI ([v1](https://api.letssign.com.br/docs/partners-v1/openapi.json), [v2](https://api.letssign.com.br/docs/partners-v2/openapi.json)) e indicam o substituto na descrição; toda mudança de contrato passa a ser anotada nesta página. ## 2026-09 **Documentação** - Propriedade de enum que aceita nulo passou a listar os valores aceitos na página de referência. Antes ela saía do gerador como `oneOf: [null, $ref]` e o leitor via só "one of: null"; agora a propriedade aponta direto para o enum ou traz os valores e `null` em `type` e `enum`. Os valores aceitos são os mesmos de sempre. - Contrato OpenAPI 3.1 publicado para as duas versões, gerado pela própria API, com `operationId` estável em cada operação (padrão `partners_v{n}_{recurso}_{ação}`), descrições, exemplos de requisição e resposta, enums com o significado de cada valor e as features exigidas em `x-required-features`. - A orientação de descartar com 2xx o evento cujo `event` a integração não trata entrou no guia [Webhooks](https://api.letssign.com.br/docs/guides/webhooks), junto com as páginas dos dois eventos novos. - Os dez eventos de webhook entraram no objeto `webhooks` dos dois documentos, com envelope, payload de exemplo e o contrato de entrega. - Referência em Markdown (`/docs/partners/v1.md`, `/docs/partners/v2.md`), `llms.txt`, `llms-full.txt`, `robots.txt`, `sitemap.xml` e `docs/index.json`, para leitura por ferramentas e modelos de IA. Os guias desta seção. - Rotas antigas da documentação redirecionam com `301`: `/api-docs/**` para `/docs/**` e `/docs/{documento}/swagger.json` para `/docs/{documento}/openapi.json`. - Coleção Postman de cada versão ([v1](https://api.letssign.com.br/docs/partners/v1.postman_collection.json), [v2](https://api.letssign.com.br/docs/partners/v2.postman_collection.json)), gerada do mesmo contrato, com autenticação, variáveis e exemplos prontos, e o guia [Ferramentas e agentes de IA](https://api.letssign.com.br/docs/guides/ferramentas-e-agentes): importação em Postman, Bruno, Insomnia e Hoppscotch, servidor MCP a partir do OpenAPI, sandbox e orientações para agentes. - A descrição de `deadlineForSignature` passou a dizer que somente a data é considerada e que o cancelamento ocorre no decorrer do dia informado, e os exemplos deixaram de sugerir precisão de hora. Ela também orienta a informar a data sem fuso ou em UTC: um offset desloca o instante e pode mudar o dia gravado. O comportamento não mudou: o cancelamento por prazo sempre comparou apenas a data, em horário de Brasília. - `partners_v1_documents_update_groups` e `partners_v1_groups_list` passaram a avisar que o vínculo com grupo desativado não aparece em `groups` nas leituras, mas continua na base: devolver no PUT a lista lida do documento remove esse vínculo em definitivo. O comportamento não mudou; faltava o aviso para quem faz read-modify-write. **Contrato** - `partners_v1_document_signatures_edit_signer` passou a recusar com 400 dois casos que antes aceitava: papel que não existe na conta (`O Papel (X) não existe`) e uso de SMS ou WhatsApp, seja na autenticação ou no envio do link, sem o recurso contratado. A inclusão de signatário já recusava os dois; a edição não, e a diferença deixava a conta usar o canal trocando-o depois que o signatário estava salvo. Integrações que editam signatários com papéis fora da lista de `partners_v1_document_signature_roles_list`, ou que trocam o canal para SMS/WhatsApp sem o recurso, passam a receber 400 onde antes recebiam 204. - Dois eventos de webhook novos para as assinaturas que caem: `DocumentSignaturesExpired`, no vencimento do prazo, com `deadlineForSignature`; e `DocumentSignaturesCanceled`, no cancelamento pedido pela API ou pelo aplicativo. Os dois saem uma vez por envelope, e `documents` traz os documentos atingidos com `pendingSigners`, os signatários que ainda não tinham assinado — informação que o cancelamento apaga do documento e que nenhuma consulta devolve depois. Antes desta mudança o vencimento do prazo não gerava evento algum: só o polling de `partners_v1_document_signatures_status` revelava o cancelamento, e sem distinguir prazo vencido de assinatura nunca configurada. - `partners_v1_document_signatures_cancel`, que não disparava webhook, passa a disparar `DocumentSignaturesCanceled`. `partners_v1_documents_delete` passa a disparar `DocumentRemoved` e, quando o documento estava aguardando assinaturas, `DocumentSignaturesCanceled`. - Correção de documentação: `DocumentRemoved` **não** gera um evento por documento de um envelope excluído, como esta página e a do evento afirmavam. Ele sai uma vez, com o id do envelope; os documentos atingidos vêm no `DocumentSignaturesCanceled` da mesma exclusão, quando o documento estava aguardando assinaturas. - O prazo de assinatura enviado em `deadlineForSignature` passou a ser gravado em `partners_v1_document_signatures_create_from_file`, onde antes era aceito, validado e descartado. Documentos criados por esse endpoint agora respeitam o prazo, inclusive no cancelamento automático das assinaturas quando ele vence. - `partners_v1_document_signatures_cancel` passa a zerar o `deadlineForSignature` do documento, como já faziam os outros caminhos de cancelamento. Depois do cancelamento o campo vem `null` nas consultas que o devolvem; uma nova solicitação por `partners_v1_documents_request_signatures` grava o prazo enviado nela. - As listagens de documentos (`partners_v1_documents_list`, `partners_v2_documents_list`) e a consulta `partners_v1_document_signatures_status` passaram a devolver `deadlineForSignature`. O campo `endDate` continua no contrato, mas é o fim da vigência do documento, não o prazo de assinatura: a descrição dele foi corrigida. - Os filtros `deadlineDateFrom` e `deadlineDateTo` das listagens passaram a filtrar pelo prazo de assinatura, como a descrição já indicava. Na v1, `deadlineDateTo` era ignorado e o intervalo colapsava no dia informado em `deadlineDateFrom`. - Marcados como obsoletos, com substituto na v2: `partners_v1_documents_list`, `partners_v1_categories_list`, `partners_v1_users_list` e `partners_v1_documents_download_with_attachments`. Continuam respondendo; veja [Migração da v1 para a v2](https://api.letssign.com.br/docs/guides/migracao-v1-para-v2). - Documentado o contrato de entrega dos webhooks como ele é hoje: qualquer 2xx em até 20 segundos, até 5 tentativas, sem cabeçalho de assinatura e sem identificador de entrega; `occurredAt` é o instante da tentativa. Evento `Test` enviado só no cadastro da URL. - Documentada a semântica dos erros: `400` para regra de negócio, `422` para payload inválido. - `partners_v1_document_signatures_create_from_file` passa a aceitar `groups`, os grupos de acesso da conta que veem o documento. Campo opcional: omitido, o comportamento é o de antes. Grupo inexistente, inativo ou de outra conta responde `422`; conta sem o recurso de grupos de acesso responde `400`. - Novo `partners_v1_documents_update_groups` (`PUT /documents/{id}/groups`): substitui os grupos de acesso de um documento já criado. Exige o recurso `groups`. - `partners_v1_documents_list` e `partners_v2_documents_list` passam a devolver `groups` em cada documento, no mesmo formato de `categories`. Grupo inativo não entra na lista, para a leitura ficar alinhada ao `partners_v1_groups_list` e aos ids que `partners_v1_documents_update_groups` aceita. - `partners_v1_documents_update_groups` exige o campo `groups` no corpo: requisição sem ele responde `422`. Para remover todos os grupos do documento, envie a lista vazia. - `partners_v1_forms_create` recusa com `422`, citando os ids, a lista `groups` que contenha grupo inexistente, inativo ou de outra conta. Antes bastava um id válido na lista para a validação passar, e o id inválido derrubava a criação com `500`. - A recusa de `groups` passa a dizer `não existe(m) ou está(ão) inativo(s)`, em vez de só `não existe(m)`: o id de um grupo desativado no aplicativo existe, e a mensagem anterior sugeria o contrário. --- # V1 Partners API Versão `v1`. Referência completa em Markdown; o mesmo contrato está em [OpenAPI 3.1 JSON](https://api.letssign.com.br/docs/partners-v1/openapi.json) e em [página navegável](https://api.letssign.com.br/docs/partners/v1). 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 **v1**, que concentra a maior parte dos endpoints. Quatro deles estão obsoletos (as listagens paginadas de documentos, categorias e usuários e o download com anexos) e têm substitutos na [Partners API v2](https://api.letssign.com.br/docs/partners/v2), que compartilha autenticação, contas e formato de erro com esta. Use a v2 sempre que o endpoint existir lá, 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 de contas do parceiro | `GET /partners/v1/accounts` | `partners_v1_accounts_list` | | Alterar logo da conta | `POST /partners/v1/accounts/{id}/change-logo` | `partners_v1_accounts_change_logo` | | Lista de features da conta | `GET /partners/v1/accounts/{accountId}/features` | `partners_v1_features_list` | | Status das assinaturas do documento | `GET /partners/v1/accounts/{accountId}/document-signatures/{documentId}/status` | `partners_v1_document_signatures_status` | | Criação de documento e envio de solicitação de assinaturas | `POST /partners/v1/accounts/{accountId}/document-signatures` | `partners_v1_document_signatures_create_from_file` | | Adicionar signatário no documento | `POST /partners/v1/accounts/{accountId}/document-signatures/{documentId}/signature` | `partners_v1_document_signatures_add_signer` | | Remover signatário do documento | `DELETE /partners/v1/accounts/{accountId}/document-signatures/{documentId}/signature/{signatureId}/remove` | `partners_v1_document_signatures_remove_signer` | | Cancelar assinaturas do documento e remover signatários | `PATCH /partners/v1/accounts/{accountId}/document-signatures/{documentId}/cancel` | `partners_v1_document_signatures_cancel` | | Reenviar solicitação de assinatura para os signatários | `POST /partners/v1/accounts/{accountId}/document-signatures/{documentId}/signature/{signatureId}/resend` | `partners_v1_document_signatures_resend` | | Edita um signatário do documento | `PUT /partners/v1/accounts/{accountId}/document-signatures/{documentId}/signature/{signatureId}` | `partners_v1_document_signatures_edit_signer` | | Lista paginada de documentos da conta (obsoleta) | `GET /partners/v1/accounts/{accountId}/documents` | `partners_v1_documents_list` | | Listagem do mapeamento das assinaturas do documento | `GET /partners/v1/accounts/{accountId}/documents/{id}/mapped-signatures` | `partners_v1_documents_mapped_signatures` | | Info para download do documento original | `GET /partners/v1/accounts/{accountId}/documents/{id}/download/original` | `partners_v1_documents_download_original` | | Info para download do documento com anexos (obsoleta) | `GET /partners/v1/accounts/{accountId}/documents/{id}/download/with-atachments` | `partners_v1_documents_download_with_attachments` | | Info para download do documento assinado | `GET /partners/v1/accounts/{accountId}/documents/{id}/download/signed` | `partners_v1_documents_download_signed` | | Info para download do documento com certificado digital | `GET /partners/v1/accounts/{accountId}/documents/{id}/download/digital-certificate` | `partners_v1_documents_download_digital_certificate` | | Envio de solicitação de assinaturas para um documento existente | `POST /partners/v1/accounts/{accountId}/documents/{id}/request-signatures` | `partners_v1_documents_request_signatures` | | Lista campos de informações do documento | `GET /partners/v1/accounts/{accountId}/documents/{id}/informations` | `partners_v1_documents_informations_list` | | Adiciona/atualiza campo de informação no documento | `POST /partners/v1/accounts/{accountId}/documents/{id}/informations` | `partners_v1_documents_informations_upsert` | | Remove campo de informação no documento | `DELETE /partners/v1/accounts/{accountId}/documents/{id}/informations/{informationFieldId}` | `partners_v1_documents_informations_delete` | | Remove um documento | `DELETE /partners/v1/accounts/{accountId}/documents/{id}` | `partners_v1_documents_delete` | | Lista campos do formulário do documento | `GET /partners/v1/accounts/{accountId}/documents/{id}/form-fields` | `partners_v1_documents_form_fields_list` | | Atualiza os métodos de autenticação adicionais dos signatários do documento | `PUT /partners/v1/accounts/{accountId}/documents/{id}/signatures/additional-authentication-methods` | `partners_v1_documents_update_additional_authentication_methods` | | Altera pasta de um documento | `PUT /partners/v1/accounts/{accountId}/documents/{id}/folder` | `partners_v1_documents_change_folder` | | Substitui os grupos de acesso do documento | `PUT /partners/v1/accounts/{accountId}/documents/{id}/groups` | `partners_v1_documents_update_groups` | | Lista de webhooks da conta | `GET /partners/v1/accounts/{accountId}/webhooks` | `partners_v1_webhooks_list` | | Adicionar webhook na conta | `POST /partners/v1/accounts/{accountId}/webhooks` | `partners_v1_webhooks_create` | | Remover webhook da conta | `DELETE /partners/v1/accounts/{accountId}/webhooks/{id}` | `partners_v1_webhooks_delete` | | Lista pastas da conta | `GET /partners/v1/accounts/{accountId}/folders` | `partners_v1_folders_list` | | Cria uma pasta na Conta | `POST /partners/v1/accounts/{accountId}/folders` | `partners_v1_folders_create` | | Lista paginada de categorias da conta (obsoleta) | `GET /partners/v1/accounts/{accountId}/categories` | `partners_v1_categories_list` | | Adicionar categoria na conta | `POST /partners/v1/accounts/{accountId}/categories` | `partners_v1_categories_create` | | Busca categoria da conta por id | `GET /partners/v1/accounts/{accountId}/categories/{id}` | `partners_v1_categories_get` | | Editar categoria da conta | `PUT /partners/v1/accounts/{accountId}/categories/{id}` | `partners_v1_categories_update` | | Remover categoria da conta | `DELETE /partners/v1/accounts/{accountId}/categories/{id}` | `partners_v1_categories_delete` | | Alterar status da categoria da conta | `PATCH /partners/v1/accounts/{accountId}/categories/{id}/change-status` | `partners_v1_categories_change_status` | | Buscar pessoa por cpf | `GET /partners/v1/accounts/{accountId}/contacts/person/{cpf}` | `partners_v1_contacts_get_person` | | Cria ou atualiza uma pessoa | `POST /partners/v1/accounts/{accountId}/contacts/person` | `partners_v1_contacts_upsert_person` | | Buscar empresa por CNPJ | `GET /partners/v1/accounts/{accountId}/contacts/company/{cnpj}` | `partners_v1_contacts_get_company` | | Cria ou atualiza uma Empresa | `POST /partners/v1/accounts/{accountId}/contacts/company` | `partners_v1_contacts_upsert_company` | | Remove um contato por CPF ou CNPJ | `DELETE /partners/v1/accounts/{accountId}/contacts/{cpfOrCnpj}` | `partners_v1_contacts_delete` | | Lista paginada de usuários da conta (obsoleta) | `GET /partners/v1/accounts/{accountId}/users` | `partners_v1_users_list` | | Adicionar usuários na conta | `POST /partners/v1/accounts/{accountId}/users` | `partners_v1_users_add` | | Alterar status de um usuário da conta | `PATCH /partners/v1/accounts/{accountId}/users/{id}/change-status` | `partners_v1_users_change_status` | | Lista grupos da conta | `GET /partners/v1/accounts/{accountId}/groups` | `partners_v1_groups_list` | | Lista de papéis de signatários (Assinar como) | `GET /partners/v1/accounts/{accountId}/document-signature-roles` | `partners_v1_document_signature_roles_list` | | Lista campos de informação | `GET /partners/v1/accounts/{accountId}/information-fields` | `partners_v1_information_fields_list` | | Lista modelos de formulários da conta | `GET /partners/v1/accounts/{accountId}/form-templates` | `partners_v1_form_templates_list` | | Criação de formulários da conta | `POST /partners/v1/accounts/{accountId}/forms` | `partners_v1_forms_create` | | Lista de planos vínculados ao parceiro | `GET /partners/v1/plans` | `partners_v1_plans_list` | ## Endpoints ### Accounts Contas operadas pelo parceiro. Todo o restante da API é escopado por `accountId`; comece aqui para obter os identificadores. #### Lista de contas do parceiro `GET /partners/v1/accounts` - operationId: `partners_v1_accounts_list` - Autenticação: `ApiKey` Lista as contas ativas que o parceiro pode operar com esta chave. É o ponto de partida da integração: o `id` de cada conta é o `accountId` exigido nas demais rotas. - Só entram contas ativas e vinculadas ao parceiro; a ordem é alfabética por `name`. - Não há paginação: a lista vem completa. - Não exige feature de plano, apenas a chave válida. - Somente leitura, sem efeitos colaterais. **Respostas** | Status | Descrição | Corpo | | --- | --- | --- | | `200` | OK | [PartnerAccountDto](#partneraccountdto)[] (`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 [ { "id": "0199143a-7c2e-7b1a-9f2d-3c4b5a6d7e8f", "name": "Imobiliária Horizonte", "companyName": "Horizonte Negócios Imobiliários Ltda", "createdAt": "2025-03-12T13:45:10Z", "isTrial": false, "initDate": "2025-03-12T00:00:00Z", "personType": "Company", "documentNumber": "12345678000195", "active": true } ] ``` #### Alterar logo da conta `POST /partners/v1/accounts/{id}/change-logo` - operationId: `partners_v1_accounts_change_logo` - Autenticação: `ApiKey` Substitui o logotipo da conta, exibido nos e-mails enviados aos signatários e na página de assinatura. A imagem vai em base64 no campo `contentFile`, com o tipo MIME em `contentType`. - Formatos aceitos: PNG, JPG e JPEG. Não há limite próprio de tamanho além dos 70 MB do corpo. - Sobrescreve o logotipo anterior; repetir a chamada com a mesma imagem não tem efeito extra. - A URL devolvida em `logo` traz um parâmetro `q` que muda a cada troca, para invalidar caches. - A troca fica registrada na auditoria da conta. Não exige feature de plano. - Erros `400`: `Conta não existe`, `Parceiro não pode realizar operações na conta solicitada`, `Não foi possível armazenar o logo`. **Parâmetros** | Nome | Em | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | --- | | `id` | path | string (uuid) | sim | Identificador da conta. Obtenha a lista em `partners_v1_accounts_list`. | **Corpo da requisição** (`application/json`, obrigatório) Schema: [ChangePartnerAccountLogo](#changepartneraccountlogo) ```json { "contentType": "image/png", "contentFile": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==" } ``` **Respostas** | Status | Descrição | Corpo | | --- | --- | --- | | `200` | OK | [PartnerAccountLogoDto](#partneraccountlogodto) (`application/json`) | | `400` | Regra de negócio não satisfeita: recurso inexistente na conta, estado que não permite a operação, recurso do plano ausente ou cota atingida. O corpo (`ProblemDetailsResult`) traz as mensagens em `errors`. | [ProblemDetailsResult](#problemdetailsresult) (`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 | | `422` | Payload rejeitado: JSON malformado ou campos que não passaram na validação (obrigatórios, tamanhos, formatos, combinações). O corpo (`ProblemDetailsResult`) traz as mensagens em `errors` e, em `problems`, cada mensagem com o campo (`propertyName`). | [ProblemDetailsResult](#problemdetailsresult) (`application/json`) | Exemplo de resposta `200`: ```json { "logo": "https://storage.exemplo.com.br/logos/0199143a-7c2e-7b1a-9f2d-3c4b5a6d7e8f.png?q=638923456789012345" } ``` ### Features Funcionalidades liberadas pelo plano de cada conta. Operações exigem features específicas e respondem 403 sem elas. #### Lista de features da conta `GET /partners/v1/accounts/{accountId}/features` - operationId: `partners_v1_features_list` - Autenticação: `ApiKey` Lista as features do plano vigente da conta. Cada item traz o `id` (o código que aparece em `x-required-features` e na descrição das operações) e uma descrição legível. - Consulte antes de chamar operações que exigem features: sem elas a resposta é `403`. - As features vêm do plano do grupo de faturamento da conta; a lista muda quando o plano muda. - Ordem alfabética por `description`. Não há paginação. - Somente leitura, sem efeitos colaterais. **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`. | **Respostas** | Status | Descrição | Corpo | | --- | --- | --- | | `200` | OK | [FeatureSimplifiedDto](#featuresimplifieddto)[] (`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 [ { "id": "categories", "description": "Categorias" }, { "id": "contacts", "description": "Contatos" }, { "id": "documents", "description": "Documentos" }, { "id": "documents_signatures", "description": "Assinatura de documentos" }, { "id": "integrations", "description": "Integrações" } ] ``` ### DocumentSignatures Fluxo de assinatura: criar documento a partir de arquivo e solicitar assinaturas, acompanhar o status, adicionar, editar, remover e reenviar signatários, cancelar. #### Status das assinaturas do documento `GET /partners/v1/accounts/{accountId}/document-signatures/{documentId}/status` - operationId: `partners_v1_document_signatures_status` - Autenticação: `ApiKey` Situação atual das assinaturas de um documento: o status geral em `signatureStatusId` e um item por signatário em `signatures`, com `signed`, `signedAt` e os dados informados no ato da assinatura (`name`, `documentNumber`, `birthDate`). - `signatures[].id` é o `signatureId` usado para editar, remover e reenviar a solicitação. - `order` mostra a posição na ordenação quando o documento é ordenado. - Responde `404` quando o documento não pertence à conta. - Prefira os webhooks `DocumentSignatureMember` e `DocumentSignatureFinished` para acompanhar; use esta consulta para conferir ou quando não houver webhook. - Somente leitura, sem efeitos colaterais. **Features exigidas no plano da conta:** `documents`, `documents_signatures`. **Parâmetros** | Nome | Em | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | --- | | `documentId` | 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 | [DocumentSignaturesStatusDto](#documentsignaturesstatusdto) (`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`, `documents_signatures`. | sem corpo | | `404` | Recurso não encontrado na conta informada. | sem corpo | Exemplo de resposta `200`: ```json { "signatureStatusId": "WaitingSignatures", "signatureStatus": "Aguardando assinaturas", "deadlineForSignature": "2026-09-30T12:00:00Z", "signatures": [ { "id": "01991441-0a1b-7c2d-8e3f-4a5b6c7d8e9f", "email": "maria.silva@exemplo.com.br", "role": "Parte", "signed": true, "authenticationMethod": "Email", "signatureLinkMethod": "Email", "telephone": { "countryCode": "55", "number": "11987654321", "value": "5511987654321", "formatted": "+55 (11) 9-8765-4321" }, "name": "Maria da Silva", "documentNumberType": "Cpf", "documentNumber": "11144477735", "birthDate": "1988-05-17T00:00:00Z", "handwritten": true, "order": 1, "signedAt": "2026-08-21T10:12:45Z", "requireDocumentNumber": true }, { "id": "01991441-9f8e-7d6c-8b5a-4c3d2e1f0a9b", "email": "joao.souza@exemplo.com.br", "role": "Testemunha", "signed": false, "authenticationMethod": "Email", "handwritten": true, "order": 2, "requireDocumentNumber": true } ] } ``` #### Criação de documento e envio de solicitação de assinaturas `POST /partners/v1/accounts/{accountId}/document-signatures` - operationId: `partners_v1_document_signatures_create_from_file` - Autenticação: `ApiKey` Cria um documento a partir de um arquivo e envia a solicitação de assinatura a todos os signatários em uma única chamada. É a operação principal da API. **Como montar a requisição** - `contentFile` leva o arquivo em base64 e `contentType` o tipo MIME correspondente. PDF é usado como está; DOC e DOCX são convertidos para PDF. PDF com senha ou com edição bloqueada é recusado. - `signers` precisa de ao menos um item com `email` e `role`. Cada signatário pode ter método de autenticação, canal do link, telefone, evidências adicionais, suplentes e idioma próprios. - `signatureAreas` posiciona assinatura e rubrica no PDF por página e coordenadas em percentual; cada área aponta para um signatário por `email`, `role` e `authenticationMethod`. A página deve existir no arquivo. Contas configuradas para exigir posicionamento recusam a chamada sem áreas. - `order` nos signatários cria a assinatura sequencial: informe para todos ou para nenhum. - `scheduledTo` agenda o envio; `deadlineForSignature` define o prazo; `reminderFrequency` liga os lembretes automáticos por e-mail (até 3 por signatário). - `categories` desconhecidas são ignoradas; `folderId` inexistente responde `400`. - `groups` define quais grupos de acesso da conta veem o documento (`partners_v1_groups_list`). Diferente de `categories`, id desconhecido não é ignorado: grupo inexistente, inativo ou de outra conta responde `422` citando os ids recusados. Grupos do documento e da pasta são condições cumulativas — só vê o documento quem está nos dois. Sem `groups`, o acesso é decidido pelos grupos da pasta; fora de pasta, o documento fica visível para toda a conta. Depois da criação, use `partners_v1_documents_update_groups`. **O que acontece** - O documento nasce com status `Finished` e status de assinatura `WaitingSignatures` (ou `SignaturesDeliveryScheduled` quando agendado). - O webhook `DocumentSentToSignature` é disparado na criação, mesmo com agendamento. - Os signatários recebem o link pelo canal configurado (e-mail, SMS ou WhatsApp); com ordenação, só a primeira posição é notificada. Observadores recebem o documento assinado ao final. - Signatários com `saveAsContact` verdadeiro, nome e CPF válido viram contatos da conta quando o plano tem a feature `contacts`. - Consome um documento da cota do plano e, quando há SMS ou WhatsApp, a cota desses canais. **Regras que respondem `400`** - Papel inexistente na conta: `Um ou mais papéis (...) não existe(m)`. Consulte `partners_v1_document_signature_roles_list`. - Conta sem o recurso de SMS, WhatsApp, biometria facial, informações do documento ou grupos de acesso. - Cota de documentos, SMS ou WhatsApp esgotada. - Áreas em páginas que o arquivo não tem; pasta inexistente. Não há chave de idempotência: cada chamada cria um documento novo. A resposta traz o `id` do documento e a URL da página dele no aplicativo. **Features exigidas no plano da conta:** `documents`, `documents_signatures`. **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`. | **Corpo da requisição** (`application/json`, obrigatório) Schema: [CreateDocumentWithSignaturesFromFile](#createdocumentwithsignaturesfromfile) ```json { "documentName": "Contrato de locação - Apto 501", "contentType": "application/pdf", "contentFile": "JVBERi0xLjcKJcTl8uXrp/Og0MTGCjEgMCBvYmoKPDwgL1R5cGUgL0NhdGFsb2cgPj4KZW5kb2JqCg==", "folderId": "0199143c-2e3f-7a4b-9c5d-6e7f8a9b0c1d", "categories": [ "0199143b-1d2e-7f3a-8b4c-5d6e7f8a9b0c" ], "groups": [ "0199143d-3f40-7b5c-8d6e-7f8a9b0c1d2e" ], "customMessage": "Olá! Segue o contrato de locação do apartamento 501 para assinatura até 30/09.", "deadlineForSignature": "2026-09-30T12:00:00Z", "reminderFrequency": "ThreeDays", "observers": [ "financeiro@exemplo.com.br" ], "signers": [ { "email": "maria.silva@exemplo.com.br", "name": "Maria da Silva", "documentNumber": "11144477735", "role": "Parte", "order": 1, "authenticationMethod": "Email", "telephoneCountryCode": "55", "telephone": "11987654321", "additionalAuthenticationMethods": [ "DocumentIdWithPhoto" ], "language": "Portuguese", "saveAsContact": true }, { "email": "joao.souza@exemplo.com.br", "name": "João de Souza", "role": "Testemunha", "order": 2, "authenticationMethod": "Email", "substitutes": [ { "email": "carla.mendes@exemplo.com.br", "name": "Carla Mendes" } ] } ], "signatureAreas": [ { "type": "Signature", "page": 3, "x": 12.5, "y": 78, "width": 15, "height": 5, "email": "maria.silva@exemplo.com.br", "role": "Parte", "authenticationMethod": "Email" }, { "type": "Initials", "page": 1, "x": 85, "y": 92, "width": 6, "height": 4, "email": "maria.silva@exemplo.com.br", "role": "Parte", "authenticationMethod": "Email" }, { "type": "Signature", "page": 3, "x": 55, "y": 78, "width": 15, "height": 5, "email": "joao.souza@exemplo.com.br", "role": "Testemunha", "authenticationMethod": "Email" } ], "informations": [ { "informationFieldId": "0199143d-3f4a-7b5c-8d6e-7f8a9b0c1d2e", "value": "CT-2026-0451" } ] } ``` **Respostas** | Status | Descrição | Corpo | | --- | --- | --- | | `201` | Created | [CreatedDocumentInfoDto](#createddocumentinfodto) (`application/json`) | | `400` | Regra de negócio não satisfeita: recurso inexistente na conta, estado que não permite a operação, recurso do plano ausente ou cota atingida. O corpo (`ProblemDetailsResult`) traz as mensagens em `errors`. | [ProblemDetailsResult](#problemdetailsresult) (`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`, `documents_signatures`. | sem corpo | | `422` | Payload rejeitado: JSON malformado ou campos que não passaram na validação (obrigatórios, tamanhos, formatos, combinações). O corpo (`ProblemDetailsResult`) traz as mensagens em `errors` e, em `problems`, cada mensagem com o campo (`propertyName`). | [ProblemDetailsResult](#problemdetailsresult) (`application/json`) | Exemplo de resposta `201`: ```json { "id": "01991440-5a6b-7c8d-9e0f-1a2b3c4d5e6f", "uri": "https://app.letssign.com.br/app/documents/01991440-5a6b-7c8d-9e0f-1a2b3c4d5e6f/signatures" } ``` #### Adicionar signatário no documento `POST /partners/v1/accounts/{accountId}/document-signatures/{documentId}/signature` - operationId: `partners_v1_document_signatures_add_signer` - Autenticação: `ApiKey` Adiciona um signatário a um documento que já está aguardando assinaturas e envia a ele o link de assinatura. - Exige status de assinatura `WaitingSignatures` e status do documento diferente de `WaitingFormFill`; fora disso responde `400`. - A combinação `email` + `role` não pode existir no documento; o mesmo e-mail com outro papel é aceito. - Em documentos ordenados, o novo signatário entra na última posição e só é notificado quando chegar a vez dele. - Se algum signatário já assinou com certificado digital, a inclusão é recusada, pois invalidaria a assinatura existente. - `additionalAuthenticationMethods` não é aplicado nesta operação; use `partners_v1_documents_update_additional_authentication_methods` em seguida. - Dispara o webhook `SignerAddedToDocument`. Nada é enviado quando `signatureLinkMethod` é `NotSend`. - A resposta traz o `id` da assinatura (`signatureId`). **Features exigidas no plano da conta:** `documents`, `documents_signatures`. **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` | path | string (uuid) | sim | Identificador do documento, devolvido na criação (`id`) e nas listagens. | **Corpo da requisição** (`application/json`, obrigatório) Schema: [AddSigner](#addsigner) ```json { "email": "carlos.lima@exemplo.com.br", "name": "Carlos Lima", "documentNumber": "52998224725", "role": "Testemunha", "authenticationMethod": "Sms", "telephoneCountryCode": "55", "telephone": "21998765432", "signatureLinkMethod": "Sms", "language": "Portuguese", "signatureAreas": [ { "type": "Signature", "page": 3, "x": 55, "y": 88, "width": 15, "height": 5 } ] } ``` **Respostas** | Status | Descrição | Corpo | | --- | --- | --- | | `200` | OK | [SignerAddedDto](#signeraddeddto) (`application/json`) | | `400` | Regra de negócio não satisfeita: recurso inexistente na conta, estado que não permite a operação, recurso do plano ausente ou cota atingida. O corpo (`ProblemDetailsResult`) traz as mensagens em `errors`. | [ProblemDetailsResult](#problemdetailsresult) (`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`, `documents_signatures`. | sem corpo | | `422` | Payload rejeitado: JSON malformado ou campos que não passaram na validação (obrigatórios, tamanhos, formatos, combinações). O corpo (`ProblemDetailsResult`) traz as mensagens em `errors` e, em `problems`, cada mensagem com o campo (`propertyName`). | [ProblemDetailsResult](#problemdetailsresult) (`application/json`) | Exemplo de resposta `200`: ```json { "id": "01991449-d3e4-7f5a-8b6c-7d8e9f0a1b2c" } ``` #### Remover signatário do documento `DELETE /partners/v1/accounts/{accountId}/document-signatures/{documentId}/signature/{signatureId}/remove` - operationId: `partners_v1_document_signatures_remove_signer` - Autenticação: `ApiKey` Remove um signatário que ainda não assinou. As demais assinaturas permanecem. - Responde `400` se o signatário já assinou (`Signatário não pode ser removido pois já assinou o documento`) ou não existe. - Em documentos ordenados, as posições seguintes são reordenadas; se o removido era o da vez, o próximo é notificado. - Se após a remoção todos os restantes já tiverem assinado, o documento é finalizado. - A remoção fica na trilha de auditoria do documento. Não envia e-mail ao removido nem webhook. - Repetir a chamada responde `400` (`Signatário não existe`). **Features exigidas no plano da conta:** `documents`, `documents_signatures`. **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` | path | string (uuid) | sim | Identificador do documento, devolvido na criação (`id`) e nas listagens. | | `signatureId` | path | string (uuid) | sim | Identificador da assinatura (o signatário dentro do documento). Aparece em `signatures[].id` de `partners_v1_document_signatures_status` e no retorno de `partners_v1_document_signatures_add_signer`. | **Respostas** | Status | Descrição | Corpo | | --- | --- | --- | | `204` | No Content | sem corpo | | `400` | Regra de negócio não satisfeita: recurso inexistente na conta, estado que não permite a operação, recurso do plano ausente ou cota atingida. O corpo (`ProblemDetailsResult`) traz as mensagens em `errors`. | [ProblemDetailsResult](#problemdetailsresult) (`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`, `documents_signatures`. | sem corpo | | `422` | Payload rejeitado: JSON malformado ou campos que não passaram na validação (obrigatórios, tamanhos, formatos, combinações). O corpo (`ProblemDetailsResult`) traz as mensagens em `errors` e, em `problems`, cada mensagem com o campo (`propertyName`). | [ProblemDetailsResult](#problemdetailsresult) (`application/json`) | #### Cancelar assinaturas do documento e remover signatários `PATCH /partners/v1/accounts/{accountId}/document-signatures/{documentId}/cancel` - operationId: `partners_v1_document_signatures_cancel` - Autenticação: `ApiKey` Cancela a solicitação de assinaturas em andamento: remove todos os signatários, apaga a trilha de eventos de assinatura e volta o status de assinatura para `SignatureNotSet`. O documento continua na conta e pode receber uma nova solicitação com `partners_v1_documents_request_signatures`. - Exige status de assinatura `WaitingSignatures`; fora disso responde `400`. - Envia e-mail de cancelamento a todos os signatários e suplentes; `message` entra nesse e-mail. - Assinaturas já realizadas são descartadas junto com o arquivo assinado digitalmente. - Dispara o webhook `DocumentSignaturesCanceled`. Cancela apenas o documento informado: em um envelope, os demais seguem aguardando assinaturas. - Para excluir o documento, use `partners_v1_documents_delete`. **Features exigidas no plano da conta:** `documents`, `documents_signatures`. **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` | path | string (uuid) | sim | Identificador do documento, devolvido na criação (`id`) e nas listagens. | **Corpo da requisição** (`application/json`, obrigatório) Schema: [CancelSignatures](#cancelsignatures) ```json { "message": "Contrato substituído por uma nova versão; desconsidere esta solicitação." } ``` **Respostas** | Status | Descrição | Corpo | | --- | --- | --- | | `204` | No Content | sem corpo | | `400` | Regra de negócio não satisfeita: recurso inexistente na conta, estado que não permite a operação, recurso do plano ausente ou cota atingida. O corpo (`ProblemDetailsResult`) traz as mensagens em `errors`. | [ProblemDetailsResult](#problemdetailsresult) (`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`, `documents_signatures`. | sem corpo | | `422` | Payload rejeitado: JSON malformado ou campos que não passaram na validação (obrigatórios, tamanhos, formatos, combinações). O corpo (`ProblemDetailsResult`) traz as mensagens em `errors` e, em `problems`, cada mensagem com o campo (`propertyName`). | [ProblemDetailsResult](#problemdetailsresult) (`application/json`) | #### Reenviar solicitação de assinatura para os signatários `POST /partners/v1/accounts/{accountId}/document-signatures/{documentId}/signature/{signatureId}/resend` - operationId: `partners_v1_document_signatures_resend` - Autenticação: `ApiKey` Reenvia a solicitação de assinatura a um signatário pelo canal configurado para ele (`signatureLinkMethod` ou, na falta dele, o canal do método de autenticação). - Exige documento em `WaitingSignatures`, signatário ainda não assinado e, em documentos ordenados, que seja a vez dele; caso contrário responde `400`. - Consome cota de SMS ou WhatsApp quando o canal for um desses. Suplentes não são notificados. - Sem efeito quando o canal do signatário é `NotSend`. - Pode ser repetida à vontade: cada chamada gera um novo envio. **Features exigidas no plano da conta:** `documents`, `documents_signatures`. **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` | path | string (uuid) | sim | Identificador do documento, devolvido na criação (`id`) e nas listagens. | | `signatureId` | path | string (uuid) | sim | Identificador da assinatura (o signatário dentro do documento). Aparece em `signatures[].id` de `partners_v1_document_signatures_status` e no retorno de `partners_v1_document_signatures_add_signer`. | **Respostas** | Status | Descrição | Corpo | | --- | --- | --- | | `204` | No Content | sem corpo | | `400` | Regra de negócio não satisfeita: recurso inexistente na conta, estado que não permite a operação, recurso do plano ausente ou cota atingida. O corpo (`ProblemDetailsResult`) traz as mensagens em `errors`. | [ProblemDetailsResult](#problemdetailsresult) (`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`, `documents_signatures`. | sem corpo | | `422` | Payload rejeitado: JSON malformado ou campos que não passaram na validação (obrigatórios, tamanhos, formatos, combinações). O corpo (`ProblemDetailsResult`) traz as mensagens em `errors` e, em `problems`, cada mensagem com o campo (`propertyName`). | [ProblemDetailsResult](#problemdetailsresult) (`application/json`) | #### Edita um signatário do documento `PUT /partners/v1/accounts/{accountId}/document-signatures/{documentId}/signature/{signatureId}` - operationId: `partners_v1_document_signatures_edit_signer` - Autenticação: `ApiKey` Atualiza os dados de um signatário que ainda não assinou: e-mail, nome, CPF, papel, método de autenticação, telefones, canal do link, idioma e evidências adicionais. Os campos enviados substituem os gravados por completo. - Responde `400` se o signatário já assinou ou se já existe outro com o mesmo e-mail, papel e método de autenticação. Documentos que fazem parte de um envelope não podem ser editados aqui. - `additionalAuthenticationMethods` omitido apaga as evidências adicionais existentes; envie a lista completa desejada. - `substitutes` não é considerado nesta operação. - Com `resendLinkAfterEdit` verdadeiro, o link é reenviado ao signatário pelo canal atualizado. - A edição fica na trilha de auditoria. Não dispara webhook. Repetir com os mesmos dados é seguro. **Features exigidas no plano da conta:** `documents`, `documents_signatures`. **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` | path | string (uuid) | sim | Identificador do documento, devolvido na criação (`id`) e nas listagens. | | `signatureId` | path | string (uuid) | sim | Identificador da assinatura (o signatário dentro do documento). Aparece em `signatures[].id` de `partners_v1_document_signatures_status` e no retorno de `partners_v1_document_signatures_add_signer`. | **Corpo da requisição** (`application/json`, obrigatório) Schema: [EditSigner](#editsigner) ```json { "email": "maria.silva@exemplo.com.br", "name": "Maria da Silva Santos", "documentNumber": "11144477735", "role": "Parte", "authenticationMethod": "WhatsApp", "telephoneCountryCode": "55", "telephone": "11987654321", "signatureLinkMethod": "WhatsApp", "additionalAuthenticationMethods": [ "DocumentIdWithPhoto" ], "requireDocumentNumber": true, "language": "Portuguese", "resendLinkAfterEdit": true } ``` **Respostas** | Status | Descrição | Corpo | | --- | --- | --- | | `204` | No Content | sem corpo | | `400` | Regra de negócio não satisfeita: recurso inexistente na conta, estado que não permite a operação, recurso do plano ausente ou cota atingida. O corpo (`ProblemDetailsResult`) traz as mensagens em `errors`. | [ProblemDetailsResult](#problemdetailsresult) (`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`, `documents_signatures`. | sem corpo | | `422` | Payload rejeitado: JSON malformado ou campos que não passaram na validação (obrigatórios, tamanhos, formatos, combinações). O corpo (`ProblemDetailsResult`) traz as mensagens em `errors` e, em `problems`, cada mensagem com o campo (`propertyName`). | [ProblemDetailsResult](#problemdetailsresult) (`application/json`) | ### 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/v1/accounts/{accountId}/documents` - operationId: `partners_v1_documents_list` - Autenticação: `ApiKey` - Situação: obsoleta (`deprecated`); a descrição indica o substituto **Obsoleto.** Substituído por `partners_v2_documents_list` na [Partners API v2](https://api.letssign.com.br/docs/partners/v2), que tem paginação por `page`/`perPage`, filtro por data de criação e ordenação declarada. Continua respondendo, mas não recebe evolução. Lista os documentos da conta com os filtros informados, paginada por `pageIndex` e `pageSize`. 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 | ID do documento | | `Name` | query | string | não | Nome do documento contendo... | | `DeadlineDateFrom` | query | string (date) | não | Prazo do documento a partir de... | | `DeadlineDateTo` | query | string (date) | não | Prazo do documento até... | | `SignatureDateFrom` | query | string (date) | não | Data de assinatura do documento de... | | `SignatureDateTo` | query | string (date) | não | Data de assinatura do documento até... | | `Categories` | query | string (uuid)[] | não | Categorias do documento | | `DocumentStatus` | query | [EDocumentStatus](#edocumentstatus)[] | não | Status do documento | | `DocumentSignatureStatus` | query | [EDocumentSignatureStatus](#edocumentsignaturestatus)[] | não | Status de assinatura do documento | | `pageIndex` | query | integer (int32) | sim | Número da página, a partir de 1. Padrão: `1`. | | `pageSize` | query | integer (int32) | sim | Quantidade de itens por página. Padrão: `20`. | | `sortField` | query | string | sim | Campo de ordenação. Padrão: `"Id"`. | | `sortType` | query | `"asc"` \| `"desc"` | sim | Sentido da ordenação: `asc` ou `desc`. Padrão: `"asc"`. | **Respostas** | Status | Descrição | Corpo | | --- | --- | --- | | `200` | OK | [PagedListDeprecatedOfDocumentDto](#pagedlistdeprecatedofdocumentdto) (`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" } ], "totalPages": 3, "totalRecords": 48, "pageSize": 20 } ``` #### Listagem do mapeamento das assinaturas do documento `GET /partners/v1/accounts/{accountId}/documents/{id}/mapped-signatures` - operationId: `partners_v1_documents_mapped_signatures` - Autenticação: `ApiKey` Lista as posições de assinatura e rubrica mapeadas no documento: página, coordenadas e tamanho em percentual, e o signatário dono de cada posição (`email`, `role`, `authenticationMethod`, `documentSignatureId`). - Retorna lista vazia quando nenhuma posição foi informada. - Útil para conferir o posicionamento antes de os signatários assinarem. - Somente leitura, sem efeitos colaterais. **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 | [DocumentSignatureAreaDto](#documentsignatureareadto)[] (`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 [ { "id": "01991448-c2d3-7e4f-9a5b-6c7d8e9f0a1b", "type": "Signature", "typeDescription": "Assinatura", "x": 12.5, "y": 78, "height": 5, "width": 15, "page": 3, "documentSignatureId": "01991441-0a1b-7c2d-8e3f-4a5b6c7d8e9f", "email": "maria.silva@exemplo.com.br", "role": "Parte", "authenticationMethod": "Email", "authenticationMethodDescription": "E-mail" }, { "id": "01991448-c2d3-7e4f-9a5b-6c7d8e9f0a1c", "type": "Initials", "typeDescription": "Rúbrica", "x": 85, "y": 92, "height": 4, "width": 6, "page": 1, "documentSignatureId": "01991441-0a1b-7c2d-8e3f-4a5b6c7d8e9f", "email": "maria.silva@exemplo.com.br", "role": "Parte", "authenticationMethod": "Email", "authenticationMethodDescription": "E-mail" }, { "id": "01991448-c2d3-7e4f-9a5b-6c7d8e9f0a1d", "type": "Signature", "typeDescription": "Assinatura", "x": 55, "y": 78, "height": 5, "width": 15, "page": 3, "documentSignatureId": "01991441-9f8e-7d6c-8b5a-4c3d2e1f0a9b", "email": "joao.souza@exemplo.com.br", "role": "Testemunha", "authenticationMethod": "Email", "authenticationMethodDescription": "E-mail" } ] ``` #### Info para download do documento original `GET /partners/v1/accounts/{accountId}/documents/{id}/download/original` - operationId: `partners_v1_documents_download_original` - Autenticação: `ApiKey` Devolve uma URL temporária para baixar o arquivo original do documento, em PDF, sem assinaturas. - A URL é pré-assinada e vale por 5 minutos; faça o download logo após obtê-la. Cada chamada gera uma URL nova. - `name` é o nome do documento, sem extensão. - Responde `400` quando o documento não existe na conta ou ainda não tem arquivo disponível. **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.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=300&X-Amz-Signature=3f9c0a1b2c3d4e5f" } ``` #### Info para download do documento com anexos `GET /partners/v1/accounts/{accountId}/documents/{id}/download/with-atachments` - operationId: `partners_v1_documents_download_with_attachments` - Autenticação: `ApiKey` - Situação: obsoleta (`deprecated`); a descrição indica o substituto **Obsoleto.** Substituído por `partners_v2_documents_download_with_attachments` na [Partners API v2](https://api.letssign.com.br/docs/partners/v2), que corrige a grafia da rota. Continua respondendo, mas não recebe evolução. Devolve uma URL temporária (5 minutos) para o PDF do documento com os anexos incorporados; sem anexos, devolve o arquivo original. **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" } ``` #### Info para download do documento assinado `GET /partners/v1/accounts/{accountId}/documents/{id}/download/signed` - operationId: `partners_v1_documents_download_signed` - Autenticação: `ApiKey` Devolve uma URL temporária para baixar o PDF assinado eletronicamente, com a página de assinaturas e o carimbo de cada signatário. - Com todos os signatários assinados, entrega o arquivo final. Com assinaturas pendentes, gera e entrega um PDF parcial com as assinaturas já realizadas. - Responde `400` enquanto nenhum signatário assinou (`Nenhum signatário assinou o documento até o momento.`) ou se o documento não existe na conta. - A URL é pré-assinada e vale por 5 minutos; cada chamada gera uma URL nova. - Para documentos assinados com certificado digital, use `partners_v1_documents_download_digital_certificate`. **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-signed.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=300&X-Amz-Signature=3f9c0a1b2c3d4e5f" } ``` #### Info para download do documento com certificado digital `GET /partners/v1/accounts/{accountId}/documents/{id}/download/digital-certificate` - operationId: `partners_v1_documents_download_digital_certificate` - Autenticação: `ApiKey` Devolve uma URL temporária para baixar o PDF assinado com certificado digital (ICP-Brasil), disponível quando o documento tem ao menos um signatário com `DigitalCertificate` e todos já assinaram. - Antes disso responde `400` (`O documento assinado com certificado digital não está disponível para download.`). - A URL é pré-assinada e vale por 5 minutos; cada chamada gera uma URL nova. **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-digital.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=300&X-Amz-Signature=3f9c0a1b2c3d4e5f" } ``` #### Envio de solicitação de assinaturas para um documento existente `POST /partners/v1/accounts/{accountId}/documents/{id}/request-signatures` - operationId: `partners_v1_documents_request_signatures` - Autenticação: `ApiKey` Envia a solicitação de assinaturas para um documento que já existe na conta e ainda não está em processo de assinatura: documentos criados a partir de formulário (`partners_v1_forms_create`) ou que tiveram as assinaturas canceladas. - Aceita documentos com status de assinatura `SignatureNotSet`, `SettingUpSignatures`, `SignaturesDeliveryScheduled`, `FinalizingSignatures` ou `ErrorOnFinalizingSignatures`. Em `WaitingSignatures` ou `Signed` responde `400`. - O corpo segue as mesmas regras de `partners_v1_document_signatures_create_from_file`, sem o arquivo: signatários, áreas, informações, observadores, prazo e lembretes. - `deadlineForSignature` substitui o prazo atual; omitido, o prazo é removido. `scheduledTo` não tem efeito nesta operação. - Ao contrário da criação, `Part` e `1` não são convertidos para `Parte`: envie o nome do papel. - Dispara o webhook `DocumentSentToSignature` e notifica os signatários. Consome cota de SMS e WhatsApp quando usados. - Repetir a chamada responde `400`, pois o documento passa a `WaitingSignatures`. **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`. | **Corpo da requisição** (`application/json`, obrigatório) Schema: [RequestDocumentSignatures](#requestdocumentsignatures) ```json { "customMessage": "Segue a ficha cadastral preenchida para assinatura.", "deadlineForSignature": "2026-09-30T12:00:00Z", "reminderFrequency": "SevenDays", "signers": [ { "email": "maria.silva@exemplo.com.br", "name": "Maria da Silva", "documentNumber": "11144477735", "role": "Parte", "authenticationMethod": "Email" }, { "email": "ana.pereira@exemplo.com.br", "name": "Ana Pereira", "role": "Aprovador", "authenticationMethod": "Email" } ], "signatureAreas": [ { "type": "Signature", "page": 2, "x": 12.5, "y": 80, "width": 15, "height": 5, "email": "maria.silva@exemplo.com.br", "role": "Parte", "authenticationMethod": "Email" } ] } ``` **Respostas** | Status | Descrição | Corpo | | --- | --- | --- | | `200` | OK | [CreatedDocumentInfoDto](#createddocumentinfodto) (`application/json`) | | `400` | Regra de negócio não satisfeita: recurso inexistente na conta, estado que não permite a operação, recurso do plano ausente ou cota atingida. O corpo (`ProblemDetailsResult`) traz as mensagens em `errors`. | [ProblemDetailsResult](#problemdetailsresult) (`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 | | `422` | Payload rejeitado: JSON malformado ou campos que não passaram na validação (obrigatórios, tamanhos, formatos, combinações). O corpo (`ProblemDetailsResult`) traz as mensagens em `errors` e, em `problems`, cada mensagem com o campo (`propertyName`). | [ProblemDetailsResult](#problemdetailsresult) (`application/json`) | Exemplo de resposta `200`: ```json { "id": "01991440-5a6b-7c8d-9e0f-1a2b3c4d5e6f", "uri": "https://app.letssign.com.br/app/documents/01991440-5a6b-7c8d-9e0f-1a2b3c4d5e6f/signatures" } ``` #### Lista campos de informações do documento `GET /partners/v1/accounts/{accountId}/documents/{id}/informations` - operationId: `partners_v1_documents_informations_list` - Autenticação: `ApiKey` Lista os campos de informação preenchidos no documento, com o campo da conta (`informationField`), o valor e, para texto formatado, o valor sem marcação. - Retorna lista vazia quando o documento não tem informações. - Somente leitura, sem efeitos colaterais. **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 | [DocumentInformationDto](#documentinformationdto)[] (`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 [ { "id": "01991447-b1c2-7d3e-8f4a-5b6c7d8e9f0a", "informationFieldId": "0199143d-3f4a-7b5c-8d6e-7f8a9b0c1d2e", "informationField": { "id": "0199143d-3f4a-7b5c-8d6e-7f8a9b0c1d2e", "name": "Número do contrato", "type": "Text", "typeDescription": "Texto curto" }, "value": "CT-2026-0451" } ] ``` #### Adiciona/atualiza campo de informação no documento `POST /partners/v1/accounts/{accountId}/documents/{id}/informations` - operationId: `partners_v1_documents_informations_upsert` - Autenticação: `ApiKey` Grava um campo de informação no documento. Se o documento já tem valor para o `informationFieldId`, o valor é substituído; caso contrário, o campo é adicionado. - Exige a feature `document_informations` no plano; sem ela responde `400`. - O valor deve seguir o tipo do campo: data em `YYYY-MM-DD`, números com ponto decimal, `Party` com id, CPF ou CNPJ de um contato da conta. Valor fora do formato responde `400`. - Não altera o status do documento nem dispara webhook. Idempotente por `informationFieldId`. **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`. | **Corpo da requisição** (`application/json`, obrigatório) Schema: [AddDocumentInformation](#adddocumentinformation) ```json { "informationFieldId": "0199143d-3f4a-7b5c-8d6e-7f8a9b0c1d2e", "value": "CT-2026-0451" } ``` **Respostas** | Status | Descrição | Corpo | | --- | --- | --- | | `200` | OK | [DocumentInformationDto](#documentinformationdto) (`application/json`) | | `400` | Regra de negócio não satisfeita: recurso inexistente na conta, estado que não permite a operação, recurso do plano ausente ou cota atingida. O corpo (`ProblemDetailsResult`) traz as mensagens em `errors`. | [ProblemDetailsResult](#problemdetailsresult) (`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 | | `422` | Payload rejeitado: JSON malformado ou campos que não passaram na validação (obrigatórios, tamanhos, formatos, combinações). O corpo (`ProblemDetailsResult`) traz as mensagens em `errors` e, em `problems`, cada mensagem com o campo (`propertyName`). | [ProblemDetailsResult](#problemdetailsresult) (`application/json`) | Exemplo de resposta `200`: ```json { "id": "01991447-b1c2-7d3e-8f4a-5b6c7d8e9f0a", "informationFieldId": "0199143d-3f4a-7b5c-8d6e-7f8a9b0c1d2e", "informationField": { "id": "0199143d-3f4a-7b5c-8d6e-7f8a9b0c1d2e", "name": "Número do contrato", "type": "Text", "typeDescription": "Texto curto" }, "value": "CT-2026-0451" } ``` #### Remove campo de informação no documento `DELETE /partners/v1/accounts/{accountId}/documents/{id}/informations/{informationFieldId}` - operationId: `partners_v1_documents_informations_delete` - Autenticação: `ApiKey` Remove o valor de um campo de informação do documento. - Responde `400` quando o documento não tem valor para o campo (`Campo de informação não existe`), inclusive ao repetir a chamada. - Não altera o status do documento nem dispara webhook. **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`. | | `informationFieldId` | path | string (uuid) | sim | Identificador do campo de informação da conta (`partners_v1_information_fields_list`). | **Respostas** | Status | Descrição | Corpo | | --- | --- | --- | | `204` | No Content | sem corpo | | `400` | Regra de negócio não satisfeita: recurso inexistente na conta, estado que não permite a operação, recurso do plano ausente ou cota atingida. O corpo (`ProblemDetailsResult`) traz as mensagens em `errors`. | [ProblemDetailsResult](#problemdetailsresult) (`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 | | `422` | Payload rejeitado: JSON malformado ou campos que não passaram na validação (obrigatórios, tamanhos, formatos, combinações). O corpo (`ProblemDetailsResult`) traz as mensagens em `errors` e, em `problems`, cada mensagem com o campo (`propertyName`). | [ProblemDetailsResult](#problemdetailsresult) (`application/json`) | #### Remove um documento `DELETE /partners/v1/accounts/{accountId}/documents/{id}` - operationId: `partners_v1_documents_delete` - Autenticação: `ApiKey` Exclui o documento da conta, com as assinaturas em andamento e os arquivos. - Documentos com status de assinatura `Signed` não podem ser excluídos (`O documento já está assinado`, `400`). - Signatários e suplentes recebem e-mail de cancelamento. Dispara o webhook `DocumentRemoved` e, quando o documento estava aguardando assinaturas, o `DocumentSignaturesCanceled`, que lista os documentos atingidos. - A exclusão fica no registro de eventos da conta e é definitiva. - Repetir a chamada responde `400` (`Document não existe`). **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 | | --- | --- | --- | | `204` | No Content | sem corpo | | `400` | Regra de negócio não satisfeita: recurso inexistente na conta, estado que não permite a operação, recurso do plano ausente ou cota atingida. O corpo (`ProblemDetailsResult`) traz as mensagens em `errors`. | [ProblemDetailsResult](#problemdetailsresult) (`application/json`) | | `404` | Recurso não encontrado na conta informada. | [ProblemDetailsResult](#problemdetailsresult) (`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 | #### Lista campos do formulário do documento `GET /partners/v1/accounts/{accountId}/documents/{id}/form-fields` - operationId: `partners_v1_documents_form_fields_list` - Autenticação: `ApiKey` Lista os campos do formulário que originou o documento (criado por `partners_v1_forms_create`), com tipo, tag, enunciado, obrigatoriedade, quem preenche (`filler`) e o valor preenchido. - Retorna lista vazia para documentos que não vieram de formulário. - Ordenado por `order`. Somente leitura. **Features exigidas no plano da conta:** `custom_models`, `default_models`, `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 | [FormFieldSimplifiedDto](#formfieldsimplifieddto)[] (`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: `custom_models`, `default_models`, `documents`. | sem corpo | Exemplo de resposta `200`: ```json [ { "id": "01991446-a0b1-7c2d-9e3f-4a5b6c7d8e9f", "type": "Text", "tag": "nome_locatario", "name": "Nome do locatário", "statement": "Informe o nome completo do locatário", "required": true, "capitalize": false, "writeOut": false, "order": 1, "filler": { "name": "Maria da Silva", "email": "maria.silva@exemplo.com.br", "filledAt": "2026-08-21T09:30:00Z" }, "value": "Maria da Silva" }, { "id": "01991446-a0b1-7c2d-9e3f-4a5b6c7d8ea0", "type": "Currency", "tag": "valor_aluguel", "name": "Valor do aluguel", "statement": "Valor mensal do aluguel", "required": true, "capitalize": false, "writeOut": true, "order": 4, "value": "2500.00" } ] ``` #### Atualiza os métodos de autenticação adicionais dos signatários do documento `PUT /partners/v1/accounts/{accountId}/documents/{id}/signatures/additional-authentication-methods` - operationId: `partners_v1_documents_update_additional_authentication_methods` - Autenticação: `ApiKey` Define as evidências adicionais exigidas na assinatura (selfie, documento com foto, biometria facial) de um ou mais signatários de um documento aguardando assinaturas. A lista enviada substitui a existente em cada signatário; `[]` remove todas. - Exige status de assinatura `WaitingSignatures`; fora disso responde `400`. - Identificadores de signatário desconhecidos são ignorados sem erro. - A resposta traz todos os signatários do documento com as evidências vigentes. - Idempotente. Não dispara webhook nem reenvia links. **Features exigidas no plano da conta:** `documents`, `documents_signatures`. **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`. | **Corpo da requisição** (`application/json`, obrigatório) Schema: [UpdateDocumentSignaturesAdditionalAuthenticationMethods](#updatedocumentsignaturesadditionalauthenticationmethods) ```json { "signatures": [ { "documentSignatureId": "01991441-0a1b-7c2d-8e3f-4a5b6c7d8e9f", "additionalAuthenticationMethods": [ "DocumentIdWithPhoto" ] }, { "documentSignatureId": "01991441-9f8e-7d6c-8b5a-4c3d2e1f0a9b", "additionalAuthenticationMethods": [] } ] } ``` **Respostas** | Status | Descrição | Corpo | | --- | --- | --- | | `200` | OK | [SignaturesAdditionalAuthenticationMethodsUpdatedDto](#signaturesadditionalauthenticationmethodsupdateddto) (`application/json`) | | `400` | Regra de negócio não satisfeita: recurso inexistente na conta, estado que não permite a operação, recurso do plano ausente ou cota atingida. O corpo (`ProblemDetailsResult`) traz as mensagens em `errors`. | [ProblemDetailsResult](#problemdetailsresult) (`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`, `documents_signatures`. | sem corpo | | `422` | Payload rejeitado: JSON malformado ou campos que não passaram na validação (obrigatórios, tamanhos, formatos, combinações). O corpo (`ProblemDetailsResult`) traz as mensagens em `errors` e, em `problems`, cada mensagem com o campo (`propertyName`). | [ProblemDetailsResult](#problemdetailsresult) (`application/json`) | Exemplo de resposta `200`: ```json { "documentId": "01991440-5a6b-7c8d-9e0f-1a2b3c4d5e6f", "signatures": [ { "documentSignatureId": "01991441-0a1b-7c2d-8e3f-4a5b6c7d8e9f", "role": "Parte", "authenticationMethod": "Email", "email": "maria.silva@exemplo.com.br", "name": "Maria da Silva", "additionalAuthenticationMethods": [ "DocumentIdWithPhoto" ] }, { "documentSignatureId": "01991441-9f8e-7d6c-8b5a-4c3d2e1f0a9b", "role": "Testemunha", "authenticationMethod": "Email", "email": "joao.souza@exemplo.com.br", "name": "João de Souza", "additionalAuthenticationMethods": [] } ] } ``` #### Altera pasta de um documento `PUT /partners/v1/accounts/{accountId}/documents/{id}/folder` - operationId: `partners_v1_documents_change_folder` - Autenticação: `ApiKey` Move o documento para outra pasta da conta, ou para a raiz quando `folderId` é nulo. - A pasta de destino precisa existir na conta (`Pasta destino não encontrada`, `400`). - Idempotente e sem efeitos colaterais além da mudança de pasta. Responde `200` sem corpo. **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`. | **Corpo da requisição** (`application/json`, obrigatório) Schema: [ChangeDocumentFolder](#changedocumentfolder) ```json { "folderId": "0199143c-2e3f-7a4b-9c5d-6e7f8a9b0c1d" } ``` **Respostas** | Status | Descrição | Corpo | | --- | --- | --- | | `200` | OK | sem corpo | | `400` | Regra de negócio não satisfeita: recurso inexistente na conta, estado que não permite a operação, recurso do plano ausente ou cota atingida. O corpo (`ProblemDetailsResult`) traz as mensagens em `errors`. | [ProblemDetailsResult](#problemdetailsresult) (`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 | | `422` | Payload rejeitado: JSON malformado ou campos que não passaram na validação (obrigatórios, tamanhos, formatos, combinações). O corpo (`ProblemDetailsResult`) traz as mensagens em `errors` e, em `problems`, cada mensagem com o campo (`propertyName`). | [ProblemDetailsResult](#problemdetailsresult) (`application/json`) | #### Substitui os grupos de acesso do documento `PUT /partners/v1/accounts/{accountId}/documents/{id}/groups` - operationId: `partners_v1_documents_update_groups` - Autenticação: `ApiKey` Define quais grupos de acesso da conta veem o documento. O conjunto enviado em `groups` substitui o atual: o que está na lista fica, o que não está sai. Consulte os ids em `partners_v1_groups_list`. - Só aceita grupo **ativo** da própria conta; qualquer outro id responde `422` citando os ids recusados. O campo `groups` é obrigatório: corpo sem ele, ou com `null`, responde `422`; para remover todos os grupos, envie a lista vazia. - **Cuidado com read-modify-write.** O vínculo com grupo desativado no aplicativo não aparece em `groups` nas leituras do documento, mas continua na base — e a substituição não o poupa: devolver aqui a lista que veio da leitura remove esse vínculo em definitivo, e reativar o grupo depois não devolve a visibilidade do documento. Quando um grupo do documento pode estar desativado, monte a lista a partir dos ids que você controla, não do que a leitura devolveu. - Grupos do documento e grupos da pasta são condições **cumulativas**, não alternativas: um documento com o grupo `Jurídico` dentro de uma pasta restrita a `Diretoria` é visto por quem está nos dois. Remover todos os grupos do documento não o torna invisível — o acesso volta a ser decidido pelos grupos da pasta, e o documento fora de pasta fica visível para toda a conta. - Aplica-se ao documento informado, em qualquer status. Num envelope, os documentos filhos não são afetados: cada um tem os seus próprios grupos. - Documento que não é da conta responde `400` (`Documento não encontrado`). - Idempotente. Responde `204` sem corpo. **Features exigidas no plano da conta:** `documents`, `groups`. **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`. | **Corpo da requisição** (`application/json`, obrigatório) Schema: [SetDocumentGroups](#setdocumentgroups) ```json { "groups": [ "0199143d-3f40-7b5c-8d6e-7f8a9b0c1d2e" ] } ``` **Respostas** | Status | Descrição | Corpo | | --- | --- | --- | | `204` | No Content | sem corpo | | `400` | Regra de negócio não satisfeita: recurso inexistente na conta, estado que não permite a operação, recurso do plano ausente ou cota atingida. O corpo (`ProblemDetailsResult`) traz as mensagens em `errors`. | [ProblemDetailsResult](#problemdetailsresult) (`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`, `groups`. | sem corpo | | `422` | Payload rejeitado: JSON malformado ou campos que não passaram na validação (obrigatórios, tamanhos, formatos, combinações). O corpo (`ProblemDetailsResult`) traz as mensagens em `errors` e, em `problems`, cada mensagem com o campo (`propertyName`). | [ProblemDetailsResult](#problemdetailsresult) (`application/json`) | ### Webhooks URLs da conta que recebem um POST a cada evento: documento enviado, signatário assinou, assinaturas concluídas, status alterado, documento removido, formulário preenchido. #### Lista de webhooks da conta `GET /partners/v1/accounts/{accountId}/webhooks` - operationId: `partners_v1_webhooks_list` - Autenticação: `ApiKey` Lista as URLs de webhook cadastradas na conta, em ordem de criação. `available` reflete o resultado do evento `Test` enviado no cadastro. - Todas as URLs recebem todos os eventos da conta; não há filtro por evento. - Somente leitura, sem efeitos colaterais. **Features exigidas no plano da conta:** `integrations`. **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`. | **Respostas** | Status | Descrição | Corpo | | --- | --- | --- | | `200` | OK | [AccountWebHookDto](#accountwebhookdto)[] (`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: `integrations`. | sem corpo | Exemplo de resposta `200`: ```json [ { "id": "0199143e-4a5b-7c6d-9e7f-8a9b0c1d2e3f", "accountId": "0199143a-7c2e-7b1a-9f2d-3c4b5a6d7e8f", "uri": "https://integracao.exemplo.com.br/letssign/webhook", "available": true, "createdAt": "2026-08-20T14:05:00Z" } ] ``` #### Adicionar webhook na conta `POST /partners/v1/accounts/{accountId}/webhooks` - operationId: `partners_v1_webhooks_create` - Autenticação: `ApiKey` Cadastra uma URL para receber os eventos da conta por `POST` JSON: documento enviado, signatário adicionado, signatário assinou, assinaturas concluídas, status alterado, documento removido e formulário preenchido. - No cadastro, um evento `Test` é enviado de imediato; a URL deve responder `200` ou `202` em até 20 segundos. O resultado fica em `available`, mas a URL é gravada mesmo quando o teste falha. - Exige `http://` ou `https://`, host em minúsculas com TLD de 2 a 5 letras. A mesma URL não pode ser cadastrada duas vezes na conta (`A URL ... já é usada como webhook na conta`, `400`). - Entregas com falha são repetidas até 5 vezes. Não há cabeçalho de assinatura: valide a origem pelo `accountId` do payload e, se preciso, por um segredo na própria URL. - Os payloads de cada evento estão na página inicial da documentação. **Features exigidas no plano da conta:** `integrations`. **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`. | **Corpo da requisição** (`application/json`, obrigatório) Schema: [CreateAccountWebhook](#createaccountwebhook) ```json { "uri": "https://integracao.exemplo.com.br/letssign/webhook" } ``` **Respostas** | Status | Descrição | Corpo | | --- | --- | --- | | `201` | Created | [AccountWebHookDto](#accountwebhookdto) (`application/json`) | | `400` | Regra de negócio não satisfeita: recurso inexistente na conta, estado que não permite a operação, recurso do plano ausente ou cota atingida. O corpo (`ProblemDetailsResult`) traz as mensagens em `errors`. | [ProblemDetailsResult](#problemdetailsresult) (`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: `integrations`. | sem corpo | | `422` | Payload rejeitado: JSON malformado ou campos que não passaram na validação (obrigatórios, tamanhos, formatos, combinações). O corpo (`ProblemDetailsResult`) traz as mensagens em `errors` e, em `problems`, cada mensagem com o campo (`propertyName`). | [ProblemDetailsResult](#problemdetailsresult) (`application/json`) | Exemplo de resposta `201`: ```json { "id": "0199143e-4a5b-7c6d-9e7f-8a9b0c1d2e3f", "accountId": "0199143a-7c2e-7b1a-9f2d-3c4b5a6d7e8f", "uri": "https://integracao.exemplo.com.br/letssign/webhook", "available": true, "createdAt": "2026-08-20T14:05:00Z" } ``` #### Remover webhook da conta `DELETE /partners/v1/accounts/{accountId}/webhooks/{id}` - operationId: `partners_v1_webhooks_delete` - Autenticação: `ApiKey` Remove uma URL de webhook da conta. Eventos futuros deixam de ser enviados a ela. - Responde `400` quando o webhook não existe na conta, inclusive ao repetir a chamada. **Features exigidas no plano da conta:** `integrations`. **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` | path | string (uuid) | sim | Identificador do webhook, devolvido na criação e na listagem. | **Respostas** | Status | Descrição | Corpo | | --- | --- | --- | | `204` | No Content | sem corpo | | `400` | Regra de negócio não satisfeita: recurso inexistente na conta, estado que não permite a operação, recurso do plano ausente ou cota atingida. O corpo (`ProblemDetailsResult`) traz as mensagens em `errors`. | [ProblemDetailsResult](#problemdetailsresult) (`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: `integrations`. | sem corpo | | `422` | Payload rejeitado: JSON malformado ou campos que não passaram na validação (obrigatórios, tamanhos, formatos, combinações). O corpo (`ProblemDetailsResult`) traz as mensagens em `errors` e, em `problems`, cada mensagem com o campo (`propertyName`). | [ProblemDetailsResult](#problemdetailsresult) (`application/json`) | ### Folders Pastas que organizam os documentos da conta. #### Lista pastas da conta `GET /partners/v1/accounts/{accountId}/folders` - operationId: `partners_v1_folders_list` - Autenticação: `ApiKey` Lista todas as pastas da conta, com `parentId` para montar a árvore e `path` com o caminho completo. - Pode responder de um cache de até 3 horas; criar uma pasta por `partners_v1_folders_create` invalida o cache da conta. - Não há paginação. 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`. | **Respostas** | Status | Descrição | Corpo | | --- | --- | --- | | `200` | OK | [FolderDto](#folderdto)[] (`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 [ { "id": "0199143c-2e3f-7a4b-9c5d-6e7f8a9b0c1d", "name": "Contratos 2026", "hasChildren": true, "path": "Contratos 2026" }, { "id": "0199144a-e4f5-7a6b-9c7d-8e9f0a1b2c3d", "name": "Locação", "parentId": "0199143c-2e3f-7a4b-9c5d-6e7f8a9b0c1d", "hasChildren": false, "path": "Contratos 2026/Locação" } ] ``` #### Cria uma pasta na Conta `POST /partners/v1/accounts/{accountId}/folders` - operationId: `partners_v1_folders_create` - Autenticação: `ApiKey` Cria uma pasta na conta, na raiz ou dentro de `parentId`. - O nome deve ser único dentro da pasta pai (sem diferenciar maiúsculas) e a pasta pai precisa existir na conta; ambos respondem `400`. - A nova pasta herda as permissões de grupos da pasta pai. - Repetir a chamada com o mesmo nome e pai responde `400`. **Features exigidas no plano da conta:** `folder_writer`. **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`. | **Corpo da requisição** (`application/json`, obrigatório) Schema: [CreateFolder](#createfolder) ```json { "name": "Contratos 2026", "parentId": null } ``` **Respostas** | Status | Descrição | Corpo | | --- | --- | --- | | `201` | Created | [FolderDto](#folderdto) (`application/json`) | | `400` | Regra de negócio não satisfeita: recurso inexistente na conta, estado que não permite a operação, recurso do plano ausente ou cota atingida. O corpo (`ProblemDetailsResult`) traz as mensagens em `errors`. | [ProblemDetailsResult](#problemdetailsresult) (`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: `folder_writer`. | sem corpo | | `422` | Payload rejeitado: JSON malformado ou campos que não passaram na validação (obrigatórios, tamanhos, formatos, combinações). O corpo (`ProblemDetailsResult`) traz as mensagens em `errors` e, em `problems`, cada mensagem com o campo (`propertyName`). | [ProblemDetailsResult](#problemdetailsresult) (`application/json`) | Exemplo de resposta `201`: ```json { "id": "0199143c-2e3f-7a4b-9c5d-6e7f8a9b0c1d", "name": "Contratos 2026", "hasChildren": false, "path": "Contratos 2026" } ``` ### Categories Categorias que classificam os documentos da conta. #### Lista paginada de categorias da conta `GET /partners/v1/accounts/{accountId}/categories` - operationId: `partners_v1_categories_list` - Autenticação: `ApiKey` - Situação: obsoleta (`deprecated`); a descrição indica o substituto **Obsoleto.** Substituído por `partners_v2_categories_list` na [Partners API v2](https://api.letssign.com.br/docs/partners/v2), com paginação por `page`/`perPage` e ordenação declarada. Continua respondendo, mas não recebe evolução. Lista as categorias da conta, com filtro por nome e situação, paginada por `pageIndex` e `pageSize`. 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`. | | `pageIndex` | query | integer (int32) | sim | Número da página, a partir de 1. Padrão: `1`. | | `pageSize` | query | integer (int32) | sim | Quantidade de itens por página. Padrão: `20`. | | `sortField` | query | string | sim | Campo de ordenação. Padrão: `"Id"`. | | `sortType` | query | `"asc"` \| `"desc"` | sim | Sentido da ordenação: `asc` ou `desc`. Padrão: `"asc"`. | **Respostas** | Status | Descrição | Corpo | | --- | --- | --- | | `200` | OK | [PagedListDeprecatedOfCategoryDto](#pagedlistdeprecatedofcategorydto) (`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 } ], "totalPages": 1, "totalRecords": 1, "pageSize": 20 } ``` #### Adicionar categoria na conta `POST /partners/v1/accounts/{accountId}/categories` - operationId: `partners_v1_categories_create` - Autenticação: `ApiKey` Cria uma categoria na conta. Categorias classificam documentos e servem de filtro nas listagens. - O nome deve ser único na conta, sem diferenciar maiúsculas (`Este nome de categoria já existe`, `400`). A categoria nasce ativa. - Responde `201` com a categoria e o cabeçalho `Location`. **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`. | **Corpo da requisição** (`application/json`, obrigatório) Schema: [CreateCategory](#createcategory) ```json { "name": "Contratos de locação" } ``` **Respostas** | Status | Descrição | Corpo | | --- | --- | --- | | `201` | Created | [CategoryDto](#categorydto) (`application/json`) | | `400` | Regra de negócio não satisfeita: recurso inexistente na conta, estado que não permite a operação, recurso do plano ausente ou cota atingida. O corpo (`ProblemDetailsResult`) traz as mensagens em `errors`. | [ProblemDetailsResult](#problemdetailsresult) (`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 | | `422` | Payload rejeitado: JSON malformado ou campos que não passaram na validação (obrigatórios, tamanhos, formatos, combinações). O corpo (`ProblemDetailsResult`) traz as mensagens em `errors` e, em `problems`, cada mensagem com o campo (`propertyName`). | [ProblemDetailsResult](#problemdetailsresult) (`application/json`) | Exemplo de resposta `201`: ```json { "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 } ``` #### Busca categoria da conta por id `GET /partners/v1/accounts/{accountId}/categories/{id}` - operationId: `partners_v1_categories_get` - Autenticação: `ApiKey` Busca uma categoria da conta pelo identificador. - Responde `404` quando não existe na conta. - Somente leitura, sem efeitos colaterais. **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`. | | `id` | path | string (uuid) | sim | Identificador da categoria. | **Respostas** | Status | Descrição | Corpo | | --- | --- | --- | | `200` | OK | [CategoryDto](#categorydto) (`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 | | `404` | Recurso não encontrado na conta informada. | sem corpo | Exemplo de resposta `200`: ```json { "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 } ``` #### Editar categoria da conta `PUT /partners/v1/accounts/{accountId}/categories/{id}` - operationId: `partners_v1_categories_update` - Autenticação: `ApiKey` Renomeia uma categoria da conta. A situação (`active`) não muda. - O novo nome deve ser único na conta; categoria inexistente ou nome repetido respondem `400`. - Idempotente. **Features exigidas no plano da conta:** `categories`. **Parâmetros** | Nome | Em | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | --- | | `id` | path | string (uuid) | sim | Identificador da categoria. | | `accountId` | path | string (uuid) | sim | Identificador da conta operada. Obtenha a lista em `partners_v1_accounts_list`. | **Corpo da requisição** (`application/json`, obrigatório) Schema: [UpdateCategory](#updatecategory) ```json { "name": "Contratos de locação residencial" } ``` **Respostas** | Status | Descrição | Corpo | | --- | --- | --- | | `200` | OK | [CategoryDto](#categorydto) (`application/json`) | | `400` | Regra de negócio não satisfeita: recurso inexistente na conta, estado que não permite a operação, recurso do plano ausente ou cota atingida. O corpo (`ProblemDetailsResult`) traz as mensagens em `errors`. | [ProblemDetailsResult](#problemdetailsresult) (`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 | | `422` | Payload rejeitado: JSON malformado ou campos que não passaram na validação (obrigatórios, tamanhos, formatos, combinações). O corpo (`ProblemDetailsResult`) traz as mensagens em `errors` e, em `problems`, cada mensagem com o campo (`propertyName`). | [ProblemDetailsResult](#problemdetailsresult) (`application/json`) | Exemplo de resposta `200`: ```json { "id": "0199143b-1d2e-7f3a-8b4c-5d6e7f8a9b0c", "name": "Contratos de locação residencial", "accountId": "0199143a-7c2e-7b1a-9f2d-3c4b5a6d7e8f", "createdAt": "2025-03-12T13:45:10Z", "active": true } ``` #### Remover categoria da conta `DELETE /partners/v1/accounts/{accountId}/categories/{id}` - operationId: `partners_v1_categories_delete` - Autenticação: `ApiKey` Exclui uma categoria da conta. - Não é possível excluir categoria vinculada a documentos ou a modelos de documento; a resposta `400` diz qual vínculo impede. Nesse caso, desative-a com `partners_v1_categories_change_status`. - Repetir a chamada responde `400` (`Categoria não existe`). **Features exigidas no plano da conta:** `categories`. **Parâmetros** | Nome | Em | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | --- | | `id` | path | string (uuid) | sim | Identificador da categoria. | | `accountId` | path | string (uuid) | sim | Identificador da conta operada. Obtenha a lista em `partners_v1_accounts_list`. | **Respostas** | Status | Descrição | Corpo | | --- | --- | --- | | `204` | No Content | sem corpo | | `400` | Regra de negócio não satisfeita: recurso inexistente na conta, estado que não permite a operação, recurso do plano ausente ou cota atingida. O corpo (`ProblemDetailsResult`) traz as mensagens em `errors`. | [ProblemDetailsResult](#problemdetailsresult) (`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 | | `422` | Payload rejeitado: JSON malformado ou campos que não passaram na validação (obrigatórios, tamanhos, formatos, combinações). O corpo (`ProblemDetailsResult`) traz as mensagens em `errors` e, em `problems`, cada mensagem com o campo (`propertyName`). | [ProblemDetailsResult](#problemdetailsresult) (`application/json`) | #### Alterar status da categoria da conta `PATCH /partners/v1/accounts/{accountId}/categories/{id}/change-status` - operationId: `partners_v1_categories_change_status` - Autenticação: `ApiKey` Inverte a situação da categoria: ativa passa a inativa e inativa passa a ativa. Não recebe corpo. - Categoria inativa deixa de ser oferecida para novos documentos, mas continua nos documentos que já a têm. - Categoria inexistente responde `400`. Chamar duas vezes volta ao estado original. **Features exigidas no plano da conta:** `categories`. **Parâmetros** | Nome | Em | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | --- | | `id` | path | string (uuid) | sim | Identificador da categoria. | | `accountId` | path | string (uuid) | sim | Identificador da conta operada. Obtenha a lista em `partners_v1_accounts_list`. | **Respostas** | Status | Descrição | Corpo | | --- | --- | --- | | `200` | OK | [CategoryDto](#categorydto) (`application/json`) | | `400` | Regra de negócio não satisfeita: recurso inexistente na conta, estado que não permite a operação, recurso do plano ausente ou cota atingida. O corpo (`ProblemDetailsResult`) traz as mensagens em `errors`. | [ProblemDetailsResult](#problemdetailsresult) (`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 | | `422` | Payload rejeitado: JSON malformado ou campos que não passaram na validação (obrigatórios, tamanhos, formatos, combinações). O corpo (`ProblemDetailsResult`) traz as mensagens em `errors` e, em `problems`, cada mensagem com o campo (`propertyName`). | [ProblemDetailsResult](#problemdetailsresult) (`application/json`) | Exemplo de resposta `200`: ```json { "id": "0199143b-1d2e-7f3a-8b4c-5d6e7f8a9b0c", "name": "Contratos de locação", "accountId": "0199143a-7c2e-7b1a-9f2d-3c4b5a6d7e8f", "createdAt": "2025-03-12T13:45:10Z", "active": false } ``` ### Contacts Pessoas físicas (CPF) e jurídicas (CNPJ) cadastradas na conta, reutilizáveis como signatários. #### Buscar pessoa por cpf `GET /partners/v1/accounts/{accountId}/contacts/person/{cpf}` - operationId: `partners_v1_contacts_get_person` - Autenticação: `ApiKey` Busca um contato do tipo pessoa pelo CPF. - Informe só os 11 dígitos. CPF inválido responde `400`; CPF não cadastrado na conta, ou cadastrado como empresa, responde `404`. - Somente leitura, sem efeitos colaterais. **Features exigidas no plano da conta:** `contacts`, `integrations`. **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`. | | `cpf` | path | string | sim | CPF da pessoa, somente os 11 dígitos, sem pontuação. | **Respostas** | Status | Descrição | Corpo | | --- | --- | --- | | `200` | OK | [PersonDto](#persondto) (`application/json`) | | `400` | Regra de negócio não satisfeita: recurso inexistente na conta, estado que não permite a operação, recurso do plano ausente ou cota atingida. O corpo (`ProblemDetailsResult`) traz as mensagens em `errors`. | [ProblemDetailsResult](#problemdetailsresult) (`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: `contacts`, `integrations`. | sem corpo | | `404` | Recurso não encontrado na conta informada. | sem corpo | Exemplo de resposta `200`: ```json { "name": "Maria da Silva", "alias": "Maria", "email": "maria.silva@exemplo.com.br", "addressInformation": { "address": "Rua das Flores", "number": "120", "complement": "Sala 4", "district": "Centro", "zipCode": "01001000", "city": "São Paulo", "state": "SP", "formattedZipCode": "01001-000", "complete": "Rua das Flores, 120, Sala 4, Centro, 01001-000, São Paulo-SP" }, "phone1": { "number": "11987654321", "formated": "(11) 9-8765-4321", "formatted": "(11) 9-8765-4321" }, "cpf": "11144477735", "rg": "12.345.678-9", "issuingAgency": "SSP", "stateIssuingAgency": "SP", "nationality": "Brasileira", "profession": "Arquiteta", "maritalStatus": "Married" } ``` #### Cria ou atualiza uma pessoa `POST /partners/v1/accounts/{accountId}/contacts/person` - operationId: `partners_v1_contacts_upsert_person` - Autenticação: `ApiKey` Cria ou atualiza um contato do tipo pessoa. A chave é o CPF: se já existe na conta, o contato é atualizado; senão, é criado. - A atualização substitui o cadastro por completo: campos omitidos ficam vazios. Envie sempre o contato inteiro. - Responde `200` nos dois casos, com o contato gravado. Idempotente. - Contatos podem ser referenciados em campos de informação do tipo `Party`. **Features exigidas no plano da conta:** `contacts`, `integrations`. **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`. | **Corpo da requisição** (`application/json`, obrigatório) Schema: [RegisterPerson](#registerperson) ```json { "name": "Maria da Silva", "alias": "Maria", "email": "maria.silva@exemplo.com.br", "cpf": "11144477735", "rg": "12.345.678-9", "issuingAgency": "SSP", "stateIssuingAgency": "SP", "nationality": "Brasileira", "profession": "Arquiteta", "maritalStatus": "Married", "phone1": { "number": "11987654321" }, "addressInformation": { "address": "Rua das Flores", "number": "120", "complement": "Sala 4", "district": "Centro", "zipCode": "01001000", "city": "São Paulo", "state": "SP" } } ``` **Respostas** | Status | Descrição | Corpo | | --- | --- | --- | | `200` | OK | [PersonDto](#persondto) (`application/json`) | | `400` | Regra de negócio não satisfeita: recurso inexistente na conta, estado que não permite a operação, recurso do plano ausente ou cota atingida. O corpo (`ProblemDetailsResult`) traz as mensagens em `errors`. | [ProblemDetailsResult](#problemdetailsresult) (`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: `contacts`, `integrations`. | sem corpo | | `422` | Payload rejeitado: JSON malformado ou campos que não passaram na validação (obrigatórios, tamanhos, formatos, combinações). O corpo (`ProblemDetailsResult`) traz as mensagens em `errors` e, em `problems`, cada mensagem com o campo (`propertyName`). | [ProblemDetailsResult](#problemdetailsresult) (`application/json`) | Exemplo de resposta `200`: ```json { "name": "Maria da Silva", "alias": "Maria", "email": "maria.silva@exemplo.com.br", "addressInformation": { "address": "Rua das Flores", "number": "120", "complement": "Sala 4", "district": "Centro", "zipCode": "01001000", "city": "São Paulo", "state": "SP", "formattedZipCode": "01001-000", "complete": "Rua das Flores, 120, Sala 4, Centro, 01001-000, São Paulo-SP" }, "phone1": { "number": "11987654321", "formated": "(11) 9-8765-4321", "formatted": "(11) 9-8765-4321" }, "cpf": "11144477735", "rg": "12.345.678-9", "issuingAgency": "SSP", "stateIssuingAgency": "SP", "nationality": "Brasileira", "profession": "Arquiteta", "maritalStatus": "Married" } ``` #### Buscar empresa por CNPJ `GET /partners/v1/accounts/{accountId}/contacts/company/{cnpj}` - operationId: `partners_v1_contacts_get_company` - Autenticação: `ApiKey` Busca um contato do tipo empresa pelo CNPJ. - Informe só os 14 caracteres, sem pontuação. CNPJ inválido responde `400`; CNPJ não cadastrado na conta, ou cadastrado como pessoa, responde `404`. - Somente leitura, sem efeitos colaterais. **Features exigidas no plano da conta:** `contacts`, `integrations`. **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`. | | `cnpj` | path | string | sim | CNPJ da empresa, somente os 14 caracteres, sem pontuação. | **Respostas** | Status | Descrição | Corpo | | --- | --- | --- | | `200` | OK | [CompanyDto](#companydto) (`application/json`) | | `400` | Regra de negócio não satisfeita: recurso inexistente na conta, estado que não permite a operação, recurso do plano ausente ou cota atingida. O corpo (`ProblemDetailsResult`) traz as mensagens em `errors`. | [ProblemDetailsResult](#problemdetailsresult) (`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: `contacts`, `integrations`. | sem corpo | | `404` | Recurso não encontrado na conta informada. | sem corpo | Exemplo de resposta `200`: ```json { "name": "Horizonte Negócios Imobiliários Ltda", "alias": "Imobiliária Horizonte", "email": "contato@exemplo.com.br", "addressInformation": { "address": "Avenida Paulista", "number": "1000", "complement": "Conjunto 101", "district": "Bela Vista", "zipCode": "01310100", "city": "São Paulo", "state": "SP", "formattedZipCode": "01310-100", "complete": "Avenida Paulista, 1000, Conjunto 101, Bela Vista, 01310-100, São Paulo-SP" }, "phone1": { "number": "1133334444", "formated": "(11) 3333-4444", "formatted": "(11) 3333-4444" }, "cnpj": "11222333000181", "nire": "35300012345", "stateRegistration": "110.042.490.114", "municipalRegistration": "1.234.567-8" } ``` #### Cria ou atualiza uma Empresa `POST /partners/v1/accounts/{accountId}/contacts/company` - operationId: `partners_v1_contacts_upsert_company` - Autenticação: `ApiKey` Cria ou atualiza um contato do tipo empresa. A chave é o CNPJ: se já existe na conta, o contato é atualizado; senão, é criado. - A atualização substitui o cadastro por completo: campos omitidos ficam vazios. Envie sempre o contato inteiro. - Responde `200` nos dois casos, com o contato gravado. Idempotente. - Contatos podem ser referenciados em campos de informação do tipo `Party`. **Features exigidas no plano da conta:** `contacts`, `integrations`. **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`. | **Corpo da requisição** (`application/json`, obrigatório) Schema: [RegisterCompany](#registercompany) ```json { "name": "Horizonte Negócios Imobiliários Ltda", "alias": "Imobiliária Horizonte", "email": "contato@exemplo.com.br", "cnpj": "11222333000181", "nire": "35300012345", "stateRegistration": "110.042.490.114", "municipalRegistration": "1.234.567-8", "phone1": { "number": "1133334444" }, "addressInformation": { "address": "Avenida Paulista", "number": "1000", "complement": "Conjunto 101", "district": "Bela Vista", "zipCode": "01310100", "city": "São Paulo", "state": "SP" } } ``` **Respostas** | Status | Descrição | Corpo | | --- | --- | --- | | `200` | OK | [CompanyDto](#companydto) (`application/json`) | | `400` | Regra de negócio não satisfeita: recurso inexistente na conta, estado que não permite a operação, recurso do plano ausente ou cota atingida. O corpo (`ProblemDetailsResult`) traz as mensagens em `errors`. | [ProblemDetailsResult](#problemdetailsresult) (`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: `contacts`, `integrations`. | sem corpo | | `422` | Payload rejeitado: JSON malformado ou campos que não passaram na validação (obrigatórios, tamanhos, formatos, combinações). O corpo (`ProblemDetailsResult`) traz as mensagens em `errors` e, em `problems`, cada mensagem com o campo (`propertyName`). | [ProblemDetailsResult](#problemdetailsresult) (`application/json`) | Exemplo de resposta `200`: ```json { "name": "Horizonte Negócios Imobiliários Ltda", "alias": "Imobiliária Horizonte", "email": "contato@exemplo.com.br", "addressInformation": { "address": "Avenida Paulista", "number": "1000", "complement": "Conjunto 101", "district": "Bela Vista", "zipCode": "01310100", "city": "São Paulo", "state": "SP", "formattedZipCode": "01310-100", "complete": "Avenida Paulista, 1000, Conjunto 101, Bela Vista, 01310-100, São Paulo-SP" }, "phone1": { "number": "1133334444", "formated": "(11) 3333-4444", "formatted": "(11) 3333-4444" }, "cnpj": "11222333000181", "nire": "35300012345", "stateRegistration": "110.042.490.114", "municipalRegistration": "1.234.567-8" } ``` #### Remove um contato por CPF ou CNPJ `DELETE /partners/v1/accounts/{accountId}/contacts/{cpfOrCnpj}` - operationId: `partners_v1_contacts_delete` - Autenticação: `ApiKey` Exclui um contato da conta pelo CPF ou CNPJ, informado só com dígitos. - Valor inválido responde `400` (`CPF/CNPJ é inválido`); contato inexistente responde `400` (`Contato não existe`). - A exclusão é definitiva e não afeta documentos já assinados por essa pessoa ou empresa. **Features exigidas no plano da conta:** `contacts`, `integrations`. **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`. | | `cpfOrCnpj` | path | string | sim | CPF (11 dígitos) ou CNPJ (14 caracteres) do contato, sem pontuação. | **Respostas** | Status | Descrição | Corpo | | --- | --- | --- | | `204` | No Content | sem corpo | | `400` | Regra de negócio não satisfeita: recurso inexistente na conta, estado que não permite a operação, recurso do plano ausente ou cota atingida. O corpo (`ProblemDetailsResult`) traz as mensagens em `errors`. | [ProblemDetailsResult](#problemdetailsresult) (`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: `contacts`, `integrations`. | sem corpo | | `422` | Payload rejeitado: JSON malformado ou campos que não passaram na validação (obrigatórios, tamanhos, formatos, combinações). O corpo (`ProblemDetailsResult`) traz as mensagens em `errors` e, em `problems`, cada mensagem com o campo (`propertyName`). | [ProblemDetailsResult](#problemdetailsresult) (`application/json`) | ### Users Usuários vinculados à conta. #### Lista paginada de usuários da conta `GET /partners/v1/accounts/{accountId}/users` - operationId: `partners_v1_users_list` - Autenticação: `ApiKey` - Situação: obsoleta (`deprecated`); a descrição indica o substituto **Obsoleto.** Substituído por `partners_v2_users_list` na [Partners API v2](https://api.letssign.com.br/docs/partners/v2), com paginação por `page`/`perPage`, filtro por e-mail e ordenação declarada. Continua respondendo, mas não recebe evolução. Lista os usuários da conta, com filtros por nome, situação, visibilidade e perfil, paginada por `pageIndex` e `pageSize`. 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 | ID do usuário | | `Name` | query | string | não | Nome do usuário | | `Active` | query | boolean | não | O usuário está ativo | | `Visible` | query | boolean | não | O usuário está visível | | `Profile` | query | [EProfile](#eprofile) | não | Perfil do usuário | | `pageIndex` | query | integer (int32) | sim | Número da página, a partir de 1. Padrão: `1`. | | `pageSize` | query | integer (int32) | sim | Quantidade de itens por página. Padrão: `20`. | | `sortField` | query | string | sim | Campo de ordenação. Padrão: `"Id"`. | | `sortType` | query | `"asc"` \| `"desc"` | sim | Sentido da ordenação: `asc` ou `desc`. Padrão: `"asc"`. | **Respostas** | Status | Descrição | Corpo | | --- | --- | --- | | `200` | OK | [PagedListDeprecatedOfPartnerUserAccountDto](#pagedlistdeprecatedofpartneruseraccountdto) (`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" } ], "totalPages": 1, "totalRecords": 2, "pageSize": 20 } ``` #### Adicionar usuários na conta `POST /partners/v1/accounts/{accountId}/users` - operationId: `partners_v1_users_add` - Autenticação: `ApiKey` Adiciona usuários à conta e envia a cada um o e-mail de convite com o código de acesso. - Um e-mail que já existe em outra conta do LetsSign é reaproveitado; um e-mail novo cria o usuário. - `onlyForSignature` verdadeiro cria o usuário com perfil `User` (só vê e assina os próprios documentos) e exige a feature `only_signature` no plano; falso cria como `Admin`. - O lote é atômico: se qualquer e-mail já pertence à conta, ninguém é adicionado e a resposta `400` lista os repetidos. - Conta inativa ou sem plano ativo responde `400`. A resposta traz os usuários adicionados. **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`. | **Corpo da requisição** (`application/json`, obrigatório) Schema: [AddUsersInAccount](#addusersinaccount) ```json { "users": [ { "firstName": "Ana", "lastName": "Pereira", "email": "ana.pereira@exemplo.com.br", "onlyForSignature": false }, { "firstName": "Bruno", "lastName": "Costa", "email": "bruno.costa@exemplo.com.br", "onlyForSignature": true } ] } ``` **Respostas** | Status | Descrição | Corpo | | --- | --- | --- | | `200` | OK | [PartnerUserAccountDto](#partneruseraccountdto)[] (`application/json`) | | `400` | Regra de negócio não satisfeita: recurso inexistente na conta, estado que não permite a operação, recurso do plano ausente ou cota atingida. O corpo (`ProblemDetailsResult`) traz as mensagens em `errors`. | [ProblemDetailsResult](#problemdetailsresult) (`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 | | `422` | Payload rejeitado: JSON malformado ou campos que não passaram na validação (obrigatórios, tamanhos, formatos, combinações). O corpo (`ProblemDetailsResult`) traz as mensagens em `errors` e, em `problems`, cada mensagem com o campo (`propertyName`). | [ProblemDetailsResult](#problemdetailsresult) (`application/json`) | Exemplo de resposta `200`: ```json [ { "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" } ] ``` #### Alterar status de um usuário da conta `PATCH /partners/v1/accounts/{accountId}/users/{id}/change-status` - operationId: `partners_v1_users_change_status` - Autenticação: `ApiKey` Inverte a situação do usuário na conta: ativo passa a inativo e inativo passa a ativo. Não recebe corpo. - Usuário inativo perde o acesso à conta, mas mantém o histórico. - Usuário inexistente ou de outra conta responde `400` (`Usuário não existe`). - Evite desativar o usuário de integração da conta: as operações da API que criam documentos e formulários dependem dele. **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` | path | string (uuid) | sim | Identificador do usuário na conta. | **Respostas** | Status | Descrição | Corpo | | --- | --- | --- | | `200` | OK | [PartnerUserAccountDto](#partneruseraccountdto) (`application/json`) | | `400` | Regra de negócio não satisfeita: recurso inexistente na conta, estado que não permite a operação, recurso do plano ausente ou cota atingida. O corpo (`ProblemDetailsResult`) traz as mensagens em `errors`. | [ProblemDetailsResult](#problemdetailsresult) (`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 | | `422` | Payload rejeitado: JSON malformado ou campos que não passaram na validação (obrigatórios, tamanhos, formatos, combinações). O corpo (`ProblemDetailsResult`) traz as mensagens em `errors` e, em `problems`, cada mensagem com o campo (`propertyName`). | [ProblemDetailsResult](#problemdetailsresult) (`application/json`) | Exemplo de resposta `200`: ```json { "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": false, "profile": "User", "profileDescription": "Usuário" } ``` ### Groups Grupos de usuários da conta. #### Lista grupos da conta `GET /partners/v1/accounts/{accountId}/groups` - operationId: `partners_v1_groups_list` - Autenticação: `ApiKey` Lista os grupos ativos da conta, em ordem alfabética. Grupos controlam o acesso a pastas e documentos. Os ids daqui são os aceitos em `groups` por `partners_v1_document_signatures_create_from_file`, `partners_v1_forms_create` e `partners_v1_documents_update_groups`. - Grupo desativado no aplicativo sai desta lista e deixa de ser aceito: o id passa a responder `422` nos três endpoints acima e não aparece mais em `groups` nas listagens de documento. O vínculo em si continua na base: devolver em `partners_v1_documents_update_groups` a lista de `groups` lida do documento remove em definitivo o vínculo com o grupo desativado. Ativar e desativar é operação do aplicativo — esta API não altera grupo. - Pode responder de um cache de até 3 horas. Não há paginação. Somente leitura. **Features exigidas no plano da conta:** `groups`. **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`. | **Respostas** | Status | Descrição | Corpo | | --- | --- | --- | | `200` | OK | [GroupSimplifiedDto](#groupsimplifieddto)[] (`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: `groups`. | sem corpo | Exemplo de resposta `200`: ```json [ { "id": "01991444-8e9f-7a0b-9c2d-3e4f5a6b7c8d", "name": "Comercial" }, { "id": "0199144b-f5a6-7b7c-8d8e-9f0a1b2c3d4e", "name": "Jurídico" } ] ``` ### DocumentSignatureRoles Papéis de signatário disponíveis na conta (o "assinar como": parte, testemunha e outros). #### Lista de papéis de signatários (Assinar como) `GET /partners/v1/accounts/{accountId}/document-signature-roles` - operationId: `partners_v1_document_signature_roles_list` - Autenticação: `ApiKey` Lista os nomes dos papéis de assinatura ativos na conta (o "assina como" do signatário), para uso em `role` ao criar ou editar signatários. - Toda conta nasce com os papéis padrão (`Parte`, `Testemunha`, `Aprovador`, `Contratante`, `Contratada`, entre outros) e pode criar os seus no aplicativo. - `Aprovador` muda o fluxo: o signatário aprova em vez de assinar. Ele vem primeiro; os demais em ordem alfabética. - Pode responder de um cache de até 1 hora. 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`. | **Respostas** | Status | Descrição | Corpo | | --- | --- | --- | | `200` | OK | string[] (`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 [ "Aprovador", "Acionista", "Advogado(a)", "Contratada", "Contratante", "Parte", "Testemunha" ] ``` ### InformationFields Campos de informação configurados na conta, que podem ser preenchidos em cada documento. #### Lista campos de informação `GET /partners/v1/accounts/{accountId}/information-fields` - operationId: `partners_v1_information_fields_list` - Autenticação: `ApiKey` Lista os campos de informação definidos na conta, com o tipo que determina o formato do valor (`Text`, `FormattedText`, `Date`, `Money`, `Number`, `Percentage`, `Party`). Use o `id` em `informations[].informationFieldId` ao criar documentos ou em `partners_v1_documents_informations_upsert`. - Ordem alfabética. Não há paginação. Somente leitura. **Features exigidas no plano da conta:** `document_informations`. **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`. | **Respostas** | Status | Descrição | Corpo | | --- | --- | --- | | `200` | OK | [InformationFieldDto](#informationfielddto)[] (`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: `document_informations`. | sem corpo | Exemplo de resposta `200`: ```json [ { "id": "0199143d-3f4a-7b5c-8d6e-7f8a9b0c1d2e", "name": "Número do contrato", "type": "Text", "typeDescription": "Texto curto" }, { "id": "0199144c-f6a7-7b8c-8d9e-0a1b2c3d4e5f", "name": "Valor do contrato", "type": "Money", "typeDescription": "Moeda" } ] ``` ### FormTemplates Modelos de formulário da conta, base para criar documentos a partir de campos preenchidos. #### Lista modelos de formulários da conta `GET /partners/v1/accounts/{accountId}/form-templates` - operationId: `partners_v1_form_templates_list` - Autenticação: `ApiKey` Lista os modelos de formulário ativos da conta, com os campos de cada um (`fields`): tag, tipo, enunciado, obrigatoriedade e opções. As tags são o que `partners_v1_forms_create` espera em `fillers[].fieldsTags` e `filledFields[].tag`. - Pode responder de um cache de até 3 horas. Ordem alfabética. Somente leitura. **Features exigidas no plano da conta:** `custom_models`, `default_models`. **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`. | **Respostas** | Status | Descrição | Corpo | | --- | --- | --- | | `200` | OK | [SimpleFormTemplateDto](#simpleformtemplatedto)[] (`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: `custom_models`, `default_models`. | sem corpo | Exemplo de resposta `200`: ```json [ { "id": "01991442-6c7d-7e8f-9a0b-1c2d3e4f5a6b", "source": "File", "name": "Ficha cadastral de locatário", "slug": "ficha-cadastral-de-locatario", "instructions": "Preencha os dados conforme o documento de identidade.", "finalMessage": "Obrigado! Em breve você receberá o contrato para assinatura.", "fields": [ { "id": "01991445-9fa0-7b1c-8d2e-3f4a5b6c7d8e", "formTemplateId": "01991442-6c7d-7e8f-9a0b-1c2d3e4f5a6b", "type": "Text", "typeDescription": "Resposta curta", "tag": "nome_locatario", "name": "Nome do locatário", "statement": "Informe o nome completo do locatário", "required": true, "capitalize": false, "writeOut": false, "order": 1, "possibleValues": [] }, { "id": "01991445-9fa0-7b1c-8d2e-3f4a5b6c7d8f", "formTemplateId": "01991442-6c7d-7e8f-9a0b-1c2d3e4f5a6b", "type": "Cpf", "typeDescription": "CPF", "tag": "cpf_locatario", "name": "CPF do locatário", "statement": "Informe o CPF do locatário", "required": true, "capitalize": false, "writeOut": false, "order": 2, "possibleValues": [] }, { "id": "01991445-9fa0-7b1c-8d2e-3f4a5b6c7d90", "formTemplateId": "01991442-6c7d-7e8f-9a0b-1c2d3e4f5a6b", "type": "LongText", "typeDescription": "Parágrafo", "tag": "endereco_locatario", "name": "Endereço do locatário", "statement": "Informe o endereço completo", "required": true, "capitalize": false, "writeOut": false, "order": 3, "possibleValues": [] }, { "id": "01991445-9fa0-7b1c-8d2e-3f4a5b6c7d91", "formTemplateId": "01991442-6c7d-7e8f-9a0b-1c2d3e4f5a6b", "type": "Currency", "typeDescription": "Moeda", "tag": "valor_aluguel", "name": "Valor do aluguel", "statement": "Valor mensal do aluguel", "required": true, "capitalize": false, "writeOut": true, "order": 4, "possibleValues": [] }, { "id": "01991445-9fa0-7b1c-8d2e-3f4a5b6c7d92", "formTemplateId": "01991442-6c7d-7e8f-9a0b-1c2d3e4f5a6b", "type": "Select", "typeDescription": "Lista suspensa", "tag": "dia_vencimento", "name": "Dia de vencimento", "statement": "Escolha o dia de vencimento", "required": true, "capitalize": false, "writeOut": false, "order": 5, "possibleValues": [ "5", "10", "15" ] } ] } ] ``` ### Forms Criação de documentos a partir de um modelo de formulário preenchido. #### Criação de formulários da conta `POST /partners/v1/accounts/{accountId}/forms` - operationId: `partners_v1_forms_create` - Autenticação: `ApiKey` Cria um formulário a partir de um modelo da conta e o documento que será gerado com as respostas. O documento nasce com status `WaitingFormFill`; quando o formulário estiver completo, o PDF é gerado e o documento pode receber assinaturas por `partners_v1_documents_request_signatures`. - Toda tag do modelo precisa estar em `fillers[].fieldsTags` ou em `filledFields`, e cada tag só pode aparecer uma vez. Faltando tag, a resposta `400` lista quais. - Cada pessoa em `fillers` recebe um e-mail com o link para preencher os seus campos. Campos em `filledFields` já entram preenchidos; se tudo for preenchido aqui, o documento é gerado de imediato. - `groups` restringe quais grupos de acesso da conta veem o documento gerado (`partners_v1_groups_list`). Só aceita grupo **ativo** da própria conta; grupo inexistente, inativo ou de outra conta responde `422` citando os ids recusados. Omitido ou vazio, o documento não recebe grupo próprio e quem o vê é decidido pelos grupos da pasta. - Quando o formulário fica completo, os usuários em `notifiables` são avisados e o webhook `FormFilled` é disparado. - Exige um usuário de integração definido na conta; sem ele responde `400`. Consome um documento da cota do plano. - Não há chave de idempotência: cada chamada cria um formulário e um documento novos. A resposta traz o `id` do formulário e o `documentId`. **Features exigidas no plano da conta:** `custom_models`, `default_models`. **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`. | **Corpo da requisição** (`application/json`, obrigatório) Schema: [RegisterForm](#registerform) ```json { "name": "Ficha cadastral - Maria da Silva", "formTemplateId": "01991442-6c7d-7e8f-9a0b-1c2d3e4f5a6b", "instructions": "Preencha os dados do locatário exatamente como constam no documento de identidade.", "finalMessage": "Obrigado! Em breve você receberá o contrato para assinatura.", "folderId": "0199143c-2e3f-7a4b-9c5d-6e7f8a9b0c1d", "notifiables": [ "financeiro@exemplo.com.br" ], "groups": [ "01991444-8e9f-7a0b-9c2d-3e4f5a6b7c8d" ], "fillers": [ { "name": "Maria da Silva", "email": "maria.silva@exemplo.com.br", "fieldsTags": [ "nome_locatario", "cpf_locatario", "endereco_locatario" ] } ], "filledFields": [ { "tag": "valor_aluguel", "value": "2500.00" }, { "tag": "dia_vencimento", "value": "5" } ] } ``` **Respostas** | Status | Descrição | Corpo | | --- | --- | --- | | `201` | Created | [FormCreatedDto](#formcreateddto) (`application/json`) | | `400` | Regra de negócio não satisfeita: recurso inexistente na conta, estado que não permite a operação, recurso do plano ausente ou cota atingida. O corpo (`ProblemDetailsResult`) traz as mensagens em `errors`. | [ProblemDetailsResult](#problemdetailsresult) (`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: `custom_models`, `default_models`. | sem corpo | | `422` | Payload rejeitado: JSON malformado ou campos que não passaram na validação (obrigatórios, tamanhos, formatos, combinações). O corpo (`ProblemDetailsResult`) traz as mensagens em `errors` e, em `problems`, cada mensagem com o campo (`propertyName`). | [ProblemDetailsResult](#problemdetailsresult) (`application/json`) | Exemplo de resposta `201`: ```json { "id": "01991443-7d8e-7f9a-8b1c-2d3e4f5a6b7c", "documentId": "01991440-5a6b-7c8d-9e0f-1a2b3c4d5e6f" } ``` ### Plans Planos vinculados ao parceiro. Não exige `accountId`. #### Lista de planos vínculados ao parceiro `GET /partners/v1/plans` - operationId: `partners_v1_plans_list` - Autenticação: `ApiKey` Lista os planos ativos vinculados ao parceiro: os planos que a equipe LetsSign pode atribuir às contas do parceiro. - Não recebe `accountId`: a lista é do parceiro, não de uma conta. - `name` filtra por trecho do nome, sem diferenciar maiúsculas. Ordem alfabética. - Somente leitura, sem efeitos colaterais. **Parâmetros** | Nome | Em | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | --- | | `name` | query | string | não | Filtra pelo nome contendo o texto informado, sem diferenciar maiúsculas de minúsculas. | **Respostas** | Status | Descrição | Corpo | | --- | --- | --- | | `200` | OK | [PlanSimplifiedDto](#plansimplifieddto)[] (`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 [ { "id": "profissional", "name": "Profissional", "description": "Até 200 documentos por mês, com SMS e WhatsApp." } ] ``` ## 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. ### AccountWebHookDto | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `id` | string (uuid) | não | Identificador do webhook. Exemplo: `"0199143e-4a5b-7c6d-9e7f-8a9b0c1d2e3f"`. | | `accountId` | string (uuid) | não | Identificador da conta. Exemplo: `"0199143a-7c2e-7b1a-9f2d-3c4b5a6d7e8f"`. | | `uri` | string | não | URL que recebe os eventos. Exemplo: `"https://integracao.exemplo.com.br/letssign/webhook"`. | | `available` | boolean | não | Verdadeiro quando a URL respondeu 2xx ao evento `Test` enviado no cadastro. Exemplo: `true`. | | `createdAt` | string (date-time) | não | Data e hora do cadastro. Exemplo: `"2026-08-20T14:05:00Z"`. | ### AddDocumentInformation | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `informationFieldId` | string (uuid) | sim | Identificador do campo de informação da conta (`partners_v1_information_fields_list`). Exemplo: `"0199143d-3f4a-7b5c-8d6e-7f8a9b0c1d2e"`. | | `value` | string | sim | Valor, sempre como texto, no formato do tipo do campo: `Text` e `FormattedText` aceitam texto livre; `Date` exige `YYYY-MM-DD`; `Money`, `Number` e `Percentage` exigem número com ponto decimal (ex.: `1999.99`); `Party` exige o id, o CPF ou o CNPJ de um contato da conta. Exemplo: `"CT-2026-0451"`. | ### AddSigner | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `role` | string | sim | Papel com que assina (ex.: `Parte`, `Testemunha`). Use um dos nomes de `partners_v1_document_signature_roles_list`. Exemplo: `"Testemunha"`. | | `ipAddress` | string \| null | não | IP do usuário final que originou a ação no sistema do parceiro, gravado na trilha de auditoria. Se vazio, usa o IP da requisição. Exemplo: `"203.0.113.10"`. | | `signatureAreas` | [SimpleSignatureAreaItem](#simplesignatureareaitem)[] | não | Posições onde a assinatura e a rubrica deste signatário são carimbadas no PDF. | | `email` | string (email) | sim | E-mail do signatário. Identifica o signatário no documento e recebe o link de assinatura quando `signatureLinkMethod` é `Email`. Até 255 caracteres. Exemplo: `"maria.silva@exemplo.com.br"`. | | `name` | string \| null | não | Nome do signatário, exibido nas comunicações e pré-preenchido na assinatura. Até 255 caracteres. Exemplo: `"Maria da Silva"`. | | `documentNumber` | string \| null | não | CPF do signatário, somente dígitos ou com pontuação. Quando informado, deve ser válido; na assinatura o CPF digitado precisa coincidir. Até 30 caracteres. Exemplo: `"11144477735"`. | | `birthDate` | string (date-time) \| null | não | Data de nascimento do signatário, pré-preenchida na assinatura. Exemplo: `"1988-05-17T00:00:00Z"`. | | `authenticationMethod` | `"Email"` \| `"Sms"` \| `"WhatsApp"` \| `"DigitalCertificate"` \| `"NoAuthentication"` \| `"FaceToFace"` \| null | não | Como o signatário comprova a identidade ao assinar. `Sms` e `WhatsApp` exigem `telephone`; `DigitalCertificate` exige `requireDocumentNumber` verdadeiro. Sem valor, `Email`. `Email` (E-mail), `Sms` (SMS), `WhatsApp` (WhatsApp), `DigitalCertificate` (Certificado Digital), `NoAuthentication` (Sem Autenticação), `FaceToFace` (Assinatura presencial). Padrão: `"Email"`. Exemplo: `"Email"`. | | `additionalAuthenticationMethods` | [EAdditionalAuthenticationMethod](#eadditionalauthenticationmethod)[] \| null | não | Evidências adicionais exigidas na assinatura (selfie, documento com foto, biometria facial). Biometria facial, com ou sem prova de vida, deve ser o único item da lista. Exemplo: `["SelfieWithFacialBiometrics"]`. | | `telephoneCountryCode` | string \| null | não | Código do país do telefone do signatário, somente dígitos. Sem valor, `55` (Brasil). Exemplo: `"55"`. | | `telephone` | string \| null | não | Telefone do signatário com DDD, somente dígitos (mínimo 8). Obrigatório quando `authenticationMethod` é `Sms` ou `WhatsApp`: o código de confirmação vai para este número. Exemplo: `"11987654321"`. | | `signatureLinkMethod` | [ESignatureLinkMethod](#esignaturelinkmethod) \| null | não | Canal pelo qual o link de assinatura é enviado. Sem valor, o link vai por e-mail; `NotSend` cria a assinatura sem notificar (o parceiro conduz o signatário). Exemplo: `"WhatsApp"`. | | `signatureLinkTelephoneCountryCode` | string \| null | não | Código do país do telefone que recebe o link de assinatura por SMS ou WhatsApp. Sem valor, `55`. Exemplo: `"55"`. | | `signatureLinkTelephone` | string \| null | não | Telefone com DDD, somente dígitos, que recebe o link de assinatura quando `signatureLinkMethod` é `Sms` ou `WhatsApp`. Sem valor, usa `telephone`. Exemplo: `"11987654321"`. | | `requireDocumentNumber` | boolean \| null | não | Exige que o signatário informe o CPF ao assinar. Sem valor, verdadeiro. Obrigatoriamente verdadeiro com `DigitalCertificate`. Padrão: `true`. Exemplo: `true`. | | `substitutes` | [SubstituteSigner](#substitutesigner)[] | não | Suplentes que podem assinar no lugar do titular. Recebem o mesmo link; a assinatura de um deles conclui a etapa. E-mails não podem repetir nem coincidir com o titular. | | `language` | [EAppLanguage](#eapplanguage) \| null | não | Idioma das comunicações e da página de assinatura deste signatário. Sem valor, português. Exemplo: `"Portuguese"`. | | `saveAsContact` | boolean | não | Grava o signatário como contato da conta (pessoa, pelo CPF) ao criar a assinatura. Exemplo: `false`. | ### AddUserInAccount | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `firstName` | string | sim | Primeiro nome do usuário. Até 100 caracteres. Exemplo: `"Ana"`. | | `lastName` | string \| null | não | Sobrenome do usuário. Até 100 caracteres. Exemplo: `"Pereira"`. | | `email` | string (email) | sim | E-mail do usuário. Recebe o convite de acesso; um e-mail já cadastrado em outra conta é reaproveitado. Até 255 caracteres. Exemplo: `"ana.pereira@exemplo.com.br"`. | | `onlyForSignature` | boolean | não | Verdadeiro: perfil `User`, que só visualiza e assina documentos em que é signatário (exige a feature `only_signature` no plano). Falso: perfil `Admin`, com todas as features da conta. Exemplo: `false`. | ### AddUsersInAccount | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `users` | [AddUserInAccount](#adduserinaccount)[] | sim | Usuários a adicionar. Se qualquer e-mail já pertencer à conta, nenhum é adicionado. | ### AddressInformation | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `address` | string \| null | não | Logradouro. Até 255 caracteres. Exemplo: `"Rua das Flores"`. | | `number` | string \| null | não | Número. Até 50 caracteres. Exemplo: `"120"`. | | `complement` | string \| null | não | Complemento. Até 255 caracteres. Exemplo: `"Sala 4"`. | | `district` | string \| null | não | Bairro. Até 50 caracteres. Exemplo: `"Centro"`. | | `zipCode` | string \| null | não | CEP, com 8 dígitos ou no formato 00000-000. Até 9 caracteres. Exemplo: `"01001000"`. | | `city` | string \| null | não | Cidade. Até 100 caracteres. Exemplo: `"São Paulo"`. | | `state` | string \| null | não | Estado (sigla). Até 50 caracteres. Exemplo: `"SP"`. | | `formattedZipCode` | string \| null | não | CEP formatado (00000-000). Somente leitura. Exemplo: `"01001-000"`. | | `complete` | string \| null | não | Endereço completo em uma linha. Somente leitura. Exemplo: `"Rua das Flores, 120, Sala 4, Centro, 01001-000, São Paulo-SP"`. | ### BaseDocumentInformation | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `informationFieldId` | string (uuid) | sim | Identificador do campo de informação da conta (`partners_v1_information_fields_list`). Exemplo: `"0199143d-3f4a-7b5c-8d6e-7f8a9b0c1d2e"`. | | `value` | string | sim | Valor, sempre como texto, no formato do tipo do campo: `Text` e `FormattedText` aceitam texto livre; `Date` exige `YYYY-MM-DD`; `Money`, `Number` e `Percentage` exigem número com ponto decimal (ex.: `1999.99`); `Party` exige o id, o CPF ou o CNPJ de um contato da conta. Exemplo: `"CT-2026-0451"`. | ### CancelSignatures | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `message` | string \| null | não | Mensagem opcional incluída no aviso de cancelamento enviado aos signatários. Exemplo: `"Contrato substituído por uma nova versão; desconsidere esta solicitação."`. | ### 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`. | ### ChangeDocumentFolder | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `folderId` | string (uuid) \| null | sim | Id da pasta para onde o documento será movido. Vazio se a pasta for a raiz | ### ChangePartnerAccountLogo | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `contentFile` | string (base64) | sim | Conteúdo da imagem em base64 (PNG, JPG ou JPEG). | | `contentType` | `"image/png"` \| `"image/jpeg"` \| `"image/jpg"` | sim | Tipo MIME da imagem em `contentFile`. Exemplo: `"image/png"`. | ### CompanyDto | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `cnpj` | string | não | CNPJ, sem pontuação. Exemplo: `"11222333000181"`. | | `nire` | string \| null | não | NIRE (registro na Junta Comercial). Exemplo: `"35300012345"`. | | `stateRegistration` | string \| null | não | Inscrição estadual. Exemplo: `"110.042.490.114"`. | | `municipalRegistration` | string \| null | não | Inscrição municipal. Exemplo: `"1.234.567-8"`. | | `name` | string | não | Nome completo (pessoa) ou razão social (empresa). Exemplo: `"Maria da Silva"`. | | `alias` | string \| null | não | Apelido (pessoa) ou nome fantasia (empresa). Exemplo: `"Maria"`. | | `email` | string \| null | não | E-mail do contato. Exemplo: `"maria.silva@exemplo.com.br"`. | | `addressInformation` | [AddressInformation](#addressinformation) \| null | não | Endereço | | `phone1` | [Phone](#phone) \| null | não | Telefone 1 | | `phone2` | [Phone](#phone) \| null | não | Telefone 2 | ### CreateAccountWebhook | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `uri` | string (uri) | sim | URI do Webhook | ### CreateCategory | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `name` | string | sim | Nome da categoria, único na conta (sem diferenciar maiúsculas). Até 50 caracteres. Exemplo: `"Contratos de locação"`. | ### CreateDocumentWithSignaturesFromFile | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `documentName` | string | sim | Nome do documento, exibido aos signatários e nas listagens. Até 255 caracteres. Exemplo: `"Contrato de locação - Apto 501"`. | | `contentFile` | string (base64) | sim | Conteúdo do arquivo em base64. Aceita PDF, DOC e DOCX; DOC e DOCX são convertidos para PDF. PDF protegido por senha ou com edição bloqueada é recusado. O corpo da requisição aceita até 70 MB, o que dá cerca de 50 MB de arquivo. | | `contentType` | `"application/pdf"` \| `"application/msword"` \| `"application/vnd.openxmlformats-officedocument.wordprocessingml.document"` | sim | Tipo MIME do arquivo em `contentFile`. Deve corresponder ao conteúdo real. Exemplo: `"application/pdf"`. | | `categories` | string (uuid)[] | não | Identificadores de categorias da conta associadas ao documento (`partners_v1_categories_list`). Exemplo: `["0199143b-1d2e-7f3a-8b4c-5d6e7f8a9b0c"]`. | | `folderId` | string (uuid) \| null | não | Pasta onde o documento é criado (`partners_v1_folders_list`). Sem valor, fica na raiz. Exemplo: `"0199143c-2e3f-7a4b-9c5d-6e7f8a9b0c1d"`. | | `groups` | string (uuid)[] | não | Grupos de acesso da conta que passam a ver o documento (`partners_v1_groups_list`). Sem itens, quem vê o documento é decidido pelos grupos da pasta. Com itens, exige o recurso `groups` na conta: sem o recurso, a resposta é 400. Exemplo: `["0199143d-3f40-7b5c-8d6e-7f8a9b0c1d2e"]`. | | `ipAddress` | string \| null | não | IP do usuário final que originou a ação no sistema do parceiro, gravado na trilha de auditoria do documento. Se vazio, usa o IP da requisição. Exemplo: `"203.0.113.10"`. | | `customMessage` | string \| null | não | Mensagem personalizada incluída no e-mail e na página de assinatura enviados aos signatários. Exemplo: `"Olá! Segue o contrato de locação do apartamento 501 para assinatura até 30/09."`. | | `reminderFrequency` | [EReminderFrequency](#ereminderfrequency) \| null | não | Frequência dos lembretes automáticos enviados a quem ainda não assinou. Sem valor, nenhum lembrete automático é enviado. Exemplo: `"ThreeDays"`. | | `signers` | [SignerItem](#signeritem)[] | sim | Signatários do documento. Pelo menos um; a combinação e-mail + papel não pode repetir. | | `observers` | string[] | não | E-mails de observadores: recebem cópia do documento assinado ao final, sem assinar. Exemplo: `["financeiro@exemplo.com.br"]`. | | `signatureAreas` | [SignatureAreaItem](#signatureareaitem)[] | não | Posições (página e coordenadas em percentual) onde assinatura e rubrica são carimbadas no PDF. Sem itens, o carimbo é aplicado no padrão do sistema. | | `informations` | [BaseDocumentInformation](#basedocumentinformation)[] | não | Campos de informação gravados no documento (ex.: número do contrato). Cada campo (`informationFieldId`) pode aparecer uma vez. | | `deadlineForSignature` | string (date-time) \| null | não | Data limite para assinatura. Somente a data é considerada: o cancelamento automático ocorre no decorrer do dia informado, em horário de Brasília — o último dia integralmente disponível para assinar é o anterior. Informe a data sem fuso ou em UTC; um offset pode deslocar o dia. Não pode ser anterior à data atual. Exemplo: `"2026-09-30T12:00:00Z"`. | | `scheduledTo` | string (date-time) \| null | não | Agenda o envio das solicitações de assinatura para esta data e hora (deve ser futura). Sem valor, o envio é imediato. Exemplo: `"2026-09-04T09:00:00Z"`. | ### CreateFolder | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `parentId` | string (uuid) \| null | não | Pasta pai (`partners_v1_folders_list`). Sem valor, a pasta é criada na raiz. Exemplo: `"0199143c-2e3f-7a4b-9c5d-6e7f8a9b0c1d"`. | | `name` | string | sim | Nome da pasta, único dentro da pasta pai (sem diferenciar maiúsculas). Até 255 caracteres. Exemplo: `"Contratos 2026"`. | ### CreatedDocumentInfoDto | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `id` | string (uuid) | não | Identificador do documento, usado nas demais operações. Exemplo: `"01991440-5a6b-7c8d-9e0f-1a2b3c4d5e6f"`. | | `uri` | string | não | URL da página do documento no aplicativo, para operadores da conta (não é o link de assinatura). | ### 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"`. | ### DocumentInformationDto | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `id` | string (uuid) | não | Identificador do registro da informação no documento. Exemplo: `"01991447-b1c2-7d3e-8f4a-5b6c7d8e9f0a"`. | | `informationFieldId` | string (uuid) | não | Identificador do campo de informação da conta. Exemplo: `"0199143d-3f4a-7b5c-8d6e-7f8a9b0c1d2e"`. | | `informationField` | [InformationFieldDto](#informationfielddto) \| null | não | Campo de informação da conta (nome e tipo). | | `value` | string | não | Valor gravado, como texto. Exemplo: `"CT-2026-0451"`. | | `unformattedValue` | string \| null | não | Valor sem marcação HTML, presente só em campos `FormattedText`. | ### 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. | ### DocumentSignatureAreaDto | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `id` | string (uuid) | não | Identificador da posição. Exemplo: `"01991448-c2d3-7e4f-9a5b-6c7d8e9f0a1b"`. | | `type` | [ESignatureType](#esignaturetype) | não | O que é carimbado na posição: assinatura, rubrica ou carimbo. Exemplo: `"Signature"`. | | `typeDescription` | string \| null | não | Tipo por extenso em português. Exemplo: `"Assinatura"`. | | `x` | number (double) | não | Posição horizontal em percentual da largura da página. Exemplo: `12.5`. | | `y` | number (double) | não | Posição vertical em percentual da altura da página. Exemplo: `78`. | | `height` | number (double) | não | Altura em percentual da altura da página. Exemplo: `5`. | | `width` | number (double) | não | Largura em percentual da largura da página. Exemplo: `15`. | | `page` | integer (int32) | não | Página do documento, a partir de 1. Exemplo: `3`. | | `documentSignatureId` | string (uuid) | não | Identificador da assinatura (signatário) dona da posição. Exemplo: `"01991441-0a1b-7c2d-8e3f-4a5b6c7d8e9f"`. | | `email` | string | não | E-mail do signatário. Exemplo: `"maria.silva@exemplo.com.br"`. | | `role` | string | não | Papel do signatário. Exemplo: `"Parte"`. | | `authenticationMethod` | [EAuthenticationMethod](#eauthenticationmethod) | não | Método de autenticação do signatário. Exemplo: `"Email"`. | | `authenticationMethodDescription` | string \| null | não | Método de autenticação por extenso em português. Exemplo: `"E-mail"`. | ### 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. | ### DocumentSignaturesStatusDto | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `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"`. | | `deadlineForSignature` | string (date-time) \| null | não | Prazo de assinatura do documento, 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"`. | | `signatures` | [SignatureStatusDto](#signaturestatusdto)[] | não | Um item por signatário do documento. | ### 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. | ### EAdditionalAuthenticationMethod Valores: - `SelfieWithoutFacialBiometrics`: Selfie (sem biometria facial) - `DocumentIdWithPhoto`: Documento com foto - `SelfieWithFacialBiometrics`: Selfie (com biometria facial) - `SelfieWithFacialBiometricsAndLiveness`: Selfie (com biometria facial e prova de vida) - `ServiceProvisionEvidence`: Evidência de prestação do serviço ### EAppLanguage Valores: - `Portuguese`: Português - `English`: Inglês - `Spanish`: Espanhol ### EAuthenticationMethod Valores: - `Email`: E-mail - `Sms`: SMS - `WhatsApp`: WhatsApp - `DigitalCertificate`: Certificado Digital - `NoAuthentication`: Sem Autenticação - `FaceToFace`: Assinatura presencial ### EDocumentFieldType Valores: - `Text`: Texto curto - `FormattedText`: Texto formatado - `Date`: Data - `Money`: Moeda - `Number`: Número - `Percentage`: Percentual - `Party`: Seleção de contato ### 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 ### EFormFieldType Valores: - `Text`: Resposta curta - `LongText`: Parágrafo - `RichText`: Texto formatado - `Date`: Data - `Number`: Número - `Currency`: Moeda - `Percentage`: Percentual - `Cpf`: CPF - `Cnpj`: CNPJ - `Radio`: Múltipla escolha - `Checkbox`: Caixas de seleção - `Select`: Lista suspensa - `DocumentGenerationData`: Data da geração do documento - `FileUpload`: Upload de arquivo ### EFormTemplateSource Valores: - `File`: Modelo criado a partir de um arquivo Word (DOCX) com marcadores - `Editor`: Modelo criado no editor de texto do aplicativo ### EMaritalStatus Valores: - `NotMarried`: Solteiro(a) - `Married`: Casado(a) - `Widower`: Viúvo(a) - `Divorced`: Divorciado(a) - `Retracted`: Desquitado(a) - `Companion`: Companheiro(a) - `Others`: Outros ### EPersonType Valores: - `Individual`: Fisíca - `Company`: Jurídica ### 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 ### ESignatureLinkMethod Valores: - `NotSend`: Não enviar - `Email`: E-mail - `Sms`: SMS - `WhatsApp`: WhatsApp ### ESignatureType Valores: - `Signature`: Assinatura - `Initials`: Rúbrica - `Stamp`: Carimbo / Selo ### EditSigner | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `role` | string | sim | Papel com que assina (ex.: `Parte`, `Testemunha`). Use um dos nomes de `partners_v1_document_signature_roles_list`. Exemplo: `"Parte"`. | | `ipAddress` | string \| null | não | IP do usuário final que originou a ação no sistema do parceiro, gravado na trilha de auditoria. Se vazio, usa o IP da requisição. Exemplo: `"203.0.113.10"`. | | `resendLinkAfterEdit` | boolean | não | Reenvia o link de assinatura ao signatário logo após a edição, pelo canal em `signatureLinkMethod`. Sem valor, não reenvia. Exemplo: `true`. | | `email` | string (email) | sim | E-mail do signatário. Identifica o signatário no documento e recebe o link de assinatura quando `signatureLinkMethod` é `Email`. Até 255 caracteres. Exemplo: `"maria.silva@exemplo.com.br"`. | | `name` | string \| null | não | Nome do signatário, exibido nas comunicações e pré-preenchido na assinatura. Até 255 caracteres. Exemplo: `"Maria da Silva"`. | | `documentNumber` | string \| null | não | CPF do signatário, somente dígitos ou com pontuação. Quando informado, deve ser válido; na assinatura o CPF digitado precisa coincidir. Até 30 caracteres. Exemplo: `"11144477735"`. | | `birthDate` | string (date-time) \| null | não | Data de nascimento do signatário, pré-preenchida na assinatura. Exemplo: `"1988-05-17T00:00:00Z"`. | | `authenticationMethod` | `"Email"` \| `"Sms"` \| `"WhatsApp"` \| `"DigitalCertificate"` \| `"NoAuthentication"` \| `"FaceToFace"` \| null | não | Como o signatário comprova a identidade ao assinar. `Sms` e `WhatsApp` exigem `telephone`; `DigitalCertificate` exige `requireDocumentNumber` verdadeiro. Sem valor, `Email`. `Email` (E-mail), `Sms` (SMS), `WhatsApp` (WhatsApp), `DigitalCertificate` (Certificado Digital), `NoAuthentication` (Sem Autenticação), `FaceToFace` (Assinatura presencial). Padrão: `"Email"`. Exemplo: `"Email"`. | | `additionalAuthenticationMethods` | [EAdditionalAuthenticationMethod](#eadditionalauthenticationmethod)[] \| null | não | Evidências adicionais exigidas na assinatura (selfie, documento com foto, biometria facial). Biometria facial, com ou sem prova de vida, deve ser o único item da lista. Exemplo: `["SelfieWithFacialBiometrics"]`. | | `telephoneCountryCode` | string \| null | não | Código do país do telefone do signatário, somente dígitos. Sem valor, `55` (Brasil). Exemplo: `"55"`. | | `telephone` | string \| null | não | Telefone do signatário com DDD, somente dígitos (mínimo 8). Obrigatório quando `authenticationMethod` é `Sms` ou `WhatsApp`: o código de confirmação vai para este número. Exemplo: `"11987654321"`. | | `signatureLinkMethod` | [ESignatureLinkMethod](#esignaturelinkmethod) \| null | não | Canal pelo qual o link de assinatura é enviado. Sem valor, o link vai por e-mail; `NotSend` cria a assinatura sem notificar (o parceiro conduz o signatário). Exemplo: `"WhatsApp"`. | | `signatureLinkTelephoneCountryCode` | string \| null | não | Código do país do telefone que recebe o link de assinatura por SMS ou WhatsApp. Sem valor, `55`. Exemplo: `"55"`. | | `signatureLinkTelephone` | string \| null | não | Telefone com DDD, somente dígitos, que recebe o link de assinatura quando `signatureLinkMethod` é `Sms` ou `WhatsApp`. Sem valor, usa `telephone`. Exemplo: `"11987654321"`. | | `requireDocumentNumber` | boolean \| null | não | Exige que o signatário informe o CPF ao assinar. Sem valor, verdadeiro. Obrigatoriamente verdadeiro com `DigitalCertificate`. Padrão: `true`. Exemplo: `true`. | | `substitutes` | [SubstituteSigner](#substitutesigner)[] | não | Suplentes que podem assinar no lugar do titular. Recebem o mesmo link; a assinatura de um deles conclui a etapa. E-mails não podem repetir nem coincidir com o titular. | | `language` | [EAppLanguage](#eapplanguage) \| null | não | Idioma das comunicações e da página de assinatura deste signatário. Sem valor, português. Exemplo: `"Portuguese"`. | | `saveAsContact` | boolean | não | Grava o signatário como contato da conta (pessoa, pelo CPF) ao criar a assinatura. Exemplo: `false`. | ### ErrorItemResult | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `message` | string | não | | | `propertyName` | string \| null | não | | ### FeatureSimplifiedDto | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `id` | string | não | Código da feature, o mesmo usado em `x-required-features`. Exemplo: `"documents_signatures"`. | | `description` | string | não | Descrição legível da feature. Exemplo: `"Assinatura de documentos"`. | ### FolderDto | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `id` | string (uuid) | não | Identificador da pasta. Exemplo: `"0199143c-2e3f-7a4b-9c5d-6e7f8a9b0c1d"`. | | `name` | string | não | Nome da pasta. Exemplo: `"Contratos 2026"`. | | `parentId` | string (uuid) \| null | não | Identificador da pasta pai. Nulo para pastas na raiz. | | `hasChildren` | boolean | não | Verdadeiro quando a pasta tem subpastas. Exemplo: `false`. | | `path` | string | não | Caminho completo, da raiz até a pasta. Exemplo: `"Contratos 2026"`. | ### FormCreatedDto | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `id` | string (uuid) | não | Identificador do formulário criado. Exemplo: `"01991443-7d8e-7f9a-8b1c-2d3e4f5a6b7c"`. | | `documentId` | string (uuid) | não | Identificador do documento gerado a partir do formulário, usado nas operações de documento. Exemplo: `"01991440-5a6b-7c8d-9e0f-1a2b3c4d5e6f"`. | ### FormFieldFillerSimplifiedDto | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `name` | string | não | Nome de quem preenche. Exemplo: `"Maria da Silva"`. | | `email` | string | não | E-mail de quem preenche. Exemplo: `"maria.silva@exemplo.com.br"`. | | `filledAt` | string (date-time) \| null | não | Data e hora do preenchimento. Nulo enquanto pendente. Exemplo: `"2026-08-21T09:30:00Z"`. | ### FormFieldSimplifiedDto | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `id` | string (uuid) | não | Identificador do campo no formulário do documento. Exemplo: `"01991446-a0b1-7c2d-9e3f-4a5b6c7d8e9f"`. | | `type` | [EFormFieldType](#eformfieldtype) \| null | não | Tipo do campo. Exemplo: `"Text"`. | | `tag` | string | não | Tag do campo no modelo. Exemplo: `"nome_locatario"`. | | `name` | string | não | Nome do campo. Exemplo: `"Nome do locatário"`. | | `statement` | string | não | Enunciado exibido a quem preenche. Exemplo: `"Informe o nome completo do locatário"`. | | `description` | string \| null | não | Texto de apoio exibido junto ao enunciado. | | `required` | boolean | não | Verdadeiro quando o preenchimento é obrigatório. Exemplo: `true`. | | `capitalize` | boolean | não | Verdadeiro quando o valor é gravado em maiúsculas no documento. Exemplo: `false`. | | `writeOut` | boolean | não | Verdadeiro quando números e datas também saem por extenso no documento. Exemplo: `false`. | | `order` | integer (int32) | não | Posição do campo no formulário. Exemplo: `1`. | | `filler` | [FormFieldFillerSimplifiedDto](#formfieldfillersimplifieddto) \| null | não | Pessoa responsável por preencher o campo. Nulo para campos preenchidos na criação. | | `value` | string \| null | não | Valor preenchido. Nulo enquanto pendente. Exemplo: `"Maria da Silva"`. | ### 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"`. | ### FormTemplateFieldDto | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `formTemplateId` | string (uuid) | não | Identificador do modelo de formulário ao qual o campo pertence. Exemplo: `"01991442-6c7d-7e8f-9a0b-1c2d3e4f5a6b"`. | | `id` | string (uuid) | não | Identificador do campo. Exemplo: `"01991445-9fa0-7b1c-8d2e-3f4a5b6c7d8e"`. | | `type` | [EFormFieldType](#eformfieldtype) \| null | não | Tipo do campo, que define o formato do valor aceito. Exemplo: `"Text"`. | | `typeDescription` | string \| null | não | Tipo por extenso em português. Exemplo: `"Resposta curta"`. | | `tag` | string | não | Tag do campo no modelo; identifica o campo no preenchimento. Exemplo: `"nome_locatario"`. | | `name` | string | não | Nome do campo. Exemplo: `"Nome do locatário"`. | | `statement` | string | não | Enunciado exibido a quem preenche. Exemplo: `"Informe o nome completo do locatário"`. | | `description` | string \| null | não | Texto de apoio exibido junto ao enunciado. Exemplo: `"Como consta no documento de identidade."`. | | `required` | boolean | não | Verdadeiro quando o preenchimento é obrigatório. Exemplo: `true`. | | `capitalize` | boolean | não | Verdadeiro quando o valor é gravado em maiúsculas no documento. Exemplo: `false`. | | `writeOut` | boolean | não | Verdadeiro quando números e datas também saem por extenso no documento. Exemplo: `false`. | | `order` | integer (int32) | não | Posição do campo no formulário. Exemplo: `1`. | | `possibleValues` | string[] \| null | não | Opções dos campos de escolha (`Radio`, `Checkbox`, `Select`). Vazio nos demais tipos. | ### GroupSimplifiedDto | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `id` | string (uuid) | não | Identificador do grupo. Exemplo: `"01991444-8e9f-7a0b-9c2d-3e4f5a6b7c8d"`. | | `name` | string | não | Nome do grupo. Exemplo: `"Comercial"`. | ### InformationFieldDto | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `id` | string (uuid) | não | Identificador do campo (`informationFieldId` nos documentos). Exemplo: `"0199143d-3f4a-7b5c-8d6e-7f8a9b0c1d2e"`. | | `name` | string | não | Nome do campo. Exemplo: `"Número do contrato"`. | | `type` | [EDocumentFieldType](#edocumentfieldtype) | não | Tipo do campo, que define o formato do valor aceito. Exemplo: `"Text"`. | | `typeDescription` | string \| null | não | Tipo por extenso em português. Exemplo: `"Texto curto"`. | ### PagedListDeprecatedOfCategoryDto | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `items` | [CategoryDto](#categorydto)[] | sim | Itens da página atual. | | `totalPages` | integer (int64) | não | Total de páginas para o filtro informado. Exemplo: `3`. | | `totalRecords` | integer (int64) | sim | Total de registros para o filtro informado. Exemplo: `48`. | | `additionalData` | qualquer | não | Dados adicionais. Sempre nulo nas listagens da Partners API. | | `pageSize` | integer (int64) | sim | Quantidade de itens por página usada na consulta. Exemplo: `20`. | ### PagedListDeprecatedOfDocumentDto | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `items` | [DocumentDto](#documentdto)[] | sim | Itens da página atual. | | `totalPages` | integer (int64) | não | Total de páginas para o filtro informado. Exemplo: `3`. | | `totalRecords` | integer (int64) | sim | Total de registros para o filtro informado. Exemplo: `48`. | | `additionalData` | qualquer | não | Dados adicionais. Sempre nulo nas listagens da Partners API. | | `pageSize` | integer (int64) | sim | Quantidade de itens por página usada na consulta. Exemplo: `20`. | ### PagedListDeprecatedOfPartnerUserAccountDto | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `items` | [PartnerUserAccountDto](#partneruseraccountdto)[] | sim | Itens da página atual. | | `totalPages` | integer (int64) | não | Total de páginas para o filtro informado. Exemplo: `3`. | | `totalRecords` | integer (int64) | sim | Total de registros para o filtro informado. Exemplo: `48`. | | `additionalData` | qualquer | não | Dados adicionais. Sempre nulo nas listagens da Partners API. | | `pageSize` | integer (int64) | sim | Quantidade de itens por página usada na consulta. Exemplo: `20`. | ### PartnerAccountDto | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `id` | string (uuid) | não | Identificador da conta: o `accountId` das demais rotas. Exemplo: `"0199143a-7c2e-7b1a-9f2d-3c4b5a6d7e8f"`. | | `name` | string | não | Nome da conta. Exemplo: `"Imobiliária Horizonte"`. | | `companyName` | string \| null | não | Razão social, quando a conta é de uma empresa. Exemplo: `"Horizonte Negócios Imobiliários Ltda"`. | | `createdAt` | string (date-time) | não | Data e hora de criação da conta. Exemplo: `"2025-03-12T13:45:10Z"`. | | `isTrial` | boolean | não | Verdadeiro quando a conta está em período de teste. Exemplo: `false`. | | `initDate` | string (date-time) \| null | não | Início da vigência do plano. Exemplo: `"2025-03-12T00:00:00Z"`. | | `endDate` | string (date-time) \| null | não | Fim da vigência do plano, quando há prazo definido. | | `personType` | [EPersonType](#epersontype) \| null | não | Tipo do titular da conta: pessoa física ou jurídica. Exemplo: `"Company"`. | | `documentNumber` | string \| null | não | CPF ou CNPJ do titular, somente dígitos. Exemplo: `"11222333000181"`. | | `active` | boolean \| null | não | Verdadeiro quando a conta está ativa. Exemplo: `true`. | ### PartnerAccountLogoDto | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `logo` | string | sim | URL pública do logotipo, com um parâmetro `q` que muda a cada troca para invalidar caches. | ### 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"`. | ### PersonDto | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `cpf` | string | não | CPF, somente dígitos. Exemplo: `"11144477735"`. | | `rg` | string \| null | não | Número do RG. Exemplo: `"12.345.678-9"`. | | `issuingAgency` | string \| null | não | Órgão emissor do RG. Exemplo: `"SSP"`. | | `stateIssuingAgency` | string \| null | não | UF do órgão emissor do RG. Exemplo: `"SP"`. | | `nationality` | string \| null | não | Nacionalidade. Exemplo: `"Brasileira"`. | | `profession` | string \| null | não | Profissão. Exemplo: `"Arquiteta"`. | | `maritalStatus` | [EMaritalStatus](#emaritalstatus) \| null | não | Estado civil. Exemplo: `"Married"`. | | `name` | string | não | Nome completo (pessoa) ou razão social (empresa). Exemplo: `"Maria da Silva"`. | | `alias` | string \| null | não | Apelido (pessoa) ou nome fantasia (empresa). Exemplo: `"Maria"`. | | `email` | string \| null | não | E-mail do contato. Exemplo: `"maria.silva@exemplo.com.br"`. | | `addressInformation` | [AddressInformation](#addressinformation) \| null | não | Endereço | | `phone1` | [Phone](#phone) \| null | não | Telefone 1 | | `phone2` | [Phone](#phone) \| null | não | Telefone 2 | ### Phone | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `number` | string \| null | não | Número com DDD, somente dígitos. Até 30 caracteres. Exemplo: `"11987654321"`. | | `formated` | string \| null | não | Número formatado para exibição. Somente leitura. Exemplo: `"(11) 9-8765-4321"`. | | `formatted` | string \| null | não | Número formatado para exibição. Somente leitura. Exemplo: `"(11) 9-8765-4321"`. | ### PlanSimplifiedDto | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `id` | string | não | Identificador do plano. Exemplo: `"profissional"`. | | `name` | string | não | Nome do plano. Exemplo: `"Profissional"`. | | `description` | string \| null | não | Descrição comercial do plano. Exemplo: `"Até 200 documentos por mês, com SMS e WhatsApp."`. | ### ProblemDetailsResult Corpo de erro da API (Problem Details, RFC 9457), enviado com `Content-Type: application/problem+json`. | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `type` | string \| null | não | URI que identifica o tipo do problema (RFC 9457). | | `title` | string \| null | não | Resumo curto do problema. | | `status` | integer (int32) \| null | não | Código HTTP da resposta. | | `detail` | string \| null | não | Explicação legível do problema. | | `instance` | string \| null | não | Método e caminho da requisição, no formato `POST /partners/v1/...`. | | `errors` | string[] | não | Mensagens de erro, uma por regra violada. | | `problems` | [ErrorItemResult](#erroritemresult)[] | não | Detalhamento estruturado dos erros, quando disponível. | | `traceId` | string | não | Identificador do trace distribuído. Informe ao suporte ao relatar um erro. | | `spanId` | string | não | Identificador do span da requisição dentro do trace. | | `requestId` | string | não | Identificador da requisição no servidor. Informe ao suporte ao relatar um erro. | ### RegisterCompany | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `cnpj` | string | sim | CNPJ válido, com ou sem pontuação. É a chave do contato na conta: um CNPJ já cadastrado é atualizado. Até 30 caracteres. Exemplo: `"11222333000181"`. | | `nire` | string \| null | não | NIRE (registro na Junta Comercial). Até 30 caracteres. Exemplo: `"35300012345"`. | | `stateRegistration` | string \| null | não | Inscrição estadual. Até 50 caracteres. Exemplo: `"110.042.490.114"`. | | `municipalRegistration` | string \| null | não | Inscrição municipal. Até 50 caracteres. Exemplo: `"1.234.567-8"`. | | `name` | string | sim | Nome completo (pessoa) ou razão social (empresa). Até 255 caracteres. Exemplo: `"Maria da Silva"`. | | `alias` | string \| null | não | Apelido (pessoa) ou nome fantasia (empresa). Até 255 caracteres. Exemplo: `"Maria"`. | | `email` | string (email) | sim | E-mail do contato. Até 255 caracteres. Exemplo: `"maria.silva@exemplo.com.br"`. | | `addressInformation` | [AddressInformation](#addressinformation) \| null | não | Endereço. Omitir na atualização apaga o endereço gravado. | | `phone1` | [Phone](#phone) \| null | não | Telefone principal. | | `phone2` | [Phone](#phone) \| null | não | Telefone secundário. | ### RegisterForm | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `name` | string | sim | Nome do documento gerado a partir do modelo de formulário. Até 255 caracteres. Exemplo: `"Ficha cadastral - Maria da Silva"`. | | `formTemplateId` | string (uuid) | sim | Modelo de formulário da conta (`partners_v1_form_templates_list`). Deve estar ativo. Exemplo: `"01991442-6c7d-7e8f-9a0b-1c2d3e4f5a6b"`. | | `instructions` | string \| null | não | Instruções exibidas a quem preenche o formulário. | | `finalMessage` | string \| null | não | Mensagem exibida após o preenchimento do formulário. Exemplo: `"Obrigado! Em breve você receberá o contrato para assinatura."`. | | `folderId` | string (uuid) \| null | não | Pasta onde o documento gerado é salvo (`partners_v1_folders_list`). Sem valor, fica na raiz. Exemplo: `"0199143c-2e3f-7a4b-9c5d-6e7f8a9b0c1d"`. | | `notifiables` | string[] \| null | não | E-mails de usuários da conta notificados quando o formulário for preenchido. Cada e-mail precisa pertencer a um usuário da conta. Exemplo: `["financeiro@exemplo.com.br"]`. | | `groups` | string (uuid)[] \| null | não | Grupos da conta aos quais o documento gerado é vinculado (`partners_v1_groups_list`). Exemplo: `["01991444-8e9f-7a0b-9c2d-3e4f5a6b7c8d"]`. | | `fillers` | [RegisterFormFiller](#registerformfiller)[] \| null | não | Pessoas que preenchem o formulário, cada uma com as tags dos campos sob sua responsabilidade. Recebem um e-mail com o link de preenchimento. | | `filledFields` | [RegisterFormFilledField](#registerformfilledfield)[] \| null | não | Campos preenchidos nesta chamada, sem depender de pessoa. Toda tag do modelo deve estar em `fillers` ou aqui; se tudo for preenchido aqui, o documento é gerado de imediato. | ### RegisterFormFilledField | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `tag` | string | sim | Tag do campo no modelo de formulário (ver `fields[].tag` em `partners_v1_form_templates_list`). Exemplo: `"valor_aluguel"`. | | `value` | string | não | Valor do campo, sempre como texto (obrigatório se o campo é requerido no modelo). Para `Checkbox`, separe os valores com `\|\|`, ex.: `Valor 1\|\|Valor 2`. Exemplo: `"2500.00"`. | ### RegisterFormFiller | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `name` | string | sim | Nome da pessoa que preenche o formulário. Até 255 caracteres. Exemplo: `"Maria da Silva"`. | | `email` | string (email) | sim | E-mail que recebe o link de preenchimento. Até 255 caracteres. Exemplo: `"maria.silva@exemplo.com.br"`. | | `fieldsTags` | string[] | não | Tags dos campos do modelo que esta pessoa preenche. Uma tag só pode aparecer em uma pessoa ou em `filledFields`. Exemplo: `["nome_locatario","cpf_locatario"]`. | ### RegisterPerson | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `cpf` | string | sim | CPF válido, com ou sem pontuação. É a chave do contato na conta: um CPF já cadastrado é atualizado. Até 30 caracteres. Exemplo: `"11144477735"`. | | `rg` | string \| null | não | Número do RG. Até 30 caracteres. Exemplo: `"12.345.678-9"`. | | `issuingAgency` | string \| null | não | Órgão emissor do RG. Até 30 caracteres. Exemplo: `"SSP"`. | | `stateIssuingAgency` | string \| null | não | UF do órgão emissor do RG (sigla com 2 letras). Até 2 caracteres. Exemplo: `"SP"`. | | `nationality` | string \| null | não | Nacionalidade. Até 100 caracteres. Exemplo: `"Brasileira"`. | | `profession` | string \| null | não | Profissão. Até 100 caracteres. Exemplo: `"Arquiteta"`. | | `maritalStatus` | [EMaritalStatus](#emaritalstatus) \| null | não | Estado civil. Exemplo: `"Married"`. | | `name` | string | sim | Nome completo (pessoa) ou razão social (empresa). Até 255 caracteres. Exemplo: `"Maria da Silva"`. | | `alias` | string \| null | não | Apelido (pessoa) ou nome fantasia (empresa). Até 255 caracteres. Exemplo: `"Maria"`. | | `email` | string (email) | sim | E-mail do contato. Até 255 caracteres. Exemplo: `"maria.silva@exemplo.com.br"`. | | `addressInformation` | [AddressInformation](#addressinformation) \| null | não | Endereço. Omitir na atualização apaga o endereço gravado. | | `phone1` | [Phone](#phone) \| null | não | Telefone principal. | | `phone2` | [Phone](#phone) \| null | não | Telefone secundário. | ### RequestDocumentSignatures | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `ipAddress` | string \| null | não | IP do usuário final que originou a ação no sistema do parceiro, gravado na trilha de auditoria do documento. Se vazio, usa o IP da requisição. Exemplo: `"203.0.113.10"`. | | `customMessage` | string \| null | não | Mensagem personalizada incluída no e-mail e na página de assinatura enviados aos signatários. Exemplo: `"Olá! Segue o contrato de locação do apartamento 501 para assinatura até 30/09."`. | | `reminderFrequency` | [EReminderFrequency](#ereminderfrequency) \| null | não | Frequência dos lembretes automáticos enviados a quem ainda não assinou. Sem valor, nenhum lembrete automático é enviado. Exemplo: `"ThreeDays"`. | | `signers` | [SignerItem](#signeritem)[] | sim | Signatários do documento. Pelo menos um; a combinação e-mail + papel não pode repetir. | | `observers` | string[] | não | E-mails de observadores: recebem cópia do documento assinado ao final, sem assinar. Exemplo: `["financeiro@exemplo.com.br"]`. | | `signatureAreas` | [SignatureAreaItem](#signatureareaitem)[] | não | Posições (página e coordenadas em percentual) onde assinatura e rubrica são carimbadas no PDF. Sem itens, o carimbo é aplicado no padrão do sistema. | | `informations` | [BaseDocumentInformation](#basedocumentinformation)[] | não | Campos de informação gravados no documento (ex.: número do contrato). Cada campo (`informationFieldId`) pode aparecer uma vez. | | `deadlineForSignature` | string (date-time) \| null | não | Data limite para assinatura. Somente a data é considerada: o cancelamento automático ocorre no decorrer do dia informado, em horário de Brasília — o último dia integralmente disponível para assinar é o anterior. Informe a data sem fuso ou em UTC; um offset pode deslocar o dia. Não pode ser anterior à data atual. Exemplo: `"2026-09-30T12:00:00Z"`. | | `scheduledTo` | string (date-time) \| null | não | Agenda o envio das solicitações de assinatura para esta data e hora (deve ser futura). Sem valor, o envio é imediato. Exemplo: `"2026-09-04T09:00:00Z"`. | ### SetDocumentGroups | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `groups` | string (uuid)[] \| null | não | Grupos de acesso da conta que passam a ver o documento (`partners_v1_groups_list`). Obrigatório: omitir o campo ou enviar `null` responde 422. O conjunto informado substitui o atual; a lista vazia remove todos os grupos do documento. Exemplo: `["0199143d-3f40-7b5c-8d6e-7f8a9b0c1d2e"]`. | ### SignatureAdditionalAuthenticationMethodsUpdatedItemDto | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `documentSignatureId` | string (uuid) | sim | | | `role` | string | sim | | | `authenticationMethod` | [EAuthenticationMethod](#eauthenticationmethod) | sim | | | `email` | string \| null | sim | | | `name` | string \| null | sim | | | `additionalAuthenticationMethods` | [EAdditionalAuthenticationMethod](#eadditionalauthenticationmethod)[] | sim | | ### SignatureAreaItem | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `authenticationMethod` | [EAuthenticationMethod](#eauthenticationmethod) | sim | Método de autenticação do signatário dono da posição; junto com `email` e `role`, identifica o item de `signers` correspondente. Exemplo: `"Email"`. | | `email` | string (email) | sim | E-mail do signatário dono da posição (o mesmo informado em `signers`). Exemplo: `"maria.silva@exemplo.com.br"`. | | `role` | string | sim | Papel do signatário dono da posição (o mesmo informado em `signers`). Exemplo: `"Parte"`. | | `type` | [ESignatureType](#esignaturetype) | sim | O que é carimbado na posição: assinatura, rubrica ou carimbo. Exemplo: `"Signature"`. | | `x` | number (double) | sim | Posição horizontal do canto superior esquerdo, em percentual da largura da página a partir da margem esquerda (0 a 100). Exemplo: `12.5`. | | `y` | number (double) | sim | Posição vertical do canto superior esquerdo, em percentual da altura da página a partir da margem superior (0 a 100). Exemplo: `78`. | | `page` | integer (int32) | sim | Página onde o carimbo é aplicado, a partir de 1. Exemplo: `3`. | | `height` | number (double) | sim | Altura do carimbo em percentual da altura da página. Zero usa o padrão (4). Recomenda-se proporção 1:3 entre altura e largura para assinatura e 1:1 para rubrica. Exemplo: `5`. | | `width` | number (double) | sim | Largura do carimbo em percentual da largura da página. Zero usa o padrão (18 para assinatura, 6 para rubrica). Exemplo: `15`. | ### SignatureStatusDto | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `id` | string (uuid) | não | Identificador da assinatura (`signatureId` nas operações de editar, remover e reenviar). Exemplo: `"01991441-0a1b-7c2d-8e3f-4a5b6c7d8e9f"`. | | `email` | string | não | E-mail do signatário. Exemplo: `"maria.silva@exemplo.com.br"`. | | `role` | string | não | Papel com que assina. Exemplo: `"Parte"`. | | `signed` | boolean | não | Verdadeiro quando o signatário já assinou. Exemplo: `true`. | | `authenticationMethod` | [EAuthenticationMethod](#eauthenticationmethod) | não | Método de autenticação configurado para a assinatura. Exemplo: `"Email"`. | | `signatureLinkMethod` | [ESignatureLinkMethod](#esignaturelinkmethod) \| null | não | Canal de envio do link de assinatura. Nulo quando segue o método de autenticação. Exemplo: `"Email"`. | | `telephone` | [Telephone](#telephone) \| null | não | Telefone do signatário, quando informado. | | `signatureLinkTelephone` | [Telephone](#telephone) \| null | não | Telefone que recebe o link de assinatura, quando diferente do principal. | | `name` | string \| null | não | Nome informado pelo signatário ao assinar (ou o nome pré-cadastrado). Exemplo: `"Maria da Silva"`. | | `documentNumberType` | string \| null | não | Tipo do documento informado ao assinar: `Cpf` ou `Cnpj`. Exemplo: `"Cpf"`. | | `documentNumber` | string \| null | não | Número do documento informado ao assinar, somente dígitos. Exemplo: `"11144477735"`. | | `birthDate` | string (date-time) \| null | não | Data de nascimento informada ao assinar. Exemplo: `"1988-05-17T00:00:00Z"`. | | `handwritten` | boolean | não | Verdadeiro quando a assinatura é desenhada à mão (há área de assinatura mapeada para o signatário). Exemplo: `true`. | | `order` | integer (int32) \| null | não | Posição na ordem de assinatura. Nulo em documentos sem ordenação. Exemplo: `1`. | | `signedAt` | string (date-time) \| null | não | Data e hora da assinatura. Nulo enquanto pendente. Exemplo: `"2026-08-21T10:12:45Z"`. | | `requireDocumentNumber` | boolean | não | Verdadeiro quando o signatário precisa informar o CPF ao assinar. Exemplo: `true`. | ### SignaturesAdditionalAuthenticationMethodsUpdatedDto | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `documentId` | string (uuid) | sim | | | `signatures` | [SignatureAdditionalAuthenticationMethodsUpdatedItemDto](#signatureadditionalauthenticationmethodsupdateditemdto)[] | sim | | ### SignerAddedDto | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `id` | string (uuid) | não | Identificador da assinatura criada (`signatureId` nas operações de editar, remover e reenviar). Exemplo: `"01991441-9f8e-7d6c-8b5a-4c3d2e1f0a9b"`. | ### 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. | ### SignerItem | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `role` | string | sim | Papel com que assina (ex.: `Parte`, `Testemunha`, `Aprovador`). Use um dos nomes de `partners_v1_document_signature_roles_list`; `Part` e `1` são aceitos como sinônimos de `Parte`. Exemplo: `"Parte"`. | | `order` | integer (int32) \| null | não | Ordem de assinatura, a partir de 1. Informe para todos os signatários ou para nenhum; a sequência deve ser contínua e sem repetição. Signatários com a mesma ordem assinam em paralelo; a próxima ordem só é notificada quando a anterior concluir. Exemplo: `1`. | | `email` | string (email) | sim | E-mail do signatário. Identifica o signatário no documento e recebe o link de assinatura quando `signatureLinkMethod` é `Email`. Até 255 caracteres. Exemplo: `"maria.silva@exemplo.com.br"`. | | `name` | string \| null | não | Nome do signatário, exibido nas comunicações e pré-preenchido na assinatura. Até 255 caracteres. Exemplo: `"Maria da Silva"`. | | `documentNumber` | string \| null | não | CPF do signatário, somente dígitos ou com pontuação. Quando informado, deve ser válido; na assinatura o CPF digitado precisa coincidir. Até 30 caracteres. Exemplo: `"11144477735"`. | | `birthDate` | string (date-time) \| null | não | Data de nascimento do signatário, pré-preenchida na assinatura. Exemplo: `"1988-05-17T00:00:00Z"`. | | `authenticationMethod` | `"Email"` \| `"Sms"` \| `"WhatsApp"` \| `"DigitalCertificate"` \| `"NoAuthentication"` \| `"FaceToFace"` \| null | não | Como o signatário comprova a identidade ao assinar. `Sms` e `WhatsApp` exigem `telephone`; `DigitalCertificate` exige `requireDocumentNumber` verdadeiro. Sem valor, `Email`. `Email` (E-mail), `Sms` (SMS), `WhatsApp` (WhatsApp), `DigitalCertificate` (Certificado Digital), `NoAuthentication` (Sem Autenticação), `FaceToFace` (Assinatura presencial). Padrão: `"Email"`. Exemplo: `"Email"`. | | `additionalAuthenticationMethods` | [EAdditionalAuthenticationMethod](#eadditionalauthenticationmethod)[] \| null | não | Evidências adicionais exigidas na assinatura (selfie, documento com foto, biometria facial). Biometria facial, com ou sem prova de vida, deve ser o único item da lista. Exemplo: `["SelfieWithFacialBiometrics"]`. | | `telephoneCountryCode` | string \| null | não | Código do país do telefone do signatário, somente dígitos. Sem valor, `55` (Brasil). Exemplo: `"55"`. | | `telephone` | string \| null | não | Telefone do signatário com DDD, somente dígitos (mínimo 8). Obrigatório quando `authenticationMethod` é `Sms` ou `WhatsApp`: o código de confirmação vai para este número. Exemplo: `"11987654321"`. | | `signatureLinkMethod` | [ESignatureLinkMethod](#esignaturelinkmethod) \| null | não | Canal pelo qual o link de assinatura é enviado. Sem valor, o link vai por e-mail; `NotSend` cria a assinatura sem notificar (o parceiro conduz o signatário). Exemplo: `"WhatsApp"`. | | `signatureLinkTelephoneCountryCode` | string \| null | não | Código do país do telefone que recebe o link de assinatura por SMS ou WhatsApp. Sem valor, `55`. Exemplo: `"55"`. | | `signatureLinkTelephone` | string \| null | não | Telefone com DDD, somente dígitos, que recebe o link de assinatura quando `signatureLinkMethod` é `Sms` ou `WhatsApp`. Sem valor, usa `telephone`. Exemplo: `"11987654321"`. | | `requireDocumentNumber` | boolean \| null | não | Exige que o signatário informe o CPF ao assinar. Sem valor, verdadeiro. Obrigatoriamente verdadeiro com `DigitalCertificate`. Padrão: `true`. Exemplo: `true`. | | `substitutes` | [SubstituteSigner](#substitutesigner)[] | não | Suplentes que podem assinar no lugar do titular. Recebem o mesmo link; a assinatura de um deles conclui a etapa. E-mails não podem repetir nem coincidir com o titular. | | `language` | [EAppLanguage](#eapplanguage) \| null | não | Idioma das comunicações e da página de assinatura deste signatário. Sem valor, português. Exemplo: `"Portuguese"`. | | `saveAsContact` | boolean | não | Grava o signatário como contato da conta (pessoa, pelo CPF) ao criar a assinatura. Exemplo: `false`. | ### SimpleFormTemplateDto | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `id` | string (uuid) | não | Identificador do modelo de formulário (`formTemplateId` em `partners_v1_forms_create`). Exemplo: `"01991442-6c7d-7e8f-9a0b-1c2d3e4f5a6b"`. | | `source` | [EFormTemplateSource](#eformtemplatesource) | não | Origem do modelo: arquivo Word com marcadores ou editor do aplicativo. Exemplo: `"File"`. | | `name` | string | não | Nome do modelo. Exemplo: `"Ficha cadastral de locatário"`. | | `slug` | string | não | Identificador legível do modelo, único na conta. Exemplo: `"ficha-cadastral-de-locatario"`. | | `instructions` | string \| null | não | Instruções padrão exibidas a quem preenche. Exemplo: `"Preencha os dados conforme o documento de identidade."`. | | `finalMessage` | string \| null | não | Mensagem padrão exibida após o preenchimento. Exemplo: `"Obrigado! Em breve você receberá o contrato para assinatura."`. | | `fields` | [FormTemplateFieldDto](#formtemplatefielddto)[] | não | Campos do modelo; as tags são usadas em `fillers[].fieldsTags` e `filledFields[].tag`. | ### SimpleSignatureAreaItem | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `type` | [ESignatureType](#esignaturetype) | sim | O que é carimbado na posição: assinatura, rubrica ou carimbo. Exemplo: `"Signature"`. | | `x` | number (double) | sim | Posição horizontal do canto superior esquerdo, em percentual da largura da página a partir da margem esquerda (0 a 100). Exemplo: `12.5`. | | `y` | number (double) | sim | Posição vertical do canto superior esquerdo, em percentual da altura da página a partir da margem superior (0 a 100). Exemplo: `78`. | | `page` | integer (int32) | sim | Página onde o carimbo é aplicado, a partir de 1. Exemplo: `3`. | | `height` | number (double) | sim | Altura do carimbo em percentual da altura da página. Zero usa o padrão (4). Recomenda-se proporção 1:3 entre altura e largura para assinatura e 1:1 para rubrica. Exemplo: `5`. | | `width` | number (double) | sim | Largura do carimbo em percentual da largura da página. Zero usa o padrão (18 para assinatura, 6 para rubrica). Exemplo: `15`. | ### SubstituteSigner | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `email` | string (email) | sim | E-mail do signatário. Identifica o signatário no documento e recebe o link de assinatura quando `signatureLinkMethod` é `Email`. Até 255 caracteres. Exemplo: `"maria.silva@exemplo.com.br"`. | | `name` | string \| null | não | Nome do signatário, exibido nas comunicações e pré-preenchido na assinatura. Até 255 caracteres. Exemplo: `"Maria da Silva"`. | | `documentNumber` | string \| null | não | CPF do signatário, somente dígitos ou com pontuação. Quando informado, deve ser válido; na assinatura o CPF digitado precisa coincidir. Até 30 caracteres. Exemplo: `"11144477735"`. | | `birthDate` | string (date-time) \| null | não | Data de nascimento do signatário, pré-preenchida na assinatura. Exemplo: `"1988-05-17T00:00:00Z"`. | | `authenticationMethod` | `"Email"` \| `"Sms"` \| `"WhatsApp"` \| `"DigitalCertificate"` \| `"NoAuthentication"` \| `"FaceToFace"` \| null | não | Como o signatário comprova a identidade ao assinar. `Sms` e `WhatsApp` exigem `telephone`; `DigitalCertificate` exige `requireDocumentNumber` verdadeiro. Sem valor, `Email`. `Email` (E-mail), `Sms` (SMS), `WhatsApp` (WhatsApp), `DigitalCertificate` (Certificado Digital), `NoAuthentication` (Sem Autenticação), `FaceToFace` (Assinatura presencial). Padrão: `"Email"`. Exemplo: `"Email"`. | | `additionalAuthenticationMethods` | [EAdditionalAuthenticationMethod](#eadditionalauthenticationmethod)[] \| null | não | Evidências adicionais exigidas na assinatura (selfie, documento com foto, biometria facial). Biometria facial, com ou sem prova de vida, deve ser o único item da lista. Exemplo: `["SelfieWithFacialBiometrics"]`. | | `telephoneCountryCode` | string \| null | não | Código do país do telefone do signatário, somente dígitos. Sem valor, `55` (Brasil). Exemplo: `"55"`. | | `telephone` | string \| null | não | Telefone do signatário com DDD, somente dígitos (mínimo 8). Obrigatório quando `authenticationMethod` é `Sms` ou `WhatsApp`: o código de confirmação vai para este número. Exemplo: `"11987654321"`. | | `signatureLinkMethod` | [ESignatureLinkMethod](#esignaturelinkmethod) \| null | não | Canal pelo qual o link de assinatura é enviado. Sem valor, o link vai por e-mail; `NotSend` cria a assinatura sem notificar (o parceiro conduz o signatário). Exemplo: `"WhatsApp"`. | | `signatureLinkTelephoneCountryCode` | string \| null | não | Código do país do telefone que recebe o link de assinatura por SMS ou WhatsApp. Sem valor, `55`. Exemplo: `"55"`. | | `signatureLinkTelephone` | string \| null | não | Telefone com DDD, somente dígitos, que recebe o link de assinatura quando `signatureLinkMethod` é `Sms` ou `WhatsApp`. Sem valor, usa `telephone`. Exemplo: `"11987654321"`. | | `requireDocumentNumber` | boolean \| null | não | Exige que o signatário informe o CPF ao assinar. Sem valor, verdadeiro. Obrigatoriamente verdadeiro com `DigitalCertificate`. Padrão: `true`. Exemplo: `true`. | | `language` | [EAppLanguage](#eapplanguage) \| null | não | Idioma das comunicações e da página de assinatura deste signatário. Sem valor, português. Exemplo: `"Portuguese"`. | | `saveAsContact` | boolean | não | Grava o signatário como contato da conta (pessoa, pelo CPF) ao criar a assinatura. Exemplo: `false`. | ### Telephone | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `countryCode` | string \| null | não | Código do país, somente dígitos. Exemplo: `"55"`. | | `number` | string \| null | não | Número com DDD, somente dígitos. Exemplo: `"11987654321"`. | | `value` | string \| null | não | Código do país seguido do número, somente dígitos. Exemplo: `"5511987654321"`. | | `formatted` | string \| null | não | Número formatado para exibição, com o código do país. Exemplo: `"+55 (11) 9-8765-4321"`. | ### 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`. | ### UpdateCategory | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `name` | string | sim | Nome da categoria, único na conta (sem diferenciar maiúsculas). Até 50 caracteres. Exemplo: `"Contratos de locação"`. | ### UpdateDocumentSignaturesAdditionalAuthenticationMethods | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `signatures` | [UpdateDocumentSignaturesAdditionalAuthenticationMethodsItem](#updatedocumentsignaturesadditionalauthenticationmethodsitem)[] | sim | Lista de signatários | ### UpdateDocumentSignaturesAdditionalAuthenticationMethodsItem | Propriedade | Tipo | Obrigatória | Descrição | | --- | --- | --- | --- | | `documentSignatureId` | string (uuid) | sim | Id do Signatário no documento | | `additionalAuthenticationMethods` | [EAdditionalAuthenticationMethod](#eadditionalauthenticationmethod)[] | sim | Métodos de autenticação adicionais do signatário | --- # 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`. |