Introdução à documentação

Esta é a porta de entrada do portal da API pública da SuperSign. Ela explica o que a API v4 faz, define os termos que aparecem em todos os guias e mostra por onde começar, conforme o que você precisa construir.

O que é a API v4

A API v4 permite que o seu sistema crie, configure, envie e acompanhe envelopes de assinatura eletrônica sem passar pelo aplicativo. Tudo o que você faz por ela segue as mesmas regras de visibilidade e de plano do aplicativo: a chave age em nome de um usuário e só enxerga o que esse usuário enxerga.

Uma integração típica faz cinco coisas:

Valida a chave de API no Sandbox.

Cria um envelope, com documento, participantes e campos.

Envia o envelope para assinatura.

Recebe avisos por webhook quando algo muda, em vez de consultar a API em laço.

Guarda o documento selado e confere a sua autenticidade quando precisar.

Toda integração nova usa os endpoints /v4/api/*. Os endpoints das versões anteriores continuam funcionando por um período de transição, mas não recebem recursos novos. Veja a seção de migração na Introdução.

Glossário de termos essenciais

Termo	O que significa na SuperSign
Envelope	O pacote de assinatura: reúne documentos, participantes, campos, prazo e mensagem. É a unidade que você cria, envia, acompanha e, se preciso, anula. Seus estados estão em Estados do envelope.
Documento	Cada arquivo PDF dentro de um envelope. O mesmo envelope pode ter vários. Depois que todos assinam, a SuperSign gera a versão selada.
Participante	Qualquer pessoa que recebe o envelope. Tem um papel: signatário, aprovador ou observador.
Signatário	Participante que assina. Na criação e na consulta de participantes pela API o papel é `SIGNATORY`; nos payloads de webhook de recusa e de e-mail não entregue o mesmo papel aparece como `SIGNER`.
Aprovador	Participante que aprova ou recusa o envelope sem assinar. Papel `APPROVER`.
Observador	Participante que apenas acompanha e recebe cópia. Papel `OBSERVER`.
Campo	Elemento posicionado no documento e atribuído a um participante. Os tipos do contrato são `SIGNATURE` (assinatura), `INITIALS` (rubrica) e `TEXT` (texto). A posição é dada em coordenadas da página.
Modelo	Envelope pré-configurado, com documentos e vagas de participante já definidos. Serve para criar envelopes repetidos informando só quem vai assinar. Veja Criar um envelope a partir de um modelo.
Pasta	Agrupamento de envelopes e modelos na conta. A visibilidade das pastas define o que a sua chave enxerga.
Webhook	Endereço do seu sistema que a SuperSign chama quando um evento acontece, como `ENVELOPE_COMPLETED`. Veja Webhooks.
Chave de API	Credencial enviada no header `Authorization: Bearer`. Age em nome do usuário que a criou. Chaves de teste começam com `ss_test_` e as de produção com `ss_live_`.
Escopo	Limite opcional de uma chave: lista as operações que ela pode fazer, como `envelopes:read`. Um escopo só restringe, nunca amplia.
Sandbox	Ambiente de desenvolvimento e teste, com o mesmo contrato da produção, sem validade jurídica. Os documentos são identificados como teste.
Produção	Ambiente real, com validade jurídica. Só use depois de homologar no Sandbox.
Idempotência	Garantia de que repetir a mesma chamada não duplica o efeito. Toda operação `POST` exige o header `Idempotency-Key`. Veja Idempotência e erros.

Escolha seu caminho

Se você quer...	Comece por
Ver um envelope funcionando de ponta a ponta	Primeiro envelope em 5 minutos
Entender ambientes, autenticação e permissões da chave	Introdução
Testar sem escrever código	Testar a API no Postman
Gerar uma biblioteca para a sua linguagem	Gerar um cliente (SDK)
Receber avisos de assinatura no seu sistema	Webhooks
Criar envelopes repetidos a partir de um modelo	Criar um envelope a partir de um modelo
Conferir um documento já selado	Verificar um documento selado
Tratar erros e repetir chamadas com segurança	Idempotência e erros e Catálogo de erros
Sair da API v2 ou v3	Seção de migração da Introdução
Consultar cada operação, parâmetro e resposta	Referência da API

Como o portal está organizado

O menu de documentos segue esta ordem. Os endpoints, com parâmetros e respostas, ficam na Referência da API.

Introdução: esta página, a visão geral da API, o primeiro envelope, as ferramentas de teste, os limites de requisição, a idempotência, os erros e o changelog.

Assinatura: envelopes e seus estados, criação a partir de modelo, posicionamento de campos e verificação de documento selado.

Webhooks: visão geral, uma página para cada evento, segurança e verificação, entregas e retentativas e como testar.

Integrações: guias para usar a API com outras ferramentas.

Referência da API: cada operação do contrato.

Ajuda

Antes de pedir ajuda, consulte o Catálogo de erros: ele explica cada código e o que fazer.

Para dúvidas sobre a sua integração, fale com o suporte da SuperSign pelos canais da sua conta e informe o ambiente (Sandbox ou Produção), o horário da chamada e o corpo do erro devolvido (sem a chave). Nunca envie a sua chave de API nem o segredo de um webhook.

Mudanças no contrato e nos guias ficam registradas no Changelog.

O que é a API v4#

Glossário de termos essenciais#

Escolha seu caminho#

Como o portal está organizado#

Ajuda#

O que é a API v4

Glossário de termos essenciais

Escolha seu caminho

Como o portal está organizado

Ajuda