# Introdução # 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](https://docs.supersign.com.br). ## Autenticação Envie a chave em todas as requisições: ```http Authorization: Bearer ss_test_sua_chave ``` 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: ```bash curl --request GET \ --url https://api.sandbox.supersign.com.br/v4/api/me \ --header 'Authorization: Bearer ss_test_sua_chave' ``` 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](#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. ```http Idempotency-Key: 8f3fdb8e-43d8-4e21-81d9-b8596a1d1498 ``` 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 1. Valide a chave com `GET /v4/api/me`. 2. Crie o rascunho com `POST /v4/api/envelopes/`. 3. Configure título, mensagem e prazo com `PATCH /v4/api/envelopes/{envelopeId}/settings`. 4. Defina os participantes com `PUT /v4/api/envelopes/{envelopeId}/participants`. 5. Registre o PDF com `POST /v4/api/envelopes/{envelopeId}/documents`. 6. Envie o binário para a URL assinada retornada. O conteúdo do PDF não é enviado em Base64 para a API. 7. Posicione os campos com `PUT /v4/api/envelopes/{envelopeId}/documents/{documentId}/fields`. 8. Envie o envelope com `POST /v4/api/envelopes/{envelopeId}/send`. 9. 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. ### 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.