Assinatura com Certificado ICP-Brasil via API: A1 na Sessão Direta, A3 pela Expressa e pelo App

Quando o documento precisa de assinatura qualificada, a pergunta que chega ao time de integração é sempre a mesma: "dá para assinar com certificado ICP-Brasil pela API?". A resposta curta é sim, mas o caminho muda conforme o tipo de certificado do signatário. O A1 (arquivo instalado no computador ou no celular) é assinado diretamente na sessão criada pela API, na própria página hospedada, sem que a chave privada saia do dispositivo do titular. O A3 (token USB ou cartão inteligente) é assinado pela Assinatura Expressa ou pelo app da SignDocs, por meio do SignDocsBrasil Assinador, o aplicativo gratuito de desktop que faz a ponte entre o token e a página de assinatura.

Este guia mostra os dois caminhos de ponta a ponta: o perfil DIGITAL_CERTIFICATE e suas etapas, o que acontece no navegador do signatário quando ele usa um A1, como o Assinador entra em cena para o A3, os erros de certificado que você vai encontrar e o que fica registrado como evidência. No fim há uma regra prática para decidir, caso a caso, entre a sessão direta e a Expressa.

Se você ainda está avaliando se o documento precisa mesmo de certificado, o guia de autenticação multimétodo compara todos os perfis; o de API brasileira com ICP-Brasil explica o contexto legal. Aqui o foco é a mecânica.

Quando exigir certificado ICP-Brasil

A assinatura com certificado ICP-Brasil é a assinatura qualificada da Lei 14.063/2020: a que carrega a presunção de veracidade do art. 10, §1º, da MP 2.200-2/2001 em relação ao signatário. Na prática, o integrador exige certificado em três situações:

• Quando a norma ou o edital pede assinatura qualificada. Alguns atos perante órgãos públicos e alguns contratos regulados exigem ICP-Brasil expressamente. Nesses casos não há escolha: o perfil é DIGITAL_CERTIFICATE.
• Quando a contraparte já opera com certificado. Escritórios de contabilidade, advocacia, empresas que assinam notas fiscais e procurações eletrônicas costumam ter e-CNPJ ou e-CPF à mão; para elas, o certificado é o caminho de menor atrito.
• Quando o valor em jogo justifica a presunção máxima. Para a maioria dos contratos, a assinatura avançada com OTP ou biometria é suficiente e converte melhor. O certificado entra onde a disputa sobre autoria seria cara.

O perfil DIGITAL_CERTIFICATE: criação e etapas

A sessão é criada como qualquer outra, trocando apenas o perfil de política. Não há campo para enviar o certificado do signatário, e isso é proposital: o integrador nunca manuseia chave nem arquivo do titular.

Internamente, o perfil vira uma sequência fixa de duas etapas, executadas nessa ordem na página hospedada:

Dois detalhes que evitam chamados de suporte: DIGITAL_SIGN_A1 é o nome da etapa, não do perfil. Enviar "profile": "DIGITAL_SIGN_A1" devolve 400. E o nome da etapa não limita o tipo de certificado que a plataforma como um todo aceita: ele descreve o que a sessão direta da API executa, que é o A1. O A3 tem outro caminho, descrito adiante.

O que acontece na página hospedada com um A1

O ponto central do desenho é que a chave privada nunca sai do dispositivo do signatário. O servidor da SignDocs prepara o que precisa ser assinado, o navegador assina, o servidor monta a assinatura final. Passo a passo:

1. Seleção do certificado. O signatário escolhe o arquivo A1 (.pfx/.p12) e informa a senha. O arquivo é aberto localmente, no navegador.
2. Preparação. A página envia ao servidor apenas a cadeia de certificados (a parte pública, em PEM). O servidor valida a cadeia, calcula o resumo criptográfico do documento com SHA-256 e devolve o material a assinar (hashToSign/dataToSign) junto de um identificador da requisição de assinatura (signatureRequestId) e dos algoritmos usados.
3. Assinatura local. A chave privada, ainda no navegador, assina esse resumo. O que volta para o servidor é a assinatura bruta em base64 (rawSignatureBase64), nunca a chave, nunca a senha.
4. Montagem. O servidor combina a assinatura bruta com a cadeia e o documento, monta a estrutura CMS/PAdES e grava o resultado da etapa com geolocalização e informações do dispositivo. A sessão conclui, o webhook SIGNING_SESSION.COMPLETED dispara e o documento assinado fica disponível para download.

Quer ver o formato do arquivo final antes de integrar? A página de assinar PDF com e-CPF ou e-CNPJ mostra o resultado do ponto de vista de quem assina.

Erros de certificado: o que a página recusa

A validação acontece na etapa de preparação, antes de qualquer assinatura. A página recusa cadeia inválida ou vencida e explica ao signatário o que fazer. Os casos mais comuns:

Do lado da API, esses casos não geram erro na criação da sessão: a sessão nasce ACTIVE e a recusa acontece na interação do signatário. Monitore pelos eventos STEP.FAILED e pelo status da transação, como descrito em webhooks e eventos.

A3: token e cartão pelo SignDocsBrasil Assinador

O certificado A3 vive dentro de um dispositivo criptográfico (token USB ou cartão inteligente) e, por definição, a chave privada não pode ser exportada. Um navegador não conversa com esse dispositivo sozinho. Por isso a SignDocs mantém o SignDocsBrasil Assinador: um aplicativo gratuito para Windows, macOS e Linux que fala PKCS#11 com o token e faz a ponte, localmente, com a página de assinatura.

Como a ponte funciona:

1. O signatário instala o Assinador e o driver (middleware) do fabricante do token, como SafeSign, SafeNet ou OpenSC. A tabela de compatibilidade lista os modelos testados.
2. Ao abrir a página de assinatura da Assinatura Expressa em um navegador baseado em Chromium (Chrome, Edge, Brave), a página se comunica com o Assinador que está rodando no próprio computador, por HTTPS na porta 8757 (ou HTTP na porta 8756).
3. O Assinador lê os certificados disponíveis no token, o signatário escolhe o dele e digita o PIN. A assinatura é calculada dentro do dispositivo; o Assinador devolve apenas a assinatura à página.
4. A plataforma monta o CMS/PAdES, registra as mesmas evidências (data e hora, IP, geolocalização, dispositivo, cadeia) e conclui a assinatura.

O app da SignDocs (Android e iOS) usa a mesma conexão com o Assinador para assinar com A3: o documento é aberto no app, e a assinatura acontece no computador onde o token está conectado. O que não existe é leitura de token diretamente pelo celular.

A1, A3 e certificado em nuvem: comparação para o integrador

Sobre o certificado em nuvem (BirdID, VIDaaS, SafeID, NeoID e similares): o suporte depende de o provedor expor uma interface compatível com o Assinador. Não trate como garantido; peça a confirmação ao suporte da SignDocs para o provedor específico do seu cliente antes de desenhar o fluxo.

Sessão direta ou Assinatura Expressa: como decidir

A decisão é por signatário, não por projeto. Um mesmo contrato pode ter o representante da empresa assinando com e-CNPJ A3 pela Expressa e o cliente assinando com biometria pela sessão direta.

Para testar o fluxo A1 sem custo, use o ambiente de homologação: crie a sessão com DIGITAL_CERTIFICATE, abra o link e assine com um certificado A1 de teste ou com o seu próprio. O documento e as evidências ficam disponíveis por sete dias. O fluxo A3 é testado na Assinatura Expressa com o Assinador instalado.

O que fica registrado como evidência

Assinatura qualificada não dispensa a trilha de auditoria; ela a complementa. Para cada assinatura com certificado, a transação registra:

• A cadeia de certificados apresentada pelo signatário, com titular, AC emissora e validade, junto do resultado da validação.
• O hash SHA-256 do documento no momento da assinatura e a assinatura criptográfica montada em CMS/PAdES, verificável em qualquer leitor compatível e no verificador público.
• As evidências de contexto: data e hora em UTC, IP, geolocalização, user-agent e informações do dispositivo, tanto no aceite quanto na assinatura.
• O aceite dos termos feito na etapa CLICK_ACCEPT.

Tudo isso compõe o pacote de evidências (.p7m) da transação, baixável pela API depois da conclusão. Em caso de contestação, você apresenta o documento assinado com o certificado e, além dele, a prova de como e quando a assinatura aconteceu.

Perguntas Frequentes