Como Integrar uma API de Assinatura Digital: Guia Passo a Passo

Integrar uma API de assinatura digital ao seu produto não precisa ser um projeto de meses. Com o roadmap certo, você sai do zero a uma primeira assinatura coletada em homologação no mesmo dia, e chega à produção com confiança jurídica em poucas semanas. Este guia mostra, passo a passo, o caminho completo de integração: da escolha da API e das credenciais OAuth2 ao envio de documentos, coleta de assinaturas, webhooks e go-live.

Escrevemos para desenvolvedores, tech leads e CTOs que estão avaliando ou já começando a integrar assinatura eletrônica via API. Em vez de mergulhar em um único detalhe técnico, este artigo dá a visão de cima de todo o fluxo e aponta, em cada etapa, para os guias específicos que aprofundam o assunto.

Se você ainda está na fase de avaliação, vale começar pela visão geral da API de assinatura digital da SignDocs. Se já decidiu integrar, siga as nove etapas abaixo na ordem apresentada.

Visão geral: o roadmap de integração em 9 etapas

Antes de entrar nos detalhes, veja o mapa completo. Cada etapa abaixo tem uma seção dedicada mais adiante e, quando aplicável, um link para o guia aprofundado correspondente.

Etapa 1 — Escolher entre envelopes e Assinatura Expressa

A primeira decisão de arquitetura define todo o resto da integração. A SignDocs expõe duas superfícies de API, pensadas para casos de uso diferentes:

Assinatura Expressa (Signing Sessions)

É a opção mais rápida. Uma única chamada POST /v1/signing-sessions cria uma sessão e devolve o link de checkout hospedado (e o clientSecret, que também permite abrir o fluxo em um pop-up dentro da sua aplicação via @signdocs-brasil/js). Ideal para fluxos de um signatário por vez, onboarding, aceites e qualquer cenário em que você quer que o usuário assine na hora, sem orquestrar um ciclo de vida complexo.

Envelopes (multi-signatário)

É a opção de controle total para múltiplas partes. O documento sobe uma vez no envelope, cada signatário recebe a sua própria sessão (com perfil de autenticação individual), a ordem é controlada por signingMode e signerIndex, e você acompanha cada transição de estado. Indicada para contratos com várias partes, fluxos de aprovação e integrações que precisam reagir a cada etapa do fluxo transacional completo.

Etapa 2 — Criar conta e gerar credenciais OAuth2

Com o modelo escolhido, você precisa de credenciais para autenticar sua aplicação. A SignDocs usa o fluxo OAuth2 client-credentials: um par client_id / client_secret que sua aplicação troca por um token de acesso bearer.

1. Crie sua conta no painel da SignDocs (o sandbox de homologação é gratuito, sem cartão).
2. Acesse a área de desenvolvedores e gere um par de credenciais para o ambiente de homologação.
3. Guarde o client_secret com segurança — ele é exibido uma única vez. Use um cofre de segredos (AWS Secrets Manager, Vault, etc.), nunca commit no repositório.

Os tokens emitidos são JWT assinados com ECDSA (ES256), expiram em 15 minutos, e as chaves residem em KMS. Para clientes enterprise ou regulados — integrações BACEN e Open Finance, por exemplo — há ainda a opção de mTLS para reforçar a segurança no transporte. O passo a passo detalhado de geração e rotação está em como obter sua API key de assinatura.

Etapa 3 — Configurar o ambiente de homologação

Nunca desenvolva contra produção. A SignDocs oferece um ambiente de homologação (sandbox) com host próprio: api-hml.signdocs.com.br (atenção: é a forma com traço, não api.hml.signdocs.com.br). Nele você cria transações, coleta assinaturas simuladas e recebe webhooks idênticos aos de produção, sem custo e sem efeito jurídico.

Etapa 4 — Sua primeira chamada à API

Hora de validar que tudo está conectado. O fluxo é sempre o mesmo: troque suas credenciais por um token e use esse token no header Authorization. Dois detalhes que evitam erros bobos: o endpoint é /oauth2/token (com o "2") e o corpo vai em application/x-www-form-urlencoded, não em JSON. Primeiro, obtenha o token:

Em seguida, use o token em uma chamada autenticada simples para confirmar que tudo funciona:

Um HTTP 200 aqui confirma que credenciais, ambiente e token estão corretos. Se você prefere ir direto ao ponto com um exemplo end-to-end, o guia primeiros passos com a API em 5 minutos leva você da credencial à primeira assinatura sem desvios. Os detalhes do fluxo de token, escopos e renovação estão em autenticação OAuth2 na API de assinatura.

Etapa 5 — Enviar um documento para assinatura

Com a autenticação funcionando, você cria sua primeira sessão de assinatura. Abaixo, o exemplo com a Assinatura Expressa: uma chamada envia o documento, define o signatário e devolve o link. (Para múltiplos signatários, o caminho equivalente é criar um envelope e adicionar uma sessão por signatário.)

O link que o signatário abre é a url com o clientSecret anexado como ?cs=. A SignDocs aceita o documento em base64 (até 10 MB) ou por presigned URL, e cada sessão devolve o seu próprio link. O aprofundamento — incluindo o upload por presigned URL e os envelopes multi-signatário — está em como enviar um documento para assinatura via API.

Etapa 6 — Coletar a assinatura: perfis de autenticação

Aqui está o coração do valor jurídico: como o signatário comprova quem é ao assinar. A SignDocs combina diferentes métodos de autenticação em perfis de política, conforme o nível de garantia que o seu caso de uso exige.

Esses métodos se combinam em perfis (por exemplo, BIOMETRIC_PLUS_OTP). Um ponto que confunde quem está começando: o perfil de política que aciona certificado ICP-Brasil é DIGITAL_CERTIFICATE; DIGITAL_SIGN_A1 é o tipo de etapa que aparece no resultado, nunca um valor de profile. A classe do certificado (certificateType) e a política ICP-Brasil (certificatePolicyOid) ficam registradas na evidência da assinatura. Para escolher a combinação certa, veja o guia de autenticação multimétodo na API de assinatura.

Etapa 7 — Receber webhooks em tempo real

Polling não escala. A forma correta de acompanhar uma transação é registrar um endpoint de webhook e deixar a API avisar sua aplicação a cada mudança de estado: SIGNING_SESSION.COMPLETED, TRANSACTION.COMPLETED, SIGNING_SESSION.CANCELLED, STEP.FAILED, entre outros.

Os webhooks da SignDocs são entregues por HTTPS POST, com assinatura HMAC-SHA256 no header para você verificar a autenticidade, idempotência via o id do evento e retry com backoff exponencial em caso de falha. Sempre valide a assinatura HMAC antes de processar o payload e retorne HTTP 200 rapidamente, processando o resto de forma assíncrona. O guia completo de arquitetura, verificação e idempotência está em webhooks e eventos da API de assinatura.

Etapa 8 — Baixar o documento assinado e o evidence pack

Quando o evento TRANSACTION.COMPLETED chega, o documento final está pronto. Você baixa duas coisas:

• O PDF assinado, no padrão PAdES baseline (assinatura + certificado + carimbo de hora do servidor + trilha de auditoria; CAdES para outros tipos de arquivo). Os níveis com carimbo de tempo de uma ACT e LTV (PAdES-B-T/B-LT/B-LTA) não são gerados atualmente pela API.
• O evidence pack (.p7m), um container PKCS#7/CMS com a trilha de auditoria append-only, o carimbo de hora do servidor, o hash SHA-256 do documento e os dados de cada autenticação (método, IP, geolocalização).

Esse pacote é a sua prova jurídica. Arquive-o num bucket WORM ou repositório imutável. Qualquer parte pode validar a autenticidade de forma independente no verificador público da SignDocs, sem conta nem acesso à API. Para entender a anatomia do container e como apresentá-lo em juízo, veja evidence pack .p7m e prova jurídica via API.

Etapa 9 — Ir para produção

Depois de validar o fluxo ponta a ponta em homologação, a promoção para produção é direta — mas exige atenção a alguns pontos:

1. Gere credenciais de produção separadas das de homologação. Nunca reutilize segredos entre ambientes.
2. Troque o host base de api-hml.signdocs.com.br para o host de produção. Centralize isso em uma variável de ambiente, não em strings espalhadas pelo código.
3. Registre webhooks de produção apontando para o seu endpoint público com HTTPS válido e a nova chave secreta HMAC.
4. Confirme a base legal: em produção, suas assinaturas têm validade sob a MP 2.200-2/2001 (ICP-Brasil) com conformidade LGPD. A SignDocs é multi-região na AWS e LGPD-first; o diferencial brasileiro está em ser nativa de ICP-Brasil, com produto e suporte em pt-BR.
5. Monitore as primeiras transações reais e tenha um plano de reconciliação (polling de fallback) para o improvável caso de um webhook perdido.

Perguntas Frequentes