SuperSign - API Oficial
  1. SuperSign API Pública
  • SuperSign API Pública
    • Introdução
      • Primeiro envelope em 5 minutos
      • 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
    • Referência da API
      • Conta
        • Consultar a conta da integração
        • Consultar capacidades da integração
        • Consultar o catálogo de capacidades
        • Validar a chave de API
      • Envelopes
        • Excluir rascunho de envelope
        • Consultar histórico do envelope
        • Criar rascunho de envelope
        • Listar envelopes
        • Atualizar configurações do envelope
        • Enviar envelope
        • Get Envelope
        • Move envelope to folder
        • Void envelope
      • Participantes
        • Listar participantes do envelope
        • Sincronizar participantes
        • Enviar lembrete ao participante
      • Documentos
        • Listar documentos do envelope
        • Substituir campos do documento
        • Listar campos do documento
        • Adicionar documento ao envelope
        • Gerar URL de download do documento
      • Contatos
        • Criar contato
        • Listar contatos
        • Consultar contato
        • Atualizar contato
        • Excluir contato
      • Equipe
        • Listar membros da conta
      • Pastas
        • Listar conteúdo da pasta
        • Consultar acesso da pasta
        • Excluir pasta
        • Renomear pasta
        • Mover pasta
        • Criar pasta
      • Convites
        • Listar convites da conta
      • Webhooks
        • Excluir webhook
        • Criar webhook
        • List webhook endpoints
        • Edit webhook endpoint
  1. SuperSign API Pública

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#

AmbienteURL base
Sandboxhttps://api.sandbox.supersign.com.br
Produçãohttps://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.

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 é um principal da conta inteira. Ela não herda a visibilidade de pastas do usuário que a criou.
Somente o proprietário da conta 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.
Essa separação impede que mudanças de pasta alterem o escopo da integração. No modelo atual, remover ou suspender o usuário responsável encerra a credencial de forma fail-closed; rotacione a chave antes de remover esse usuário. A autorização continua vinculada à conta, ao recurso solicitado e aos direitos do plano.

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#

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.
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 adaptar o fluxo de criação do envelope.
API legadaNova APIObservação
POST /v2/envelopesPOST /v4/api/envelopes/A criação passa a ser realizada em etapas.
PATCH /v2/envelopes/{id}/titlePATCH /v4/api/envelopes/{envelopeId}/settingsTítulo, mensagem e prazo ficam na mesma operação.
PATCH /v2/envelopes/{id}/deadlinePATCH /v4/api/envelopes/{envelopeId}/settingsTítulo, mensagem e prazo ficam na mesma operação.
PATCH /v2/envelopes/{id}/movePATCH /v4/api/envelopes/{envelopeId}/moveEquivalente público disponível.
GET /v2/envelopesGET /v4/api/envelopes/Equivalente público disponível.
GET /v2/envelopes/{id}GET /v4/api/envelopes/{envelopeId}Equivalente público disponível.
POST /v2/envelopes/{id}/voidPOST /v4/api/envelopes/{envelopeId}/voidA operação é irreversível.
PATCH /v2/signatories/{id}PUT /v4/api/envelopes/{envelopeId}/participantsA nova operação sincroniza a coleção de participantes.
POST /v2/signatories/{id}/send-reminderPOST /v4/api/envelopes/{envelopeId}/participants/{participantId}/reminderO envelope e o participante fazem parte do caminho.
Sem equivalente públicoPUT /v4/api/envelopes/{envelopeId}/documents/{documentId}/fieldsPosiciona e substitui campos de assinatura.
GET /v2/documents/{id}/downloadGET /v4/api/documents/{documentId}/downloadEquivalente público disponível.
POST /v2/foldersPOST /v4/api/folders/Equivalente público disponível.
POST /v2/webhooksPOST /v4/api/webhooks/Equivalente público disponível.
GET /v2/webhooksGET /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.

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.
Modificado em 2026-09-08 22:04:56
Próxima página
Primeiro envelope em 5 minutos
Built with