Pular para o conteúdo principal

Carimbos em PDF - Rest PKI Core

Um carimbo é um carimbo de tempo de documento PAdES que o Rest PKI Core adiciona a um PDF: um carimbo de tempo de um dos planos de carimbo de tempo da instância, embutido no PDF como um campo de assinatura, que prova que o documento existia exatamente daquela forma naquele momento. Ele não envolve o certificado de um signatário, então nenhum usuário participa. Opcionalmente, o carimbo tem uma aparência visível, com texto e imagem, numa página do PDF.

dica

A partir daqui, descrevemos chamadas ao Rest PKI Core. Leia antes o artigo Primeiros passos. A chave de API da aplicação precisa de um papel que permita carimbar PDFs, como Operador (veja Escolhendo os papéis).

Carimbando um PDF​

Em .NET, chame IRestPkiService.StampPdfAsync() com o PDF, como referência de arquivo, e as opções:

var result = await restPkiService.StampPdfAsync(FileReference.FromFile(@"C:\AppData\Documents\document.pdf"), new StampPdfOptions() {
	TimestampTier = "PkiBrazil",
});

// result.File é uma referência ao PDF carimbado

Passe as opções mesmo que não defina nenhuma delas: o StampPdfAsync() não aceita null.

Se for chamar a API diretamente, faça:

POST {endpoint}/api/pdf/stamp
{
	"file": {
		"content": "JVBERi0xLjcK...",
		"name": "document.pdf"
	},
	"timestampTier": "PkiBrazil"
}

A requisição tem estes campos (em .NET, as propriedades de StampPdfOptions, com os mesmos nomes):

CampoDescrição
fileO PDF. Obrigatório
timestampTierO ID ou o nome do plano de carimbo de tempo, como PkiBrazil. Se omitido, o Rest PKI Core usa o plano padrão da instância: na instância SaaS, sempre informe o plano (veja Solicitando carimbos de tempo)
customSignatureFieldNameO nome do campo de assinatura do carimbo no PDF. Até 100 caracteres, sem pontos
reasonO motivo registrado no carimbo. Até 1024 caracteres
visualRepresentationA aparência visível do carimbo: veja abaixo. Sem ela, o carimbo não aparece nas páginas
forceBlobResultRetornar o PDF carimbado como link temporário mesmo quando ele é pequeno (veja O resultado)

A chamada falha com TimestampTierNotFound quando o plano não existe, com TimestampTierDisabled quando ele está desabilitado e com TimestampTierRestricted quando a sua organização não pode usá-lo. Um número de página além da última falha com InvalidPage.

Em Node.js, a biblioteca restpki-core-client chama esta rota com stampPdf() e, em Python, a restpki-ng-python-client com PdfApi.api_pdf_stamp_post(). As bibliotecas de Java e PHP não têm um método que funcione para ela: chame a rota diretamente, como descrito em Chamando a API diretamente.

Cada carimbo é contado como uma transação de Carimbo de PDF. A chamada falha quando a organização atingiu o limite de transações de carimbo de PDF ou de carimbo de tempo.

A aparência visível​

O visualRepresentation recebe o mesmo modelo da representação visual de uma assinatura PAdES, com text, image e position. Por exemplo, o carimbo desenhado pela demonstração do dashboard, no rodapé da primeira página:

"visualRepresentation": {
	"text": {
		"text": "Lacuna Software",
		"fontSize": 13.0,
		"includeSigningTime": true,
		"horizontalAlign": "Left",
		"container": { "left": 0.2, "top": 0.2, "right": 0.2, "bottom": 0.2 }
	},
	"image": {
		"resource": { "url": "https://cdn.lacunasoftware.com/img/pdf-stamp.png", "mimeType": "image/png" },
		"horizontalAlign": "Right",
		"verticalAlign": "Center"
	},
	"position": {
		"pageNumber": 1,
		"measurementUnits": "Centimeters",
		"auto": {
			"container": { "left": 1.0, "right": 1.0, "bottom": 1.0, "height": 4.94 },
			"signatureRectangleSize": { "width": 8.0, "height": 4.94 },
			"rowSpacing": 0.3,
			"horizontalDirection": "LeftToRight",
			"verticalDirection": "BottomUp"
		}
	}
}

O texto é desenhado como foi passado: tags como {{name}}, que uma assinatura substitui por dados do certificado do signatário, não são substituídas num carimbo, já que não há signatário.

O resultado​

O resultado é o PDF carimbado, como referência de arquivo: em content, em Base64, quando ele tem até 5 MB, ou então como uma url da qual você pode baixá-lo por tempo limitado. Com forceBlobResult = true, ele sempre vem como url. Em .NET, result.File é uma FileReference.

A inspeção de assinaturas do PDF carimbado lista o carimbo como um signatário com isDocumentTimestamp = true.

PDFs assinados​

Você pode carimbar um PDF que já está assinado. Ao carimbar, o Rest PKI Core não valida as assinaturas que já estão nele, e o carimbo é adicionado como uma nova assinatura seria, como o PKI SDK faz para adicionar LTV a um PDF assinado.

Testando no dashboard​

Nas instâncias que emitem carimbos de tempo, o dashboard tem uma demonstração: no menu lateral, clique em Demonstrações e depois em Carimbo de PDF. Escolha um Plano de fornecimento de carimbo de tempo, faça upload de um PDF e clique em Carimbar: o dashboard abre o PDF carimbado, com a aparência mostrada acima.

Carimbos e marcas em PDF​

Um carimbo não é a forma mais nova das marcas em PDF do Rest PKI (PdfMarker, POST Api/Pdf/AddMarks), que desenham textos, imagens e QR codes nas páginas, por exemplo para gerar a versão para impressão de um documento assinado. O Rest PKI Core continua atendendo a rota de marcas com os modelos do Rest PKI (veja Migração do Rest PKI), e as duas fazem coisas diferentes:

Marcas em PDF (Api/Pdf/AddMarks)Carimbo (api/pdf/stamp)
O que adicionaDesenhos nas páginas, sem criptografiaUm carimbo de tempo de documento, com aparência opcional
O que pode desenharVários elementos por marca, com texto formatado, imagens, QR codes, bordas, fundos e rotaçãoUma aparência, com um texto e uma imagem
OndeTodas as páginas, uma página (contada do início ou do fim) ou uma nova páginaUma página
Num PDF assinadoInvalida as assinaturas, a menos que o abortIfSigned faça a chamada falhar com CannotApplyPdfMarksCarimba o PDF (veja PDFs assinados)
Carimbo de tempoNenhumEmitido por um plano de carimbo de tempo
No Rest PKIPdfMarkerSem equivalente

Veja também​

Ver em Markdown