Integrar a assinatura eletrónica em 20 minutos
Descubra como integrar uma API de assinatura eletrónica em menos de 20 minutos: criação de um pedido, envio da ligação, receção do webhook assinado e obtenção do PDF assinado.
Integrar a assinatura eletrónica na sua aplicação não exige semanas de desenvolvimento. Com uma API bem concebida, pode disponibilizar a assinatura em poucos minutos. Este tutorial mostra-lhe passo a passo como criar um pedido de assinatura, transmitir a ligação ao signatário, receber uma notificação assinada e obter o documento assinado, utilizando o Sign-Hub. Abordaremos também os aspetos de segurança e de conformidade essenciais.
Porquê integrar a assinatura eletrónica?
A assinatura eletrónica tornou-se um padrão para contratos, orçamentos ou qualquer documento que necessite de validação. Integrá-la na sua aplicação evita as idas e voltas de impressão, digitalização e envio postal. Para um programador, isso significa automatizar um processo de negócio e oferecer uma experiência fluida ao utilizador final.
Visão geral da API Sign-Hub
O Sign-Hub é um serviço de assinatura eletrónica editado pela NEW VISION OF APPS (SAS, Janzé, França). Posiciona-se como uma solução API-first: o conjunto das funcionalidades está acessível através de uma API REST. Uma única rota permite criar um pedido de assinatura. O serviço encarrega-se depois do envio dos emails, do acompanhamento das assinaturas e da geração dos documentos comprovativos.
A API está documentada segundo a especificação OpenAPI 3.1. Está disponível um SDK TypeScript para facilitar a integração. Além disso, um ficheiro llms.txt foi concebido para ser lido por um assistente de código, o que acelera o desenvolvimento.
Pré-requisitos
- Uma conta Sign-Hub (oferta Découverte gratuita, 10 atos por mês)
- Uma chave API (disponível no painel de controlo)
- Um ambiente de desenvolvimento (Node.js para este tutorial)
Passo 1: Criar um pedido de assinatura
O primeiro passo consiste em chamar a API para criar um pedido. Deve fornecer o documento a assinar (PDF), o identificador do signatário (email, nome) e, eventualmente, opções como a ordem de assinatura.
Exemplo de pedido com curl:
curl -X POST "https://api.sign-hub.example.com/v1/signature-requests" \
-H "Authorization: Bearer VOTRE_CLE_API" \
-H "Content-Type: application/json" \
-d '{
"document": {"name": "contrat.pdf", "content": "base64..."},
"signers": [
{"email": "client@example.com", "first_name": "Jean", "last_name": "Dupont"}
]
}'
A resposta contém um identificador de pedido e uma ligação pública de assinatura. Esta ligação é única para cada signatário. Pode transmiti-la por email ou apresentá-la na sua interface.
Passo 2: Transmitir a ligação ao signatário
A ligação pública pode ser integrada num email automático ou apresentada numa página da sua aplicação. O Sign-Hub também gere o envio de emails de relance se o configurar. No nosso exemplo, enviamos a ligação diretamente através da API da sua escolha.
Passo 3: Receber o webhook assinado
Quando o signatário terminar a sua assinatura, o Sign-Hub envia uma notificação ao seu servidor através de um webhook. Este webhook é assinado com um segredo HMAC para garantir a sua autenticidade. São propostas duas versões: uma simples e uma com data/hora anti-replay.
Para verificar o webhook, deve calcular a assinatura HMAC a partir do corpo do pedido e comparar com o cabeçalho fornecido. Em caso de falha, ignore o pedido.
Exemplo de verificação em Node.js:
const crypto = require('crypto');
function verifyWebhook(payload, signature, secret) {
const expected = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return expected === signature;
}
Passo 4: Obter o PDF assinado e o dossiê de prova
Após o webhook, pode obter o PDF assinado e o dossiê de prova através da API. O PDF é selado no formato PAdES, garantindo a sua integridade. O dossiê de prova contém todas as informações necessárias para verificar a validade da assinatura.
Exemplo de obtenção:
curl -X GET "https://api.sign-hub.example.com/v1/signature-requests/{id}/signed-pdf" \
-H "Authorization: Bearer VOTRE_CLE_API"
A prova verificável: um trunfo diferenciador
Ao contrário de muitos intervenientes, o Sign-Hub permite a qualquer pessoa verificar a validade de uma assinatura sem confiar no editor. O dossiê de prova é assinado com uma chave Ed25519, cuja chave pública é publicada num endereço bem conhecido. Pode verificar um proof.json offline ou através de uma ferramenta em linha. Esta transparência reforça o valor probatório.
Segurança e conformidade
O Sign-Hub respeita o regulamento eIDAS (regulamento (UE) n.º 910/2014) para a assinatura eletrónica simples. O consentimento do signatário é explicitamente registado, a impressão digital do documento é fixada no momento da assinatura, e os dados de ligação são anonimizados em conformidade com o RGPD, sem quebrar a prova. Os dados estão alojados na União Europeia.
É importante notar que a assinatura proposta é uma assinatura eletrónica simples, reforçada pela verificação de email e pela selagem. Não constitui uma assinatura avançada ou qualificada na aceção do eIDAS. Para atos em que a lei exige uma assinatura qualificada, podem ser necessárias outras soluções como a Universign.
Comparação com outras soluções
A Yousign, a DocuSign e a Universign também oferecem APIs de assinatura eletrónica. A maioria propõe funcionalidades semelhantes: envio de ligações, acompanhamento, webhooks. O Sign-Hub distingue-se pela sua transparência na verificação da prova e pela sua abordagem API-first com uma documentação pensada para a IA. O seu tarifário por ato, sem subscrição obrigatória, pode convir às pequenas estruturas.
Para ir mais longe
O SDK TypeScript permite integrar rapidamente a API nos seus projetos. A especificação OpenAPI 3.1 está disponível, e o ficheiro llms.txt pode ser utilizado por assistentes de código para gerar código de integração. Para testar, crie uma conta na oferta Découverte e utilize a sua primeira chave API.
Conclusão
Integrar a assinatura eletrónica na sua aplicação está ao alcance de qualquer programador, e o Sign-Hub torna-o simples e rápido. Em menos de 20 minutos, pode criar um pedido, receber o webhook e obter o documento assinado. A documentação completa e as ferramentas fornecidas permitir-lhe-ão ir mais longe de acordo com as suas necessidades.