Changelog da API pública

Este histórico registra mudanças do contrato /v4/api/*. Correção interna que não altera o contrato não gera uma nova entrada.

2026-10-07 (limite por ciclo de envelopes com ICP-Brasil e com selfie)

O envio de envelope (POST /v4/api/envelopes/{envelopeId}/send e POST /v4/api/envelopes/send-now) pode responder 403 com dois códigos novos: PKI_QUOTA_EXCEEDED, quando a conta atinge o limite do ciclo de envelopes com certificado ICP-Brasil, e SELFIE_QUOTA_EXCEEDED, quando atinge o limite do ciclo de envelopes com verificação por selfie. Conta um envelope por vez, mesmo que ele tenha vários signatários com o mesmo método.

Nada é gravado quando a recusa acontece. O limite renova no próximo ciclo da cota de envelopes da conta; para ampliar, fale com a SuperSign®.

O recurso fica atrás de uma chave de ativação e só passa a valer quando for ligado em produção. Até lá nada muda. Mudança compatível/aditiva: dois códigos novos de erro, que devem ser tratados como string livre.

2026-10-07 (locale no PATCH de participante)

PATCH /v4/api/envelopes/{envelopeId}/participants/{participantId} passa a aceitar o campo opcional locale (pt-BR, en ou es), para trocar o idioma de um participante sem reenviar a lista inteira. Ausente, o idioma atual não muda. Valor fora da lista responde 400, e campos desconhecidos continuam recusados com 400.

A troca vale para a página de assinatura e para os próximos e-mails e mensagens. O que já foi enviado não é reenviado nem alterado, e trocar só o locale não dispara novo convite. A operação segue as mesmas regras de estado de antes: envelope em curso e participante que ainda não concluiu (caso contrário, 409 ou 403 como hoje).

Mudança compatível/aditiva: nenhum campo existente muda.

2026-10-07 (motivo da desativação e última falha em webhooks)

O objeto de webhook (GET /v4/api/webhooks e PATCH /v4/api/webhooks/{webhookId}) passa a preencher disabledAt e disabledReason também quando você desativa o endpoint (isActive: false): disabledReason vem manual. Para a desativação automática da plataforma, continua falhas_consecutivas. Reativar limpa os dois campos.

GET /v4/api/webhooks passa a devolver o objeto opcional lastFailure (at, statusCode, errorType), com a última tentativa de entrega que falhou: a data, o status HTTP (null quando não houve resposta, como em timeout) e a categoria do erro. Não traz o corpo da resposta do seu servidor. Vem null quando não há falha registrada no período de retenção das entregas e não vem na resposta do PATCH.

Mudança compatível/aditiva: um campo novo na listagem e um valor novo (manual) em disabledReason, que deve ser tratado como string livre. Webhooks desativados antes desta mudança seguem com disabledAt e disabledReason null.

2026-10-07 (documentação do campo locale dos participantes)

Melhoria de documentação, sem mudança de comportamento: o campo opcional locale do participante (pt-BR, en ou es) passa a ter descrição e exemplo no contrato e nos guias. Ele define o idioma da página de assinatura e dos e-mails e mensagens que o participante recebe; sem ele, o padrão é pt-BR.

Onde o campo é aceito: POST /v4/api/envelopes/send-now (signatories, approvers, observers, carbonCopies), PUT /v4/api/envelopes/{envelopeId}/participants, POST /v4/api/templates/{templateId}/envelopes e os participantes e cópias de modelo (PUT /v4/api/templates/{templateId}/participants e PUT /v4/api/templates/{templateId}/carbon-copies). As respostas de listagem de participantes também o devolvem.

PATCH /v4/api/envelopes/{envelopeId}/participants/{participantId} continua corrigindo só contato e não aceita locale (o corpo é estrito e recusa o campo com 400). Superado pela entrada de 2026-10-07 (PATCH aceita locale).

2026-10-07 (evento de teste de webhook)

Nova operação POST /v4/api/webhooks/{webhookId}/test (operationId webhooks.sendTest, escopo webhooks:write): envia na hora um único evento WEBHOOK_TEST ao endpoint, assinado com o segredo atual e pelas mesmas proteções de URL dos eventos reais, e devolve 200 com deliveryId, status (DELIVERED, FAILED ou SKIPPED), httpStatus, durationMs, errorType e responseSnippet (até 500 caracteres do corpo, sem cabeçalhos, com dados pessoais mascarados). Falha do seu servidor não é erro da rota: volta 200 com status FAILED.

Uma tentativa, com espera máxima de 10 segundos. Funciona com o endpoint desativado (para validar antes de reativar) e não conta para a desativação automática por falhas seguidas. Limite de 10 testes por minuto por endpoint (429 RATE_LIMIT_EXCEEDED com Retry-After). Não exige Idempotency-Key e nunca devolve resultado antigo. Webhook de outra conta responde 404 RESOURCE_NOT_FOUND.

A entrega de teste aparece em GET /v4/api/webhooks/{webhookId}/deliveries com event WEBHOOK_TEST, e o retry dela responde 409 WEBHOOK_DELIVERY_NOT_RESENDABLE. WEBHOOK_TEST não entra no campo events do cadastro. Quem lista entregas deve tolerar esse valor novo de event.

Mudança compatível/aditiva: nenhuma rota, campo ou comportamento existente muda. Um client gerado a partir do OpenAPI com enum fechado em event precisa aceitar WEBHOOK_TEST ao ler entregas.

2026-10-07 (campo environment em GET /v4/api/request-logs)

GET /v4/api/request-logs passa a devolver, em cada item, o campo opcional environment (LIVE ou TEST): o ambiente da chave que fez a chamada. Chamadas registradas antes de 07/10/2026 vêm com environment: null.

Mudança compatível/aditiva: nenhum campo existente muda. Um client que recuse campos desconhecidos nos itens precisa tolerar environment, e o conjunto de valores pode crescer.

Esta lista continua mostrando só chamadas com chave reconhecida. Chamada sem credencial válida (401) não aparece nela, porque não identifica uma conta; a SuperSign passa a registrá-las em log interno, sem a chave, para diagnóstico de abuso e de erro de credencial.

2026-10-07 (lembrete recusado quando o e-mail do participante está bloqueado)

POST /v4/api/envelopes/{envelopeId}/participants/{participantId}/reminder passa a responder 409 com o código PARTICIPANT_EMAIL_BLOCKED quando o participante recebe por e-mail e o endereço está bloqueado por falha definitiva de entrega (bounce do tipo HARD ou SUPPRESSED registrado para o e-mail atual). Antes, a chamada respondia 204 sem enviar nada.

Nenhuma mensagem é enfileirada e nenhum saldo de mensagens é consumido. A recusa vale só enquanto o bloqueio existir: corrigir o e-mail do participante (PATCH /v4/api/envelopes/{envelopeId}/participants/{participantId}) libera o endereço novo imediatamente. Bounce temporário (SOFT), de outro endereço ou sem tipo registrado não bloqueia, e participantes que recebem por WhatsApp ou SMS não são afetados.

O recurso fica atrás de uma chave de ativação e só passa a valer quando for ligado em produção. Até lá o comportamento (204) não muda. A rota POST /v2/envelopes/{envelopeId}/participants/{participantId}/reminder (usada pelo aplicativo) segue a mesma regra.

O histórico do envelope ganha o evento EMAIL_SKIPPED_BLOCKED (um por participante e por bounce) quando um e-mail deixa de ser enviado por esse motivo. Quem lista o histórico deve tolerar valores novos de evento.

Mudança observável: integrações que tratavam todo sucesso do lembrete como 2xx precisam tratar o 409 e orientar a correção do e-mail.

2026-10-06 (PDF de exemplo para testar a integração)

Nova operação GET /v4/api/sample-document: devolve sempre o mesmo PDF de 1 página (A4), com a marca d’água "EXEMPLO, SEM VALOR" e o texto "Documento de exemplo da SuperSign®". Serve para percorrer o fluxo de envelope sem precisar de um arquivo seu; o tamanho em bytes do arquivo baixado deve ser usado em fileSize ao registrar o documento.

Não exige API Key e não devolve dado de nenhuma conta. Tem limite próprio de 20 requisições por minuto por IP (resposta 429 ao exceder) e cache de 7 dias, com ETag e resposta 304 quando o arquivo não mudou.

O guia Primeiro envelope em 5 minutos passa a usar esse PDF.

Mudança compatível/aditiva: nenhuma operação existente muda.

2026-10-06 (bloco quota em GET /v4/api/account/entitlements)

GET /v4/api/account/entitlements passa a devolver o objeto opcional quota, com a janela de cota vigente da conta (mode, windowStart, windowEnd, envelopesPerWindow, messageCreditsPerWindow). envelopesPerWindow é o mesmo número que o envio usa como limite da janela; limits.envelopesPerCycle continua sendo a taxa mensal do plano e pode diferir no plano anual (por exemplo 20 contra 240).

quota vem null quando a chave não pertence a um proprietário ou administrador, quando a conta não tem assinatura ativa ou quando a leitura falha naquele momento (o restante da resposta sai normalmente, com 200). Enquanto a conta seguir a regra atual, mode vem LEGACY e os números refletem o ciclo da assinatura.

A lista de valores de mode pode crescer; trate um valor desconhecido como informativo.

Mudança compatível/aditiva: nenhum campo existente muda. Um client que recuse campos desconhecidos na raiz da resposta precisa tolerar quota.

2026-10-05 (nomes de operação padronizados no OpenAPI)

O campo operationId de todas as operações do openapi-public.json passa a seguir o padrão estável recurso.acao (por exemplo envelopes.create, envelopes.send, participants.remind, webhooks.rotateSecret), no lugar dos nomes derivados do caminho (como postEnvelopesEnvelopeIdSend). Os nomes são curados e não mudam quando o caminho é reorganizado.

Nenhuma rota, método, parâmetro ou payload mudou. Só o rótulo de cada operação no contrato. Quem gera cliente ou SDK a partir do OpenAPI verá nomes de métodos novos na próxima geração; quem chama a API por HTTP não é afetado.

2026-10-05 (saldo de mensagens em GET /v4/api/account/entitlements)

GET /v4/api/account/entitlements passa a devolver o campo limits.messageCreditsPerCycle (número) e o objeto opcional messageBalance, com o saldo de mensagens do ciclo (model, cycleStart, cycleEnd, credits, used, remaining, usedByChannel, legacyQuotas). O modelo unified conta WhatsApp como 1 e SMS como 2; no modelo legacy o consumo não é medido e os números vêm null.

messageBalance vem null quando a chave não pertence a um proprietário ou administrador, quando a conta não tem assinatura ativa ou quando a leitura do saldo falha naquele momento. Nesse último caso o restante da resposta (features e limits) continua saindo normalmente, com 200.

Liberação gradual: enquanto o saldo único estiver desligado, messageBalance mostra o modelo legacy, sem consumo medido.

Mudança compatível/aditiva: nenhum campo existente muda. Um client que recuse campos desconhecidos em limits ou na raiz da resposta precisa tolerar messageCreditsPerCycle e messageBalance.

2026-10-05 (histórico de entregas de webhook por 15 dias)

O histórico de entregas de webhook (GET /v4/api/webhooks/{webhookId}/deliveries, o detalhe da entrega e o reenvio) passa a ficar disponível por 15 dias; antes eram 30. Entregas mais antigas são apagadas automaticamente e deixam de aparecer na listagem, no detalhe (404) e de poder ser reenviadas. A retentativa automática (cerca de 7 horas) não muda.

Entregas de um envelope apagado em definitivo (rascunho ou anulado sem nenhuma assinatura) também são apagadas junto com ele.

O formato das respostas não muda. Integração que consulta ou reenvia entregas com mais de 15 dias deve fazê-lo antes disso.

2026-10-04 (resposta do seu servidor mascarada no detalhe da entrega)

Em GET /v4/api/webhooks/{webhookId}/deliveries/{deliveryId}, o campo responseSnippet de cada tentativa (o trecho da resposta do seu servidor) passa a vir com dados pessoais mascarados: e-mail (j***@d***.com), telefone no formato brasileiro com hífen (fica com os 4 últimos dígitos), CPF e CNPJ escritos com pontuação (ficam com os 2 últimos) e endereço IPv4/IPv6; URLs, tokens JWT e credenciais Bearer/Basic são removidos. Datas, horários, timestamps, versões e números sem pontuação não são alterados.

O payload dessa leitura não muda: continua igual ao corpo que o webhook entregou.

O formato dos campos não muda, só o conteúdo do trecho.

2026-10-04 (desativação automática de webhook)

Webhook que falha por dias seguidos é desativado automaticamente: com falha há 3 dias ou mais e 20 ou mais entregas FAILED seguidas, o endpoint passa a isActive: false. Um dia antes disso o dono da conta recebe um aviso por e-mail. Entrega ok zera a contagem; entrega SKIPPED não conta. Veja Entregas, retentativas e reenvio.

O objeto de webhook (GET /v4/api/webhooks e PATCH /v4/api/webhooks/{webhookId}) passa a devolver disabledAt (data) e disabledReason (falhas_consecutivas), ambos null quando a plataforma nunca desativou o endpoint. PATCH com isActive: true reativa e zera a contagem.

Liberação gradual, desligada por padrão: com o recurso desligado nada é desativado nem avisado.

Mudança compatível/aditiva: dois campos novos na resposta, nenhum existente muda.

2026-10-03 (prazo parado na suspensão por pagamento pendente)

Quando a conta é suspensa por pagamento pendente, o prazo dos envelopes dela para no dia da suspensão (Termos de Uso 1.2, item 5.2.1). Enquanto durar a suspensão, o envelope com prazo não expira, o signatário que chega depois do prazo ainda consegue assinar, e lembretes de envelope, boletim e aviso antecipado de tarefa não são enviados para a conta. O lembrete comum de tarefa (no dia do vencimento) continua saindo, de propósito: tarefa é controle interno da conta, não prazo de envelope. Suspensão por fraude ou administrativa não para o prazo.

Na reativação, o deadline dos envelopes SENT da conta é estendido pelos dias de calendário (Brasília) em que ficou parado, mantendo o formato YYYY-MM-DDT23:59:59.999Z. Quem lê o envelope por GET /v4/api/envelopes/{envelopeId} passa a ver o prazo novo. Prazo que já tinha vencido antes da suspensão não é estendido.

O histórico do envelope registra o evento novo DEADLINE_EXTENDED_BY_SUSPENSION, com de, para, dias e motivo.

Liberação gradual, desligada por padrão: com o recurso desligado nada muda.

Mudança compatível/aditiva: evento novo no histórico e deadline que pode mudar sem chamada do cliente. Integração que guarda o prazo localmente deve relê-lo depois da reativação da conta.

2026-10-03 (CPF esperado na assinatura ICP-Brasil)

Novo campo opcional expectedDocumentNumber nos signatários INDIVIDUAL de PUT /v4/api/envelopes/{envelopeId}/participants: o CPF (com ou sem pontuação) que o certificado ICP-Brasil do signatário tem de ter. Ausente mantém o valor gravado; null remove a conferência. CPF inválido responde 400 INVALID_CPF.

Com o campo preenchido, a assinatura com certificado (authMethod: "PKI_BRAZIL"), individual ou em lote, só conclui se o CPF do certificado for o esperado. Outro CPF, ou certificado que não traz CPF, é recusado (um e-CNPJ que traz o CPF do responsável é comparado normalmente) com 422 PKI_CERTIFICATE_CPF_MISMATCH: nada da assinatura é gravado, o signatário vê a mensagem e pode assinar de novo com o certificado certo. O histórico do envelope registra o evento PKI_CERTIFICATE_CPF_MISMATCH, com só os 3 últimos dígitos de cada CPF.

GET /v4/api/envelopes/{envelopeId}/participants passa a devolver expectedDocumentNumberMasked nos signatários: o CPF esperado mascarado (***.456.789-**), ou null sem conferência. O número inteiro nunca é devolvido.

Sem o campo, nada muda: a assinatura ICP segue como antes.

Mudança compatível/aditiva: campo novo opcional na entrada, campo novo na leitura, código e evento novos. Um client que recuse campos desconhecidos nos signatários precisa tolerar expectedDocumentNumberMasked.

2026-10-03 (envelope anulado: hadSignature)

GET /v4/api/envelopes/{envelopeId} passa a devolver o campo opcional hadSignature (booleano). Em envelope anulado é true quando já houve assinatura ou aprovação, caso em que a exclusão do anulado é recusada com 409 VOIDED_ENVELOPE_HAS_SIGNATURE. Nos demais status vem false.

Mudança compatível/aditiva: campo novo e opcional, nenhum existente muda.

2026-10-03 (webhook exige API e não vai para conta suspensa)

Entregas de webhook para conta suspensa (fraude ou administrativa) deixam de ser enviadas: ficam SKIPPED com errorType conta_suspensa e podem ser reenviadas depois da reativação. Conta suspensa por pagamento pendente segue recebendo.

Webhooks fazem parte do plano com API. POST /v4/api/webhooks e a reativação (PATCH com isActive: true) recusam com 403 API_NOT_IN_PLAN em conta sem API. Editar, desativar e excluir seguem permitidos. Entrega para conta sem API fica SKIPPED com errorType api_fora_do_plano.

Mudança compatível/aditiva na leitura: valores novos de errorType, tratados como string livre.

2026-10-03 (convite de SUPERVISOR)

Convidar alguém com papel SUPERVISOR (POST /v4/api/invites e painel) passa a exigir que quem convida seja OWNER, ADMIN ou MANAGER, a mesma regra que já valia para MANAGER. Quem não pode recebe o 403 que já existe para convite acima do próprio papel. O aceite revalida o papel atual de quem convidou.

Convite de MEMBER não muda. Medido em produção: nenhum convite de SUPERVISOR foi emitido por MEMBER ou SUPERVISOR.

2026-10-03 (teto de endpoints de webhook)

POST /v4/api/webhooks passa a recusar com 409 WEBHOOK_ENDPOINT_LIMIT_REACHED quando a conta já tem o máximo de endpoints de webhook (ativos e inativos contam). O teto padrão é 20 por conta, igual para todos os planos; quem precisar de mais fala com o suporte.

Editar, reativar e excluir endpoints não mudam. Conta que já está acima do teto não perde nenhum endpoint, apenas não cria novos. Nenhuma conta existente chega perto do teto hoje.

Mudança compatível/aditiva: código novo, emitido só na criação acima do teto.

2026-10-03 (campos automáticos: nome e CPF do signatário)

Novos tipos de campo SIGNER_NAME (nome do signatário) e SIGNER_DOCUMENT (CPF do signatário) em PUT /v4/api/envelopes/{envelopeId}/documents/{documentId}/fields e PUT /v4/api/templates/{templateId}/documents/{documentId}/fields (e nas respostas de leitura dos campos). Funcionam como o SIGNING_DATE: campo único com pages + position (ou anchor) e size, properties vazio ({}), e o signatário não preenche nada.

No documento selado é impresso, dentro da caixa do campo, o nome do signatário (sem o nome de quem executou em nome de um grupo, que o carimbo mostra como "Executor (Signatário)") e o mesmo CPF do relatório de auditoria. O CPF sai completo e formatado (000.000.000-00). Signatário sem CPF (por exemplo, estrangeiro) deixa a caixa vazia.

Novo código 400 FIELD_BOX_TOO_SMALL_FOR_AUTOMATIC_VALUE no PUT de campos, quando a caixa cortaria o valor no selado (10 pt, 12 pt por linha). SIGNER_DOCUMENT precisa de pelo menos 75 x 12 pt: o CPF formatado ocupa cerca de 70 pt em Helvetica 10 e fica numa linha. SIGNER_NAME precisa comportar um nome de 30 caracteres (por exemplo, 151 x 12 pt numa linha ou 111 x 24 pt em duas); nome mais longo que a caixa sai com reticências no corpo e inteiro no carimbo e no relatório. details: fieldId, fieldType, boxWidth, boxHeight, minWidthSingleLine, minHeight.

Em assinatura com certificado ICP-Brasil, os campos SIGNER_NAME e SIGNER_DOCUMENT ficam em branco no documento: o nome e o CPF constam na assinatura digital e no relatório.

A data do SIGNING_DATE e a "Data e Hora" do relatório de auditoria fixam explicitamente o fuso de Brasília, independente do ambiente.

Mudança compatível/aditiva: nenhum tipo existente muda. Integração que não conhece os tipos novos e lê campos de um envelope que os tenha deve ignorar tipos desconhecidos.

2026-10-03 (regras na opção: campo condicional e texto padrão)

Nas opções de RADIO_GROUP, CHECKBOX_GROUP e DROPDOWN (em properties.options[]), duas chaves opcionais novas no PUT de campos de envelope e de modelo e nas leituras:

linkedFieldId: id de um campo TEXT ou TEXTAREA do mesmo documento e do mesmo participante. Com a opção escolhida, o campo vinculado fica habilitado e passa a ser obrigatório; sem a opção escolhida, o valor dele é descartado e não vai para o documento selado. O isRequired do próprio campo vinculado é ignorado: quem decide é a opção.

textWhenSelected: texto padrão fixo (até 3.000 caracteres) gravado como valor do campo vinculado quando a opção é escolhida. O signatário não edita: o valor enviado para o campo vinculado é substituído por este texto. Exige linkedFieldId na mesma opção.

Novo código 400 FIELD_OPTION_LINK_INVALID no PUT de campos, com details = { fieldId, optionId, linkedFieldId, reason }. reason: TARGET_NOT_FOUND (o campo não está no documento), TARGET_TYPE_NOT_TEXT, TARGET_OTHER_PARTICIPANT, TARGET_LINKED_BY_ANOTHER_FIELD (um campo vinculado pertence às opções de um único campo), CONFLICTING_TEXTS (em CHECKBOX_GROUP, duas opções no mesmo campo vinculado com texto fixo) e TEXT_DOES_NOT_FIT (o texto fixo não cabe na caixa do campo vinculado).

Envelope criado a partir de modelo, envelope ou modelo duplicado e modelo importado do catálogo mantêm os vínculos, apontando para os campos da cópia.

No selado, o texto de TEXTAREA passa a respeitar as quebras de linha digitadas. Vale também para envelopes já em andamento que forem selados depois desta versão: texto multilinha que antes podia passar da caixa agora termina com reticências dentro dela. Texto sem quebra de linha sai igual.

A assinatura em lote aplica as mesmas regras; se uma opção escolhida exigir o campo vinculado e ele estiver vazio, o lote é recusado com o erro de campo obrigatório, e o signatário preenche pela assinatura individual.

Mudança compatível/aditiva: opção sem as chaves novas funciona como antes.

Novo tipo de campo DROPDOWN em PUT /v4/api/envelopes/{envelopeId}/documents/{documentId}/fields e PUT /v4/api/templates/{templateId}/documents/{documentId}/fields (e nas respostas de leitura dos campos). Campo único com pages + position (ou anchor) e size, como o TEXT. properties: options (2 a 50 itens { id, label }, id único no campo, label com até 120 caracteres), isRequired (padrão false) e placeholder opcional.

O signatário escolhe uma opção; o valor gravado é o id da opção. id que não pertence ao campo responde 400 FIELD_OPTION_INVALID; campo obrigatório sem escolha responde 400 (campo obrigatório vazio), como os demais tipos.

Novo código 400 FIELD_OPTION_LABEL_TOO_LONG_FOR_BOX no PUT de campos, quando o maior rótulo não cabe na caixa e sairia truncado no selado (10 pt; cerca de 5 pt por caractere mais 1 pt, e 12 pt por linha). details: fieldId, label, boxWidth, boxHeight, minWidthSingleLine.

No documento selado é impresso o rótulo (label) da opção escolhida, dentro da caixa do campo. O rótulo é o gravado no campo do envelope no momento da assinatura; envelope criado a partir de modelo copia as opções e não muda se o modelo for editado depois.

Mudança compatível/aditiva: nenhum tipo existente muda. Integração que não conhece DROPDOWN e lê campos de um envelope que tenha esse tipo deve ignorar tipos desconhecidos.

2026-10-02 (conta suspensa por pagamento pendente)

Novo código 403 ACCOUNT_SUSPENDED_BILLING: a conta está suspensa por pagamento pendente. A chave de API continua autenticando só para leitura e download: GET /v4/api/envelopes, GET /v4/api/envelopes/{envelopeId}, GET /v4/api/envelopes/{envelopeId}/documents, GET /v4/api/envelopes/{envelopeId}/participants, GET /v4/api/envelopes/{envelopeId}/download e GET /v4/api/documents/{documentId}/download. Qualquer outra operação (criar, enviar, editar, anular, webhooks, contatos, membros etc.) responde 403 ACCOUNT_SUSPENDED_BILLING, com details = { accountId, origin: "BILLING", suspendedAt, allowed: ["READ_ENVELOPES", "DOWNLOAD_DOCUMENTS"] }, sem dados pessoais.

Conta suspensa por qualquer outro motivo continua respondendo 403 ACCOUNT_SUSPENDED em todas as operações, como antes.

A integração de serviço /v4/service/* não muda: conta suspensa por qualquer motivo, inclusive pagamento pendente, continua recebendo 403 ACCOUNT_SUSPENDED em todas as operações.

Envelopes já enviados seguem o fluxo normal: a assinatura dos participantes, a selagem e a validação não passam por esta checagem.

Mudança compatível/aditiva: código novo, emitido só quando a conta é suspensa por pagamento pendente; antes essa conta recebia ACCOUNT_SUSPENDED em tudo.

2026-10-02 (documentos visíveis por participante)

PUT /v4/api/envelopes/{envelopeId}/participants passa a gravar allowedDocumentIds de cada signatário, aprovador e observador. Antes a chave era aceita e descartada. Com ids, o participante só vê, baixa e recebe no ZIP os documentos listados; nos demais, a página de assinatura não os mostra e os downloads respondem 404. Lista vazia remove a restrição (vê todos). Chave ausente mantém a restrição já gravada (antes o OpenAPI anunciava default: []; como nada era gravado, o efeito para quem não manda a chave continua o mesmo: vê todos). Em participante GROUP, a restrição vale para todos os membros do grupo.

Novo código 400 PARTICIPANT_DOCUMENT_ACCESS_INVALID: algum id de allowedDocumentIds não é documento do envelope (details.documentIds); nada é gravado.

Novo código 400 FIELD_DOCUMENT_NOT_VISIBLE (details.participantId, details.documentId): em PUT .../documents/{documentId}/fields, campo de participante em documento que ele não vê; em PUT .../participants, restrição que deixaria fora um documento onde o participante já tem campo. Remova o campo ou libere o documento.

A restrição vale também nos e-mails ao participante (convite, conclusão com anexos, recusa, anulação, comprovante): o documento que ele não vê não aparece pelo nome nem vai anexado.

A troca de arquivo do documento mantém o mesmo id e a mesma restrição.

Duplicar o envelope copia a restrição.

O dono e os membros da conta continuam vendo todos os documentos. Quem o participante vê não muda a selagem: cada documento selado continua com o próprio relatório de auditoria, que lista todos os signatários do envelope.

Mudança compatível/aditiva: envelopes sem allowedDocumentIds (todos os existentes) não mudam.

2026-10-02 (âncora no send-now)

POST /v4/api/envelopes/send-now passa a aceitar anchor em cada campo, no lugar de pageNumber + position, com size obrigatório (mesmas opções do PUT .../fields; até 20 campos com anchor; CHECKBOX_GROUP e RADIO_GROUP não aceitam). Antes, a chave anchor respondia 400.

Comportamento assíncrono: o 201 volta antes de o PDF existir. A busca roda depois que os documentos processam e antes do envio; se não for possível posicionar (texto não achado, PDF sem texto, PDF grande demais, campo fora da página, busca indisponível), o envelope não é enviado e é anulado, e o motivo vem em cancellationReason no webhook ENVELOPE_VOIDED. Falha temporária da busca é repetida sozinha.

Novo erro no POST: 503 ANCHOR_SEARCH_UNAVAILABLE quando a busca está desligada no ambiente; nenhum envelope é criado.

Mudança compatível/aditiva: send-now sem anchor não muda (mesma validação, mesma resposta, mesmo envio). Detalhes em Posicionar campos por texto âncora.

2026-10-02 (exemplos de corpo e Idempotency-Key)

Documentação, sem mudança de contrato: todos os corpos JSON de requisição da v4 passam a publicar examples nomeados (por exemplo, PUT .../fields por coordenadas, por texto âncora e com SIGNING_DATE; criação de envelope, participantes, webhooks, contatos, pastas e modelos). Cada exemplo é validado contra o schema da própria operação.

O cabeçalho Idempotency-Key ganha example e a orientação de gerar um valor novo por operação, sem reaproveitar um valor fixo.

Nenhum schema, validação ou comportamento muda.

2026-10-02 (âncora direto no campo)

PUT /v4/api/envelopes/{envelopeId}/documents/{documentId}/fields e PUT /v4/api/templates/{templateId}/documents/{documentId}/fields aceitam, em cada campo, anchor no lugar de pages + position:

{ text, occurrence ("first" padrão, N ou "all"), caseSensitive, matchWholeWord, offset, ifNotFound ("error" padrão ou "ignore") }

. A SuperSign procura o texto antes de gravar (uma busca por documento) e grava a página e a posição achadas; a âncora não é guardada. Exatamente um entre pages + position e anchor (os dois, ou nenhum: 400).

Novo código 422 ANCHOR_NOT_FOUND (texto não achado com ifNotFound: "error"; details traz anchors (lista de TODAS as âncoras não achadas, cada uma com fieldId e text) e truncated) e 422 ANCHOR_TOO_MANY_MATCHES (mais de 200 campos gerados). Com anchor, o PUT também pode responder os erros da busca: 409 DOCUMENT_NOT_READY, 422 DOCUMENT_HAS_NO_TEXT / DOCUMENT_TEXT_UNREADABLE / DOCUMENT_TOO_LARGE_FOR_ANCHOR, 503 ANCHOR_SEARCH_BUSY / ANCHOR_SEARCH_UNAVAILABLE com Retry-After. Campo posicionado pela âncora que sai da página: 400 FIELD_GEOMETRY_INVALID.

occurrence: "all" gera um campo por ocorrência; a partir da 2ª, o id é um UUID v5 derivado e estável. O id do campo passa a aceitar UUID v4 ou v5.

POST /v4/api/envelopes/send-now recusava campo com anchor com 400 (antes a chave seria ignorada); passou a aceitar na entrada seguinte, acima.

Mudança compatível/aditiva: PUT só com pages + position não muda (mesma validação, mesma resposta, nenhuma busca). Detalhes em Posicionar campos por texto âncora.

2026-10-02 (posicionar campos por texto âncora)

Nova operação POST /v4/api/envelopes/{envelopeId}/documents/{documentId}/anchors:find: procura até 20 textos (âncoras) no documento e devolve, para cada ocorrência, key, page, x, y, width e height em pontos de PDF, no mesmo sistema de coordenadas de PUT .../fields (origem no canto superior esquerdo, rotação já aplicada), com o offset pedido já somado; devolve também pages (tamanho de cada página). Opções por âncora: occurrence (all, first ou N), caseSensitive, matchWholeWord e offset. Escopo envelopes:read. Não exige Idempotency-Key.

Equivalente em modelos: POST /v4/api/templates/{templateId}/documents/{documentId}/anchors:find, escopo templates:read.

Só leitura: não grava campos e não altera o PDF. Âncora não encontrada não é erro (não aparece em matches). Documento em processamento: 409 DOCUMENT_NOT_READY. PDF sem texto (escaneado): 422 DOCUMENT_HAS_NO_TEXT. Leitura que excede os limites: 422 DOCUMENT_TEXT_UNREADABLE. Arquivo acima de 30 MiB: 422 DOCUMENT_TOO_LARGE_FOR_ANCHOR. Busca indisponível no ambiente, ocupada ou com falha temporária: 503 ANCHOR_SEARCH_UNAVAILABLE / 503 ANCHOR_SEARCH_BUSY, com Retry-After. A disponibilidade da busca é liberada por ambiente; enquanto não estiver liberada, a operação responde 503 ANCHOR_SEARCH_UNAVAILABLE. A resposta traz truncated: true quando o documento passa de 500 páginas (as demais não são lidas). Fora da conta ou da visibilidade: 404. Detalhes em Posicionar campos por texto âncora.

Mudança compatível: operações novas; o contrato de campos (PUT .../fields) não muda.

2026-10-02 (tamanho das páginas do documento)

Nova operação GET /v4/api/envelopes/{envelopeId}/documents/{documentId}/pages: devolve pages, uma entrada por página com page (a partir de 1), width e height (tamanho visível em pontos de PDF, já com a rotação aplicada) e rotate (0, 90, 180 ou 270). É o mesmo sistema de coordenadas de PUT .../fields: consulte antes de posicionar campos para não colocá-los fora da página. Escopo envelopes:read.

Documento ainda em processamento, ou processado antes da disponibilidade desta operação, responde 409 PAGE_GEOMETRY_UNAVAILABLE. Documento de outra conta, fora da pasta do usuário responsável pela chave ou inexistente: 404.

Mudança compatível: operação nova; nenhuma operação existente muda.

2026-10-02 (verificação pública de documento selado na v4)

Nova operação GET /v4/api/documents/{idOrHash}/verify: informa se um documento foi selado pela SuperSign e é autêntico, quando foi selado (sealedAt) e o status, sem dados pessoais e sem o arquivo. Aceita o id do documento ou o SHA-256 do PDF selado; com ?hash=, diz se o arquivo em mãos confere (hashMatches). Documento inexistente responde 200 com exists: false; hash fora do formato responde 400. Detalhes em Verificar um documento selado.

É a única operação sem API Key (security: [] no contrato): não responde 401 e não conta no teto por conta. Tem teto próprio de 20 requisições por minuto por IP (429 com retry-after).

Mudança compatível: nenhuma operação existente muda. GET /v2/documents/{idOrHash}/verify continua igual.

2026-10-02 (verificação pública de documento selado na v4)

Mudança compatível: nenhuma operação existente muda. GET /v2/documents/{idOrHash}/verify continua igual.

2026-10-02 (detalhe do envelope v2: evento interno fora de logs[])

GET /v2/envelopes/{envelopeId}: logs[] deixa de trazer eventos internos de recursos sob consulta, como já acontecia em GET /v4/api/envelopes/{envelopeId}/logs. Nenhum campo muda; os demais eventos seguem iguais e na mesma ordem.

2026-10-02 (ENVELOPE_COMPLETED: hash do arquivo selado)

Webhook ENVELOPE_COMPLETED: cada item de data.documents[] ganha sealedFileHash (string ou null), o hash SHA-256 do arquivo selado - o que a verificação pública confere. originalFileHash continua sendo o hash do arquivo enviado. Detalhes em Evento ENVELOPE_COMPLETED.

Mudança compatível e aditiva: a chave nova entra no fim de cada item; nenhum campo existente muda de nome, tipo, valor ou ordem. Um receptor que valide o corpo com schema fechado precisa tolerar a chave nova.

2026-10-02 (correção: papel do signatário nos eventos de recusa e e-mail não entregue)

Correção: em PARTICIPANT_DECLINED e EMAIL_BOUNCED, data.participant.role passa a valer SIGNATORY para o signatário (antes SIGNER), alinhado às demais rotas da API v4. APPROVER e OBSERVER não mudam. Não havia consumidores inscritos nesses eventos.

2026-10-02 (webhook de e-mail não entregue: EMAIL_BOUNCED)

Novo evento de webhook EMAIL_BOUNCED: um e-mail enviado a um participante (convite, lembrete, código de verificação e demais avisos) não foi entregue. O corpo traz envelope (id), participant (id, name, email, role = SIGNATORY, APPROVER ou OBSERVER), channel (EMAIL), failureType (HARD, SOFT, SUPPRESSED ou OTHER) e occurredAt. No mesmo ciclo de envio, um participante só gera outro evento se a falha piorar (SOFT/OTHER → HARD/SUPPRESSED). Não cobre e-mail enviado pelo SMTP próprio da conta. Detalhes em Evento EMAIL_BOUNCED.

events em POST /v4/api/webhooks/ e PATCH /v4/api/webhooks/{webhookId} passa a aceitar EMAIL_BOUNCED, e o filtro event das entregas também.

Mudança compatível e opcional: nenhum endpoint existente passa a receber o evento sem incluí-lo em events; nenhum evento existente muda. Um client que valide events contra uma lista fechada precisa tolerar o valor novo.

2026-10-01 (webhook de recusa: PARTICIPANT_DECLINED)

Novo evento de webhook PARTICIPANT_DECLINED: um participante recusou o envelope, que passa a DECLINED. Cobre o signatário (recusa pelo link) e o aprovador (recusa pelo link ou por POST /v4/api/envelopes/{envelopeId}/participants/{participantId}/decline); data.participant.role vale SIGNATORY ou APPROVER. O corpo traz envelope (id, status, occurredAt), participant (id, name, email, role) e reason (o motivo inteiro, ou null). Detalhes em Evento PARTICIPANT_DECLINED.

events em POST /v4/api/webhooks/ e PATCH /v4/api/webhooks/{webhookId} passa a aceitar PARTICIPANT_DECLINED, e o filtro event das entregas também.

2026-10-01 (aprovação pela API registra a origem)

POST /v4/api/envelopes/{envelopeId}/participants/{participantId}/approve: a aprovação feita pela API passa a ficar registrada, no histórico de evidências, com a origem API_INTEGRATION. Esse registro não equivale a um aceite dos Termos de Assinatura: a data do aceite e a versão do termo ficam vazias, porque quem aprovou foi a integração, e não uma pessoa marcando o aceite.

Nada muda no contrato: o corpo continua opcional, as respostas são as mesmas e nenhum código de erro novo aparece na v4. A exigência de aceite dos termos, quando for ligada, vale só para a página de assinatura e não alcança a v4.

GET /v2/documents/{documentId}/validate passa a exigir login (sessão do painel/app: Authorization: Bearer <jwt> + x-account-id) e só responde documento da própria conta, visível ao membro pela regra de pastas. Sem login: 401. Documento de outra conta, fora da pasta do membro ou inexistente: 404 (antes: 400 INVALID_DOCUMENT para inexistente). O corpo de sucesso não muda.

Mudança incompatível em contrato v2, aceita por decisão do produto (opção C): a rota devolvia a URL assinada do selado e os nomes dos signatários a quem tivesse o id. A verificação pública passa a ser GET /v2/documents/{idOrHash}/verify, sem dados pessoais.

A validação por upload (POST /v2/documents/validate) passa a buscar por um critério único (o hash do arquivo); a resposta não muda. GET /v4/api/documents/{documentId}/validation não muda.

2026-10-01 (participantes: dados de quem já agiu são os do ato)

GET /v4/api/envelopes/{envelopeId}/participants e o webhook ENVELOPE_COMPLETED: para quem já assinou (ou já aprovou), name, email e phoneNumber passam a ser os gravados no momento da assinatura (ou da aprovação). Antes, saía o cadastro atual do participante, que pode ter sido editado depois (por exemplo, numa correção do envelope). Se o ato não registrou e-mail ou telefone, o campo vem null: um contato acrescentado depois não é apresentado como dado do ato. Quem ainda não agiu continua com o cadastro.

Correção, sem alteração de schema: nenhum campo novo, removido ou com outro tipo.

2026-10-01 (validação: nome de quem assinou é o do ato)

GET /v4/api/documents/{documentId}/validate (e as rotas v2 de validação): para quem já assinou, signatories[].name passa a ser o nome gravado no momento da assinatura. Antes, saía o cadastro atual do participante, que pode ter sido editado depois (por exemplo, numa correção do envelope). Quem ainda não assinou continua com o nome do cadastro.

Correção, sem alteração de schema: nenhum campo novo, removido ou com outro tipo.

2026-10-01 (correção de envelope: troca de tipo ou grupo)

PUT /v4/api/envelopes/{envelopeId}/participants: com o envelope em correção, trocar o tipo (INDIVIDUAL ↔ GROUP) ou o grupo de um participante que já foi enviado passa a responder 409 PARTICIPANT_TYPE_CHANGE_NOT_ALLOWED. Antes, a troca era aceita, mas os links do grupo antigo continuavam valendo e o grupo novo não recebia link. Para trocar, remova o participante e adicione um novo na mesma chamada.

Em rascunho, nada muda. Reenviar o mesmo tipo e o mesmo grupo continua aceito.

Mudança compatível para quem já trata 409: o código é novo, e o 409 já estava declarado na operação.

2026-09-30 (escritas seguem o direito do usuário responsável)

POST /v4/api/envelopes/{envelopeId}/void, PATCH /v4/api/envelopes/{envelopeId}/participants/{participantId}, POST /v4/api/envelopes/{envelopeId}/participants/{participantId}/reminder, POST /v4/api/envelopes/{envelopeId}/participants/{participantId}/approve, PATCH /v4/api/envelopes/{envelopeId}/move e POST /v4/api/envelopes/send-now (com folderId de pasta privada) passam a exigir do usuário responsável pela chave o mesmo direito que o aplicativo exige: ser quem criou o envelope, ter papel OWNER, ADMIN ou MANAGER, ou ter permissão de escrita na pasta. Antes, bastava o envelope ou a pasta estarem visíveis para ele.

A recusa usa o mesmo código do aplicativo: 403 VOID_NOT_ALLOWED ao anular, 403 ENVELOPE_WRITE_NOT_ALLOWED nas demais operações sobre o envelope, e na pasta de destino privada 404 (sem permissão) ou 403 (só leitura).

Chaves emitidas pelo proprietário da conta não mudam. Nenhum formato de resposta de sucesso mudou.

2026-09-30 (prazo de `PATCH /v2/envelopes/{envelopeId}/deadline`)

A rota v2 de alterar prazo (aceita chave de API) passa a validar deadline como as demais entradas de prazo: YYYY-MM-DD (o dia informado) ou data-hora ISO 8601 (com fuso: o dia correspondente em Brasília). Antes, 2026-10-15T23:30:00-03:00 gravava o dia 16, e datas inexistentes como 2026-02-30 eram aceitas.

Entrada inválida passa a responder 400 VALIDATION. A resposta de sucesso (204) e o formato gravado (fim do dia) não mudam.

A rota não faz parte do contrato /v4/api; o openapi-public.json não muda.

2026-09-30 (erro de validação: `error.context` no corpo vazio)

Erros de validação de corpo vazio passam a trazer error.context: um 400 VALIDATION de qualquer operação de /v4/api enviado com Content-Type: application/json e corpo vazio (ou com corpo que não é um objeto JSON) passa a responder { "error": { "code": "VALIDATION", "context": "body", "message": "..." } }. O servidor já montava o context, mas ele era descartado antes de sair.

No contrato, o tipo ApiError ganha context (string) opcional; ele só aparece em erros de validação.

v2 e v3 também passam a receber error.context no mesmo 400 de corpo vazio: é um campo opcional a mais, nada foi removido.

Mudança compatível: campo aditivo; nenhum campo removido ou com outro tipo.

2026-09-30 (deadline de entrada tipado como string)

Em POST /v4/api/envelopes/send-now, PATCH /v4/api/envelopes/{envelopeId}/settings e POST /v4/api/templates/{templateId}/envelopes, o campo deadline passa a ser documentado como string (YYYY-MM-DD ou data-hora ISO 8601), podendo ser null. Antes ele saía sem tipo, e um SDK gerado podia tipá-lo como qualquer valor.

Mudança compatível: a validação não mudou; os mesmos valores continuam aceitos e recusados.

2026-09-30 (webhooks: segredo fora do replay e URL IPv6)

POST /v4/api/webhooks/: o signingSecret da resposta deixa de ser guardado no cache de idempotência. Repetir a criação com a mesma Idempotency-Key continua não criando outro endpoint, mas passa a responder 409 IDEMPOTENCY_SECRET_NOT_REPLAYABLE (código novo), com o id do endpoint na mensagem, em vez de repetir o 201 com o segredo. Obtenha o segredo girando-o em POST /v4/api/webhooks/{webhookId}/secret/rotate.

A validação da URL de webhook passa a recusar IPv6 literal que aponta para rede privada por um IPv4 embutido ([::ffff:a00:1], [64:ff9b::a00:1], [2002:a00:1::]) e faixas IPv6 não públicas. URL com host público não muda.

Mudança compatível para quem trata 409 como "já feito / aguarde": o código é novo e só aparece no replay da criação de webhook.

2026-09-30 (validade da chave no /me)

GET /v4/api/me passa a devolver integration.expiresAt: a data de vencimento da própria chave (ISO 8601, UTC), ou null quando ela não vence. Use para saber com antecedência quando trocar a chave, antes do 401 API_KEY_EXPIRED.

Quem criou a chave e quem pode gerenciar chaves na conta passa a receber um aviso por e-mail 14 dias e 3 dias antes do vencimento. O e-mail mostra só o nome, o início da chave, o ambiente e a data; a chave completa nunca é enviada.

Mudança compatível: um campo novo na resposta. Nenhuma operação nova.

2026-09-29 (contato: email e phoneNumber sempre presentes)

Nas respostas de contato (GET /v4/api/contacts/{contactId}, PUT e PATCH /v4/api/contacts/{contactId}), email e phoneNumber passam a ser documentados como sempre presentes, podendo vir null. O dado não mudou: as duas chaves já vinham em toda resposta; só o contrato passou a dizer isso, como já dizia em criar e listar.

O contato ganha nome no contrato: o tipo Contact, o mesmo nas respostas de criar, listar, obter e editar.

Mudança compatível: nenhum campo novo, removido ou com outro tipo.

2026-09-29 (API_KEY_EXPIRED: chave com validade)

Código novo API_KEY_EXPIRED na resposta 401 de qualquer operação de /v4/api: a chave é válida e não foi revogada, mas passou da validade. Emita outra chave no painel e troque na integração. Chave revogada continua respondendo 401 INVALID_API_KEY.

A chave pode ser emitida com validade (30, 90, 180 ou 365 dias). Sem validade escolhida, ela não vence, como antes. As chaves já existentes não têm validade e seguem funcionando.

Acesso total passa a ser uma escolha explícita da chave. As chaves já existentes mantêm o acesso total; nenhuma perde permissão.

Mudança compatível para quem trata 401 como "chave não vale": só o código do erro é novo.

2026-09-29 (corrigir modelo montado pela API)

Operações novas para corrigir um modelo em rascunho montado pela API:

PATCH /v4/api/templates/{templateId}/documents/reorder reordena os documentos (documentIds com todos, uma vez cada);

DELETE /v4/api/templates/{templateId}/documents/{documentId} remove um documento e os campos posicionados nele;

PUT /v4/api/templates/{templateId}/carbon-copies define quem recebe cópia dos envelopes criados a partir do modelo;

DELETE /v4/api/templates/{templateId} apaga um modelo em rascunho.

Todas seguem as regras da montagem pela API: exigem quem gerencia modelos, o recurso de modelos no plano e o escopo templates:write, e só valem em rascunho. Num modelo ativo, a resposta é 409 TEMPLATE_NOT_DRAFT. Pela API, modelo ativo não é apagado; a exclusão dele é feita no aplicativo.

Envelopes já criados a partir de um modelo não são afetados.

Mudança compatível: quatro operações novas.

2026-09-29 (tagIds valida UUID)

GET /v4/api/envelopes/: o parâmetro tagIds agora exige que cada id do CSV seja um UUID válido. Um id malformado responde 400 (antes, apenas devolvia lista vazia, silenciosamente). Mudança compatível para quem já manda ids válidos.

2026-09-29 (etiquetas na listagem)

GET /v4/api/envelopes/ ganha o parâmetro opcional tagIds: ids de etiquetas separados por vírgula (até 50). Devolve os envelopes com qualquer uma delas, sempre dentro do que a chave já listaria. Mais de 50 ids responde 400.

Cada envelope da listagem passa a trazer tags: as etiquetas aplicadas (id, name, color), em ordem de nome, com lista vazia quando não há. GET /v4/api/envelopes/{envelopeId} já devolvia tags.

Mudança compatível: um parâmetro opcional e um campo novo na resposta. Nenhuma operação nova.

2026-09-29 (montar modelos pela API)

Operações novas para montar um modelo inteiro pela API, sem passar pela tela:

POST /v4/api/templates cria o modelo vazio em rascunho, privado, com o usuário responsável pela chave como criador;

POST /v4/api/templates/{templateId}/documents registra os documentos e devolve as URLs para enviar os arquivos (mesmos limites de tamanho e quantidade do envelope);

GET /v4/api/templates/{templateId}/documents/{documentId}/status informa quando o documento terminou de processar;

PUT /v4/api/templates/{templateId}/participants define as vagas. A lista substitui a anterior inteira: vaga omitida é removida junto com os campos dela. Envie sempre a lista completa;

PUT /v4/api/templates/{templateId}/documents/{documentId}/fields posiciona os campos de um documento;

PATCH /v4/api/templates/{templateId}/activate ativa o modelo (exige documentos prontos).

Também novas: PUT /v4/api/templates/{templateId} (título e descrição) e POST /v4/api/templates/{templateId}/duplicate (cópia em rascunho).

Regras da API, mais estritas que as da tela:

só escreve em modelo quem gerencia modelos: proprietário, administrador, supervisor, gerente ou permissão de gerenciar modelos. Os demais recebem 403;

documentos, vagas e campos só mudam em rascunho. Num modelo ativo, a resposta é 409 TEMPLATE_NOT_DRAFT. Para alterar um modelo ativo, duplique, ajuste a cópia e ative-a;

toda operação de modelo exige o recurso de modelos no plano.

Escopo novo templates:write. Uma chave emitida com escopos só alcança a montagem se ele for incluído. A tabela de escopos do guia de introdução foi completada, com templates:read, audit:read e reports:read, que faltavam.

Mudança compatível: oito operações novas.

2026-09-29 (etiquetas)

Operação nova: GET /v4/api/tags lista as etiquetas da conta com a quantidade de envelopes em cada uma. O id é o tagId das operações abaixo. Escopo novo tags:read.

Operação nova: POST /v4/api/envelopes/{envelopeId}/tags aplica uma etiqueta ({ "tagId": "..." }) ao envelope. Reaplicar é inócuo; um envelope aceita no máximo 3, e a quarta responde 409 ENVELOPE_TAG_LIMIT. Etiqueta ou envelope inexistente, de outra conta ou fora da visibilidade responde 404. Exige Idempotency-Key. Escopo novo tags:write.

Operação nova: DELETE /v4/api/envelopes/{envelopeId}/tags/{tagId} remove a etiqueta do envelope; remover uma que não está aplicada é inócuo. Escopo tags:write.

Os escopos tags:read e tags:write são novos: uma chave emitida com escopos só alcança estas operações se eles forem incluídos. Chave sem escopos continua podendo tudo.

Criar, renomear e apagar etiquetas do catálogo, e o filtro por etiqueta na listagem, seguem só no aplicativo por enquanto.

Mudança compatível: três operações novas (passam a 68 publicadas).

2026-09-29 (consumo do ciclo)

Operação nova: GET /v4/api/account/usage devolve o consumo de envelopes da conta no ciclo de cobrança vigente: cycle.startDate e cycle.endDate, e em envelopes os campos sent, completed, quota, remaining, usagePercentage e unlimited. A cota é a mesma que o limite de envio aplica, já com o ajuste contratado da conta, e por isso pode diferir do envelopesPerCycle de /account/entitlements em plano anual. Os números são da conta inteira e não dependem do usuário responsável pela chave. Escopo account:read.

Mudança compatível: uma operação nova (passam a 65 publicadas).

2026-09-29 (reordenar documentos e duplicar envelope)

Operação nova: PATCH /v4/api/envelopes/{envelopeId}/documents/reorder define a ordem dos documentos de um envelope em rascunho ou em ajuste. O corpo leva documentIds com todos os documentos do envelope, uma vez cada, na ordem desejada. Lista incompleta, repetida ou com documento de outro envelope responde 400; envelope fora de rascunho ou ajuste responde 403. O conteúdo dos arquivos não muda. Escopo envelopes:write.

Operação nova: POST /v4/api/envelopes/{envelopeId}/duplicate cria um envelope novo em rascunho com os mesmos documentos, participantes, campos e cópias de um envelope existente. Assinaturas, selos, links de assinatura e valores preenchidos não são copiados. title é opcional; sem ele, a cópia recebe o título original com " (cópia)". Documento do original que não está pronto responde 409 ENVELOPE_DOCUMENT_NOT_DUPLICABLE. Exige Idempotency-Key. Escopo envelopes:write.

Mudança compatível: duas operações novas (passam a 64 publicadas).

2026-09-28 (listar grupos)

Operação nova: GET /v4/api/groups lista os grupos da conta em ordem de nome, com membersCount, paginada (até 100 por página, resposta com meta) e com filtro opcional q pelo nome. O id de cada grupo é o groupId que a API já aceitava nos participantes e em send-now e já devolvia no relatório de uso; até aqui não havia como descobri-lo pela API.

Escopo members:read, o mesmo de GET /members. Chave sem escopos continua podendo tudo; chave com escopos que não inclua members:read recebe 403 API_SCOPE_INSUFFICIENT.

Só leitura: criar, editar e apagar grupo seguem só pelo aplicativo.

Guia de introdução ganha "Montando a URL" e "Onde está cada coisa", com os caminhos mais tentados que não existem.

Mudança compatível: uma operação nova (passam a 62 publicadas).

2026-09-28 (relatório de uso aceita a permissão de ver relatórios)

GET /v4/api/reports/envelopes-usage passa a aceitar a chave de um membro com a permissão avulsa de ver relatórios, além do proprietário e do administrador. Antes essa chave recebia 403 aqui e 200 em GET /v4/api/reports/envelopes; agora as duas rotas seguem a mesma regra do painel.

A descrição das duas rotas no contrato foi corrigida: dizia "só proprietário ou administrador", mas /reports/envelopes já aceitava a permissão avulsa.

Mudança compatível: só amplia quem recebe 200; sem a permissão, o 403 continua. Nenhuma operação nova (seguem 61 publicadas).

2026-09-28 (prazo aceita a data sozinha como o dia informado)

deadline (entrada) em POST /v4/api/envelopes/send-now, POST /v4/api/templates/{templateId}/envelopes e PATCH /v4/api/envelopes/{envelopeId}/settings passa a ser tratado como dia de calendário em Brasília:

"2026-09-17" (só a data) vale como o dia 17. Antes era lido como 17T00:00Z, que em Brasília ainda é o dia 16, e o prazo vencia um dia antes do pedido.

Data-hora com fuso (2026-09-17T22:00:00-03:00, 2026-09-18T01:00:00Z) vale como o dia daquele instante em America/Sao_Paulo (nos dois exemplos, dia 17). Data-hora sem fuso vale como o dia escrito.

O valor gravado e devolvido nas leituras passa a ser YYYY-MM-DDT23:59:59.999Z do dia, o mesmo formato que a edição de prazo pelo painel já gravava. O envelope vence quando esse dia termina em Brasília.

Data impossível (ex.: 2026-02-30) responde 400. Antes era aceita em silêncio e rolava para o mês seguinte (2026-02-30 virava 02/03); quem manda dia 31 em mês de 30 dias passa a receber erro.

A recusa vale também para data impossível com hora ou fuso (2026-02-30T10:00:00Z, 2026-04-31T12:00:00-03:00): a parte de data é conferida antes da conversão.

null continua aceito. Em send-now vale como sem prazo, igual a omitir o campo (antes virava 1970-01-01 e o envelope nascia vencido). Em templates/{templateId}/envelopes segue sem prazo. Em PATCH .../settings remove o prazo do envelope (antes gravava 1970-01-01, vencendo o envelope na hora).

Mudança compatível para quem já manda data-hora com fuso: o dia resultante é o mesmo. Envelopes já criados não mudam. Nenhuma operação nova (seguem 61 publicadas).

2026-09-26 (filtro pelo estado do participante)

GET /v4/api/envelopes/ ganha o parâmetro opcional participantStatus, com três valores. Junto de participantName, participantEmail ou participantPhone, os critérios valem para o mesmo participante.

PENDING: algum participante tem ação a fazer agora e ainda não cumpriu - signatário ou aprovador que não assinou/aprovou (mesmo que já tenha aberto o link), ou observador com visualização obrigatória que ainda não visualizou. Só devolve envelopes em andamento (SENT). Quem aguarda a própria vez num fluxo sequencial, o observador sem visualização obrigatória e o observador que já visualizou não entram.

COMPLETED: algum participante já cumpriu a sua parte - assinou, aprovou ou (observador) visualizou.

DECLINED: algum participante recusou.

Valor fora desses três responde 400. A visibilidade não muda: o filtro só restringe o que a chave já listaria.

Mudança compatível: parâmetro novo e opcional; nenhuma operação nova (seguem 61 publicadas).

2026-09-19 (opções do participante no modelo)

GET /v4/api/templates/{templateId}: cada participante do modelo passa a trazer allowReturnForAdjustment (signatários e aprovadores) e allowEditPreviousFields (só signatários), os mesmos nomes que o envelope já usa. Modelos existentes devolvem false nos dois.

Os valores são copiados para os participantes do envelope criado a partir do modelo (POST /v4/api/templates/{templateId}/envelopes). Se o modelo tiver allowEditPreviousFields numa posição que não é sequencial no envelope (order 1 ou compartilhada), a opção é desligada na cópia e o envelope é criado normalmente.

Mudança compatível: só campos novos na resposta; nenhuma operação nova e nenhum contrato de requisição alterado (seguem as mesmas operações publicadas).

2026-09-19 (contagem de "pendentes")

GET /v4/api/reports/envelopes: summary.totalPending passa a contar também os envelopes em ajuste (CORRECTING) e devolvidos para ajuste (RETURNED), além de enviados e em selagem. O filtro ?status=PENDING usa exatamente os mesmos status, então lista e resumo continuam batendo.

Efeito para quem integra: em contas que usam "Ajustar envelope" e "Devolver para ajuste", totalPending fica maior do que vinha antes, sem que nada tenha mudado na conta. Quem reconcilia esse número com um contador próprio precisa incluir os dois status. Nenhum campo novo, nenhum campo removido.

GET /v4/api/reports/envelopes-usage: summary.totalPending e data[].pendingEnvelopes passam a usar a mesma regra, contando também CORRECTING e RETURNED. Os dois relatórios agora batem na mesma conta, e pendingEnvelopes fica maior em contas que usam ajuste/devolução.

Mudança de comportamento, não de formato: o schema da resposta é o mesmo e seguem 61 operações publicadas.

2026-09-18 (paginação das listas)

Quatro listas passam a aceitar page (a partir de 1) e perPage (de 1 a 100; de 1 a 500 em logs), ambos opcionais: GET /v4/api/members, GET /v4/api/invites, GET /v4/api/webhooks e GET /v4/api/envelopes/{envelopeId}/logs.

Quem não envia parâmetros recebe o mesmo formato de antes, só que limitado à primeira página de até 100 itens (perPage padrão = 100; 500 em logs). Contas com mais de 100 itens numa dessas listas passam a receber apenas os 100 primeiros até pedir as demais páginas; antes vinha tudo.

members e invites ganham o campo meta (page, perPage, totalPages, totalCount) ao lado da lista, como em contacts.

webhooks e logs têm um array na raiz da resposta; para não quebrar quem lê esse array, o corpo não muda e a paginação vem nos cabeçalhos X-Page, X-Per-Page, X-Total-Pages e X-Total-Count.

perPage acima de 100, e page menor que 1 ou fracionária, respondem 400. Página além da última devolve lista vazia.

A ordem passa a ser estável entre páginas: membros, convites e webhooks por id; logs do mais recente ao mais antigo (desempate por id).

Por que 100 (e 500 nos logs): medido em produção em 18/09/2026. Membros por conta (25.847 contas): máximo 446, 1 conta acima de 100. Convites (85 contas): máximo 202, 1 acima de 100. Webhooks (20 contas): máximo 11, nenhuma acima de 100. Logs por envelope (234.352 envelopes): máximo 2.865; 1.619 (0,7%) passam de 100, 326 de 200 e 13 de 500. Só os logs têm cauda real, então o padrão e o teto deles são 500 (cobre 99,99% dos envelopes numa chamada).

Quando X-Total-Count (ou meta.totalCount) exceder os itens retornados, pagine com ?page=. Os cabeçalhos de paginação de webhooks e logs agora constam no contrato (respostas 200).

Mudança compatível: parâmetros opcionais e campo/cabeçalhos novos; nenhuma operação nova (seguem 50 publicadas).

2026-09-18

GET /v4/api/envelopes/ ganha três parâmetros opcionais, para o integrador parar de varrer a lista inteira: folderId (só os envelopes da pasta; a pasta a que a chave não tem acesso devolve lista vazia, como qualquer outro filtro), updatedSince (data ISO 8601; devolve os envelopes com updatedAt maior ou igual ao valor; data inválida responde 400) e o valor updatedAt em orderBy. O padrão de ordenação não muda (createdAt, decrescente).

Nova operação: PATCH /v4/api/contacts/{contactId} - atualização parcial: só os campos enviados mudam e o que for omitido permanece (inclusive phoneNumber, que o PUT limpa quando ausente). null limpa phoneNumber, expectedCpf e preferences, como no PUT. Escopo contacts:write; não usa Idempotency-Key. Passam a ser 51 operações publicadas.

Mudança compatível: parâmetros novos e opcionais e uma operação nova; nada existente muda.

Duas operações novas, de participante:

PATCH /v4/api/envelopes/{envelopeId}/participants/{participantId} - corrige name, email, phoneNumber ou deliveryMethod de um participante (ao menos um campo), inclusive depois do envio, com as mesmas regras da tela. Trocar e-mail ou telefone de quem está na vez invalida o link anterior e reenvia o convite ao novo endereço, e esse reenvio conta no limite de mensagens da conta (429 quando excedido). Responde 204 sem corpo: o link de assinatura nunca é devolvido. Recusas: 403 CANNOT_EDIT_PARTICIPANT (participante que já assinou, aprovou ou recusou), 400 PHONE_NUMBER_REQUIRED, 404 (envelope ou participante inexistente ou de outra conta). Escopo envelopes:write; não usa Idempotency-Key.

POST /v4/api/envelopes/{envelopeId}/participants/{participantId}/decline - recusa por um participante aprovador, par de .../approve. Corpo: reason (10 a 500 caracteres, o mesmo da tela). A recusa encerra o envelope como recusado, igual à recusa pelo link, e o histórico registra o evento como feito pela integração (via: API). Exige o recurso "aprovação pela API" (403), escopo approvals:write e Idempotency-Key. Recusas: 409 (não é aprovador, grupo, já recusou, envelope fora de andamento), 400 APPROVAL_ALREADY_PROCESSED (já aprovou), 403 (fora da vez, prazo vencido), 404.

Quatro operações novas, somente leitura, reaproveitando as consultas do painel.

GET /v4/api/audit/voided-envelopes - envelopes anulados da conta (título, quem anulou, quando e o motivo), paginado (page, perPage). Escopo audit:read (novo). Só para quem é proprietário ou administrador da conta; os demais recebem 403.

GET /v4/api/reports/envelopes - relatório de envelopes com resumo agregado, filtros por período (startDate, endDate), status e participante, paginado. Escopo reports:read (novo). Só para proprietário ou administrador da conta; os demais recebem 403.

GET /v4/api/reports/envelopes-usage - consumo de envelopes por grupo, com filtro por período; sem datas, considera os últimos 30 dias; no máximo 500 grupos, sem paginação. Só para proprietário ou administrador da conta (403 para os demais). Escopo reports:read.

GET /v4/api/documents/{documentId}/validation - resultado da validação de um documento selado da conta da chave: hash do arquivo selado, título e data do envelope, signatários (nome e data da assinatura) e URL temporária do arquivo. Sem e-mail, sem CPF e sem histórico. Documento inexistente, de outra conta ou ainda não selado responde 404. Escopo envelopes:read.

Os escopos audit:read e reports:read passam a existir para emitir chaves restritas; chaves sem escopos (acesso total) já alcançam as rotas.

Fora da API pública, de propósito: trilha de exclusões, eventos de auditoria unificados e o feed de atividade, que trazem nomes de contatos, pastas e modelos apagados.

Mudança compatível: quatro operações novas; nenhuma operação existente muda.

Quatro operações novas, somente leitura:

GET /v4/api/contacts/{contactId}/envelopes - envelopes em que o contato participa (por e-mail ou, sem e-mail, por telefone), do mais recente ao mais antigo, paginado por offset (limit até 20; nextOffset na resposta, null no fim). Só aparecem os envelopes que o usuário responsável pela chave vê (mesmo recorte de pastas de GET /v4/api/envelopes). Não devolve link nem token de assinatura; sem CPF nem comparação de CPF; é um resumo recente (offset até 1000, depois nextOffset vem null). Contato inexistente ou de outra conta: 404. Escopo contacts:read.

GET /v4/api/contact-lists e GET /v4/api/contact-lists/{listId} - listas de contatos (participantes salvos) que o usuário responsável vê; o detalhe traz os contatos paginados (page, perPage). Criar, editar e apagar lista não existem na API pública. Escopo contacts:read.

GET /v4/api/request-logs - as chamadas feitas pela própria chave, nos últimos 30 dias, paginadas por cursor, com filtro status. Só metadados (método, rota, caminho, status, duração, código de erro, horário): sem corpo, cabeçalhos, IP nem Idempotency-Key. Nunca mostra chamadas de outra chave da conta. Escopo novo logs:read - chaves emitidas com escopos que precisem desta rota devem ganhá-lo; chaves sem escopos continuam podendo tudo.

Somando todas as operações novas de 18/09 acima, são 61 operações publicadas.

Mudança compatível: só operações novas e parâmetros opcionais; nenhuma operação existente muda.

Quatro operações novas de entregas e segredo de webhook, reaproveitando as mesmas regras da tela do Desenvolvedor:

GET /v4/api/webhooks/{webhookId}/deliveries - lista as entregas (tentativas de disparo) de um webhook, paginado, com filtro opcional por status (PENDING, DELIVERED, FAILED, SKIPPED) e por event.

GET /v4/api/webhooks/{webhookId}/deliveries/{deliveryId} - detalha uma entrega: o payload exato enviado e cada tentativa, com código HTTP e um recorte truncado da resposta (responseSnippet).

POST /v4/api/webhooks/{webhookId}/deliveries/{deliveryId}/retry - reenvia uma entrega FAILED ou SKIPPED, criando uma nova entrega com o mesmo payload. Exige Idempotency-Key. Responde 409 para entrega não reenviável (DELIVERED/PENDING) ou endpoint removido/inativo; 404 para webhookId/deliveryId inexistente, de outra conta, ou de outro webhook da mesma conta.

POST /v4/api/webhooks/{webhookId}/secret/rotate - gera um novo segredo de assinatura HMAC e o devolve em texto puro uma única vez. A rotação substitui o segredo na hora, sem período de convivência com o anterior. Não é idempotente e não aceita Idempotency-Key: repetir a chamada gira de novo e sempre devolve o segredo atual, nunca um replay do antigo.

Guia atualizado: Webhooks → Ver e reenviar entregas / Girar o segredo de assinatura.

Não existe GET .../secret (revelar) na API pública. O painel interno tem essa operação para quem administra a conta pelo navegador; na API pública o segredo só aparece na criação do endpoint e na rotação, nunca por consulta. Perdeu o segredo? Rotacione.

São 47 operações publicadas (as 42 anteriores, o ZIP do envelope e estas quatro).

Mudança compatível: quatro operações novas; nenhuma operação existente muda.

Nova operação: GET /v4/api/envelopes/{envelopeId}/download - gera uma URL temporária para baixar, em um único arquivo ZIP, todos os documentos do envelope: a versão selada, quando existir, ou a original, quando não. Aceita ?tipo=assinados (padrão) ou ?tipo=originais, o mesmo lote que a tela oferece em "Baixar todos". São 43 operações publicadas.

A resposta é { "url": "...", "expiresAt": "...", "fileName": "..." }, no mesmo formato de GET /v4/api/documents/{documentId}/download. A URL expira em 60 segundos e aponta para a mesma rota pública de streaming que a tela usa - não é um objeto novo no storage, e sim um ticket assinado que autoriza um download só.

Reusa a mesma autorização e a mesma checagem de conteúdo do "Baixar todos" da tela, sem rota nova além desta; nenhuma lógica de montagem do ZIP foi duplicada.

Escopo: envelopes:read.

A URL vale para um único download e expira em 60 segundos. Uma segunda chamada com a mesma URL - retry, dois cliques, cache do integrador - recebe a mesma recusa de "ticket inválido ou expirado" de um ticket já gasto, sem diferenciar os dois casos. Um ticket emitido antes do deploy que introduziu esse controle não é aceito.

Mudança compatível: operação nova; nenhuma operação existente muda.

Três operações novas, de modelos: GET /v4/api/templates (lista os modelos visíveis à integração, com paginação), GET /v4/api/templates/{templateId} (documentos, vagas de participante e campos posicionados - o que é preciso para preencher a próxima operação) e POST /v4/api/templates/{templateId}/envelopes (cria um envelope a partir do modelo, preenchendo cada vaga com os dados reais do participante - nome, e-mail, telefone - e opcionalmente enviando na mesma chamada com send: true). São 50 operações publicadas (as 47 anteriores e estas três).

Para usar: chame GET /v4/api/templates/{templateId}, pegue o id de cada item em participants (a vaga) e mande de volta em participants[].templateParticipantId no corpo do POST. Casar por posição no array ou pelo nome do papel não é seguro - o id é a única referência estável se o modelo for reordenado depois.

A resposta do POST segue o mesmo formato de GET /v4/api/envelopes/{envelopeId}. Exige Idempotency-Key, como todo POST desta API.

Recusas: 404 RESOURCE_NOT_FOUND quando o modelo não existe na conta ou é privado sem acesso da integração (a mesma resposta nos dois casos, de propósito); 403 quando a conta não tem o recurso de modelos no plano; 422 UNPROCESSABLE_ENTITY quando falta participante para alguma vaga do modelo que exige pessoa (signatário/aprovador etc.) e send: true - o corpo error.details.missingSlots lista as vagas faltantes, checado antes de qualquer instanciação; e os mesmos 403/400/409 de POST /v4/api/envelopes/{envelopeId}/send quando send: true - os limites do plano (cota do ciclo, documentos por envelope, volume) valem exatamente como no envio direto.

Com send: false o preenchimento parcial das vagas continua válido - o rascunho é criado com o que veio, e o restante pode ser completado depois.

O que fica de fora nesta primeira versão, por decisão registrada no PR: CPF do participante e valor inicial de campo não são aceitos no corpo. Nenhum caminho existente do produto preenche esses dois dados fora da tela de assinatura, e abrir isso agora seria escrever regra de produto nova sem pedido.

POST /v4/api/templates/{templateId}/envelopes exige o escopo envelopes:send da chave, mesmo quando o corpo só monta rascunho (send: false) - o mapa de escopos é por rota, e esta rota pode enviar. Uma chave que só deve ler modelo e montar rascunho usa POST /v4/api/envelopes no fluxo em várias chamadas.

Mudança compatível: três operações novas; nenhuma operação existente muda.

2026-09-17

Escopos da chave passam a valer. Uma chave emitida com escopos recebe 403 API_SCOPE_INSUFFICIENT em qualquer operação fora deles, com o escopo que falta em error.details.requiredScope. A lista de escopos e as operações de cada um estão em Introdução. Toda operação publicada passa a declarar esse 403.

Mudança compatível para as chaves existentes: todas foram emitidas sem escopos, e chave sem escopos continua podendo tudo. GET /v4/api/me não exige escopo.

A chave passa a enxergar o que o usuário responsável enxerga. Até aqui ela via a conta inteira, inclusive pastas restritas e os envelopes dentro delas, mesmo quando quem a emitiu não os via no aplicativo. Agora:

GET /v4/api/folders/tree, GET /v4/api/folders/contents e GET /v4/api/envelopes listam, contam e paginam só o que o usuário responsável (ou o membro em x-on-behalf-of) vê: pastas públicas, pastas em que ele tem permissão e o caminho até elas, e os envelopes dessas pastas. meta.totalCount e hasMore seguem o mesmo recorte;

envelope sem pasta: já enviado, é visível a todos os membros da conta; ainda rascunho, só a quem o criou e ao proprietário, como no aplicativo;

operações sobre um envelope, documento ou pasta fora dessa visibilidade, inclusive a pasta de destino de uma movimentação ou de um send-now, respondem 404 RESOURCE_NOT_FOUND, como um identificador inexistente. Para uma pasta citada por identificador vale a regra direta (pública, ou com permissão do usuário nela): ter permissão numa subpasta não dá acesso à pasta pai;

canWrite em GET /v4/api/folders/contents deixa de vir sempre true e passa a refletir a permissão do usuário responsável;

excluir pasta, excluir rascunho e criar subpasta em pasta privada passam a exigir da chave o mesmo que o aplicativo exige do usuário responsável (permissão de escrita na pasta, ou ser quem criou o rascunho, ou papel que administra a conta). Fora dessas três, uma operação de escrita sobre um envelope ou pasta que o usuário responsável vê continua sem exigir permissão de escrita nem papel administrativo;

webhooks não mudam: um endpoint cadastrado pela chave continua recebendo eventos de todos os envelopes da conta, independentemente de quem emitiu a chave.

Quem é afetado: só chaves emitidas por quem não é o proprietário da conta (papel DEVELOPER ou permissão API_CREDENTIALS_MANAGE), ou que agem em nome de outro membro. Proprietário é o membro com papel OWNER; a chave dele continua vendo e operando a conta inteira. Para uma integração que precisa enxergar uma pasta restrita, dê ao usuário responsável acesso a essa pasta.

2026-09-16

Nova operação: POST /v4/api/envelopes/{envelopeId}/participants/{participantId}/approve - a integração registra a aprovação de um participante com papel de aprovador, quando é a vez dele. São 41 operações publicadas.

Para usar: liste os participantes com GET /v4/api/envelopes/{envelopeId}/participants, escolha o aprovador (pelo e-mail, por exemplo) e chame a operação com o id dele e uma Idempotency-Key. O corpo é opcional: { "documentNumber": "<CPF>" }, se quiser registrar o CPF.

A resposta traz approvalId, approvedAt, alreadyApproved e approvedVia, que vale API (a aprovação foi registrada por esta operação) ou OTHER (veio de outro caminho: link do aprovador, assinatura em lote no app ou origem não registrada). Repetir a chamada depois de aprovado devolve 200 com alreadyApproved: true, sem gravar de novo, inclusive quando a aprovação veio de outro caminho (nesse caso, approvedVia: "OTHER"). Duas chamadas simultâneas também recebem esse sucesso.

No histórico do envelope a aprovação aparece como API integração - nome da chave, com o nome do aprovador em metadata.approverName e metadata.via = "API". O evento continua PARTICIPANT_APPROVED. O nome da chave fica só no histórico da conta: no histórico que os participantes veem pelo link de assinatura, a aprovação aparece com o nome do aprovador, e os demais eventos feitos pela integração aparecem como Integração da conta. No relatório de aprovações do documento selado, a aprovação traz o nome do aprovador e a linha Registrada por: API integração - nome da chave.

Exige o recurso aprovação pela API, liberado por conta: sem ele, 403 API_APPROVAL_NOT_ENABLED. Novo campo features.apiApprovalEnabled em GET /v4/api/account/entitlements diz se a conta tem o recurso.

Recusas com código próprio: 409 PARTICIPANT_NOT_APPROVER (signatário e observador não são aprovados por aqui), 409 GROUP_APPROVER_NOT_SUPPORTED, 409 PARTICIPANT_ALREADY_DECLINED, 409 ENVELOPE_NOT_APPROVABLE (com details.status), 403 APPROVER_WAITING_TURN, 403 DEADLINE_EXPIRED e 400 INVALID_CPF.

Mudança compatível: operação nova e campo novo em features; nenhum campo existente muda. Um client que recuse campos desconhecidos em features precisa tolerar apiApprovalEnabled.

Nova operação: GET /v4/api/folders/tree. Lista todas as pastas da conta, de todos os níveis, numa lista plana. Cada item traz id, parentId, name, isPublic e depth (0 para as pastas da raiz). Os itens vêm ordenados por profundidade e depois por nome, então cada pasta aparece depois da pasta que a contém, e a árvore pode ser montada numa única leitura. Paginação igual à de GET /v4/api/folders/contents: page, perPage (até 500, padrão 500) e meta.hasMore. São 42 operações publicadas.

Por quê perPage default é o teto (500) e não 100: a paginação é por OFFSET sobre uma consulta recursiva, que reprocessa a árvore inteira da conta a cada página. Medido em produção: a maior conta tem 1.929 pastas (10.820 pastas em 1.787 contas no total); com default 100 essa conta precisaria de 20 páginas, cada uma reprocessando a árvore inteira. Com 500, caem para 4.

Por quê a operação existe: GET /v4/api/folders/contents devolve um nível por chamada, e montar a árvore exigia uma chamada para cada pasta com subpastas.

Mudança compatível: operação nova; nenhuma operação existente muda.

GET /v4/api/invites passa a trazer expiresAt (data e hora) e expired (booleano) em cada convite. Convites de membro vencem 30 dias depois do envio; reenviar o convite pela tela de Membros renova a validade. O convite vencido continua na listagem, com expired: true, até ser reenviado ou removido.

Mudança compatível: campos novos; nenhum campo existente muda. Um client que recuse campos desconhecidos nos itens de invites precisa tolerá-los.

Mudança que quebra compatibilidade: GET /v4/api/envelopes/{envelopeId}/participants deixa de devolver documentNumber nos signatários. No lugar entra documentNumberMasked - o CPF sempre mascarado, ***.456.789-**, ou null quando o signatário não tem CPF de 11 dígitos.

Por quê: o CPF inteiro nunca é devolvido pela API. É o dado de uma pessoa que não é quem integra, e acompanhar o andamento do envelope não depende do número completo - o mesmo critério de expectedCpfMasked nos contatos, desde 2026-09-15.

O que fazer: um client que lia documentNumber passa a ler documentNumberMasked. O CPF que o signatário informa ao assinar continua gravado e indo para a assinatura; só a leitura por esta operação é mascarada.

POST /v4/api/envelopes/send-now passa a responder 429 ACCOUNT_HOURLY_VOLUME_LIMIT quando a conta já criou, na última hora, o teto de envelopes do plano: 20 no gratuito e 150 nos pagos. Contam todos os envelopes da conta criados na janela que não são rascunho, inclusive os que ainda aguardam o envio dos documentos. O mesmo vale para POST /v2/envelopes e POST /v3/envelopes.

A mesma operação passa a responder 403 ENVELOPE_SIGNATORIES_LIMIT quando o envelope tem mais destinatários que o teto do plano: 50 no gratuito e 100 nos pagos. Participante de grupo conta por membro do grupo. O mesmo vale para POST /v2/envelopes e POST /v3/envelopes.

Nos dois casos a recusa acontece na criação: nenhum envelope é criado e nenhuma URL de upload é devolvida. São os mesmos tetos que POST /v4/api/envelopes/{envelopeId}/send já aplicava.

O 429 de send-now passa a declarar os dois motivos, com um exemplo de cada: RATE_LIMIT_EXCEEDED (teto de requisições por minuto, com retry-after) e ACCOUNT_HOURLY_VOLUME_LIMIT (teto de envelopes por hora, sem retry-after). Diferencie pelo error.code: repetir a chamada em segundos não resolve o segundo.

GET /v4/api/folders/contents passa a trazer currentFolder.canWrite (booleano) quando a listagem é de uma pasta. Pela chave de API ele vem sempre true: a integração age pela conta e não herda a permissão de pasta do membro que emitiu a chave. Na raiz, currentFolder continua null.

Mudança compatível: campo novo; nenhum campo existente muda. Um client que recuse campos desconhecidos em currentFolder precisa tolerá-lo.

GET /v4/api/folders/contents passa a trazer canWrite (booleano) em cada item do tipo FOLDER de items. Pela chave de API ele vem sempre true, pelo mesmo motivo de currentFolder.canWrite. Itens do tipo ENVELOPE não mudam.

Mudança compatível: campo novo; nenhum campo existente muda. Um client que recuse campos desconhecidos nos itens de pasta precisa tolerá-lo.

2026-09-15

Nova operação: POST /v4/api/envelopes/send-now - cria o envelope com documentos, participantes, cópias e campos numa só chamada, devolve as URLs para enviar os arquivos, e o envio aos participantes acontece sozinho quando todos os documentos terminam de processar. É o equivalente de POST /v3/envelopes na API pública, com o mesmo corpo. Exige Idempotency-Key. No histórico do envelope, a criação e o envio aparecem como API integração - nome da chave. São 40 operações publicadas.

role em GET /v4/api/members e GET /v4/api/invites pode trazer um valor novo: DEVELOPER - o membro que administra chaves de API e webhooks sem ser proprietário.

Mudança compatível: nenhum papel existente muda. Um client que valide role contra uma lista fixa precisa incluir o valor novo.

Novo limite do plano: documentsPerEnvelope em GET /v4/api/account/entitlements - quantos documentos cabem num envelope. Padrão: 10 no plano gratuito e 20 nos pagos; 0 significa sem teto (liberado por conta).

POST /v4/api/envelopes/{envelopeId}/documents passa a responder 422 DOCUMENTS_PER_ENVELOPE_EXCEEDED quando o envelope passaria do limite, com details.limit, details.current e details.incoming. O mesmo vale para POST /v2/envelopes e POST /v3/envelopes. Nenhum documento é criado quando a recusa acontece.

Contatos ganham dois campos opcionais em POST /v4/api/contacts e PUT /v4/api/contacts/{contactId}: expectedCpf (CPF esperado, validado pelos dígitos; null limpa) e preferences (role, qualification, deliveryMethod, authMethod; null limpa). Omitir o campo no PUT mantém o valor gravado.

As respostas de contato trazem expectedCpfMasked (sempre mascarado, ***.456.789-**, ou null) e preferences. O CPF inteiro nunca é devolvido. O CPF esperado serve só para conferência: não preenche nem substitui o CPF que a pessoa declara ao assinar.

Mudança compatível: campos novos e opcionais; nenhum campo existente muda.

2026-09-14

authMethod aceita um valor novo: SELFIE_WITH_DOCUMENT - UMA foto, com o rosto e o documento de identificação na mão, ao lado. É diferente de DOCUMENT_AND_SELFIE, que pede fotos separadas (selfie, frente e verso).

Mudança compatível: nenhum método existente muda. Um client que valide authMethod contra uma lista fixa precisa incluir o valor novo.

Correção de comportamento: SELFIE_ONLY e DOCUMENT_ONLY, anunciados em 2026-09-08, agora concluem a assinatura com as fotos do próprio método. Antes a sessão de captura só fechava com as três fotos, e esses métodos não conseguiam assinar.

2026-09-10

Os POST da API pública passam a declarar as recusas da idempotência, e não só o sucesso. Entram no contrato dois status que ele não tinha: 422 e 503. O comportamento do servidor não muda - o que muda é o contrato passar a descrevê-lo, para um gerador de client criar o ramo de tratamento antes de a recusa aparecer em produção.

422 - a Idempotency-Key já foi usada em uma requisição com rota ou corpo diferente. É a proteção contra reaproveitar a mesma chave para outra operação: a segunda chamada é recusada em vez de devolver o resultado da primeira, que seria a resposta errada para o pedido feito. Gere uma chave nova por operação lógica.

503 - o serviço de idempotência está indisponível e a operação foi recusada por isso. É recusa deliberada, e não falha de infraestrutura vazando: sem poder registrar a chave, o servidor não consegue garantir que um retry seu não vire duplicata. Trate como retentável, com espera.

400 (Idempotency-Key ausente) já era exigido antes desta data e continua igual; o que muda é ele estar declarado nas operações onde faltava.

A distinção entre 409 e 422 importa para quem integra: 409 é conflito do recurso (o estado não permite a operação); 422 é conflito da chave (esta chave já respondeu outra coisa).

2026-09-09

O histórico do envelope passa a poder trazer o evento ENVELOPE_RESEALED: o selo de um envelope já concluído foi refeito por operação interna. Ele não aparece em envelope novo - só quando um documento precisa ser selado de novo, tipicamente depois de uma falha de processamento.

Mudança compatível: nenhum evento existente muda de nome ou de significado. Mas um client que valide o evento contra uma lista fixa, ou que use switch sem default, precisa tolerar valores novos - a lista de eventos cresce com a plataforma.

O envelope continua COMPLETED durante e depois da reselagem, e a notificação de conclusão não é reenviada aos signatários. O webhook ENVELOPE_COMPLETED continua saindo, como já saía.

2026-09-08

authMethod aceita dois valores novos: SELFIE_ONLY (só a selfie) e DOCUMENT_ONLY (frente e verso do documento, sem selfie). DOCUMENT_AND_SELFIE continua pedindo as três fotos e não muda.

Mudança compatível: quem não usar os valores novos não é afetado, e nenhuma assinatura existente muda de comportamento. Mas um client que valide authMethod contra uma lista fixa precisa incluí-los - senão recusa um envelope que a API aceita.

O que muda na prática para quem integra: ao configurar um participante com um desses métodos, ele fotografa apenas as etapas correspondentes. A assinatura é recusada se as fotos entregues não forem exatamente as exigidas pelo método.

2026-09-07

Nova operação: POST /v4/api/envelopes/{envelopeId}/documents/{documentId}/confirm-conversion. Ela fecha o envio de .docx pela API pública: quem manda um .docx em POST .../documents recebe a prévia convertida em PDF e precisa confirmá-la antes de seguir. Sem esta operação o envelope ficava parado na conversão, sem caminho de saída pela API. São 39 operações publicadas.

As operações passaram a declarar as recusas, e não só o sucesso: 400, 403, 404, 409 e 413 agora fazem parte do OpenAPI, com exemplo de corpo. Antes, um gerador de client não criava o ramo de tratamento desses status e a recusa aparecia primeiro em produção.

A resposta de erro voltou a trazer details. O campo existe em 409 SIGNATURES_NEED_RESET (details.affectedSignatoryIds), em 400 FIELD_PAGE_OUT_OF_BOUNDS (details.documentId, page, pageCount) e em 413 DOCUMENT_TOO_LARGE.

403 por limite de plano na API pública passou a sair como 403. Antes, o serializer recusava o corpo e o cliente recebia 500 no lugar da recusa.

Os limites de tamanho de arquivo do plano da conta passaram a valer também em POST /v2/envelopes e POST /v3/envelopes, que antes aplicavam só o teto técnico. O contrato dessas rotas não mudou; o comportamento sim.

Sem mudança: 401 (chave ausente, inválida ou revogada) e 429 (teto de requisições da conta) já eram declarados antes desta data.

2026-09-06

A referência passou a organizar as 38 operações em nove recursos.

Sandbox e Produção passaram a constar no contrato, com Sandbox em primeiro lugar.

Todas as operações passaram a declarar operationId, título e descrição públicos.

Headers de rate limit e a resposta 429 passaram a fazer parte do OpenAPI.

Foram adicionados guias de IA, Postman, paginação, erros e exemplos por linguagem.

Política

Mudança compatível: pode ser publicada na v4 com registro neste changelog.

Mudança incompatível: exige nova versão ou período formal de migração.

A remoção de campo, status, evento ou comportamento publicado nunca deve acontecer silenciosamente.

Changelog

Changelog da API pública#

2026-10-07 (limite por ciclo de envelopes com ICP-Brasil e com selfie)#

2026-10-07 (locale no PATCH de participante)#

2026-10-07 (motivo da desativação e última falha em webhooks)#

2026-10-07 (documentação do campo locale dos participantes)#

2026-10-07 (evento de teste de webhook)#

2026-10-07 (campo environment em GET /v4/api/request-logs)#

2026-10-07 (lembrete recusado quando o e-mail do participante está bloqueado)#

2026-10-06 (PDF de exemplo para testar a integração)#

2026-10-06 (bloco quota em GET /v4/api/account/entitlements)#

2026-10-05 (nomes de operação padronizados no OpenAPI)#

2026-10-05 (saldo de mensagens em GET /v4/api/account/entitlements)#

2026-10-05 (histórico de entregas de webhook por 15 dias)#

2026-10-04 (resposta do seu servidor mascarada no detalhe da entrega)#

2026-10-04 (desativação automática de webhook)#

2026-10-03 (prazo parado na suspensão por pagamento pendente)#

2026-10-03 (CPF esperado na assinatura ICP-Brasil)#

2026-10-03 (envelope anulado: hadSignature)#

2026-10-03 (webhook exige API e não vai para conta suspensa)#

2026-10-03 (convite de SUPERVISOR)#

2026-10-03 (teto de endpoints de webhook)#

2026-10-03 (campos automáticos: nome e CPF do signatário)#

2026-10-03 (regras na opção: campo condicional e texto padrão)#

2026-10-02 (campo Lista Suspensa: DROPDOWN)#

2026-10-02 (conta suspensa por pagamento pendente)#

2026-10-02 (documentos visíveis por participante)#

2026-10-02 (âncora no send-now)#

2026-10-02 (exemplos de corpo e Idempotency-Key)#

2026-10-02 (âncora direto no campo)#

2026-10-02 (posicionar campos por texto âncora)#

2026-10-02 (tamanho das páginas do documento)#

2026-10-02 (verificação pública de documento selado na v4)#

2026-10-02 (verificação pública de documento selado na v4)#

2026-10-02 (detalhe do envelope v2: evento interno fora de logs[])#

2026-10-02 (ENVELOPE_COMPLETED: hash do arquivo selado)#

2026-10-02 (correção: papel do signatário nos eventos de recusa e e-mail não entregue)#

2026-10-02 (webhook de e-mail não entregue: EMAIL_BOUNCED)#

2026-10-01 (webhook de recusa: PARTICIPANT_DECLINED)#

2026-10-01 (aprovação pela API registra a origem)#

2026-10-01 (validação por id passa a exigir login)#

2026-10-01 (participantes: dados de quem já agiu são os do ato)#

2026-10-01 (validação: nome de quem assinou é o do ato)#

2026-10-01 (correção de envelope: troca de tipo ou grupo)#

2026-09-30 (escritas seguem o direito do usuário responsável)#

2026-09-30 (prazo de PATCH /v2/envelopes/{envelopeId}/deadline)#

2026-09-30 (erro de validação: error.context no corpo vazio)#

2026-09-30 (deadline de entrada tipado como string)#

2026-09-30 (webhooks: segredo fora do replay e URL IPv6)#

2026-09-30 (validade da chave no /me)#

2026-09-29 (contato: email e phoneNumber sempre presentes)#

2026-09-29 (API_KEY_EXPIRED: chave com validade)#

2026-09-29 (corrigir modelo montado pela API)#

2026-09-29 (tagIds valida UUID)#

2026-09-29 (etiquetas na listagem)#

2026-09-29 (montar modelos pela API)#

2026-09-29 (etiquetas)#

2026-09-29 (consumo do ciclo)#

2026-09-29 (reordenar documentos e duplicar envelope)#

2026-09-28 (listar grupos)#

2026-09-28 (relatório de uso aceita a permissão de ver relatórios)#

2026-09-28 (prazo aceita a data sozinha como o dia informado)#

2026-09-26 (filtro pelo estado do participante)#

2026-09-19 (opções do participante no modelo)#

2026-09-19 (contagem de "pendentes")#

2026-09-18 (paginação das listas)#

2026-09-18#

2026-09-17#

2026-09-16#

2026-09-15#

2026-09-14#

2026-09-10#

2026-09-09#

2026-09-08#

2026-09-07#

2026-09-06#

Política#

Changelog da API pública

2026-10-07 (limite por ciclo de envelopes com ICP-Brasil e com selfie)

2026-10-07 (locale no PATCH de participante)

2026-10-07 (motivo da desativação e última falha em webhooks)

2026-10-07 (documentação do campo locale dos participantes)

2026-10-07 (evento de teste de webhook)

2026-10-07 (campo environment em GET /v4/api/request-logs)

2026-10-07 (lembrete recusado quando o e-mail do participante está bloqueado)

2026-10-06 (PDF de exemplo para testar a integração)

2026-10-06 (bloco quota em GET /v4/api/account/entitlements)

2026-10-05 (nomes de operação padronizados no OpenAPI)

2026-10-05 (saldo de mensagens em GET /v4/api/account/entitlements)

2026-10-05 (histórico de entregas de webhook por 15 dias)

2026-10-04 (resposta do seu servidor mascarada no detalhe da entrega)

2026-10-04 (desativação automática de webhook)

2026-10-03 (prazo parado na suspensão por pagamento pendente)

2026-10-03 (CPF esperado na assinatura ICP-Brasil)

2026-10-03 (envelope anulado: hadSignature)

2026-10-03 (webhook exige API e não vai para conta suspensa)

2026-10-03 (convite de SUPERVISOR)

2026-10-03 (teto de endpoints de webhook)

2026-10-03 (campos automáticos: nome e CPF do signatário)

2026-10-03 (regras na opção: campo condicional e texto padrão)

2026-10-02 (campo Lista Suspensa: DROPDOWN)

2026-10-02 (conta suspensa por pagamento pendente)

2026-10-02 (documentos visíveis por participante)

2026-10-02 (âncora no send-now)

2026-10-02 (exemplos de corpo e Idempotency-Key)

2026-10-02 (âncora direto no campo)

2026-10-02 (posicionar campos por texto âncora)

2026-10-02 (tamanho das páginas do documento)

2026-10-02 (verificação pública de documento selado na v4)

2026-10-02 (verificação pública de documento selado na v4)

2026-10-02 (detalhe do envelope v2: evento interno fora de logs[])

2026-10-02 (ENVELOPE_COMPLETED: hash do arquivo selado)

2026-10-02 (correção: papel do signatário nos eventos de recusa e e-mail não entregue)

2026-10-02 (webhook de e-mail não entregue: EMAIL_BOUNCED)

2026-10-01 (webhook de recusa: PARTICIPANT_DECLINED)

2026-10-01 (aprovação pela API registra a origem)

2026-10-01 (validação por id passa a exigir login)

2026-10-01 (participantes: dados de quem já agiu são os do ato)

2026-10-01 (validação: nome de quem assinou é o do ato)

2026-10-01 (correção de envelope: troca de tipo ou grupo)

2026-09-30 (escritas seguem o direito do usuário responsável)

2026-09-30 (prazo de `PATCH /v2/envelopes/{envelopeId}/deadline`)

2026-09-30 (erro de validação: `error.context` no corpo vazio)

2026-09-30 (deadline de entrada tipado como string)

2026-09-30 (webhooks: segredo fora do replay e URL IPv6)

2026-09-30 (validade da chave no /me)

2026-09-29 (contato: email e phoneNumber sempre presentes)

2026-09-29 (API_KEY_EXPIRED: chave com validade)

2026-09-29 (corrigir modelo montado pela API)

2026-09-29 (tagIds valida UUID)

2026-09-29 (etiquetas na listagem)

2026-09-29 (montar modelos pela API)

2026-09-29 (etiquetas)

2026-09-29 (consumo do ciclo)

2026-09-29 (reordenar documentos e duplicar envelope)

2026-09-28 (listar grupos)

2026-09-28 (relatório de uso aceita a permissão de ver relatórios)

2026-09-28 (prazo aceita a data sozinha como o dia informado)

2026-09-26 (filtro pelo estado do participante)

2026-09-19 (opções do participante no modelo)

2026-09-19 (contagem de "pendentes")

2026-09-18 (paginação das listas)

2026-09-18

2026-09-17

2026-09-16

2026-09-15

2026-09-14

2026-09-10

2026-09-09

2026-09-08

2026-09-07

2026-09-06

Política