SuperSign - API Oficial
  1. Introdução
  • SuperSign API Pública
    • Introdução
      • Crie seu primeiro envelope no Sandbox
      • Integrar com IA
      • Testar a API no Postman
      • Paginação e filtros
      • Catálogo de erros
      • Receitas em Node.js, PHP e Python
      • Changelog
      • Idempotência e erros
      • Estados do envelope
      • Webhooks
      • Limites de requisição
      • Criar um envelope a partir de um modelo
      • Gerar cliente com OpenAPI
      • Evento ENVELOPE_SENT
      • Evento SIGNATORY_SIGNED
      • Evento ENVELOPE_COMPLETED
      • Evento ENVELOPE_VOIDED
      • Evento ENVELOPE_EXPIRED
      • Segurança e verificação
      • Entregas, retentativas e reenvio
      • Testar na Sandbox e automatizar
      • Conceitos da API V4
      • Posicionar campos por texto âncora
      • Verificar um documento selado
      • Evento PARTICIPANT_DECLINED
      • Evento EMAIL_BOUNCED
      • Entrega do convite pela integração
      • Evento PARTICIPANT_VIEWED
      • Guia completo da API V4
      • Assinatura embutida (sob consulta)
      • Salvar os documentos assinados no seu Drive
    • Referência da API
      • Conta
        • Consultar a conta da integração
        • Consultar capacidades da integração
        • Consultar o catálogo de capacidades
        • Listar chamadas da própria chave
        • Consultar consumo do ciclo
        • Validar a chave de API
      • Envelopes
        • Excluir rascunho de envelope
        • Consultar histórico do envelope
        • Criar e enviar envelope numa chamada
        • Gerar URL de download do envelope em ZIP
        • Duplicar envelope
        • Criar rascunho de envelope
        • Listar envelopes
        • Atualizar configurações do envelope
        • Enviar envelope
        • Consultar envelope
        • Mover envelope para outra pasta
        • Anular envelope
      • Participantes
        • Listar participantes do envelope
        • Aprovar participante aprovador
        • Recusar como participante aprovador
        • Corrigir contato do participante
        • Consultar link de assinatura
        • Sincronizar participantes
        • Enviar lembrete ao participante
      • Documentos
        • Listar documentos do envelope
        • Substituir campos do documento
        • Listar campos do documento
        • Confirmar o PDF convertido de um DOCX
        • Validar um documento selado
        • Reordenar documentos do envelope
        • Consultar o tamanho das páginas
        • Achar texto (âncora) no documento
        • Verificar um documento selado
        • Baixar o PDF de exemplo
        • Adicionar documento ao envelope
        • Gerar URL de download do documento
      • Contatos
        • Atualizar contato parcialmente
        • Listar envelopes do contato
        • Listar listas de contatos
        • Consultar lista de contatos
        • Criar contato
        • Listar contatos
        • Consultar contato
        • Atualizar contato
        • Excluir contato
      • Equipe
        • Listar grupos da conta
        • Listar membros da conta
      • Pastas
        • Listar conteúdo da pasta
        • Consultar acesso da pasta
        • Excluir pasta
        • Renomear pasta
        • Mover pasta
        • Listar todas as pastas
        • Criar pasta
      • Convites
        • Listar convites da conta
      • Webhooks
        • Excluir webhook
        • Listar entregas de um webhook
        • Detalhar uma entrega de webhook
        • Reenviar uma entrega de webhook
        • Girar o segredo de assinatura do webhook
        • Enviar um evento de teste para o webhook
        • Atualizar webhook
        • Criar webhook
        • Listar webhooks
      • Modelos
        • Listar modelos
        • Consultar modelo
        • Criar envelope a partir de modelo
        • Criar modelo em rascunho
        • Editar título e descrição do modelo
        • Consultar processamento do documento do modelo
        • Ativar modelo
        • Duplicar modelo
        • Enviar documentos do modelo
        • Definir vagas do modelo
        • Posicionar campos no documento do modelo
        • Apagar modelo em rascunho
        • Reordenar documentos do modelo
        • Remover documento do modelo
        • Definir cópias do modelo
        • Achar texto (âncora) no documento do modelo
      • Auditoria e relatórios
        • Relatório de consumo do plano
        • Relatório de recusas, anulações e prazos vencidos
        • Listar envelopes anulados
        • Relatório de envelopes
        • Relatório de uso por grupo
      • Etiquetas
        • Aplicar etiqueta ao envelope
        • Remover etiqueta do envelope
        • Listar etiquetas da conta
  1. Introdução

Salvar os documentos assinados no seu Drive

Este guia mostra como guardar uma cópia dos documentos assinados no seu próprio Google Drive (ou OneDrive, Dropbox, S3) usando o webhook ENVELOPE_COMPLETED e a API pública. Serve para quem monta o fluxo no n8n, no Zapier ou no Make, e também para quem prefere escrever um pequeno serviço em Node.
O caminho é sempre o mesmo, em quatro passos:
1.
Você cadastra um endpoint de webhook assinando ENVELOPE_COMPLETED.
2.
A SuperSign avisa seu endpoint quando um envelope é concluído e os documentos já estão selados.
3.
Seu fluxo verifica a assinatura do aviso, responde 2xx e guarda o evento.
4.
Em segundo plano, seu fluxo pede a URL de download do documento assinado pela API, baixa o PDF e grava no Drive.
O aviso não carrega o arquivo nem link de download. Ele traz só os ids e os hashes. O download sempre passa pela API autenticada com a sua chave ss_live_. Visão geral dos webhooks em Webhooks.

Antes de começar#

Plano com API. Conta sem API não cadastra webhook e não recebe entregas (403 API_NOT_IN_PLAN).
Uma chave ss_live_ com os escopos certos. Para cadastrar o endpoint, a chave precisa de webhooks:write. Para baixar os documentos, o fluxo precisa de envelopes:read. O ideal é usar duas chaves: uma administrativa, só para cadastrar o endpoint, e outra só com envelopes:read dentro do n8n, Zapier ou Make. Se a chave de download vazar, ela só lê. Veja Escopos da chave.
Quem a chave representa. O webhook é da conta e avisa sobre todos os envelopes. Mas o download segue a visibilidade do usuário dono da chave: envelope de pasta que ele não enxerga responde 404 RESOURCE_NOT_FOUND. Para guardar tudo da conta, emita a chave de download pelo proprietário da conta (papel OWNER).
Teste na Sandbox primeiro, com chave ss_test_ e https://api.sandbox.supersign.com.br. Em produção a base é https://api.sign.supersign.com.br.

Passo 1: cadastrar o endpoint#

A resposta 201 traz o signingSecret (whsec_...) uma única vez. Guarde-o num cofre de segredos. Se perder, gire o segredo (veja Girar o segredo de assinatura). A URL precisa ser HTTPS, na porta 443, em host público (veja Requisitos da URL).
Para testar sem criar envelope, use o evento de teste.

Passo 2: o que chega no ENVELOPE_COMPLETED#

{
  "id": "9d4fb916-5ab7-4a49-9014-1249345f1c6c",
  "event": "ENVELOPE_COMPLETED",
  "createdAt": "2026-09-03T18:30:00.000Z",
  "data": {
    "envelope": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "COMPLETED",
      "completedAt": "2026-09-03T18:29:58.000Z"
    },
    "documents": [
      {
        "id": "2f1c5d8d-97dd-40a8-aefe-1eec9d17e301",
        "name": "contrato.pdf",
        "originalFileHash": "4f6f53d15ea7ed8cb002f85d2cb1f6c0f2bd5861d89fc3f9f30670ecf40cb3d2",
        "sealedFileHash": "9b2e6c0a1d4f8e3b7a5c2d9f0e1b4a6c8d3f5e7a9b1c2d4e6f8a0b3c5d7e9f1a"
      }
    ],
    "signatories": []
  }
}
O que você usa para o backup:
CampoPara que serve
idId do evento. É a chave para deduplicar entregas repetidas.
data.envelope.idId do envelope. Boa chave para a pasta no seu Drive.
data.documents[].idId do documento. É o que vai na rota de download.
data.documents[].nameNome original do arquivo. Use para nomear a cópia.
data.documents[].sealedFileHashSHA-256 do PDF selado, para conferir o que você baixou.
O formato completo, com todos os campos, está em Evento ENVELOPE_COMPLETED. Em produção o campo environment não existe; na Sandbox ele vale "sandbox".

Passo 3: verificar a assinatura#

Toda entrega traz o cabeçalho:
X-SuperSign-Signature: t=1700000000,v1=<hex>
t é o horário do disparo, em segundos (epoch).
v1 é HMAC-SHA256(segredo, "<t>.<corpo cru>"), em hexadecimal.
Verifique sobre o corpo cru (os bytes do POST), antes de qualquer parse de JSON. Rejeite se |agora - t| passar de 5 minutos e compare em tempo constante. O detalhe completo e o exemplo em Python estão em Segurança e verificação.

Passo 4: baixar o PDF assinado#

Um documento por vez (recomendado para o backup)#

{ "url": "https://storage.googleapis.com/..." }
Rota: GET /v4/api/documents/{documentId}/download. O parâmetro type é obrigatório: signed (assinado) ou original.
Escopo da chave: envelopes:read.
A resposta traz só a url. Ela é temporária, assinada, e vale por 15 minutos.
Baixe com um GET simples na url, sem o cabeçalho Authorization. Não grave a URL em log nem em planilha.
Se o documento não tiver versão assinada, a resposta é um erro e a SuperSign nunca devolve o original no lugar do assinado quando você pede signed.

Todos os documentos de uma vez (ZIP)#

{ "url": "...", "expiresAt": "2026-09-03T18:31:00.000Z", "fileName": "..." }
Rota: GET /v4/api/envelopes/{envelopeId}/download, com tipo=assinados (padrão) ou tipo=originais. Escopo envelopes:read.
A url do ZIP vale para um único download e expira em 60 segundos. Pedir de novo a mesma URL é recusado. Peça e baixe na sequência, sem guardar a URL.

E o certificado de conclusão?#

A página de comprovação (quem assinou, quando, hashes e o selo) é gerada na selagem e fica dentro do PDF assinado. Baixar o documento com type=signed já traz esse certificado. A API pública não tem uma rota separada para o certificado.

Conferir a integridade#

Calcule o SHA-256 do arquivo baixado e compare com documents[].sealedFileHash do evento. Se vier null, o selado não tem hash registrado (documento legado) e a conferência não é possível. Se divergir, descarte, não grave no Drive e tente de novo.

Exemplo em Node#

Receptor mínimo, sem dependências, que verifica a assinatura, guarda o evento e responde 2xx logo. O trabalho pesado (baixar e gravar) roda num worker. As funções fila e salvarNoDrive são pontos de extensão seus:

Exemplo no n8n#

Nomes de campos podem variar entre versões do n8n. Nenhuma credencial real vai no fluxo: use sempre o gerenciador de credenciais.
#NóConfiguração
1WebhookMétodo POST. Em Options, ligue Raw Body. Em Respond, escolha Using 'Respond to Webhook' Node. Cadastre a URL de produção desse nó no passo 1.
2Code (verificar)Lê o corpo cru e o cabeçalho x-supersign-signature, recalcula o HMAC e falha o fluxo se não conferir (código abaixo). Em n8n self-hosted, libere NODE_FUNCTION_ALLOW_BUILTIN=crypto.
3IFevent igual a ENVELOPE_COMPLETED. Qualquer outro evento vai direto para o nó 5.
4Data table ou PostgresInsere id do evento com chave única. Se já existir, é duplicata: siga para o nó 5 sem baixar de novo.
5Respond to WebhookCódigo 200. Responda antes de baixar os arquivos, para ficar dentro do prazo de 20 segundos.
6Split OutCampo data.documents, um item por documento.
7HTTP Request (pedir URL)GET https://api.sign.supersign.com.br/v4/api/documents/{{ $json.id }}/download?type=signed. Autenticação: credencial Header Auth com Authorization: Bearer <chave envelopes:read>. Ligue Retry on Fail e, em Batching, limite a vazão (veja Limites).
8HTTP Request (baixar PDF)GET {{ $json.url }}, sem autenticação, Response Format File.
9Google DriveOperação Upload. Pasta de destino: seu folderId. Nome: {{ $('Split Out').item.json.name }}.
Código do nó 2 (Code, modo Run Once for All Items):
No Zapier e no Make o raciocínio é o mesmo: receba o POST, confira o X-SuperSign-Signature se a ferramenta der acesso ao corpo cru, responda 2xx, peça a URL com um passo de HTTP e grave o arquivo no Drive. Se a ferramenta não der acesso ao corpo cru, use um receptor intermediário (como o exemplo em Node) e deixe só o upload na ferramenta.

Retentativas e idempotência#

Responda 2xx rápido, somente depois de guardar o evento. A tentativa tem prazo de 20 segundos.
Timeout, falha de rede ou TLS, 403, 404, 408, 425, 429 e qualquer 5xx geram nova tentativa. Redirecionamentos e os demais 4xx (como 401 e 410) não são retentados.
São até 6 tentativas: a primeira imediata e mais 5 com esperas fixas de 10 segundos, 1 minuto, 10 minutos, 1 hora e 6 horas, numa janela total de cerca de 7 horas. Depois disso a entrega fica FAILED e pode ser reenviada por POST /v4/api/webhooks/{webhookId}/deliveries/{deliveryId}/retry.
O mesmo evento pode chegar mais de uma vez, e um reenvio mantém o mesmo id. Deduplique pelo id do evento.
Reselagem. Se um envelope é selado de novo, chega um novo ENVELOPE_COMPLETED com id de evento novo, o mesmo data.envelope.id e um sealedFileHash novo. A deduplicação pelo id do evento não pega esse caso, e isso é o certo: você quer a versão nova. Grave por cima do arquivo do mesmo documento (mesma pasta e mesmo nome) em vez de criar uma segunda cópia, e confira o hash novo. O hash antigo deixa de conferir na verificação pública.
Mais detalhes em Entregas, retentativas e reenvio.

Boas práticas#

Verifique a assinatura sobre o corpo cru e rejeite timestamp velho. Quem conhece a URL do seu endpoint consegue forjar um POST sem isso.
Responda 2xx rápido e baixe depois. Baixar PDF dentro do request estoura o prazo e provoca retentativa.
Deduplique pelo id do evento com uma chave única. Marque o evento como concluído só depois do upload, para poder retomar após uma falha.
Confirme pela API antes de ações irreversíveis: GET /v4/api/envelopes/{envelopeId} deve mostrar COMPLETED.
Confira o hash do PDF baixado contra sealedFileHash.
Não registre a chave, o segredo whsec_ nem as URLs temporárias de download. O payload tem nome, e-mail e telefone de participantes: proteja logs, filas e o destino.
Responda 2xx a eventos que você não conhece. Novos tipos podem ser adicionados.
Faça uma reconciliação periódica (veja Limites). Webhook é aviso, não garantia de entrega eterna.
Nunca ponha a chave ss_live_ em código de navegador, em app ou em repositório.

Limites#

LimiteValor
Requisições da API por contaPadrão de 30 por minuto, compartilhado por todas as chaves da conta; o plano pode ter mais. Cada documento gasta uma chamada de download. Em 429, respeite o Retry-After. Veja Limites de requisição.
Validade da URL de um documento15 minutos, assinada, temporária.
Validade da URL do ZIP60 segundos e um único download.
Prazo de resposta do seu endpoint20 segundos por tentativa.
Tentativas por evento6, numa janela de cerca de 7 horas. Depois, FAILED, reenviável pela API.
Endpoints de webhook por conta20, ativos e inativos.
Desativação automáticaO webhook com falhas seguidas é desativado após 3 dias e 20 entregas FAILED, com aviso por e-mail antes. Eventos disparados com o webhook desativado não são enviados depois.
O que o aviso trazIds e hashes. Nunca o arquivo, nem link de download, nem link de assinatura.
Visibilidade da chaveSó baixa o que o usuário dono da chave enxerga; o resto responde 404.
Origem do arquivoA cópia no seu Drive é sua. O documento selado continua guardado na SuperSign, e esta integração não apaga nada de nenhum dos dois lados.

Reconciliação: não perca nada#

Se o seu receptor ficou fora do ar por mais de 7 horas, ou o webhook foi desativado, os eventos daquele período não chegam sozinhos. Duas saídas:
1.
Reenvie as entregas FAILED com GET /v4/api/webhooks/{webhookId}/deliveries?status=FAILED e POST .../deliveries/{deliveryId}/retry.
2.
Rode uma varredura diária: GET /v4/api/envelopes/?status=COMPLETED&updatedSince=<data ISO> lista os envelopes concluídos desde a última varredura, e GET /v4/api/envelopes/{envelopeId}/documents devolve os ids dos documentos. Baixe só o que ainda não está no Drive.
Num backup grande, como o de um histórico inteiro de envelopes, distribua as chamadas ao longo do tempo para não esgotar os 30 pedidos por minuto da conta.
Modificado em 2026-11-15 14:38:01
Página anterior
Assinatura embutida (sob consulta)
Próxima página
Consultar a conta da integração
Built with