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 (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	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	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	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	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 e Escolhendo os papéis.
• 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.
• 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); numa instância própria, 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.

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.

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.

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.

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.

public async Task<ActionResult> 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 e Referenciando arquivos.

string pdfPath = ...;
var documents = new List<SignatureSessionDocumentToSign> {
	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, crie a sessão sem ReturnUrl e abra a página de assinatura numa nova aba. Veja Webhooks.

[HttpPost]
public async Task<ActionResult> 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.

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.

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 e Sessões de biometria.

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.

{
	"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 e Erros no .NET.

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 não é completa.

Certificados e credenciais de teste

• Certificados de teste: baixe os certificados da ICP de testes da Lacuna em Certificados de teste 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 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.

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
• Demonstração: Timestamp a PDF
• Demonstração: Run a liveness check
• Demonstração: Enroll and authenticate your face
• Demonstração: Your certificates in the browser
• Sign a PDF with Rest PKI Core: .NET · Java · Node.js · PHP · Python · Ruby
• Sign multiple PDFs with Rest PKI Core: Node.js
• Sign a PDF with a server key using Rest PKI Core: .NET
• Signature session with Rest PKI Core: .NET · Java · PHP
• Signature session with predefined documents using Rest PKI Core: .NET · Java
• Validate files uploaded to a Rest PKI Core signature session: .NET · Java · PHP
• Receive Rest PKI Core webhooks: .NET · Java · PHP
• Authenticate with a digital certificate using Rest PKI Core: Java