---
title: "Carimbos em PDF - Rest PKI Core"
description: "Carimbe um PDF com POST api/pdf/stamp: o Rest PKI Core adiciona um carimbo de tempo de documento PAdES de um dos seus planos de carimbo de tempo, opcionalmente com aparência visível. Como ele difere das marcas em PDF."
canonical: "https://docs.lacunasoftware.com/articles/rest-pki/core/integration/pdf-stamp"
locale: "pt-BR"
product: "Rest PKI Core"
last_updated: "2026-10-12"
---

# Carimbos em PDF - Rest PKI Core

Um **carimbo** é um carimbo de tempo de documento PAdES que o [Rest PKI Core](https://docs.lacunasoftware.com/articles/rest-pki/core) adiciona a um PDF: um carimbo de tempo de um dos
[planos de carimbo de tempo](https://docs.lacunasoftware.com/articles/rest-pki/core/requesting-timestamps) 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](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/get-started). A chave de API da aplicação precisa de
> um papel que permita carimbar PDFs, como **Operador** (veja [Escolhendo os papéis](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/get-started#roles)).

## Carimbando um PDF

Em .NET, chame `IRestPkiService.StampPdfAsync()` com o PDF, como [referência de arquivo](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/file-referencing), e as opções:

```cs
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:

```text
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):

| Campo | Descrição |
| --- | --- |
| `file` | O PDF. Obrigatório |
| `timestampTier` | O 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](https://docs.lacunasoftware.com/articles/rest-pki/core/requesting-timestamps)) |
| `customSignatureFieldName` | O nome do campo de assinatura do carimbo no PDF. Até 100 caracteres, sem pontos |
| `reason` | O motivo registrado no carimbo. Até 1024 caracteres |
| `visualRepresentation` | A aparência visível do carimbo: veja [abaixo](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/pdf-stamp#a-aparência-visível). Sem ela, o carimbo não aparece nas páginas |
| `forceBlobResult` | Retornar o PDF carimbado como link temporário mesmo quando ele é pequeno (veja [O resultado](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/pdf-stamp#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](https://www.npmjs.com/package/restpki-core-client) chama esta rota com `stampPdf()` e, em Python, a
[restpki-ng-python-client](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/get-started#python) 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](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/get-started#rest).

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:

```json
"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](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/signature-inspection) 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](https://docs.lacunasoftware.com/articles/pki-sdk/signatures/pades/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](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/pdf-stamp#a-aparência-visível).

## Carimbos e marcas em PDF

Um carimbo não é a forma mais nova das marcas em PDF do [Rest PKI](https://docs.lacunasoftware.com/articles/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](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/migrating-from-rest-pki#o-que-o-rest-pki-core-atende)), e as duas fazem
coisas diferentes:

| | Marcas em PDF (`Api/Pdf/AddMarks`) | Carimbo (`api/pdf/stamp`) |
| --- | --- | --- |
| **O que adiciona** | Desenhos nas páginas, sem criptografia | Um carimbo de tempo de documento, com aparência opcional |
| **O que pode desenhar** | Vários elementos por marca, com texto formatado, imagens, QR codes, bordas, fundos e rotação | Uma aparência, com um texto e uma imagem |
| **Onde** | Todas as páginas, uma página (contada do início ou do fim) ou uma nova página | Uma página |
| **Num PDF assinado** | Invalida as assinaturas, a menos que o `abortIfSigned` faça a chamada falhar com `CannotApplyPdfMarks` | Carimba o PDF (veja [PDFs assinados](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/pdf-stamp#pdfs-assinados)) |
| **Carimbo de tempo** | Nenhum | Emitido por um plano de carimbo de tempo |
| **No Rest PKI** | `PdfMarker` | Sem equivalente |

## Veja também

* [Solicitando carimbos de tempo](https://docs.lacunasoftware.com/articles/rest-pki/core/requesting-timestamps)
* [Inspeção de assinaturas](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/signature-inspection)
* [Referenciando arquivos](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/file-referencing)