Primeira assinatura
Assine um PDF em três chamadas. Leva uns dez minutos.
Assinar um PDF são três chamadas do seu servidor à API. A assinatura em si acontece no computador do usuário, e a chave privada nunca sai de lá.
Navegador do usuário Seu servidor API ShieldSign PKI
| | |
| PDF -------------------> | 1. POST /v1/pades-signatures | devolve o token da sessão
| certificado -----------> | 2. POST .../{token}/prepare | devolve os dados a assinar
| assina localmente | |
| assinatura ------------> | 3. POST .../{token}/complete | devolve o PDF assinado
Antes de começar
Você precisa de uma chave de API (ssk_...), criada por quem administra a sua conta no painel. Veja Autenticação. Guarde a chave só no servidor.
export SHIELDSIGN_URL=https://api.pki.shieldsign.com.br
export SHIELDSIGN_KEY=ssk_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
1. Iniciar: enviar o PDF#
curl -s "$SHIELDSIGN_URL/v1/pades-signatures/multipart" \
-H "Authorization: Bearer $SHIELDSIGN_KEY" \
-F signaturePolicyId=pades-icpbrasil-ad-rb \
-F securityContextId=icp-brasil \
-F file=@contrato.pdf
$api = new ShieldSign\Client(getenv('SHIELDSIGN_URL'), getenv('SHIELDSIGN_KEY'));
$r = $api->startMultipart(
[['path' => '/var/app/contrato.pdf', 'name' => 'contrato.pdf']],
'pades-icpbrasil-ad-rb', // política de assinatura
'icp-brasil' // contexto de segurança (raízes de confiança)
);
$token = $r['token'];
A resposta (resumida):
{ "token": "o3...43 caracteres...", "documents": [ { "index": 0, "transactionId": "...", "sha256": "..." } ] }
O token vale 15 minutos e identifica a sessão. Guarde-o no seu servidor: o navegador nunca deve vê-lo. A escolha da política está em Políticas e contextos.
2. Preparar: enviar o certificado#
O navegador lê o certificado do usuário (pela extensão) e o envia ao seu servidor, que o repassa:
curl -s "$SHIELDSIGN_URL/v1/pades-signatures/$TOKEN/prepare" \
-H "Authorization: Bearer $SHIELDSIGN_KEY" -H "Content-Type: application/json" \
-d '{ "certificate": "<certificado DER em base64>" }'
$p = $api->prepare($token, $certificadoDerBase64);
foreach ($p['digests'] as $d) {
// $d['toSignData'] (base64) é o que o navegador vai assinar
}
A resposta traz digests[], um item por documento, com o toSignData que o usuário assina. A API já validou o certificado aqui. Se ele não servir, o erro vem neste passo, antes de o usuário digitar o PIN (por exemplo, certificate_not_trusted).
3. Concluir: enviar a assinatura#
curl -s "$SHIELDSIGN_URL/v1/pades-signatures/$TOKEN/complete" \
-H "Authorization: Bearer $SHIELDSIGN_KEY" -H "Content-Type: application/json" \
-d '{ "signatures": ["<assinatura em base64>"], "output": "link" }'
# baixe o PDF assinado e apague a sessão
curl -s "$SHIELDSIGN_URL/v1/pades-signatures/$TOKEN/documents/0" -H "Authorization: Bearer $SHIELDSIGN_KEY" -o assinado.pdf
curl -s -X DELETE "$SHIELDSIGN_URL/v1/pades-signatures/$TOKEN" -H "Authorization: Bearer $SHIELDSIGN_KEY"
$c = $api->complete($token, $assinaturasBase64, 'link');
$api->downloadDocument($token, 0, '/var/app/assinado.pdf');
$api->discard($token); // libera a sessão assim que guardar o PDF
Apague a sessão ao terminar
Depois de baixar o PDF, chame DELETE /v1/pades-signatures/{token}. Sessões concluídas continuam ocupando uma vaga do seu cliente até serem apagadas ou expirarem. Veja Limites e cotas.
O que o navegador faz#
A parte do usuário usa a extensão pelo SDK JavaScript: listar os certificados, enviar o escolhido ao seu servidor (passo 2) e assinar os dados que voltam. O guia Assinar PDFs no seu sistema mostra os três endpoints do seu servidor e o código do navegador, prontos para adaptar.
Quando algo dá errado#
Toda resposta de erro traz um code estável e o cabeçalho X-Request-Id. A lista completa está em Erros. Guarde o X-Request-Id ao pedir suporte.
Próximos passos#
- Assinar PDFs no seu sistema: o fluxo completo, em um documento ou em lote.
- Sessões, prazos e repetição segura: o que fazer quando a rede cai no meio.
- Identidade do certificado: ler o CPF/CNPJ e recusar antes do PIN.
- Referência da API.