Introdução

A API pública da SuperSign permite criar, configurar, enviar e acompanhar envelopes de assinatura eletrônica diretamente pelo seu sistema.

Nova integração: use exclusivamente os endpoints /v4/api/*. Comece no Sandbox com uma chave ss_test_... e passe para Produção com uma chave ss_live_... depois da homologação.

Ambiente

Ambiente	URL base
Sandbox	`https://api.sandbox.supersign.com.br`
Produção	`https://api.sign.supersign.com.br`

Sandbox e Produção executam o mesmo contrato. O Sandbox não possui validade jurídica e identifica os documentos como teste. A Beta é interna da SuperSign e não faz parte da API pública.

Montando a URL

Toda operação é URL base + caminho do contrato, e o caminho já começa em /v4/api. Não acrescente outro prefixo nem misture versões:

Certo	Errado (responde `404`)
`https://api.sign.supersign.com.br/v4/api/me`	`.../v4/api/api/me` (prefixo `/api` repetido)
`https://api.sign.supersign.com.br/v4/api/envelopes/{id}`	`.../v4/api/v2/envelopes/{id}` (versão legada dentro da v4)

Onde está cada coisa

Os nomes mais tentados que não existem, e a operação que devolve o que se procurava:

Procurando	Use
a conta e a chave (`/accounts`)	`GET /v4/api/me` e `GET /v4/api/account`
o que o plano libera (`/capabilities`)	`GET /v4/api/account/entitlements`
a lista de pastas (`/folders`, `/folders/all`)	`GET /v4/api/folders/tree` (árvore) ou `GET /v4/api/folders/contents` (conteúdo de uma pasta)
os grupos da conta e o `groupId`	`GET /v4/api/groups`
os membros da conta	`GET /v4/api/members`

A lista completa, com parâmetros e respostas, está na Referência da API.

Autenticação

Envie a chave em todas as requisições:

A chave ss_live_... não é um JWT de sessão. Não envie x-account-id: a conta é definida pela própria credencial.

Valide a integração antes de criar um envelope:

A resposta informa o ambiente, a conta, o nome da integração e o usuário responsável.

Quem a chave representa

A API Key age como o usuário que a criou (ou como o membro indicado em x-on-behalf-of, quando a chave tem essa delegação): enxerga as mesmas pastas e envelopes que essa pessoa enxerga no aplicativo. A chave do proprietário da conta (papel OWNER) vê a conta inteira.

Duas coisas não seguem essa visibilidade. Webhooks são da conta: um endpoint cadastrado pela chave recebe eventos de todos os envelopes da conta, seja quem for o usuário responsável. E, dentro do que o usuário responsável vê, parte das operações de escrita sobre um envelope (configurações, sincronizar participantes, documentos, campos, enviar) não exige da chave a permissão de escrita nem o papel administrativo que o aplicativo exigiria dele. Exigem, como no aplicativo: anular, editar participante, reenviar lembrete, aprovar pela API, mover envelope, criar envelope dentro de pasta privada, excluir rascunho, excluir pasta e criar subpasta em pasta privada. Quem não tem o direito recebe o mesmo erro que o aplicativo daria.

Somente o proprietário da conta, um membro com o papel DEVELOPER ou um membro com a permissão explícita API_CREDENTIALS_MANAGE pode criar e administrar credenciais. As ações aparecem no histórico do envelope como API integração - nome da integração, com a credencial e o usuário responsável registrados de forma estruturada para auditoria. O segredo da chave nunca é gravado no histórico.

Mudar as permissões de pasta do usuário responsável muda o que a integração enxerga. Um envelope ou uma pasta fora dessa visibilidade responde 404 RESOURCE_NOT_FOUND, como um identificador inexistente. Remover ou suspender o usuário responsável encerra a credencial de forma fail-closed; rotacione a chave antes de remover esse usuário.

Escopos da chave

Uma chave é emitida com acesso total ou com uma lista de escopos. Com acesso total, ela faz tudo o que a API oferece; com escopos, cada operação fora da lista responde 403 API_SCOPE_INSUFFICIENT, com o escopo que falta em error.details.requiredScope. As chaves emitidas antes de 29/09/2026 têm acesso total. GET /v4/api/me não exige escopo.

Uma chave pode ser emitida com validade (30, 90, 180 ou 365 dias). Depois dela, toda chamada responde 401 API_KEY_EXPIRED: emita outra chave e troque na integração. Chave emitida sem validade, como as anteriores a 29/09/2026, não vence.

Escopo	Operações
`account:read`	`GET /account`, `GET /account/entitlements`, `GET /account/entitlements/catalog`
`envelopes:read`	consultar e listar envelopes, participantes, documentos, campos, histórico e o download
`envelopes:write`	criar e excluir rascunho, configurações, participantes, documentos, campos e mover de pasta
`envelopes:send`	`POST /envelopes/{id}/send`, `POST /envelopes/send-now` e o lembrete ao participante
`envelopes:void`	`POST /envelopes/{id}/void`
`approvals:write`	`POST /envelopes/{id}/participants/{participantId}/approve`
`folders:read`	`GET /folders/tree`, `GET /folders/contents`, `GET /folders/{id}`
`folders:write`	criar, renomear, mover e excluir pasta
`contacts:read`	listar e consultar contatos, seus envelopes e as listas de contatos (`GET /contact-lists`)
`contacts:write`	criar, editar e excluir contato
`members:read`	`GET /members`, `GET /groups`, `GET /invites`
`templates:read`	listar e consultar modelos e o processamento dos documentos do modelo
`templates:write`	criar, editar, duplicar e ativar modelo; documentos, vagas e campos do modelo
`tags:read`	`GET /tags` (catálogo de etiquetas)
`tags:write`	aplicar e remover etiqueta de um envelope
`webhooks:read`	`GET /webhooks`
`webhooks:write`	criar, editar e excluir webhook
`logs:read`	`GET /request-logs` (chamadas da própria chave)
`audit:read`	`GET /audit/voided-envelopes`
`reports:read`	`GET /reports/envelopes`, `GET /reports/envelopes-usage`

Os escopos só restringem: nenhum deles amplia o que a chave enxerga nem o que o plano da conta permite. O que a chave pode fazer dentro do que enxerga está descrito em Quem a chave representa.

Idempotência

Todas as operações POST exigem o header Idempotency-Key, com um valor único de 8 a 255 caracteres ASCII imprimíveis.

Em uma repetição causada por timeout, reutilize a mesma chave somente se a requisição for exatamente a mesma. Resultados bem-sucedidos ficam disponíveis para replay por 24 horas.

Fluxo de um envelope

Valide a chave com GET /v4/api/me.

Crie o rascunho com POST /v4/api/envelopes/.

Configure título, mensagem e prazo com PATCH /v4/api/envelopes/{envelopeId}/settings.

Defina os participantes com PUT /v4/api/envelopes/{envelopeId}/participants.

Registre o PDF com POST /v4/api/envelopes/{envelopeId}/documents.

Envie o binário para a URL assinada retornada. O conteúdo do PDF não é enviado em Base64 para a API.

Posicione os campos com PUT /v4/api/envelopes/{envelopeId}/documents/{documentId}/fields.

Envie o envelope com POST /v4/api/envelopes/{envelopeId}/send.

Consulte o estado com GET /v4/api/envelopes/{envelopeId}.

Enquanto um documento estiver em processamento, o envio pode responder 409 ENVELOPE_DOCUMENTS_NOT_READY. Aguarde e repita a mesma operação com a mesma Idempotency-Key.

As rotas de coleção terminam com / no contrato atual. Preserve a barra final em /envelopes/, /folders/, /members/, /invites/ e /webhooks/.

Migração da API legada

As APIs /v2 e /v3 continuam atendendo integrações existentes com seus contratos atuais. Não inicie uma nova integração nelas.

Desde 29/09/2026, as respostas de POST /v3/envelopes trazem os cabeçalhos Deprecation e Link (rel="deprecation"), apontando para este guia. Eles só avisam: o corpo, o status e o comportamento da rota não mudam, e ainda não há data de desligamento. Quando houver, ela será anunciada no changelog e no cabeçalho Sunset, com antecedência.

O contrato dessas rotas não muda, mas os limites do plano da conta valem igualmente nelas: desde 07/09/2026, POST /v2/envelopes e POST /v3/envelopes recusam documento acima do tamanho máximo de arquivo do plano, do mesmo jeito que /v4/api/*. O teto é o do plano contratado - consulte GET /v4/api/account/entitlements para saber o valor da sua conta.

As novas chaves ss_live_... operam em /v4/api/*. Uma integração existente não migra apenas trocando o token: é necessário atualizar os endpoints e, conforme a rota, o formato das chamadas.

Criar e enviar numa chamada

POST /v3/envelopes tem o equivalente direto: POST /v4/api/envelopes/send-now, com o mesmo corpo. POST /v2/envelopes tem o mesmo propósito, mas o corpo é diferente - veja o mapeamento abaixo. Em ambos, a resposta traz as URLs para enviar os arquivos, e o envio aos participantes acontece sozinho quando todos os documentos terminam de processar. Quem precisa de controle passo a passo - revisar um DOCX convertido, posicionar campos depois do upload - usa o fluxo em etapas descrito acima.

De `POST /v2/envelopes` para `POST /v4/api/envelopes/send-now`

`POST /v2/envelopes`	`POST /v4/api/envelopes/send-now`
`title` (opcional, mínimo 2 caracteres)	`title` (obrigatório, mínimo 1 caractere)
`documents[].id`	`documents[].ref` (identificador que você escolhe; volta como `documentRef` na resposta)
`documents[].fileName`	`documents[].filename` (minúsculo)
`documents[].contentType`, `documents[].fileSize`	iguais
`signatories[].id`	`signatories[].ref`
`signatories[].signingOrder`	`signatories[].order`
`signatories[].authMethod` (obrigatório: `EMAIL`, `PKI_BRAZIL`, `SMS` ou `WHATSAPP`)	`signatories[].deliveryMethod` (obrigatório: `EMAIL`, `SMS` ou `WHATSAPP`, por onde o convite chega) e `signatories[].authMethod` (opcional, como o participante se autentica; o contrato também lista os métodos de verificação de identidade). Quem usava `authMethod: "PKI_BRAZIL"` na v2 passa a enviar `deliveryMethod` (`EMAIL`, `SMS` ou `WHATSAPP`) e `authMethod: "PKI_BRAZIL"`
`signatories[].phoneNumber` (SMS/WhatsApp)	`signatories[].phoneNumber`, exigido quando `deliveryMethod` ou `authMethod` é SMS ou WHATSAPP
`signatories[].name`, `email`, `qualification`	iguais; `name` e `email` são exigidos conforme o tipo (`type`: `INDIVIDUAL` por padrão, ou `GROUP` com `groupId`)
`observers[].email`, `notifyOnSent`, `notifyOnCompletion`	`observers[]` passa a ser um participante (`deliveryMethod`, `name`, `email`, `order`, `mandatoryView`). Os campos `notifyOnSent` e `notifyOnCompletion` não existem na v4
não existe	`approvers[]` (participantes aprovadores, mesmo formato dos observadores, sem `mandatoryView`) e `carbonCopies[]` (`name` e `email`)
`fields[].documentId`, `signatoryId`, `pageNumber`, `position {x, y, width, height}`	`fields[].documentRef`, `signatoryRef`, `pageNumber`, com `position` e `size` separados; `properties` segue o tipo do campo (o contrato lista `SIGNATURE`, `INITIALS`, `SIGNING_DATE`, `TEXT`, `ATTACHMENT`, `CHECKBOX_GROUP` e `RADIO_GROUP`)
resposta `uploadDetails[].documentId`, `fileName`, `uploadUrl`, `uploadHeaders`	`uploadDetails[].documentId`, `documentRef`, `filename` (minúsculo), `uploadUrl`, `uploadHeaders`

folderId, deadline e message são iguais nas duas versões.

O send-now e a migração da v2 não usam o campo Lista Suspensa (DROPDOWN). Ele existe só em PUT .../documents/{documentId}/fields, de envelope ou de modelo: properties.options recebe de 2 a 50 itens { id, label }, e o valor preenchido é o id da opção escolhida. No PDF selado sai o rótulo da opção, em fonte de 10 pt, dentro da caixa do campo. Por isso, dimensione size para o maior rótulo: cerca de 5 pt de largura por caractere, mais 1 pt, e 12 pt de altura por linha. Se o maior rótulo não couber, o PUT responde 400 FIELD_OPTION_LABEL_TOO_LONG_FOR_BOX, e details traz o rótulo e a largura mínima para uma linha (minWidthSingleLine).

Os campos automáticos Nome do signatário (SIGNER_NAME) e CPF do signatário (SIGNER_DOCUMENT) também existem só em PUT .../documents/{documentId}/fields, com properties: {}. Ninguém preenche: a selagem imprime o nome do signatário e o CPF do relatório. Em assinatura com certificado ICP-Brasil, o campo fica em branco; o nome e o CPF constam na assinatura digital e no relatório. Dimensione o CPF com pelo menos 75 x 12 pt e o nome para comportar 30 caracteres; caixa menor responde 400 FIELD_BOX_TOO_SMALL_FOR_AUTOMATIC_VALUE.

Na assinatura com certificado ICP-Brasil (authMethod: "PKI_BRAZIL"), o signatário INDIVIDUAL pode ter um CPF esperado: envie expectedDocumentNumber em PUT /v4/api/envelopes/{envelopeId}/participants (o send-now não recebe o campo). Preenchido, a assinatura só conclui se o CPF do certificado for esse; outro CPF, ou certificado que não traz CPF, responde (um e-CNPJ que traz o CPF do responsável é comparado normalmente) 422 PKI_CERTIFICATE_CPF_MISMATCH ao signatário e nada é gravado. Sem o campo, qualquer certificado ICP-Brasil válido assina, e o CPF registrado é o do certificado. CPF inválido responde 400 INVALID_CPF; na leitura de participantes o valor sai mascarado em expectedDocumentNumberMasked.

Uma opção de RADIO_GROUP, CHECKBOX_GROUP ou DROPDOWN pode ter regra: linkedFieldId aponta para um campo TEXT ou TEXTAREA do mesmo documento e participante, que fica obrigatório só quando a opção é escolhida e é descartado quando não é; textWhenSelected grava um texto fixo nesse campo quando a opção é escolhida. Vínculo inválido responde 400 FIELD_OPTION_LINK_INVALID, com o motivo em details.reason.

Acompanhe por webhook, não em laço

Consultar GET /v4/api/envelopes/{envelopeId} repetidamente para descobrir quando o envelope foi assinado gasta o limite de requisições por minuto da conta. Cadastre um webhook (POST /v4/api/webhooks/) para receber SIGNATORY_SIGNED e ENVELOPE_COMPLETED, e consulte o envelope só quando o evento chegar.

Tabela de equivalência

API legada	Nova API	Observação
`POST /v3/envelopes`	`POST /v4/api/envelopes/send-now`	Mesmo corpo. O envio acontece sozinho quando os documentos terminam de processar.
`POST /v2/envelopes`	`POST /v4/api/envelopes/send-now`	Uma chamada, como na v2, mas com outro corpo (veja o mapeamento acima). Para montar o envelope em etapas, use `POST /v4/api/envelopes/` e as operações seguintes.
`GET /v2/envelopes`	`GET /v4/api/envelopes/`	Os filtros `signatoryName`, `signatoryEmail` e `signatoryPhone` viram `participantName`, `participantEmail` e `participantPhone`. `perPage` aceita no máximo 100.
`GET /v2/envelopes/{id}`	`GET /v4/api/envelopes/{envelopeId}`	O detalhe v4 é mais enxuto (título, mensagem, status, prazo, pasta, etiquetas e remetente). Participantes, documentos e histórico vêm de `GET /v4/api/envelopes/{envelopeId}/participants`, `.../documents` e `.../logs`. Para saber quando algo mudou, prefira webhook a consultar em laço.
`PATCH /v2/envelopes/{id}/title`	`PATCH /v4/api/envelopes/{envelopeId}/settings`	Título, mensagem e prazo ficam na mesma operação.
`PATCH /v2/envelopes/{id}/deadline`	`PATCH /v4/api/envelopes/{envelopeId}/settings`	Título, mensagem e prazo ficam na mesma operação.
`PATCH /v2/envelopes/{id}/move`	`PATCH /v4/api/envelopes/{envelopeId}/move`	Equivalente público disponível.
`POST /v2/envelopes/{id}/void`	`POST /v4/api/envelopes/{envelopeId}/void`	A operação é irreversível.
`POST /v2/envelopes/{id}/participants/{participantId}/reminder`	`POST /v4/api/envelopes/{envelopeId}/participants/{participantId}/reminder`	O envelope e o participante fazem parte do caminho. A rota antiga `POST /v2/signatories/{id}/send-reminder` foi removida em 15/06/2026; hoje ela existe de novo como alias descontinuado, responde com o cabeçalho `Deprecation` e deve ser trocada por `POST /v2/envelopes/{envelopeId}/participants/{participantId}/reminder`.
`PATCH /v2/signatories/{id}` e `PUT /v2/envelopes/{id}/participants/{participantId}`	`PATCH /v4/api/envelopes/{envelopeId}/participants/{participantId}`	Corrige nome, e-mail, telefone ou canal de entrega de quem ainda não concluiu a sua parte, inclusive depois do envio. Quem já assinou ou aprovou não pode ser alterado.
Substituir a lista de participantes	`PUT /v4/api/envelopes/{envelopeId}/participants` - só em rascunho ou em ajuste	Substitui a coleção inteira de participantes; não serve para corrigir um envelope já enviado.
Sem equivalente público	`PUT /v4/api/envelopes/{envelopeId}/documents/{documentId}/fields`	Posiciona e substitui campos de assinatura.
`GET /v2/documents/{id}/download`	`GET /v4/api/documents/{documentId}/download`	Devolve uma URL temporária para baixar o arquivo.
`POST /v2/envelopes/{id}/download-ticket` + `GET /v2/envelopes/{id}/download`	`GET /v4/api/envelopes/{envelopeId}/download`	Devolve uma URL temporária para baixar todos os documentos do envelope num `.zip` (selados, ou originais com `?tipo=originais`).
`GET /v2/members`	`GET /v4/api/members/`	Somente leitura.
`POST /v2/folders`	`POST /v4/api/folders/`	Equivalente público disponível.
`POST /v2/webhooks`	`POST /v4/api/webhooks/`	Equivalente público disponível.
`GET /v2/webhooks`	`GET /v4/api/webhooks/`	Equivalente público disponível.
`PATCH /v2/webhooks/{id}`	`PATCH /v4/api/webhooks/{webhookId}`	Equivalente público disponível.
`DELETE /v2/webhooks/{id}`	`DELETE /v4/api/webhooks/{webhookId}`	Equivalente público disponível.
Relatórios	`GET /v4/api/reports/envelopes` e `GET /v4/api/reports/envelopes-usage`	Relatório de envelopes e de uso por grupo.
Contatos (CRUD)	`POST /v4/api/contacts/`, `GET /v4/api/contacts/`, `GET`/`PUT`/`PATCH`/`DELETE /v4/api/contacts/{contactId}`	Criar, listar, consultar, atualizar (total ou parcial) e excluir.
Envelopes de um contato	`GET /v4/api/contacts/{contactId}/envelopes`	Só os envelopes que o dono da chave pode ver.
Listas de contatos (leitura)	`GET /v4/api/contact-lists/` e `GET /v4/api/contact-lists/{listId}`	Somente leitura.
Etiquetas	`GET /v4/api/tags/`, `POST /v4/api/envelopes/{envelopeId}/tags` e `DELETE /v4/api/envelopes/{envelopeId}/tags/{tagId}`	Listar as etiquetas da conta, aplicar e remover em um envelope. Há limite de etiquetas por envelope (409 ao atingir).
Grupos	`GET /v4/api/groups/`	Somente leitura.
Convites	`GET /v4/api/invites/`	Somente leitura.
Modelos	`GET /v4/api/templates/`, `GET`/`PUT`/`DELETE /v4/api/templates/{templateId}`, `POST /v4/api/templates/{templateId}/envelopes` e as rotas de montagem (documentos, vagas, campos, cópias, ativação e duplicação)	Listar, excluir (rascunho), montar e criar envelope a partir de modelo.
Pastas	`GET /v4/api/folders/tree`, `GET /v4/api/folders/contents`, `GET /v4/api/folders/{folderId}`, `PATCH /v4/api/folders/{folderId}/rename`, `PATCH /v4/api/folders/{folderId}/move` e `DELETE /v4/api/folders/{folderId}`	Árvore, conteúdo, detalhe de acesso, renomear, mover e excluir.
Aprovações	`POST /v4/api/envelopes/{envelopeId}/participants/{participantId}/approve` e `.../decline`	Aprovar ou recusar como participante aprovador.
Validação de documento	`GET /v4/api/documents/{documentId}/validation`	Valida um documento selado que está na conta.
Envelopes anulados (auditoria)	`GET /v4/api/audit/voided-envelopes`	Lista os envelopes anulados.
Chamadas da própria chave	`GET /v4/api/request-logs/`	Lista as chamadas feitas com a chave.

Ainda sem equivalente público: operações em lote (mover, etiquetar e anular vários envelopes de uma vez); correção e devolução de envelope; compartilhamento e visibilidade de pasta; favoritar contato; criar, editar e excluir listas de contatos e etiquetas; validar documento por upload de arquivo (a validação pública atende só documento selado que já está na conta); atividade e auditoria da conta. Já estão disponíveis: corrigir contato de participante (inclusive depois do envio), montar modelo pela API (POST /v4/api/templates e as rotas de documentos, vagas, campos e ativação), criar envelope a partir de modelo e reenviar uma entrega de webhook (POST /v4/api/webhooks/{webhookId}/deliveries/{deliveryId}/retry).

Segurança

Armazene a chave somente no servidor ou em um gerenciador de segredos.

Nunca exponha a chave em aplicações frontend, repositórios ou logs.

Use sempre HTTPS.

Não envie a chave em query string.

Revogue imediatamente qualquer chave exposta ou sem uso.

Não publique payloads, IDs ou exemplos extraídos de clientes reais.

Introdução

Introdução#

Ambiente#

Montando a URL#

Onde está cada coisa#

Autenticação#

Quem a chave representa#

Escopos da chave#

Idempotência#

Fluxo de um envelope#

Migração da API legada#

Criar e enviar numa chamada#

De POST /v2/envelopes para POST /v4/api/envelopes/send-now#

Acompanhe por webhook, não em laço#

Tabela de equivalência#

Segurança#

Introdução

Ambiente

Montando a URL

Onde está cada coisa

Autenticação

Quem a chave representa

Escopos da chave

Idempotência

Fluxo de um envelope

Migração da API legada

Criar e enviar numa chamada

De `POST /v2/envelopes` para `POST /v4/api/envelopes/send-now`

Acompanhe por webhook, não em laço

Tabela de equivalência

Segurança