API de assinatura digital SuperSign: guia de integração v4

Revisado em 23/09/2026. Este guia descreve a API v4 da SuperSign para novas integrações. A documentação pública é a referência para campos, respostas e eventuais mudanças de contrato.

A API de assinatura digital da SuperSign permite que um sistema crie envelopes, inclua participantes e PDFs, envie documentos para assinatura e acompanhe o resultado por consulta ou webhook. Para começar, use o ambiente de testes, mantenha a chave somente no servidor e siga o fluxo da versão /v4/api.

Quando usar a API

A integração faz sentido quando contratos, termos ou propostas nascem em um ERP, CRM, portal ou produto SaaS e o status da assinatura precisa voltar ao mesmo fluxo. A aplicação de origem continua responsável por decidir quando iniciar o envio e o que fazer após a conclusão; a SuperSign executa o processo de assinatura e expõe seus eventos e documentos pelas rotas documentadas.

Se a decisão ainda é entre integração própria, uso da plataforma e automação de processos, leia também como integrar assinaturas ao site ou sistema. Esta página se concentra no caminho técnico da API v4.

Ambientes, credenciais e primeiro teste

• Sandbox: https://api.sandbox.supersign.com.br, para desenvolvimento e homologação. Documentos e assinaturas de teste não devem ser tratados como produção com validade jurídica.
• Produção: https://api.sign.supersign.com.br. Use uma chave própria deste ambiente após validar o fluxo.
• Autenticação: envie a chave no cabeçalho Authorization: Bearer. Chaves de teste começam com ss_test_; chaves de produção, com ss_live_. Nunca as publique no navegador, aplicativo cliente, repositório ou exemplo compartilhado.

A chave é criada na área Configurações → Desenvolvedor da conta correspondente. Para confirmar a autenticação antes de montar o fluxo, consulte GET /v4/api/me. Veja a introdução oficial da API e o guia do primeiro envelope.

Fluxo de um envelope na API v4

O objeto central da integração é o envelope: ele reúne configuração, participantes, documentos e estado do processo. A sequência básica é:

1. Criar o rascunho com POST /v4/api/envelopes/.
2. Definir as configurações necessárias em PATCH /v4/api/envelopes/{id}/settings.
3. Adicionar os participantes em PUT /v4/api/envelopes/{id}/participants.
4. Registrar cada PDF em POST /v4/api/envelopes/{id}/documents, receber a URL de upload e enviar o binário diretamente para ela. Não envie o arquivo em Base64 para uma rota antiga /v1/documents.
5. Se o fluxo exigir campos no documento, configurar PUT /v4/api/envelopes/{id}/documents/{documentId}/fields.
6. Enviar com POST /v4/api/envelopes/{id}/send e consultar o estado por GET /v4/api/envelopes/{id}.

Os corpos das requisições e os campos obrigatórios dependem da operação. Copie os exemplos da documentação atual, em vez de reaproveitar snippets da antiga rota /v1/documents. Em operações POST, use Idempotency-Key com valor ASCII de 8 a 255 caracteres para que uma tentativa repetida não crie envios duplicados.

Acompanhar assinaturas com webhooks

Cadastre um endpoint do seu backend em POST /v4/api/webhooks/. Eventos como ENVELOPE_SENT, SIGNATORY_SIGNED, ENVELOPE_COMPLETED, ENVELOPE_VOIDED e ENVELOPE_EXPIRED permitem atualizar o status no sistema de origem sem depender apenas de consultas periódicas.

Processe cada evento de modo idempotente pelo seu id; notificações podem ser repetidas ou chegar fora de ordem. Quando a assinatura do webhook estiver configurada, valide o HMAC antes de aceitar a mensagem. Para decisões sensíveis, confirme também o estado atual do envelope na API. Consulte o guia oficial de webhooks.

Segurança e validade: decisões do seu fluxo

Armazene chaves em um gerenciador de segredos, limite quem pode gerá-las e separe teste de produção. No seu backend, registre o identificador do envelope, trate falhas e tentativas repetidas, restrinja o acesso aos documentos e defina retenção de dados conforme a finalidade e a LGPD.

A validade jurídica não decorre automaticamente de “usar uma API”. Ela depende do método de assinatura, do documento, da identificação dos participantes e das exigências aplicáveis ao caso. Envolva o jurídico na escolha de autenticação e nas evidências necessárias; não use o Sandbox como prova de um ato real.

Perguntas frequentes

É preciso falar com vendas para ler a documentação?

Não. A documentação da API é pública. Para testar chamadas, crie uma conta no ambiente adequado e gere sua chave de desenvolvedor.

Posso usar a mesma chave em Sandbox e produção?

Não. As chaves e bases são separadas. Valide a integração no Sandbox e configure uma chave de produção somente para o deploy de produção.

Como evitar envelopes duplicados?

Envie uma Idempotency-Key estável por operação POST, trate retries no seu backend e associe o identificador recebido ao registro de origem.

Por onde começar uma avaliação comercial?

Sua equipe vai implementar a API? Conheça a página para desenvolvedores e siga a documentação técnica. Se precisa definir condições, volume ou apoio à implantação, converse com o time comercial. Confirme o plano e o suporte para o caso de uso da sua empresa.

Próximo passo: teste o primeiro envelope no Sandbox, valide o recebimento dos webhooks e só depois promova as credenciais e URLs para produção. Abrir documentação da API SuperSign.