--- title: "Representação visual PAdES - Rest PKI Core" description: "Defina a aparência visível de uma assinatura PAdES no Rest PKI Core: texto com tags, imagem, posicionamento manual ou automático na página e os presets de posicionamento." canonical: "https://docs.lacunasoftware.com/articles/rest-pki/core/integration/pades-visual-representation" locale: "pt-BR" product: "Rest PKI Core" last_updated: "2026-11-03" --- # Representação visual PAdES - Rest PKI Core A **representação visual** de uma assinatura PAdES é a sua aparência visível no PDF: um texto, uma imagem ou os dois, desenhados dentro de um retângulo em uma das páginas. Ela é opcional: sem ela, a assinatura é **invisível**, mas continua válida, e os leitores de PDF a listam no painel de assinaturas. A representação visual tem três partes: o [texto](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/pades-visual-representation#texto), a [imagem](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/pades-visual-representation#imagem) e a [posição](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/pades-visual-representation#posicao) do retângulo na página. Somente a posição é obrigatória. ```json "visualRepresentation": { "text": { ... }, "image": { ... }, "position": { ... } } ``` > **Dica** > > A partir daqui descreveremos chamadas ao [Rest PKI Core](https://docs.lacunasoftware.com/articles/rest-pki/core). Certifique-se de ter lido o artigo [Primeiros passos](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/get-started) para > acompanhar. ## Onde definir A representação visual faz parte das opções de assinatura de PDF, `pdfSignatureOptions`, no campo `visualRepresentation`: | API | Onde | | --- | --- | | [Sessões de assinatura](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/signature-sessions): `POST {endpoint}/api/signature-sessions` | `pdfSignatureOptions.visualRepresentation`, que vale para todos os PDFs assinados na sessão | | Sessões de assinatura, [documentos predefinidos](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/signature-sessions#predefined-documents) | `documents[].pdfSignatureOptions.visualRepresentation`, para um documento | | [Assinaturas em duas etapas](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/two-step-signatures): `POST {endpoint}/api/signature` | `pdfSignatureOptions.visualRepresentation` | | [Carimbos em PDF](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/pdf-stamp): `POST {endpoint}/api/pdf/stamp` | `visualRepresentation`, no nível principal da requisição. Usa o mesmo modelo descrito aqui, mas as tags do texto não são substituídas: não há signatário, então elas permanecem como foram escritas | > **Observação** > > Quando um documento predefinido de uma sessão de assinatura tem `pdfSignatureOptions` próprio, ele **substitui** por completo o `pdfSignatureOptions` da > sessão: os dois não são combinados, então repita o `visualRepresentation` no documento. A exceção é `convertToPdfA`, que o documento herda da sessão > (veja [Conversão para PDF/A](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/signature-sessions/pdf-a-conversion)). As APIs legadas do [Rest PKI](https://docs.lacunasoftware.com/articles/rest-pki) que o Rest PKI Core ainda atende (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)) usam o mesmo modelo no campo `visualRepresentation` da requisição. ## Texto O objeto `text` desenha um texto no retângulo: | Campo | Descrição | | --- | --- | | `text` | O texto, que pode ter `{{tags}}` (veja [abaixo](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/pades-visual-representation#tags)) e quebras de linha. **Obrigatório** sempre que `text` é enviado: um objeto `text` sem ele falha | | `includeSigningTime` | Quando `true`, acrescenta uma linha com o horário da assinatura, formatado com as configurações de data e hora da organização. Padrão: `false` | | `fontSize` | O tamanho **máximo** da fonte, em pontos: o texto diminui, quando necessário, para caber no retângulo. Padrão: 12 | | `horizontalAlign` | `Left` (padrão) ou `Right` | | `container` | A região do retângulo da assinatura onde o texto é desenhado, como um [retângulo](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/pades-visual-representation#retangulos) relativo ao retângulo da assinatura (e não à página). Se omitido, o texto pode usar todo o retângulo da assinatura. O texto é alinhado ao topo da região | Por exemplo, para deixar uma margem de 0,2 em volta do texto: ```json "text": { "text": "Assinado digitalmente por {{name}}", "fontSize": 9, "includeSigningTime": true, "horizontalAlign": "Left", "container": { "left": 0.2, "top": 0.2, "right": 0.2, "bottom": 0.2 } } ``` ### Tags Em uma assinatura, as tags em `text` são substituídas por dados do certificado do signatário (em um [carimbo](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/pdf-stamp), elas permanecem como foram escritas). Elas diferenciam maiúsculas de minúsculas, e uma tag desconhecida permanece no texto como foi escrita. As mais usadas: | Tag | Valor | | --- | --- | | `{{name}}` | O nome completo do signatário | | `{{national_id}}` | O número de identidade nacional do signatário (em certificados ICP-Brasil, o CPF do titular) | | `{{email}}` | O endereço de e-mail do signatário | | `{{issuer_cn}}` | O nome comum (CN) do emissor do certificado | | `{{br_cpf_formatted}}` | O CPF do titular, formatado como 000.000.000-00 (certificados ICP-Brasil) | | `{{br_cpf_masked}}` | O CPF do titular, mascarado (certificados ICP-Brasil) | Veja a [lista completa de tags](https://docs.lacunasoftware.com/articles/rest-pki/pades-tags), que são as mesmas do Rest PKI. ## Imagem O objeto `image` desenha uma imagem no retângulo, atrás do texto: | Campo | Descrição | | --- | --- | | `resource` | A imagem, como `url` (um link de onde o servidor baixa a imagem; a imagem fica em cache por cerca de 5 minutos) ou `content` (os bytes em Base64). Um dos dois é obrigatório, e `content` prevalece quando os dois são enviados | | `opacity` | De 0 a 100. Padrão: 100 | | `horizontalAlign` | `Left`, `Center` (padrão) ou `Right` | | `verticalAlign` | `Top`, `Center` (padrão) ou `Bottom` | A imagem é redimensionada para caber no retângulo, mantendo a proporção. Quando o retângulo é mais largo que a imagem redimensionada, quem a posiciona é `horizontalAlign`; caso contrário, é `verticalAlign`. ```json "image": { "resource": { "url": "https://example.com/seal.png" }, "opacity": 40, "horizontalAlign": "Right", "verticalAlign": "Center" } ``` ## Posição O objeto `position` diz em que página a assinatura fica e em que lugar dela. Ele tem a página, a unidade de medida e **uma** das duas formas de escolher o retângulo: `manual` ou `auto`. | Campo | Descrição | | --- | --- | | `pageNumber` | A página: 1 é a primeira página; números negativos contam a partir do fim (-1 é a última página); 0 acrescenta uma nova página ao final do PDF, mas somente se o PDF ainda não tiver assinatura visível (caso contrário, usa a última página). Se omitido, vale 0. Um número de página além do número de páginas faz a assinatura falhar | | `measurementUnits` | `Centimeters` ou `PdfPoints` (1/72 de polegada). Se omitido, usa-se o valor de `measurementUnits` em `pdfSignatureOptions` e, sem ele, `Centimeters`. Vale para todas as medidas da posição e para o `container` do texto | | `manual` | Um retângulo fixo na página: veja [Posicionamento manual](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/pades-visual-representation#manual) | | `auto` | Uma região da página onde as assinaturas são colocadas uma após a outra: veja [Posicionamento automático](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/pades-visual-representation#auto) | | `pageOptimization` | Obsoleto. Também existe em `pdfSignatureOptions`, e o da posição tem precedência. As medidas em centímetros são escalonadas para um tamanho de papel de referência que o Rest PKI Core estima a partir das proporções da página (Letter, Legal ou, caso contrário, A4), a menos que `pageOptimization` informe o tamanho do papel (`paperSize`, como `A4` ou `Letter`, ou `Custom` com `customPaperSize`) e a orientação (`pageOrientation`). Assim, em páginas de tamanho fora do padrão, como A3, os tamanhos acompanham a página: para ter tamanhos absolutos, use `PdfPoints` | Se `manual` e `auto` forem enviados juntos, vale `auto`. Se nenhum dos dois for, a assinatura falha. ### Retângulos Os retângulos, como o retângulo de `manual`, o container de `auto` e o `container` do texto, são definidos pelos parâmetros `left`, `top`, `right`, `bottom`, `width` e `height`, que são margens relativas ao que contém o retângulo (a página ou o retângulo da assinatura). Você não preenche todos: o que você define decide como o retângulo se comporta. ![Parâmetros do retângulo](https://docs.lacunasoftware.com/images/pki-sdk/pades-rectangle.png) O retângulo, em vermelho, tem as suas margens relativas ao que o contém. Não defina `left`, `right` e `width` juntos: na horizontal, dois dos três (ou só `width`) bastam, e o resto ocupa o espaço restante. Na vertical funciona do mesmo jeito, com `top`, `bottom` e `height` no lugar de `left`, `right` e `width`. Os exemplos abaixo mostram as formas de definir as dimensões horizontais. Para saber mais sobre como os retângulos funcionam, veja [Definindo um container](https://docs.lacunasoftware.com/articles/pki-sdk/signatures/pades/visual-rep/containers), do PKI SDK. #### Fluido Se você define apenas `left` e `right`, o retângulo mantém as duas margens e a largura se estica para preencher o espaço restante. ![Retângulo fluido](https://docs.lacunasoftware.com/images/pki-sdk/fluid.png) #### Ancorado à esquerda Se você define apenas `left` e `width`, o retângulo mantém a margem esquerda e a largura. A margem direita ocupa o espaço restante. ![Retângulo ancorado à esquerda](https://docs.lacunasoftware.com/images/pki-sdk/left-anchored.png) #### Ancorado à direita Se você define apenas `right` e `width`, o retângulo mantém a margem direita e a largura. A margem esquerda ocupa o espaço restante. ![Retângulo ancorado à direita](https://docs.lacunasoftware.com/images/pki-sdk/right-anchored.png) #### Centralizado Se você define apenas `width`, o retângulo é centralizado horizontalmente com a largura dada. ![Retângulo centralizado](https://docs.lacunasoftware.com/images/pki-sdk/centered.png) ### Posicionamento manual Em `manual`, o retângulo da assinatura é fixo, relativo à página. Por exemplo, um retângulo de 7 por 3 cm, com margem de 2,5 cm das bordas esquerda e inferior: ```json "position": { "pageNumber": 1, "measurementUnits": "Centimeters", "manual": { "left": 2.5, "bottom": 2.5, "width": 7, "height": 3 } } ``` ![Posicionamento manual](https://docs.lacunasoftware.com/images/pki-sdk/pades-visual-rep-manual-pos.png) ### Posicionamento automático Em `auto`, você define um **container**, uma região da página, e o tamanho de cada assinatura, e o Rest PKI Core coloca as assinaturas uma após a outra dentro do container. Serve para documentos com vários signatários, já que você não sabe a posição de cada um. ![Posicionamento automático: o container e o retângulo da assinatura](https://docs.lacunasoftware.com/images/pki-sdk/auto-positioning.png) | Campo | Descrição | | --- | --- | | `container` | A região da página que recebe as assinaturas, como um [retângulo](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/pades-visual-representation#retangulos). Obrigatório | | `signatureRectangleSize` | A largura (`width`) e a altura (`height`) do retângulo de cada assinatura. Obrigatório | | `rowSpacing` | O espaço entre as linhas. Padrão: 0 | | `horizontalDirection` | `LeftToRight` (padrão) ou `RightToLeft`: a direção em que uma linha é preenchida | | `verticalDirection` | `TopDown` (padrão) ou `BottomUp`: a direção em que as linhas se empilham | Para escolher a posição de uma assinatura, o Rest PKI Core olha a última assinatura **visível** que já está na página, não importa quem a fez nem com qual ferramenta. Se a linha ainda tiver espaço para outro retângulo do mesmo tamanho, a nova assinatura vai para essa linha. Caso contrário, vai para uma nova linha, abaixo (`TopDown`) ou acima (`BottomUp`) da anterior, separada dela por `rowSpacing`. Cabem em uma linha tantas assinaturas quanto o número inteiro de vezes que a largura da assinatura cabe na largura do container. As linhas são justificadas: as colunas de uma linha se distribuem por igual pela largura do container, a primeira encostada em uma borda e a última na outra, então há espaços entre as assinaturas (cerca de 0,73 cm com o preset `Footnote`, em A4 em retrato). ![Posicionamento automático: as assinaturas dentro do container](https://docs.lacunasoftware.com/images/pki-sdk/visual-rep-result.png) > **Aviso** > > Quando o container está cheio, a assinatura é feita mesmo assim, mas **sem representação visual**, e nenhum erro é retornado. Dimensione o container para > o número de signatários esperado. O Rest PKI Core não procura espaços livres no container nem confere o restante do conteúdo da página. ### Presets Os presets devolvem um objeto `position` com a geometria usual, pronto para ser usado como está, no campo `position` da representação visual. São rotas `GET` que não precisam de autenticação: | Rota | Parâmetros | Posição | | --- | --- | --- | | `GET {endpoint}/Api/PadesVisualPositioningPresets/Footnote` | `pageNumber` (padrão -1, a última página); `rows` (padrão 1) | Um rodapé: as assinaturas ficam no fim da página, em um container com margens de 1 cm à esquerda, à direita e embaixo e altura para o número de linhas dado, preenchido de cima para baixo, da esquerda para a direita | | `GET {endpoint}/Api/PadesVisualPositioningPresets/FootnoteBottomUp` | `pageNumber` (padrão -1, a última página) | O container é a página inteira, menos uma margem de 1 cm em cada lado, e as linhas se empilham de baixo para cima | | `GET {endpoint}/Api/PadesVisualPositioningPresets/NewPage` | Nenhum | As assinaturas vão em uma nova página, com margem de 1 cm, como em `pageNumber` 0 | Os três presets usam retângulos de assinatura de 4,2 x 1,8 cm, com espaço de 0,3 cm entre as linhas. Em uma página A4 em retrato, isso dá 4 assinaturas por linha. Por exemplo, `GET {endpoint}/Api/PadesVisualPositioningPresets/Footnote?pageNumber=-1&rows=2` devolve uma posição para duas linhas de assinaturas no fim da última página, o que comporta até 8 assinaturas em A4 em retrato. ## Exemplos ### Rodapé com uma única linha As assinaturas ficam no fim da última página, em uma única linha: em A4 em retrato, até 4 assinaturas. É o preset `Footnote` com uma linha, com texto e imagem. Em uma sessão de assinatura: ```text POST {endpoint}/api/signature-sessions { ... "pdfSignatureOptions": { "visualRepresentation": { "text": { "text": "Assinado digitalmente por {{name}}\nCPF: {{br_cpf_formatted}}", "fontSize": 9, "includeSigningTime": true, "horizontalAlign": "Left", "container": { "left": 0.2, "top": 0.2, "right": 0.2, "bottom": 0.2 } }, "image": { "resource": { "url": "https://example.com/seal.png" }, "opacity": 40, "horizontalAlign": "Right", "verticalAlign": "Center" }, "position": { "pageNumber": -1, "measurementUnits": "Centimeters", "auto": { "container": { "left": 1.0, "right": 1.0, "bottom": 1.0, "height": 1.8 }, "signatureRectangleSize": { "width": 4.2, "height": 1.8 }, "rowSpacing": 0.3, "horizontalDirection": "LeftToRight", "verticalDirection": "TopDown" } } } } } ``` Um quinto signatário não teria representação visual: veja o [aviso acima](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/pades-visual-representation#auto). Os PKI Suite Samples usam esse tipo de representação visual, com posicionamento automático na última página e um retângulo de assinatura maior: * [.NET](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/dotnet/spa/PkiSuiteAspNetCoreAngularSample/PkiSuiteAspNetCoreAngularSample.Server/Classes/PadesVisualElements.cs) * [Java](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/java/springmvc/src/main/java/com/lacunasoftware/pkisuite/util/restpkicore/PadesVisualElements.java) * [Node.js](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/nodejs/expressmvc/pades-visual-elements-core.js) * [PHP](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/php/plain/public/pades-signature-rest-core/start.php) * [Python](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/python/flask/sample/views/pades_signature_rest_core.py) * [Ruby](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/ruby/rails/app/controllers/pades_signature_rest_core_controller.rb) ### Duas linhas, para até 8 signatários Para duas linhas, a altura do container é a altura de duas linhas mais o espaço entre elas: 2 x 1,8 + 0,3 = 3,9 cm. O restante é igual ao exemplo anterior, então só a `position` é mostrada: ```json "position": { "pageNumber": -1, "measurementUnits": "Centimeters", "auto": { "container": { "left": 1.0, "right": 1.0, "bottom": 1.0, "height": 3.9 }, "signatureRectangleSize": { "width": 4.2, "height": 1.8 }, "rowSpacing": 0.3, "horizontalDirection": "LeftToRight", "verticalDirection": "TopDown" } } ``` ### Um retângulo fixo, em uma assinatura em duas etapas Uma assinatura em uma posição fixa da primeira página, só com o texto: ```text POST {endpoint}/api/signature { "file": { "content": "JVBERi0x...", "name": "document.pdf" }, "certificate": { "content": "MIIG..." }, "signatureType": "Pdf", "pdfSignatureOptions": { "visualRepresentation": { "text": { "text": "Assinado por {{name}}", "includeSigningTime": true }, "position": { "pageNumber": 1, "measurementUnits": "Centimeters", "manual": { "left": 2.5, "bottom": 2.5, "width": 7, "height": 3 } } } } } ``` ## No .NET O cliente .NET não tem auxiliares dedicados para a representação visual: você a monta com os modelos da API, no namespace `Lacuna.RestPki.Api.PadesSignature`, e a define na propriedade `VisualRepresentation` de `PdfSignatureOptions` (ou de `StampPdfOptions`, em um carimbo). As classes são `PadesVisualRepresentationModel`, com `PadesVisualTextModel`, `PadesVisualImageModel` (cujo `Resource` é um `ResourceContentOrReference`) e `PadesVisualPositioningModel`, que por sua vez tem um `PadesVisualAutoPositioningModel` ou, no posicionamento manual, um `PadesVisualRectangleModel`. As propriedades têm os nomes dos campos JSON descritos acima, em PascalCase. Veja como o [exemplo em .NET](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/dotnet/spa/PkiSuiteAspNetCoreAngularSample/PkiSuiteAspNetCoreAngularSample.Server/Classes/PadesVisualElements.cs) monta uma. ## Veja também * [Assinaturas em duas etapas](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/two-step-signatures) * [Sessões de assinatura](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/signature-sessions) * [Carimbos em PDF](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/pdf-stamp) * [Tags da representação visual](https://docs.lacunasoftware.com/articles/rest-pki/pades-tags) * [Marcas de validação em PDF](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/pdf-marking), que não fazem parte da representação visual de uma assinatura