---
title: "Migração do Rest PKI para o Rest PKI Core"
description: "Leve uma aplicação do Rest PKI (pki.rest) ao Rest PKI Core: quais APIs do Rest PKI o Rest PKI Core atende como estão, o que muda e as APIs mais novas a adotar."
canonical: "https://docs.lacunasoftware.com/articles/rest-pki/core/integration/migrating-from-rest-pki"
locale: "pt-BR"
product: "Rest PKI Core"
last_updated: "2026-10-12"
---

# Migração do Rest PKI para o Rest PKI Core

O [Rest PKI](https://docs.lacunasoftware.com/articles/rest-pki), serviço em nuvem em [pki.rest](https://pki.rest/), é um produto legado: continua recebendo correções de
bugs e de segurança, mas novas integrações em nuvem devem usar o [Rest PKI Core](https://docs.lacunasoftware.com/articles/rest-pki/core). Este guia é para uma aplicação já integrada ao
Rest PKI que passa a usar o Rest PKI Core, na instância SaaS em [core.pki.rest](https://core.pki.rest/) ou numa
[instância própria](https://docs.lacunasoftware.com/articles/rest-pki/core/on-premises).

O Rest PKI Core atende à maioria das APIs do Rest PKI, por isso a migração pode acontecer em duas etapas:

1. **Aponte a aplicação para o Rest PKI Core.** As APIs do Rest PKI que ele atende mantêm as mesmas rotas e os mesmos modelos: o seu código muda
   onde obtém o endpoint e a credencial, onde as suas páginas inicializam o Web PKI e, se você criou contextos de segurança próprios, onde os
   cita. Veja [Usando o seu código como está](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/migrating-from-rest-pki#usando-o-seu-código-como-está).
1. **Adote as APIs mais novas, no seu ritmo.** As [sessões de assinatura](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/signature-sessions), as
   [assinaturas em duas etapas](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/two-step-signatures) e a [autenticação com certificado](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/cert-auth) substituem os fluxos de assinatura e de
   autenticação do Rest PKI, com páginas de assinatura hospedadas, webhooks e bibliotecas cliente mais novas. Veja
   [Migrando para as APIs mais novas](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/migrating-from-rest-pki#migrando-para-as-apis-mais-novas).

Algumas APIs do Rest PKI não têm equivalente no Rest PKI Core: confira
[O que o Rest PKI Core não atende](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/migrating-from-rest-pki#o-que-o-rest-pki-core-não-atende) antes de começar.

## Antes de começar

* **Obtenha acesso a uma instância.** Na instância SaaS, peça acesso ao [suporte ao desenvolvedor](mailto:suporte@lacunasoftware.com) se a sua
  organização ainda não o tiver; para uma instância própria, veja [Rest PKI Core on-premises](https://docs.lacunasoftware.com/articles/rest-pki/core/on-premises).
* **Crie uma aplicação e uma chave de API** no dashboard da instância, com o papel **Operador**. O Operador cobre todas as APIs do Rest PKI que o
  Rest PKI Core atende: assinaturas, autenticação com certificado, carimbos de tempo, marcas em PDF e inspeção de assinaturas. Veja
  [Crie uma chave de API](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/get-started#create-api-key).
* **Preveja a licença do Web PKI.** Com o Rest PKI em pki.rest, o Web PKI não precisa de licença, nem em produção. Com o Rest PKI Core, precisa,
  tanto na instância SaaS quanto numa instância própria. Veja [Licenciamento](https://docs.lacunasoftware.com/articles/welcome/licensing#rest-pki-core).

## Usando o seu código como está

### O que o Rest PKI Core atende

O Rest PKI Core responde a estas rotas do Rest PKI com os modelos de requisição e de resposta do Rest PKI:

| Funcionalidade do Rest PKI | Rotas |
| --- | --- |
| Assinatura PAdES | `POST Api/PadesSignatures`, `Api/v2/PadesSignatures`, `Api/PadesSignatures/{token}/SignedBytes`, `Api/PadesSignatures/{token}/Finalize`, `Api/v2/PadesSignatures/{token}/SignedBytes` |
| Assinatura CAdES, inclusive a coassinatura | `POST Api/CadesSignatures`, `Api/v2/CadesSignatures`, `Api/v3/CadesSignatures`, `Api/CadesSignatures/{token}/SignedBytes`, `Api/CadesSignatures/{token}/Finalize`, `Api/v2/CadesSignatures/{token}/SignedBytes`, `Api/CadesSignatures/RequiredHashes` |
| Assinatura XML do documento inteiro ou de um elemento | `POST Api/XmlSignatures/FullXmlSignature`, `Api/XmlSignatures/XmlElementSignature`, `Api/XmlSignatures/{token}/SignedBytes`, `Api/XmlSignatures/{token}/Finalize` |
| Abertura e validação de assinaturas | `POST Api/PadesSignatures/Open`, `Api/CadesSignatures/Open`, `Api/XmlSignatures/Open`, `Api/v2/XmlSignatures/Open` |
| Autenticação com certificado | `POST Api/Authentications`, `Api/Authentications/{token}/Finalize`, `Api/Authentications/{token}/SignedBytes`; `GET` e `POST Api/Authentication` |
| Abertura de um certificado | `POST Api/Certificates/Open` |
| Marcas em PDF (versões para impressão) | `POST Api/Pdf/AddMarks` |
| Posicionamentos predefinidos da representação visual | `GET Api/PadesVisualPositioningPresets/Footnote`, `.../FootnoteBottomUp`, `.../NewPage` |
| Upload de arquivos grandes | `POST Api/MultipartUploads`, `Api/MultipartUploads/{token}/{partNumber}`, `Api/MultipartUploads/{token}` |
| Carimbos de tempo | `POST tsp/{id}` (protocolo TSP) e `POST Api/TimestampPlans/{id}/Issue` |
| Assinatura no navegador com o `signWithRestPki()` do Web PKI | `GET` e `POST Api/PendingSignatures/{token}`, `POST Api/PendingSignatures/{token}/Certificate` (chamadas pelo Web PKI, não pelo seu código) |

As mesmas políticas de assinatura padrão estão disponíveis, com os mesmos IDs, como `StandardPadesSignaturePolicies.PkiBrazil.AdrBasica` e
`StandardCadesSignaturePolicies.PkiBrazil.AdrArquivamento`, assim como as tags da representação visual do PDF, como `{{name}}` e
`{{br_cpf_formatted}}` (veja [Tags PAdES](https://docs.lacunasoftware.com/articles/rest-pki/pades-tags)). O `callbackArgument` de uma assinatura também volta quando ela é
concluída.

### O que muda

| | Rest PKI | Rest PKI Core |
| --- | --- | --- |
| **Endpoint** | `https://pki.rest/` ou a sua instância on-premises | `https://core.pki.rest/` na instância SaaS ou o endereço do dashboard da sua instância |
| **Credencial** | Um token de acesso, gerado no **Painel de Controle** em pki.rest | Uma chave de API de uma aplicação com o papel **Operador**, criada no dashboard da instância |
| **Header** | `Authorization: Bearer <token de acesso>` | `X-Api-Key: <chave de API>`; `Authorization: Bearer <chave de API>` também é aceito, por isso uma biblioteca cliente que envia o token de acesso como token de portador funciona quando recebe a chave de API no lugar dele |
| **Web PKI** | Chama `https://restpki.lacunasoftware.com/` por padrão | Passe o endpoint do Rest PKI Core ao `init()` como `restPkiUrl` (veja abaixo) |
| **Licença do Web PKI** | Não é necessária com o pki.rest | Necessária |
| **Datas nas assinaturas de PDF** | **Região e Data** na sua conta | **Configurações** > **Região e Data** no dashboard |

Se as suas páginas assinam com o `signWithRestPki()` do Web PKI, como os exemplos do Rest PKI, o Web PKI obtém a assinatura pendente na própria
instância do Rest PKI. Informe a ele onde está o Rest PKI Core:

```javascript
pki.init({
	restPkiUrl: 'https://core.pki.rest/', // o endpoint da sua instância do Rest PKI Core
	ready: onWebPkiReady,
});
```

### Bibliotecas cliente

As bibliotecas cliente do Rest PKI enviam o token de acesso como `Authorization: Bearer`, e o Rest PKI Core aceita uma chave de API enviada
dessa forma; por isso, a aplicação pode manter de início a biblioteca do Rest PKI e só passar a ela o novo endpoint e a chave de API. As
bibliotecas do Rest PKI Core variam de linguagem para linguagem:

| Linguagem | Rest PKI | Rest PKI Core | O que a biblioteca do Rest PKI Core traz |
| --- | --- | --- | --- |
| .NET | `Lacuna.RestPki.Client` | `Lacuna.RestPkiCore.Client` 5.0.0 | Depende do `Lacuna.RestPki.Client` 5.0.0 e usa o mesmo namespace, `Lacuna.RestPki.Client`: ao adicioná-la, você mantém o `RestPkiClient`, os starters, finishers e explorers, o `Authentication` e o `PdfMarker`, ao lado do `IRestPkiService` para as APIs mais novas. As duas têm como alvo o .NET Standard 2.0 |
| Java | `com.lacunasoftware.restpki:restpki-client` | `com.lacunasoftware.restpki:restpkicore-client` 1.4.0 | Um pacote novo, `com.lacunasoftware.restpkicore`, sem as classes do Rest PKI. O `RestPkiService` dele tem métodos para as rotas do Rest PKI, como `startPadesSignature()`, `completePadesSignature()`, `startCadesSignature()`, `startFullXmlSignature()` e `addPdfMarks()`, além das APIs mais novas. As duas exigem o Java 8 |
| PHP | `lacuna/restpki-client` | `lacuna/restpkicore-client` 1.2.1 | Exige o `lacuna/restpki-client` ^2.7.0 e usa o mesmo namespace, `Lacuna\RestPki`, por isso as classes do Rest PKI continuam disponíveis. O `RestPkiService` dela cobre as sessões de assinatura e os documentos; o exemplo em PHP chama as rotas da assinatura em duas etapas pelo `getRestClient()->post()`, já que a biblioteca não tem método para elas |
| Node.js | `restpki-client` | `restpki-core-client` 1.0.2 | Classes geradas a partir da API para cada grupo de rotas, inclusive as do Rest PKI (`PadesSignatureApi`, `CadesSignatureApi`, `XmlSignatureApi`, `PdfApi`, `TimestampApi`, `AuthenticationApi`) e as mais novas (`SignatureApi`, `SignatureSessionsApi`, `DocumentsApi`, `SignatureInspectionApi`), por trás de um `RestPkiCoreClient` criado com `baseUrl` e `apiKey`. Não tem starters nem finishers |
| Python | `restpki-client` | `restpki-ng-python-client`, usado pelo exemplo em Python (0.9.1.1) | — |
| Ruby | `rest_pki` | Nenhuma: o exemplo em Ruby chama a API REST diretamente | — |

Em .NET, o cliente do Rest PKI a partir da 2.2.0 compartilha os números de versão com o `Lacuna.RestPkiCore.Client` e tem como alvo apenas o
.NET Standard 2.0; uma aplicação na 1.24.1 (.NET Framework 3.5 a 4.6) precisa atualizar antes. Veja
[.NET](https://docs.lacunasoftware.com/articles/rest-pki/dotnet#versões-e-plataformas-suportadas) na documentação do Rest PKI. Para configurar a biblioteca do Rest PKI Core
para as APIs mais novas, veja [Primeiros passos](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/get-started#calling-the-api).

TODO(docs): nenhuma página diz se as bibliotecas cliente do Rest PKI para Java, PHP, Node.js, Python e Ruby têm suporte com o Rest PKI Core, e a
biblioteca Python `restpki-ng-python-client` não está documentada em nenhum lugar.

### Contextos de segurança

O Rest PKI Core cria os contextos de segurança padrão em toda instância, com os mesmos IDs do Rest PKI; por isso, o código que passa
`StandardSecurityContexts.PkiBrazil` ou `StandardSecurityContexts.LacunaTest` funciona sem mudanças:

| Contexto de segurança | ID |
| --- | --- |
| `PkiBrazil` (ICP-Brasil) | `201856ce-273c-4058-a872-8937bd547d36` |
| `PkiItaly` | `c438b17e-4862-446b-86ad-6f85734f0bfe` |
| `WindowsServer` | `3881384c-a54d-45c5-bbe9-976b674f5ec7` |
| `LacunaTest` (ICP de testes da Lacuna, só para desenvolvimento) | `803517ad-3bbc-4169-b085-60053a8f6dbf` |

O Rest PKI Core acrescenta `PkiBrazilExtended`, `GovBR`, `PkiBrazilWithENotariado` e `PkiBrazilWithGovBrAndENotariado`.

Um contexto de segurança que você mesmo criou no Rest PKI não é levado: crie-o de novo no Rest PKI Core, onde os usuários com o papel **Gerente**
ou **Administrador** gerenciam os contextos de segurança da organização, e use o novo ID. Você também pode escolher um
**Contexto de segurança padrão** para a organização, em **Configurações** > **Configurações gerais**, que o Rest PKI Core usa quando uma chamada
não cita nenhum.

TODO(docs): nenhuma página descreve como gerenciar os contextos de segurança no dashboard do Rest PKI Core.

### Testes com a ICP de testes da Lacuna

Os [certificados de teste](https://docs.lacunasoftware.com/articles/pki-guide/test-certs) funcionam como no Rest PKI: cite o contexto de segurança `LacunaTest` nas chamadas,
apenas em desenvolvimento. Ao contrário de uma instância on-premises do Rest PKI, em que talvez seja preciso criá-lo antes, toda instância do
Rest PKI Core o cria ao iniciar. Veja [Rest PKI Core](https://docs.lacunasoftware.com/articles/pki-guide/test-certs#rest-pki-core) na página de certificados de teste.

TODO(docs): nenhuma página descreve uma sandbox ou um ambiente de testes da instância SaaS, nem chaves de API de teste para ela.

### Carimbos de tempo

No Rest PKI Core, os carimbos de tempo vêm de **tiers** (níveis) em vez de planos. O tier `PkiBrazil` (ICP-Brasil) tem o ID do plano do Rest PKI,
`a402df41-8559-47b2-a05c-be555bf66310` (`StandardTimestampPlans.PkiBrazil`); por isso, `tsp/a402df41-8559-47b2-a05c-be555bf66310` e
`Api/TimestampPlans/a402df41-8559-47b2-a05c-be555bf66310/Issue` continuam funcionando numa instância em que esse tier está habilitado, como a
instância SaaS. Essas rotas também aceitam o nome do tier em vez do ID, como `tsp/PkiBrazil`, e o Rest PKI Core acrescenta `api/tsp/{tier}`, em
que o header documentado é `Authorization: ApiKey <chave de API>`. Veja [Requisitando carimbos de tempo](https://docs.lacunasoftware.com/articles/rest-pki/core/requesting-timestamps).

## O que o Rest PKI Core não atende

* **Assinaturas XML de recursos destacados ou online**: `Api/XmlSignatures/DetachedResourceXmlSignature` e
  `Api/XmlSignatures/OnlineResourceXmlSignature` (em .NET, `DetachedResourceXmlSignatureStarter` e `OnlineResourceXmlSignatureStarter`) não foram
  portadas. O código-fonte pede a quem precisar delas que avise a Lacuna: escreva ao
  [suporte ao desenvolvedor](mailto:suporte@lacunasoftware.com).
* **APIs de conta e de gerenciamento**: gerar tokens de acesso, gerenciar contextos de segurança, listar políticas de assinatura, planos de
  carimbo de tempo e transações pelas rotas do Rest PKI (`Api/Account`, `Api/SecurityContexts`, `Api/SignaturePolicies`, `Api/TimestampPlans`,
  `Api/Transactions`, `Api/Users` e outras). O Rest PKI Core tem dashboard e APIs próprios para isso.
* **Rotas de informações do sistema** além de `api/system/info`, como `Api/System/Cultures`, `Api/System/TimeZones` e `Api/System/Date`.

As observações da API de assinatura XML no código-fonte também citam `Api/XmlSignatures/Open` como não portada, mas o Rest PKI Core 5.0.5 a
atende, junto com `Api/v2/XmlSignatures/Open`.

## Migrando para as APIs mais novas

Quando a aplicação estiver rodando no Rest PKI Core, substitua cada fluxo do Rest PKI pelo equivalente mais novo quando for conveniente:

| Com o Rest PKI | Com o Rest PKI Core | Veja |
| --- | --- | --- |
| Iniciar uma assinatura PAdES, CAdES ou XML, assinar com o `signWithRestPki()` do Web PKI na sua página e concluí-la | Criar uma sessão de assinatura e redirecionar o usuário à página de assinatura hospedada pelo Rest PKI Core, que usa o Web PKI ou certificados em nuvem; obter os documentos assinados pela API ou por um webhook | [Sessões de assinatura](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/signature-sessions) |
| O mesmo, mantendo a página de assinatura na sua aplicação | Preparar a assinatura, assinar o hash com o `signHash()` do Web PKI na sua página e concluí-la | [Assinaturas em duas etapas](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/two-step-signatures#na-sua-própria-página-com-o-web-pki) |
| Assinar com uma chave guardada no servidor (os exemplos *server key*) | Preparar a assinatura, assinar o hash no servidor e concluí-la | [Assinaturas em duas etapas](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/two-step-signatures#no-seu-servidor) |
| `Authentication`: `StartWithWebPkiAsync()`, `signWithRestPki()`, `CompleteWithWebPkiAsync()` | Preparar a autenticação, assinar o hash com o `signHash()` do Web PKI e concluí-la; o estado fica na sua página, e nonces reutilizados são rejeitados | [Autenticação com certificado](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/cert-auth) |
| Abrir e validar assinaturas (`PadesSignatureExplorer`, `CadesSignatureExplorer`, `XmlSignatureExplorer`) | Inspeção de assinaturas, `PUT api/signature-inspection`, com `validate = true` para validar | [Referência da API](https://core.pki.rest/swagger) |
| Adicionar marcas a um PDF (`PdfMarker`) | `POST api/pdf/stamp` | [Referência da API](https://core.pki.rest/swagger) |
| Requisitar um carimbo de tempo | `POST api/tsp/{tier}` | [Requisitando carimbos de tempo](https://docs.lacunasoftware.com/articles/rest-pki/core/requesting-timestamps) |

TODO(docs): nenhuma página descreve a API de inspeção de assinaturas (`api/signature-inspection`) nem a API de carimbo em PDF (`api/pdf/stamp`) do
Rest PKI Core, nem como um carimbo se compara às marcas em PDF do Rest PKI.

As APIs mais novas também trazem o que o Rest PKI não tem: [webhooks](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/webhooks),
[requisitos de certificado](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/signature-sessions/certificate-requirements), [conversão para PDF/A](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/signature-sessions/pdf-a-conversion),
[processamento em segundo plano](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/signature-sessions/background-processing) e códigos de verificação nos documentos assinados.

## Comparando os exemplos

Os projetos [PkiSuiteSamples](https://github.com/LacunaSoftware/PkiSuiteSamples) têm versões para o Rest PKI e para o Rest PKI Core de alguns
exemplos, lado a lado, que mostram a mesma funcionalidade antes e depois da migração:

| Funcionalidade | Exemplo do Rest PKI | Exemplo do Rest PKI Core |
| --- | --- | --- |
| Assinatura PAdES na sua página com o Web PKI | `PadesSignatureRestController` (.NET, Java), `pades-signature-rest` (PHP), `pades-signature-restpki.js` (Node.js) | `PadesSignatureRestCoreController` (.NET), `PadesSignatureCoreController` (Java), `pades-signature-rest-core` (PHP), `pades-signature-core.js` (Node.js), `pades_signature_rest_core.py` (Python, Flask), `pades_signature_rest_core_controller.rb` (Ruby) |
| Lote de assinaturas PAdES | `batch-pades-signature-restpki.js` (Node.js) | `batch-pades-signature-core.js` (Node.js) |
| Autenticação com certificado | `AuthenticationRestController` (.NET, Java) | `AuthenticationRestPkiCoreController` (Java) |
| Assinatura PAdES com uma chave no servidor | `pades-server-key-rest` (PHP) | `PadesServerKeyRestCoreController` (.NET) |
| Página de assinatura hospedada | — | `SignatureSessionRestCoreController` e `SignatureSessionPreDefRestCoreController` (.NET, Java), `signature-session-rest-core` (PHP), com `WebhookRestCoreController` (.NET, Java) e `webhook-rest-core` (PHP) |

Nas páginas, os exemplos do Rest PKI chamam o `signWithRestPki()` do Web PKI com o token; os exemplos do Rest PKI Core leem o certificado com o
`readCertificate()`, enviam-no ao servidor, que prepara a assinatura, e depois assinam o hash com o `signHash()`. Em .NET, os exemplos usam um
único método para o contexto de segurança, `Util.GetSecurityContextId()`, nos dois produtos, e os exemplos em Node.js, PHP, Python e Ruby passam
ao Rest PKI Core os IDs de `StandardSecurityContexts` do Rest PKI, já que os IDs padrão são os mesmos.

Ainda não há exemplo do Rest PKI Core para assinaturas CAdES, assinaturas XML (inclusive NF-e), abertura e validação de assinaturas nem versões
para impressão; para elas, a aplicação pode continuar usando as APIs do Rest PKI que o Rest PKI Core
[atende como estão](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/migrating-from-rest-pki#o-que-o-rest-pki-core-atende).

## Veja também

* [Primeiros passos para integração](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/get-started)
* [Referência rápida do Rest PKI Core](https://docs.lacunasoftware.com/articles/rest-pki/core/quick-reference)
* [Referência rápida do Rest PKI](https://docs.lacunasoftware.com/articles/rest-pki/quick-reference) (legado)