# 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.