---
title: "Inspeção de assinaturas - Rest PKI Core"
description: "Abra um arquivo PDF, CMS/CAdES ou XML assinado com PUT api/signature-inspection: liste os signatários e, com validate = true, valide as assinaturas com um contexto de segurança."
canonical: "https://docs.lacunasoftware.com/articles/rest-pki/core/integration/signature-inspection"
locale: "pt-BR"
product: "Rest PKI Core"
last_updated: "2026-10-12"
---

# Inspeção de assinaturas - Rest PKI Core

A API de inspeção de assinaturas abre um arquivo assinado e retorna os signatários: quem assinou, quando, com qual certificado e com qual política
de assinatura. Opcionalmente, ela também valida cada assinatura. Uma única rota atende os três formatos que o [Rest PKI Core](https://docs.lacunasoftware.com/articles/rest-pki/core) assina:

| Arquivo | Assinaturas |
| --- | --- |
| PDF | PAdES |
| CMS (`.p7s`, `.p7m`) | CAdES, anexadas ou destacadas |
| XML | XmlDSig e XAdES |

> **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 inspecionar assinaturas, como **Operador** (veja [Escolhendo os papéis](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/get-started#roles)).

## Inspecionando um arquivo

Envie o arquivo assinado no campo `file`, como uma [referência de arquivo](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/file-referencing):

```text
PUT {endpoint}/api/signature-inspection
{
	"file": {
		"content": "JVBERi0xLjcK...",
		"name": "contrato.pdf",
		"mimeType": "application/pdf"
	},
	"validate": true,
	"securityContextId": "201856ce-273c-4058-a872-8937bd547d36"
}
```

O Rest PKI Core identifica o formato pelo tipo MIME do arquivo: `application/pdf`, `application/xml` ou `text/xml`, ou um tipo que contenha
`pkcs7`, como `application/pkcs7-signature`. Quando a requisição não tem `mimeType`, o Rest PKI Core o deduz da extensão do nome do arquivo, ou do
`Content-Type` de um arquivo referenciado por `url`. Qualquer outro tipo falha com `UnrecognizedSignedFileMimeType`, e um arquivo cujo tipo não pode
ser determinado falha com `MimeTypeRequired`.

A requisição tem estes campos:

| Campo | Descrição |
| --- | --- |
| `file` | O arquivo assinado. Obrigatório |
| `validate` | Se as assinaturas devem ser validadas. Com `false`, o padrão, os signatários são apenas listados |
| `securityContextId` | O [contexto de segurança](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/security-contexts) que decide em quais certificados confiar, ao validar. Se omitido, o Rest PKI Core usa o contexto de segurança padrão da organização ou, sem ele, o da instância. Um ID que não existe falha com `SecurityContextNotFound`, mesmo sem validação |
| `ignoreRevocationStatusUnknown` | Ao validar, aceitar certificados cujo estado de revogação não pode ser determinado. Padrão `false` |
| `trustUncertifiedSigningTime` | Ao validar, tomar a data de assinatura declarada pelo signatário como data de referência, mesmo quando nenhum carimbo de tempo a certifica. Padrão `false` |
| `dataFile`, `dataHashes` | Os dados assinados de uma assinatura CMS destacada: veja [Assinaturas CMS destacadas](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/signature-inspection#assinaturas-cms-destacadas) |
| `extractEncapsulatedContent` | Retornar o conteúdo encapsulado num arquivo CMS. Padrão `false`; ignorado para PDF e XML |

Em Node.js, a biblioteca [restpki-core-client](https://www.npmjs.com/package/restpki-core-client) chama esta rota com `inspectSignature()` e, em
Python, a [restpki-ng-python-client](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/get-started#python) com `SignatureInspectionApi.api_signature_inspection_put()`. As bibliotecas de .NET, Java
e PHP não têm método 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).

### Validação

Com `validate = true`, o Rest PKI Core valida cada assinatura com o contexto de segurança, usando uma política básica para o formato: PAdES básica
para PDF, CAdES-BES para CMS e XmlDSig básica para XML. A requisição não recebe política de assinatura. A validação pode levar alguns segundos ou
mais.

Apenas os 10 primeiros signatários de um arquivo são validados. Na sua própria instância, o limite é a configuração
`General:SignatureInspectionMaxValidations`.

Uma inspeção com `validate = true` é contada como uma transação de **Validação de assinatura**, e uma sem validação como **Inspeção de assinatura**.

### Arquivos assinados nesta instância

Quando o arquivo foi assinado na mesma instância, por exemplo numa [sessão de assinatura](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/signature-sessions), o Rest PKI Core o reconhece e
retorna os signatários como os guardou quando o documento foi assinado, junto com o documento em `document`. Nesse caso, ele não valida as
assinaturas de novo, e o `securityContextId` não é usado.

## Lendo a resposta

Uma resposta resumida, para um PDF com um signatário:

```json
{
	"success": true,
	"signers": [
		{
			"certificate": {
				"subjectName": { "commonName": "JOHN DOE:12345678901" },
				"issuerDisplayName": "AC EXAMPLE"
			},
			"signingTime": "2026-10-12T14:30:00-03:00",
			"signatureFieldName": "Signature1",
			"isDocumentTimestamp": false,
			"validationResults": {
				"passedChecks": [],
				"errors": [],
				"warnings": []
			}
		}
	],
	"document": null
}
```

| Campo | Descrição |
| --- | --- |
| `success` | `false` apenas ao validar uma assinatura CMS destacada sem os dados dela (veja [abaixo](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/signature-inspection#assinaturas-cms-destacadas)) |
| `signers` | Uma entrada por assinatura. Vazio se o arquivo não estiver assinado |
| `document` | O documento, quando o arquivo foi [assinado nesta instância](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/signature-inspection#arquivos-assinados-nesta-instância); senão, `null` |
| `hasEncapsulatedContent`, `encapsulatedContentType`, `encapsulatedContent` | Para um arquivo CMS, se ele encapsula conteúdo e de que tipo; com `extractEncapsulatedContent = true`, também o conteúdo, como referência de arquivo |

Cada signatário traz o `certificate`, a `signingTime` da assinatura, `signaturePolicy`, `timestamps` e `archiveTimestamps` e, em PDFs, o
`signatureFieldName` e se a entrada é um carimbo de tempo de documento (`isDocumentTimestamp`). O `validationResults` traz as verificações que
passaram, os erros e os avisos, e é `null` quando a assinatura não foi validada. Uma assinatura é válida quando o `validationResults` dela não tem
`errors`.

## Assinaturas CMS destacadas

Uma assinatura CMS destacada (`.p7s`) não contém o arquivo que assina. Para validá-la, envie também os dados assinados, de uma de duas formas:

* `dataFile`: o arquivo assinado, como referência de arquivo
* `dataHashes`: os hashes dele, cada um com `algorithm` e `value` (em Base64) ou `hexValue`. Envie pelo menos o hash SHA-256. É a melhor escolha para
  arquivos grandes, já que o arquivo não precisa ser enviado

Se você validar sem enviar nenhum dos dois, a resposta traz `success = false`, `failure = DataFileRequired` e, em `missingDataHash`, o algoritmo do hash
necessário. Isso permite que uma página peça o arquivo assinado ao usuário apenas quando necessário. Sem validação, os signatários são listados sem os dados. `dataFile` e `dataHashes` só são aceitos para
CMS: com um PDF ou um XML, a chamada falha com `DataFileNotSupported`.

## Migrando do Rest PKI

No [Rest PKI](https://docs.lacunasoftware.com/articles/rest-pki/validate-signatures), as assinaturas são abertas com uma rota por formato, por meio dos explorers da biblioteca cliente
(`PadesSignatureExplorer`, `CadesSignatureExplorer` e `XmlSignatureExplorer`). O Rest PKI Core continua atendendo essas rotas (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)). A inspeção de assinaturas é diferente delas:

| | Rotas `Open` do Rest PKI | Inspeção de assinaturas |
| --- | --- | --- |
| **Rota** | Uma por formato: `POST Api/PadesSignatures/Open`, `Api/CadesSignatures/Open`, `Api/XmlSignatures/Open` | Uma para todos os formatos: `PUT api/signature-inspection` |
| **Política de assinatura** | `defaultSignaturePolicyId` e `acceptableExplicitPolicies` | Nenhuma: uma política básica para cada formato |
| **Sem contexto de segurança** | A política de assinatura decide em quem confiar | O contexto de segurança padrão da organização ou da instância |
| **Signatários validados** | Todos no Rest PKI; os 10 primeiros no Rest PKI Core | Os 10 primeiros |
| **CMS destacada sem os dados** | Falha com `MissingDataHash` | `success = false`, `failure = DataFileRequired` |
| **Resposta** | Um modelo por formato | `signers`, igual para todos os formatos, e `document` |

Para validar com uma política de assinatura específica, continue usando as rotas `Open`.

## Veja também

* [Contextos de segurança](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/security-contexts)
* [Referenciando arquivos](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/file-referencing)
* [Carimbos em PDF](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/pdf-stamp)