Como integrar uma API de assinatura digital
Roteiro técnico de integração de assinatura digital ICP-Brasil em um sistema próprio.
- 1
Obtenha a API key
Solicite a chave de teste e configure as origens permitidas do seu domínio.
- 2
Vincule o signatário
Cadastre o profissional e o certificado em nuvem que fará a assinatura.
- 3
Envie o documento
Faça o POST com o conteúdo estruturado e o identificador do tipo de documento.
- 4
Trate a autorização
O signatário aprova a assinatura no app do certificado (PIN ou biometria).
- 5
Consuma o webhook
Valide o HMAC SHA-256 sobre o corpo cru e armazene o PDF assinado e o token público.
Como funciona a assinatura digital via API
O fluxo tem três atores: o seu sistema (que monta o documento), a plataforma de assinatura (que gera o PDF e conversa com a Autoridade Certificadora) e o signatário (que autoriza a operação com o certificado dele).
Seu sistema nunca manipula a chave privada. Ela permanece protegida no HSM da Autoridade Certificadora, e cada assinatura exige uma autorização explícita do titular — é isso que garante o não repúdio.
- 1. POST de criação do documento com os dados estruturados.
- 2. Retorno imediato com o identificador do documento e o status inicial.
- 3. Autorização do signatário no app do certificado em nuvem.
- 4. Geração do PDF assinado em PAdES, com carimbo de tempo e metadados ICP-Brasil.
- 5. Webhook para o seu endpoint com o resultado final.
Padrões de assinatura: CAdES, XAdES e PAdES
Para documentos médicos, PAdES é o padrão adequado: o próprio PDF carrega a assinatura, o que permite que farmácias, operadoras e o validador do ITI verifiquem o arquivo sem depender de um segundo anexo.
| Padrão | Formato do arquivo | Melhor uso |
|---|---|---|
| PAdES | PDF com assinatura embarcada | Documentos que serão lidos por pessoas (receitas, atestados, contratos) |
| CAdES | Arquivo .p7s separado ou anexado | Integrações máquina a máquina e arquivos binários |
| XAdES | XML assinado | Notas fiscais e documentos fiscais estruturados |
Endpoints típicos de uma integração
| Operação | O que faz | Quando usar |
|---|---|---|
| Criar documento | Gera e envia para assinatura | No fim do atendimento ou fluxo de negócio |
| Listar tipos de documento | Retorna os tipos disponíveis e seus identificadores | Uma vez, em cache, no seu deploy |
| Consultar status | Emitido, assinado, enviado, dispensado | Fallback quando o webhook falhar |
| Baixar o PDF assinado | Retorna o binário final | Arquivamento no seu sistema |
| Webhook de eventos | Notifica assinatura e envio | Fluxo principal, sempre |
Validação do webhook com HMAC
Cada entrega vai com um cabeçalho de assinatura calculado em HMAC SHA-256 sobre o corpo cru da requisição, usando o segredo do parceiro. O erro mais comum de integração é calcular o HMAC sobre o JSON já parseado e re-serializado: qualquer diferença de espaçamento ou ordem de chaves invalida a comparação.
Leia o corpo como string ou buffer antes de qualquer parsing, compare em tempo constante e responda 2xx rapidamente — processamentos demorados devem ir para uma fila, senão a entrega entra em retentativa.
- Guarde o segredo em variável de ambiente, nunca no código do cliente.
- Rejeite entregas com timestamp muito antigo para evitar replay.
- Trate o webhook como idempotente: o mesmo evento pode chegar mais de uma vez.
- Responda 401 apenas quando a assinatura não bater, e 200 quando aceitar o evento.
Erros comuns e como resolver
| Sintoma | Causa provável | Correção |
|---|---|---|
| 401 na chamada da API | Chave inválida, expirada ou origem não autorizada | Verifique a API key e as origens permitidas |
| 400 na criação | Campo obrigatório ausente ou CPF/CRM inválido | Valide o payload antes do envio |
| HMAC não confere | Corpo re-serializado antes do cálculo | Calcule sobre o corpo cru |
| Assinatura nunca conclui | Sessão do certificado expirada | Renove a sessão do signatário |
| Webhook em retentativa | Endpoint lento ou respondendo 5xx | Responda 2xx e processe em fila |
Checklist antes de ir para produção
- Endpoint de webhook com HTTPS válido e verificação de HMAC ativa.
- Armazenamento do PDF assinado e do link público de validação.
- Tela para o usuário final acompanhar o status do documento.
- Tratamento de expiração da sessão de assinatura com nova autorização.
- Logs de requisição com correlação por identificador do documento.
- Plano de rotação da API key e do segredo do webhook.