--- title: "Referência rápida do Rest PKI Core" description: "Rest PKI Core em uma página: pacotes cliente, chave de API e endpoint, sessões de assinatura, webhooks, carimbos de tempo, prova de vida, erros e testes." canonical: "https://docs.lacunasoftware.com/articles/rest-pki/core/quick-reference" locale: "pt-BR" product: "Rest PKI Core" last_updated: "2026-10-12" --- # Referência rápida do Rest PKI Core O essencial do Rest PKI Core em uma página, com links para os artigos completos. ## Para que serve O Rest PKI Core acrescenta assinaturas digitais, validação de assinaturas, carimbos de tempo e verificações biométricas de identidade às suas aplicações por meio de uma API REST, como serviço em core.pki.rest ou numa instância própria (Windows, Linux, Docker ou Azure). Quando uma etapa depende do usuário, como assinar com um certificado ou tirar uma selfie, o backend cria uma sessão, envia o usuário a uma página hospedada pelo Rest PKI Core e obtém os resultados pela API. | Alternativa | Quando ela se encaixa melhor | | --- | --- | | [Rest PKI](https://docs.lacunasoftware.com/articles/rest-pki/quick-reference) (legado) | A sua aplicação já está integrada ao Rest PKI em pki.rest. O Rest PKI Core também atende à maioria das APIs do Rest PKI, o que facilita a migração. | | [PKI SDK](https://docs.lacunasoftware.com/articles/pki-sdk/quick-reference) | A sua aplicação é .NET e deve assinar e validar com uma biblioteca no próprio processo; o guia de PKI a recomenda para assinaturas no servidor em .NET. | | [PKI Express](https://docs.lacunasoftware.com/articles/pki-express/quick-reference) | Você quer assinar nos seus próprios servidores Windows ou Linux, a partir de praticamente qualquer linguagem, com um arquivo de licença em vez de um serviço de API. | | [Web PKI](https://docs.lacunasoftware.com/articles/web-pki/quick-reference) | Você precisa apenas da parte do navegador: listar os certificados do usuário e assinar com eles em JavaScript. A página de assinatura hospedada pelo Rest PKI Core já o usa para os certificados locais. | | [Signer](https://docs.lacunasoftware.com/articles/signer/quick-reference) | Você precisa de um gerenciador de documentos e assinaturas que envie documentos às pessoas e colete as assinaturas delas. | ## Instalação | Linguagem | Pacote | Major atual | Registry | | --- | --- | --- | --- | | .NET | `Lacuna.RestPkiCore.Client` (namespace `Lacuna.RestPki.Client`) | 5 (mais recente: 5.0.0) | https://www.nuget.org/packages/Lacuna.RestPkiCore.Client/ | | Java | `com.lacunasoftware.restpki:restpkicore-client` (pacote `com.lacunasoftware.restpkicore`) | 1 (mais recente: 1.4.0) | https://central.sonatype.com/artifact/com.lacunasoftware.restpki/restpkicore-client | | PHP | `lacuna/restpkicore-client` | 1 (mais recente: 1.2.1) | https://packagist.org/packages/lacuna/restpkicore-client | | Node.js | `restpki-core-client` | 1 (mais recente: 1.0.2) | https://www.npmjs.com/package/restpki-core-client | | Python | `restpki-ng-python-client` | 0 (mais recente: 0.9.1.1) | https://pypi.org/project/restpki-ng-python-client/ | | Navegador (widget de biometria) | `lacuna-restpki-widget`, também em cdn.lacunasoftware.com | 1 (mais recente: 1.4.1) | https://www.npmjs.com/package/lacuna-restpki-widget | | Qualquer outra linguagem (Ruby…) | Nenhum: chame a API REST diretamente | — | — | No .NET, execute `dotnet add package Lacuna.RestPkiCore.Client`; o pacote é compilado para o .NET Standard 2.0. No Java, não use o `com.lacunasoftware.restpki:restpki-core-client`: é um pacote mais antigo, que não é mais atualizado, embora o número de versão dele (4.0.0) seja maior. TODO(docs): os exemplos em .NET fixam versões de majors anteriores do `Lacuna.RestPkiCore.Client` (1.10.1 no PkiSuiteSamples dotnet/mvc, 1.3.0 no dotnet/spa, 4.1.0-rc01 no RestBioSamples backend/dotnet), enquanto o NuGet está na 5.0.0; nenhuma página cita o pacote Python `restpki-ng-python-client`, usado pelo exemplo em Python; os Primeiros passos não têm seção de configuração para Node.js nem para Python; a página de sessões de biometria carrega o widget 1.3.1 da CDN, enquanto o npm tem o 1.4.1. ## Configuração e autenticação * **Chave de API**: envie-a no header `X-Api-Key` de toda requisição. As chaves pertencem a uma aplicação criada no dashboard da instância (**Aplicações**), são exibidas uma única vez e têm o formato `MyApp|0f3c…`. Dê à aplicação o papel **Operador**, o de que a maioria das integrações precisa. Veja [Primeiros passos](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/get-started#parameters) e [Escolhendo os papéis](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/get-started#roles). * **Endpoints de carimbo de tempo**: recebem a chave como `Authorization: ApiKey SUA_CHAVE_DE_API`, em vez do header `X-Api-Key`. Veja [Solicitando carimbos de tempo](https://docs.lacunasoftware.com/articles/rest-pki/core/requesting-timestamps). * **Endpoint**: `https://core.pki.rest/` na instância SaaS (se a sua empresa ainda não tem acesso a ela, entre em contato com o [suporte ao desenvolvedor](mailto:suporte@lacunasoftware.com)); numa [instância própria](https://docs.lacunasoftware.com/articles/rest-pki/core/on-premises), o endereço do dashboard dela. Acrescente a ele o caminho da API, como em `https://core.pki.rest/api/signature-sessions`. O `api/system/info` não exige chave e retorna a versão da instância. * **Referência da API**: no caminho `swagger` do endpoint, como em https://core.pki.rest/swagger, e como documento OpenAPI em https://docs.lacunasoftware.com/openapi/rest-pki-core.json. * **Licenças**: a instância SaaS não usa arquivo de licença, mas uma aplicação que usa o Web PKI com o Rest PKI Core precisa de uma licença do Web PKI; uma instância on-premises precisa das licenças do PKI SDK e do Web PKI. Veja [Licenciamento](https://docs.lacunasoftware.com/articles/welcome/licensing). No ASP.NET Core, registre os serviços vinculando-os à seção de configuração `RestPki` e depois solicite o `IRestPkiService` (ou o `IRestBioService`, para sessões de biometria) por injeção de dependência. As chaves da seção são `Endpoint`, `ApiKey`, `CultureName` e `TimeoutSeconds` (60 segundos, se não for definido); mantenha a `ApiKey` fora do *appsettings.json*, nos user secrets (`RestPki:ApiKey`) durante o desenvolvimento e na variável de ambiente `RestPki__ApiKey` ou num cofre de segredos em produção. Outras aplicações .NET chamam `RestPkiServiceFactory.GetService(new RestPkiOptions() { ... })` uma vez e reutilizam o serviço. ```cs builder.Services.AddRestPki().Configure(builder.Configuration.GetSection("RestPki")); ``` TODO(docs): nenhuma página descreve um ambiente de sandbox ou de testes: a documentação cita apenas a instância SaaS em `https://core.pki.rest/` e as instâncias on-premises. ## Operações principais Os exemplos estão em C#; `restPkiService` e `restBioService` são o `IRestPkiService` e o `IRestBioService` da [Configuração](https://docs.lacunasoftware.com/articles/rest-pki/core/quick-reference#configuração-e-autenticação). ### Criar uma sessão de assinatura Permite que o usuário assine numa página hospedada pelo Rest PKI Core, fazendo upload dos documentos nela: crie a sessão com uma `returnUrl` e redirecione o usuário para a `RedirectUrl` recebida. `CreateSignatureSessionAsync`, `POST api/signature-sessions`. Veja [Sessões de assinatura](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/signature-sessions). ```cs var response = await restPkiService.CreateSignatureSessionAsync(new CreateSignatureSessionRequest() { ReturnUrl = "http://localhost:8080/SessionCallback", }); return Redirect(response.RedirectUrl); ``` ### Obter os documentos assinados Quando o usuário volta, a `returnUrl` traz `?signatureSessionId=...`: obtenha a sessão e verifique o status dela, que é `Completed` ou `UserCancelled`. `GetSignatureSessionAsync`, `GET api/signature-sessions/{id}`. A `SignedFile.Url` de cada documento é um link temporário que baixa o arquivo sem a chave de API. Veja [Sessões de assinatura](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/signature-sessions). ```cs public async Task Callback(Guid signatureSessionId) { var session = await restPkiService.GetSignatureSessionAsync(signatureSessionId); if (session.Status != SignatureSessionStatus.Completed) { return Redirect("/"); } return View(session); } ``` ### Assinar documentos que a aplicação já tem Envia os documentos na criação da sessão; o usuário os assina e não pode fazer upload de outros. Referencie cada arquivo por caminho, bytes, stream ou URL com o `FileReference`. Veja [Pré-definindo os documentos](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/signature-sessions#predefined-documents) e [Referenciando arquivos](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/file-referencing). ```cs string pdfPath = ...; var documents = new List { new SignatureSessionDocumentToSign { File = FileReference.FromFile(pdfPath), }, }; var response = await restPkiService.CreateSignatureSessionAsync(new CreateSignatureSessionRequest() { ... }, documents: documents); return Redirect(response.RedirectUrl); ``` ### Receber o webhook O Rest PKI Core envia um `POST` HTTP com um `WebhookEventModel` do tipo `DocumentSignatureCompleted` quando um documento é assinado e processado, opcionalmente com autenticação Basic, Bearer ou por chave de API. No [fluxo com webhook](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/signature-sessions#webhook-flow), crie a sessão sem `ReturnUrl` e abra a página de assinatura numa nova aba. Veja [Webhooks](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/webhooks). ```cs [HttpPost] public async Task Index(WebhookEventModel eventModel) { switch (eventModel.Type) { case WebhookEventTypes.DocumentSignatureCompleted: await OnDocumentSignatureCompletedAsync(eventModel.Document); break; } return new HttpStatusCodeResult(HttpStatusCode.OK); } private async Task OnDocumentSignatureCompletedAsync(DocumentModel model) { var apiDocument = await restPkiService.GetDocumentAsync(model); // SignedFile.Url is a temporary link that downloads the signed file without the API key. var content = await restPkiService.GetContentAsync(apiDocument.SignedFile.Url); } ``` Um usuário com o papel **Administrador** ou **Gerente** define a URL do webhook e a autenticação dele no dashboard, em **Configurações** > **Configuração de webhook**. Com a autenticação Basic, o header é `Authorization: Basic base64(usuário):base64(senha)`, e não a forma da RFC 7617. Responda com um código de status 2xx; a aba **Chamadas recentes** mostra cada notificação e a resposta da sua aplicação. Veja [Configurando os webhooks](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/webhooks#configurando-os-webhooks). ### Assinar com uma chave guardada no servidor O Rest PKI Core prepara a assinatura e retorna o hash a assinar, o seu servidor o assina e o Rest PKI Core conclui a assinatura. `PrepareSignatureAsync` e `CompleteSignatureAsync`, `POST api/signature` e `POST api/signature/completion`. Na variante com navegador, é o Web PKI que lê o certificado do usuário e assina o hash, na sua própria página. Veja [Assinaturas em duas etapas](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/two-step-signatures). ```cs var certificate = new X509Certificate2(certificatePath, "1234"); var certificateReference = CertificateReference.FromX509Certificate2(certificate); var fileReference = FileReference.FromFile(userfilePath, userfile); var signatureOptions = new PrepareSignatureOptions() { SecurityContextId = Util.GetSecurityContextId() }; var prepareSignatureResult = await restPkiService.PrepareSignatureAsync(fileReference, certificateReference, signatureOptions); var toSignHash = prepareSignatureResult.ToSignHash.Value; var signature = certificate.GetRSAPrivateKey().SignHash(toSignHash, prepareSignatureResult.ToSignHash.Algorithm.HashAlgorithmName, RSASignaturePadding.Pkcs1); var signedDocument = await restPkiService.CompleteSignatureAsync(prepareSignatureResult.State, signature); ``` ### Fazer uma prova de vida Verifica se há uma pessoa real diante da câmera. Inicie a sessão com um `TrustedOrigin` (widget na sua página) ou uma `ReturnUrl` (redirecionamento), repasse a `SessionUrl` ao frontend e conclua a sessão com o ticket que o usuário traz de volta. `StartLivenessSessionAsync` e `CompleteLivenessSessionAsync`, `POST api/bio/sessions/liveness` e `POST api/bio/sessions/liveness/completion`. Veja [Prova de vida](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/bio-sessions/liveness) e [Sessões de biometria](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/bio-sessions). ```cs var response = await restBioService.StartLivenessSessionAsync(new() { TrustedOrigin = exampleConfig.Value.TrustedOrigin, SubjectIdentifier = "Example", }); _ = response.SessionUrl; // The URL to be loaded in the Widget to start the biometric session. var result = await restBioService.CompleteLivenessSessionAsync(request.Ticket); var success = result.Success; ``` ### Solicitar um carimbo de tempo Usa o Rest PKI Core como provedor de carimbos de tempo RFC 3161: envie o hash por `POST` para `api/tsp` no endpoint, ou use o protocolo TSP em `tsp`, com o header `Authorization: ApiKey SUA_CHAVE_DE_API`. Acrescente o plano como sufixo (`api/tsp/PkiBrazil`): na instância SaaS ele é obrigatório, `PkiBrazil` ou `LacunaTest`. A resposta traz `encodedValue`, o carimbo de tempo em Base64. Veja [Solicitando carimbos de tempo](https://docs.lacunasoftware.com/articles/rest-pki/core/requesting-timestamps). ```json { "algorithm": "SHA256", "value": "L80RIvFw2jwpiObzFQN+tuEQQ4E9qnGeYYYd+4DrM8M=" } ``` ## Erros A API responde com códigos de status HTTP. No 422, o corpo é um `ErrorModel` (chamado `ErrorModelV2` na referência da API) cujo `code` é o que o seu tratamento de erros deve testar; a `message` dele está em inglês e serve para os logs. O cliente .NET lança as exceções abaixo, que derivam todas de `Lacuna.RestClient.RestException`. Veja [Códigos de status HTTP](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/get-started#http-status-codes) e [Erros no .NET](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/get-started#dotnet-errors). | Status | Exceção no .NET | O que verificar | | --- | --- | --- | | 401 | `RestErrorException` (`StatusCode`) | A chave de API está ausente, errada ou expirou; copie a chave inteira, inclusive o nome da aplicação antes do separador | | 403 | `RestForbiddenOperationException` | A aplicação não tem um papel que permita a operação, normalmente **Operador** | | 422 | `RestPkiExceptionV2` (`ErrorCode`) | A API rejeitou a requisição: veja o código de erro | | — | `ValidationException` (`ValidationResults`) | Um certificado ou uma assinatura não passou na validação | | — | `RestUnreachableException` | Não foi possível acessar o endpoint | Os primeiros códigos que costumam aparecer são `SignatureSessionNotFound` (verifique o ID da sessão), `BadSignatureSessionOperation` (a operação não é válida para o status da sessão ou do documento), `BackgroundProcessing` (o recurso ainda está sendo processado) e `DocumentNotFound`. A lista em [Códigos de erro](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/error-codes) não é completa. ## Certificados e credenciais de teste * **Certificados de teste**: baixe os certificados da ICP de testes da Lacuna em [Certificados de teste](https://docs.lacunasoftware.com/articles/pki-guide/test-certs) e nunca confie nessa ICP em produção. * **Confiar na ICP de testes**: passe o contexto de segurança padrão `StandardSecurityContexts.LacunaTest` (`803517ad-3bbc-4169-b085-60053a8f6dbf`), que confia na ICP-Brasil e na ICP de testes da Lacuna, como o `SecurityContextId` de uma sessão de assinatura ou do `PrepareSignatureOptions`, ou escolha-o como **Contexto de segurança padrão** da organização em **Configurações** > **Configurações gerais**, no dashboard. O Rest PKI Core cria esse contexto em toda instância ao iniciar. O exemplo em .NET o passa apenas em builds de debug. Veja [Rest PKI Core](https://docs.lacunasoftware.com/articles/pki-guide/test-certs#rest-pki-core) na página de certificados de teste. * **Carimbos de tempo de teste**: na instância SaaS, use o plano `LacunaTest`. * **Chave de API dos exemplos**: os projetos do PkiSuiteSamples vêm com uma chave de avaliação para a instância SaaS, que expira em 31/10/2026. Para ter uma chave própria, entre em contato com o [suporte ao desenvolvedor](mailto:suporte@lacunasoftware.com). TODO(docs): nenhuma página diz se o core.pki.rest oferece chaves de API de teste ou uma organização de avaliação. ## Experimente Abra as demonstrações ou o projeto de exemplo da sua linguagem: **Demonstrações e exemplos** - Demonstração: [Sign a file with Rest PKI Core](https://try.lacunasoftware.com/pt/pki-suite/sign-a-file-rest-pki-core) - Demonstração: [Timestamp a PDF](https://try.lacunasoftware.com/pt/pki-suite/timestamp-a-pdf) - Demonstração: [Run a liveness check](https://try.lacunasoftware.com/pt/lacuna-bio/run-a-liveness-check) - Demonstração: [Enroll and authenticate your face](https://try.lacunasoftware.com/pt/lacuna-bio/enroll-and-authenticate-your-face) - Demonstração: [Your certificates in the browser](https://try.lacunasoftware.com/pt/web-pki/certificates-in-the-browser) - Sign a PDF with Rest PKI Core: [.NET](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/dotnet/mvc/PkiSuiteAspNetMvcSample/Controllers/PadesSignatureRestCoreController.cs) · [Java](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/java/springmvc/src/main/java/com/lacunasoftware/pkisuite/controller/PadesSignatureCoreController.java) · [Node.js](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/nodejs/expressmvc/routes/pades-signature-core.js) · [PHP](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/php/plain/public/pades-signature-rest-core/index.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) - Sign multiple PDFs with Rest PKI Core: [Node.js](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/nodejs/expressmvc/routes/batch-pades-signature-core.js) - Sign a PDF with a server key using Rest PKI Core: [.NET](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/dotnet/mvc/PkiSuiteAspNetMvcSample/Controllers/PadesServerKeyRestCoreController.cs) - Signature session with Rest PKI Core: [.NET](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/dotnet/mvc/PkiSuiteAspNetMvcSample/Controllers/SignatureSessionRestCoreController.cs) · [Java](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/java/springmvc/src/main/java/com/lacunasoftware/pkisuite/controller/SignatureSessionRestCoreController.java) · [PHP](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/php/plain/public/signature-session-rest-core/index.php) - Signature session with predefined documents using Rest PKI Core: [.NET](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/dotnet/mvc/PkiSuiteAspNetMvcSample/Controllers/SignatureSessionPreDefRestCoreController.cs) · [Java](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/java/springmvc/src/main/java/com/lacunasoftware/pkisuite/controller/SignatureSessionPreDefRestCoreController.java) - Validate files uploaded to a Rest PKI Core signature session: [.NET](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/dotnet/mvc/PkiSuiteAspNetMvcSample/Controllers/ValidateFileRestCoreController.cs) · [Java](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/java/springmvc/src/main/java/com/lacunasoftware/pkisuite/controller/ValidateFileRestCoreController.java) · [PHP](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/php/plain/public/validate-file-rest-core/index.php) - Receive Rest PKI Core webhooks: [.NET](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/dotnet/mvc/PkiSuiteAspNetMvcSample/Controllers/WebhookRestCoreController.cs) · [Java](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/java/springmvc/src/main/java/com/lacunasoftware/pkisuite/controller/WebhookRestCoreController.java) · [PHP](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/php/plain/public/webhook-rest-core/index.php) - Authenticate with a digital certificate using Rest PKI Core: [Java](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/java/springmvc/src/main/java/com/lacunasoftware/pkisuite/controller/AuthenticationRestPkiCoreController.java)