Primeiros Passos: Sua Primeira Assinatura via API em 5 Minutos

Você não precisa de um sprint inteiro para colocar a primeira assinatura digital no ar. Com a Assinatura Expressa da SignDocs, o caminho mais curto cabe em três movimentos: capturar um token OAuth2, fazer uma única chamada POST /v1/signing-sessions e compartilhar o link de checkout que volta na resposta. Em cinco minutos você tem um documento assinável de verdade rodando no ambiente de homologação.

Este guia é deliberadamente enxuto. O objetivo não é cobrir cada parâmetro da plataforma, e sim levar você do zero ao primeiro 200 OK o mais rápido possível, com um caminho claro para aprofundar depois. Se você ainda está avaliando a plataforma como um todo, vale começar pela visão geral da API de assinatura digital; se já decidiu integrar, siga por aqui.

Vamos usar curl nos exemplos porque ele deixa cada cabeçalho e campo explícito, sem mágica de SDK no meio. Tudo o que você vai ver funciona igual em qualquer linguagem que faça uma requisição HTTP.

O caminho mais curto: Assinatura Expressa

A SignDocs expõe duas superfícies de API. A API de Transações trabalha com envelopes, múltiplos signatários, ordem de assinatura e o ciclo de vida completo. Já a Assinatura Expressa (também chamada de Signing Sessions) é a rota direta: uma chamada para POST /v1/signing-sessions cria a sessão e devolve um link de checkout hospedado ou um widget incorporável.

Para os primeiros passos, a Assinatura Expressa vence em todos os critérios que importam quando você quer ver algo funcionando rápido:

Antes de começar: o que você precisa

O checklist é curto. Em poucos minutos no painel você reúne tudo:

1. Uma conta SignDocs. O cadastro é gratuito em app.signdocs.com.br. Para a API, o ambiente de homologação é gratuito; o acesso de produção é contratado como plano sob medida com o time comercial.
2. Credenciais de API (client_id e client_secret). Geradas no painel, na área de desenvolvedores. O passo a passo detalhado está no guia como obter sua API key.
3. O host de homologação. Use api-hml.signdocs.com.br (com hífen) para testar sem cobrança nem validade jurídica. Lembre que entidades de homologação expiram em 7 dias.
4. Um terminal com curl (ou Postman/Insomnia, se preferir interface gráfica).

Só isso. Com as credenciais em mãos e o host certo, partimos para os três passos.

Passo 1 — Capture um token OAuth2 (≈1 min)

A SignDocs usa o fluxo OAuth2 client credentials: você troca seu client_id e client_secret por um bearer token de curta duração, que acompanha todas as chamadas seguintes no cabeçalho Authorization.

A resposta traz o token e seu tempo de vida:

Guarde o valor de access_token. Ele é um JWT assinado com ECDSA (ES256), com as chaves protegidas em KMS no lado da SignDocs — você não precisa lidar com nada disso, apenas enviar o token. Repare em dois detalhes: o endpoint é /oauth2/token (com o "2") e o corpo vai em application/x-www-form-urlencoded, não em JSON. Para o quickstart, exporte o token em uma variável de ambiente:

Em produção, você vai querer cachear e renovar o token automaticamente antes de ele expirar. Esse detalhe e a rotação segura estão cobertos no guia de autenticação OAuth2 da API de assinatura. Por agora, um token válido por 15 minutos é mais que suficiente.

Passo 2 — A chamada única que cria a assinatura (≈2 min)

Este é o coração do quickstart. Uma chamada para POST /v1/signing-sessions recebe o documento e o signatário e devolve, na mesma resposta, o link que a pessoa vai abrir para assinar.

Em poucos segundos, a resposta chega com a sessão criada e — o que mais importa agora — a URL de assinatura hospedada e o clientSecret:

O link que o signatário abre é a url com o segredo anexado como query string: url?cs=ss_secret_.... Em produção, o domínio muda para sign.signdocs.com.br.

É isso. Sem orquestração de envelope, sem várias chamadas. Vamos destrinchar os campos do corpo da requisição para você adaptar ao seu caso:

Passo 3 — Compartilhe o link e o signatário assina (≈2 min)

O campo checkout_url da resposta é o link de assinatura. Você pode entregá-lo de duas formas, e essa decisão define boa parte da sua experiência:

• Você mesmo envia o link (por e-mail próprio, WhatsApp, no seu app). Tem controle total sobre o canal e a mensagem.
• A SignDocs envia o convite por e-mail automaticamente, quando você fornece os dados do remetente. Nesse caso, o e-mail do convite só é disparado se o remetente for diferente do signatário.

Ao abrir o link, o signatário cai em uma página de checkout hospedado — uma tela pronta, responsiva e com a marca da SignDocs, onde ele revisa o documento, passa pelos passos de autenticação que você definiu (aceite, OTP etc.) e assina. Você não constrói nem mantém essa interface; ela já vem pronta, o que é justamente o que torna o quickstart tão rápido.

Se preferir manter a assinatura dentro da sua própria aplicação, em vez do checkout hospedado existe o modo de assinatura expressa incorporada, em que o widget roda embutido na sua tela. A mesma resposta atende os dois modos: para o hospedado você redireciona o signatário para a url; para o incorporado você monta o widget com o clientSecret usando o SDK JavaScript — o restante do fluxo permanece idêntico.

Depois da assinatura: webhook e download

Quando Maria conclui a assinatura, a API dispara para o endpoint que você registrou via POST /v1/webhooks um POST HTTPS assinado com HMAC-SHA256 (cabeçalho X-SignDocs-Signature). Os eventos principais para este fluxo são SIGNING_SESSION.COMPLETED (a sessão foi concluída) e TRANSACTION.COMPLETED (tudo finalizado, documento pronto).

Ao receber esse evento, sua aplicação usa o transactionId para baixar o evidence pack via GET /v1/transactions/{transactionId}/evidence (escopo evidence:read) — a resposta traz os metadados e uma URL temporária do arquivo .p7m, que reúne a prova jurídica da assinatura — trilha de auditoria append-only, hash SHA-256 do documento, carimbo de hora do servidor e os dados de autenticação que garantem validade. O PDF assinado você baixa pelo endpoint de download do documento da transação. Não é obrigatório responder com nenhum dado especial ao webhook: basta retornar 200 OK rapidamente e processar de forma assíncrona. Os detalhes de segurança, idempotência e retry estão no guia de webhooks e eventos da API.

Recapitulando: os 5 minutos, do zero ao assinado

Visto de cima, o fluxo completo é surpreendentemente curto. Estes são os marcos:

Duas chamadas de API suas, um clique do signatário e um webhook. É todo o ciclo de uma assinatura eletrônica com validade jurídica no Brasil, ancorada na MP 2.200-2/2001 e construída com prioridade em LGPD.

Erros comuns no primeiro teste (e como resolver)

Se algo não voltar como esperado, quase sempre é um destes deslizes:

• 401 Unauthorized: token expirado ou ausente. Gere um novo com o Passo 1 e confira o cabeçalho Authorization: Bearer ....
• Host errado: homologação é api-hml.signdocs.com.br (com hífen), não api.hml.signdocs.com.br. Esse ponto pega muita gente.
• 400 no profile: você passou DIGITAL_SIGN_A1 como policy.profile. Use DIGITAL_CERTIFICATE (ou CLICK_ONLY/CLICK_PLUS_OTP para o nível eletrônico).
• Documento sumiu depois de uns dias: comportamento esperado em homologação — as entidades têm TTL de 7 dias. Recrie a sessão ou mova para produção.
• Base64 inválido: verifique se o PDF foi codificado corretamente, sem quebras de linha indevidas no document.content.

Se quiser ver o documento finalizado de fora da sua integração, qualquer assinatura gerada pode ser conferida no verificador público — útil para mostrar a clientes e auditores que a prova é real e checável.

Próximos passos: do quickstart à produção

Funcionou? Ótimo. A partir daqui, cada guia aprofunda um pedaço do que você acabou de fazer:

• Autenticação para produção: cache e rotação de tokens, escopos e boas práticas em OAuth2 na API de assinatura.
• Entenda a prova jurídica: o que vai dentro do evidence pack .p7m e como verificá-lo de forma independente.
• Checkout hospedado vs. incorporado: entenda quando usar cada entrega na página da Assinatura Expressa.
• Gerar as credenciais: se ainda não fez, o passo a passo de como obter sua API key cobre cada clique no painel.
• Múltiplos signatários: quando precisar de envelopes e ordem de assinatura, migre para a API de Transações partindo da documentação central da API.

Para acelerar ainda mais, lembre que há SDKs oficiais em TypeScript/Node, Python, Go, Java, PHP e C#/.NET — todos encapsulam autenticação, retries e tipagem dos payloads. O curl que usamos aqui é só para deixar tudo transparente no aprendizado; em produção, o SDK da sua linguagem reduz boilerplate.

Perguntas Frequentes