Primeiros passos para integração - Rest PKI Core

Este artigo leva você do zero até uma primeira chamada bem-sucedida ao Rest PKI Core. Você vai:

1. Obter as credenciais: o endpoint da instância e uma chave de API
2. Configurar a biblioteca cliente da sua linguagem de programação ou chamar a API REST diretamente
3. Fazer uma primeira chamada para verificar se está tudo pronto

Como a integração funciona

A sua aplicação se comunica com o Rest PKI Core por uma API REST, autenticada por uma chave de API. As chamadas são sempre feitas pelo backend da aplicação: a chave de API dá acesso à sua organização e, por isso, nunca deve chegar a um navegador ou a um aplicativo móvel.

Quando uma operação depende do usuário, como escolher um certificado e assinar um documento ou tirar uma selfie para uma verificação biométrica, você não precisa construir essas páginas. O backend cria uma sessão, o Rest PKI Core retorna uma URL e o usuário é enviado a uma página hospedada pelo Rest PKI Core. Quando termina, o usuário volta à sua aplicação, que obtém os resultados pela API. Veja sessões de assinatura e sessões de biometria.

Obtenha as credenciais

Você precisa de dois parâmetros:

Parâmetro	Descrição
Endpoint	Endereço da instância do Rest PKI Core. Na instância SaaS, é https://core.pki.rest/. Numa instância própria, é o endereço do dashboard dela, como https://restpki.suaempresa.com.br/
Chave de API	Chave que identifica a aplicação e autentica as chamadas dela. Tem o formato MyApp|0f3c…: um prefixo tirado do nome da aplicação, um | e 64 caracteres hexadecimais

Se você usa a instância SaaS e a sua empresa ainda não tem acesso a ela, entre em contato com o nosso suporte ao desenvolvedor. Se você usa uma instância on-premises própria e ainda não tem uma organização com a qual trabalhar, veja Criação de organização.

Não há sandbox público. Os exemplos e o site de demonstração usam uma organização de avaliação na instância SaaS, cuja chave de API a Lacuna troca todo mês: pegue a chave atual no repositório de exemplos, em vez de copiá-la para o seu código.

Crie uma chave de API

As chaves de API pertencem a aplicações. Assim que conseguir entrar no dashboard, crie uma aplicação para o seu sistema e uma chave para ela:

1. Entre no dashboard da instância
2. No menu lateral, clique em Aplicações e depois em Adicionar
3. Em Nova Aplicação, preencha um Nome para a aplicação. Se for pedida uma Organização, escolha aquela em que o seu sistema vai trabalhar
4. Em Papéis, marque Operador (veja Escolhendo os papéis abaixo)
5. Clique em Criar
6. Na página da aplicação, clique em Chaves e depois em Adicionar
7. Em Nova Chave de Aplicação, preencha uma Descrição (por exemplo, o ambiente que vai usar a chave) e escolha uma Expiração (veja Expiração da chave abaixo); depois clique em Criar
8. Copie a chave exibida no diálogo Chave criada e guarde-a em um local seguro. Não será possível vê-la novamente: se você a perder, crie uma nova chave

Mantenha a chave de API em segredo

Quem tiver a chave pode agir sobre a sua organização com os papéis da aplicação dela. Guarde-a como guardaria uma senha: num cofre de segredos como o Azure Key Vault, numa variável de ambiente ou, durante o desenvolvimento, nos segredos do usuário (user secrets) do .NET. Nunca faça commit dela no controle de versão e nunca a envie a um navegador ou a um aplicativo móvel.

Escolhendo os papéis

Os papéis de uma aplicação definem o que as chaves dela podem fazer. Dê à aplicação apenas os papéis de que ela precisa:

Papel	O que permite
Operador	As operações de uma integração: criar e usar sessões de assinatura, assinar documentos, inspecionar assinaturas, autenticar usuários com certificados, emitir carimbos de tempo, executar sessões de biometria, adicionar marcas e carimbos aos documentos e consultar transações. É o papel de que a maioria das integrações precisa
Monitor	Consultar transações, sessões de biometria, cadastros em lote e faturas, sem executar nenhuma operação
Gerente	Tudo o que um Operador faz, além de gerenciar as configurações da organização e os contextos de segurança. Pode ver aplicações e usuários, mas não gerenciá-los
Administrador	Tudo, inclusive gerenciar aplicações e usuários

Expiração da chave

A Expiração de uma chave pode ser Em 1 ano, Em 2 anos ou Nunca expira. Quando uma chave expira, as chamadas feitas com ela passam a falhar com HTTP 401; por isso, se escolher uma chave que expira, planeje a substituição dela: uma aplicação pode ter mais de uma chave, o que permite criar a nova chave e passar o sistema a usá-la antes que a antiga expire.

Escolha como chamar a API

As APIs do Rest PKI Core são REST simples com JSON, mas você não precisa lidar com HTTP diretamente. A Lacuna oferece bibliotecas cliente que encapsulam a API nas convenções de cada linguagem, junto com projetos de exemplo que as usam:

Linguagem	Pacote	Código-fonte	Exemplos
.NET	Lacuna.RestPkiCore.Client no NuGet	—	PkiSuiteSamples/dotnet
PHP	lacuna/restpkicore-client no Packagist	GitHub	PkiSuiteSamples/php
Java	com.lacunasoftware.restpki:restpkicore-client no Maven Central	GitHub	PkiSuiteSamples/java
Node.js	restpki-core-client no npm	GitHub	PkiSuiteSamples/nodejs
Python	restpki-ng-python-client no PyPI	—	PkiSuiteSamples/python

Vá para a seção da sua linguagem:

• .NET
• PHP
• Java
• Node.js
• Python

Para qualquer outra linguagem, chame a API diretamente.

.NET

Adicione ao seu projeto o pacote do NuGet Lacuna.RestPkiCore.Client:

dotnet add package Lacuna.RestPkiCore.Client

O pacote é compilado para o .NET Standard 2.0, então roda no .NET 5 ou posterior, no .NET Core 2.0 ou posterior e no .NET Framework 4.6.1 ou posterior (a Microsoft recomenda a 4.7.2 ou posterior para bibliotecas .NET Standard 2.0).

observação

O pacote se chama Lacuna.RestPkiCore.Client, mas as classes dele ficam no namespace Lacuna.RestPki.Client.

Aplicações ASP.NET Core

Registre os serviços do Rest PKI Core no Program.cs, vinculando as opções deles à seção de configuração RestPki:

builder.Services.AddRestPki().Configure(builder.Configuration.GetSection("RestPki"));

Em seguida, adicione a seção ao appsettings.json, sem a chave de API:

{
	"RestPki": {
		"Endpoint": "https://core.pki.rest/"
	}
}

Forneça a chave de API por uma fonte que fique fora do controle de versão. Durante o desenvolvimento, use os segredos do usuário:

dotnet user-secrets set "RestPki:ApiKey" "YOUR_API_KEY"

Em produção, defina a variável de ambiente RestPki__ApiKey ou use um cofre de segredos como o Azure Key Vault. O ASP.NET Core combina essas fontes na mesma seção RestPki.

Onde a aplicação precisar chamar o Rest PKI Core, peça um IRestPkiService por injeção de dependência:

using Lacuna.RestPki.Client;

public class SignatureController : Controller {

	private readonly IRestPkiService restPkiService;

	public SignatureController(IRestPkiService restPkiService) {
		this.restPkiService = restPkiService;
	}

	...
}

O AddRestPki() também registra o IRestBioService, o serviço usado nas sessões de biometria.

dica

Se preferir definir as opções no código, passe-as ao AddRestPki(): builder.Services.AddRestPki(options => { options.Endpoint = ...; options.ApiKey = ...; });

Outras aplicações .NET

Se a aplicação não usa a injeção de dependência do ASP.NET Core, como numa aplicação .NET Framework ou de console, obtenha um IRestPkiService da classe estática RestPkiServiceFactory:

using Lacuna.RestPki.Client;

var restPkiService = RestPkiServiceFactory.GetService(new RestPkiOptions() {
	Endpoint = ConfigurationManager.AppSettings["RestPkiEndpoint"],
	ApiKey = ConfigurationManager.AppSettings["RestPkiApiKey"],
});

Neste exemplo, os parâmetros vêm da seção appSettings do arquivo web.config ou app.config, mas podem vir de onde você preferir. Para sessões de biometria, use RestPkiServiceFactory.GetBioService(), que recebe os mesmos parâmetros.

Cada chamada à RestPkiServiceFactory cria um novo cliente HTTP; por isso, crie o serviço uma vez e reutilize-o, por exemplo num campo estático, em vez de criar um a cada requisição.

Opções

O RestPkiOptions tem as propriedades a seguir, que também podem ser definidas na seção de configuração RestPki:

Propriedade	Descrição
Endpoint	Endereço da instância do Rest PKI Core. Se o endereço tiver um caminho, termine-o com uma barra (https://suaempresa.com.br/restpki/); caso contrário, o último segmento do caminho é descartado
ApiKey	A chave de API da aplicação
CultureName	Cultura das respostas da API, como en-US, pt-BR ou es-ES (veja Cultura abaixo). Também disponível como Culture, do tipo CultureInfo
TimeoutSeconds	Quanto tempo esperar por cada resposta, em segundos. Se não for definido, o cliente espera 60 segundos. Também disponível como Timeout, do tipo TimeSpan

Cultura

O cliente informa ao Rest PKI Core qual cultura usar em cada chamada e, por padrão, usa a cultura da thread atual (Thread.CurrentThread.CurrentUICulture). Isso funciona bem quando a aplicação define a cultura de cada requisição, como o ASP.NET Core faz com a localização de requisições (request localization).

Para usar sempre a mesma cultura, independentemente da thread, defina CultureName. No ASP.NET Core, adicione a propriedade à seção de configuração:

{
	"RestPki": {
		"Endpoint": "https://core.pki.rest/",
		"CultureName": "en-US"
	}
}

Nos demais casos, defina-a no RestPkiOptions:

var restPkiService = RestPkiServiceFactory.GetService(new RestPkiOptions() {
	...,
	CultureName = "en-US",
});

A mesma configuração define o idioma da página de captura biométrica hospedada (obtido do Accept-Language da requisição de início da sessão); portanto, definir CultureName fixa todas as páginas de captura nesse idioma.

Erros

Os métodos do IRestPkiService podem lançar as seguintes exceções:

Exceção	Quando
RestPkiExceptionV2	A API rejeitou a requisição (HTTP 422). Compare a propriedade ErrorCode, do tipo ErrorCodesV2, com os códigos de erro. A propriedade ErrorMessage descreve o erro em inglês e serve para os seus logs, não para os seus usuários
ValidationException	Um certificado ou uma assinatura não passou na validação. A propriedade ValidationResults indica o que falhou
RestForbiddenOperationException	A aplicação não tem um papel que permita a operação (HTTP 403, veja Escolhendo os papéis)
RestErrorException	Qualquer outro erro HTTP, como 401 por uma chave de API ausente ou inválida. A propriedade StatusCode tem o código de status HTTP (veja Códigos de status HTTP)
RestUnreachableException	Não foi possível acessar o endpoint: verifique o endereço do endpoint e a sua rede
TimeoutException	A resposta demorou mais que TimeoutSeconds

RestPkiExceptionV2 e ValidationException ficam no namespace Lacuna.RestPki.Client, e as demais classes Rest…Exception, no namespace Lacuna.RestClient. Todas derivam de Lacuna.RestClient.RestException; para tratar qualquer erro da API num único lugar, capture RestException (e TimeoutException, que é uma exceção padrão do .NET).

PHP

Adicione ao seu projeto o pacote do Composer lacuna/restpkicore-client (se ainda não tem o Composer, obtenha-o aqui):

composer require lacuna/restpkicore-client

O pacote requer o PHP 5.5 ou posterior e usa o Guzzle 6 ou 7 para fazer as chamadas HTTP. Ele é de código aberto, hospedado no GitHub: fique à vontade para fazer um fork se precisar personalizá-lo.

Crie um RestPkiService, que implementa RestPkiServiceInterface, passando a ele um RestPkiCoreClient construído com o endpoint e a chave de API:

use Lacuna\RestPki\RestPkiOptions;
use Lacuna\RestPki\RestPkiCoreClient;
use Lacuna\RestPki\RestPkiService;

$options = new RestPkiOptions('https://core.pki.rest/', getenv('RESTPKI_API_KEY'));
$client = new RestPkiCoreClient($options);
$service = new RestPkiService($client);

Neste exemplo, a chave de API vem da variável de ambiente RESTPKI_API_KEY, o que a mantém fora do código.

Cultura

Para definir a cultura das respostas da API, passe-a como terceiro parâmetro do RestPkiOptions:

$options = new RestPkiOptions('https://core.pki.rest/', getenv('RESTPKI_API_KEY'), 'en-US');

Erros

Todas as exceções a seguir ficam no namespace Lacuna\RestPki:

Exceção	Quando
RestPkiException	A API rejeitou a requisição (HTTP 422). getErrorCode() retorna o código de erro e getDetail() descreve o erro, para os seus logs
ValidationException	Um certificado ou uma assinatura não passou na validação
RestErrorException	Qualquer outro erro HTTP. getStatusCode() retorna o código de status HTTP (veja Códigos de status HTTP)
RestUnreachableException	Não foi possível acessar o endpoint

Exemplos em PHP

No nosso repositório de exemplos, as pastas cujo nome termina em -rest-core usam o Rest PKI Core. O endpoint e a chave de API são definidos na entrada restPkiNg do config.php.

Java

Adicione ao seu projeto o pacote com.lacunasoftware.restpki:restpkicore-client, do Maven Central. Ele requer o Java 8 ou posterior.

Com o Gradle, no build.gradle:

repositories {
	mavenCentral()
}

dependencies {
	implementation 'com.lacunasoftware.restpki:restpkicore-client:1.4.0'
}

Com o Maven, no pom.xml:

<dependency>
	<groupId>com.lacunasoftware.restpki</groupId>
	<artifactId>restpkicore-client</artifactId>
	<version>1.4.0</version>
</dependency>

Consulte o Maven Central para saber qual é a versão mais recente.

aviso

Não confunda com o com.lacunasoftware.restpki:restpki-core-client, um pacote mais antigo que não é mais atualizado.

O pacote é de código aberto, hospedado no GitHub: fique à vontade para fazer um fork se precisar personalizá-lo.

Obtenha um RestPkiService de RestPkiServiceFactory.getService(), passando um RestPkiOptions com o endpoint e a chave de API:

import com.lacunasoftware.restpkicore.RestPkiOptions;
import com.lacunasoftware.restpkicore.RestPkiService;
import com.lacunasoftware.restpkicore.RestPkiServiceFactory;

RestPkiOptions options = new RestPkiOptions();
options.setEndpoint("https://core.pki.rest/");
options.setApiKey(System.getenv("RESTPKI_API_KEY"));
RestPkiService service = RestPkiServiceFactory.getService(options);

Neste exemplo, a chave de API vem da variável de ambiente RESTPKI_API_KEY, o que a mantém fora do código. Se a aplicação acessa a internet por um proxy, defina-o com options.setProxy().

Cultura

Para definir a cultura das respostas da API, chame setCulture():

options.setCulture("en-US");

Erros

Os métodos do RestPkiService declaram throws Exception. Estas são as exceções que eles lançam, todas no pacote com.lacunasoftware.restpkicore:

Exceção	Quando
RestPkiException	A API rejeitou a requisição (HTTP 422). getErrorCode() retorna o código de erro
ValidationException	Um certificado ou uma assinatura não passou na validação
RestResourceNotFoundException	O recurso não foi encontrado (HTTP 404)
RestErrorException	Qualquer outro erro HTTP. getStatusCode() retorna o código de status HTTP (veja Códigos de status HTTP)
RestUnreachableException	Não foi possível acessar o endpoint

Exemplos em Java

No nosso repositório de exemplos, os controllers cujo nome termina em CoreController, como SignatureSessionRestCoreController, usam o Rest PKI Core. O endpoint e a chave de API são definidos em rest-pki-core, no application.yml.

Node.js

Adicione ao seu projeto o pacote restpki-core-client, do npm:

npm install restpki-core-client

O pacote não declara as versões do Node.js a que dá suporte. Ele traz as tipagens do TypeScript e faz as chamadas HTTP com o pacote request, que está descontinuado no npm. O pacote é open source, hospedado no GitHub.

Crie um RestPkiCoreClient, passando o endpoint, sem a barra final, em baseUrl e a chave de API em apiKey:

const { RestPkiCoreClient } = require('restpki-core-client');

const client = new RestPkiCoreClient({
	baseUrl: 'https://core.pki.rest',
	apiKey: process.env.RESTPKI_API_KEY,
});

Neste exemplo, a chave de API vem da variável de ambiente RESTPKI_API_KEY, o que a mantém fora do seu código. A biblioteca a envia no header X-Api-Key e monta cada URL acrescentando a rota, como /api/signature, ao baseUrl.

O RestPkiCoreClient tem um método para cada rota, como prepareSignature() para POST api/signature, completeSignature() para POST api/signature/completion e createSignatureSession() para POST api/signature-sessions. Cada método retorna uma promise de um objeto cuja propriedade data traz o corpo da resposta, e statusCode, o código de status HTTP:

const response = await client.createSignatureSession({
	returnUrl: 'https://localhost:3000/signature-callback',
});

// Redirecione o usuário para response.data.redirectUrl

aviso

Os exemplos do README do pacote criam um objeto Configuration, uma classe que a versão 1.0.2 não tem: crie um RestPkiCoreClient como acima. As opções timeout e ignoreSslErrors, que o RestPkiCoreClient aceita, não têm efeito nesta versão.

Cultura

A biblioteca não envia o header Accept-Language. Para definir a cultura das respostas da API, adicione-o em customHeaders, que a biblioteca envia em todas as requisições:

const client = new RestPkiCoreClient({
	baseUrl: 'https://core.pki.rest',
	apiKey: process.env.RESTPKI_API_KEY,
	customHeaders: { 'Accept-Language': 'pt-BR' },
});

Erros

Quando a API responde com um código de status HTTP diferente de 2xx, a promise é rejeitada com um HttpError, exportado pelo pacote, cuja propriedade statusCode traz o código de status HTTP (veja Códigos de status HTTP) e body, o corpo da resposta, já convertido de JSON. No HTTP 422, quando a API rejeitou a requisição, body é um ErrorModel. Quando o endpoint não pode ser alcançado, a promise é rejeitada com o erro do pacote request.

Exemplos em Node.js

No nosso repositório de exemplos, as rotas cujos arquivos terminam em -core.js, como pades-signature-core.js, usam o Rest PKI Core: elas assinam PDFs com assinaturas em duas etapas e adicionam carimbos em PDF. O endpoint e a chave de API são definidos em restPkiCore, no config/default.js.

Python

Adicione ao seu projeto o pacote restpki-ng-python-client, do PyPI:

pip install restpki-ng-python-client

O pacote não declara as versões do Python a que dá suporte. Ele depende do pydantic 2 e do urllib3 abaixo da 2.1. Não instale as versões de pré-lançamento dele (pip install --pre): a 0.9.2rc1 não contém a biblioteca.

observação

O pacote se chama restpki-ng-python-client, mas você o importa como restpki_ng_python_client.

A biblioteca é gerada a partir da API: há uma classe para cada grupo de rotas, como SignatureApi, SignatureSessionsApi, DocumentsApi, SignatureInspectionApi e PdfApi, e um método para cada rota, com o nome dela, como api_signature_post() para POST api/signature. Crie um ApiClient com o endpoint, sem a barra final, e envie a chave de API no header X-Api-Key:

import os
import certifi
from restpki_ng_python_client import ApiClient, Configuration, SignatureApi

configuration = Configuration(host='https://core.pki.rest', ssl_ca_cert=certifi.where())
client = ApiClient(configuration)
client.set_default_header('X-Api-Key', os.environ['RESTPKI_API_KEY'])

signature_api = SignatureApi(client)

Neste exemplo, a chave de API vem da variável de ambiente RESTPKI_API_KEY, o que a mantém fora do seu código, e as ACs confiáveis para o HTTPS vêm do pacote certifi. A biblioteca monta cada URL acrescentando a rota ao host; por isso, um endpoint terminado em / gera URLs com //.

aviso

Não use a classe RestPkiClient da versão 0.9.1.1: ela desliga a verificação do certificado TLS do servidor.

Cultura

A biblioteca não envia o header Accept-Language. Para definir a cultura das respostas da API, adicione-o como header padrão:

client.set_default_header('Accept-Language', 'pt-BR')

Erros

Todas as exceções a seguir estão no módulo restpki_ng_python_client.exceptions e derivam de ApiException:

Exceção	Quando
BadRequestException	HTTP 400: a requisição está malformada
UnauthorizedException	HTTP 401: a chave de API está ausente, é inválida ou expirou
ForbiddenException	HTTP 403: a aplicação não tem um papel que permita a operação (veja Escolhendo os papéis)
NotFoundException	HTTP 404
ServiceException	HTTP 500 ou outro 5xx
ApiException	Qualquer outro erro HTTP, inclusive o 422, quando a API rejeitou a requisição. A biblioteca não interpreta o ErrorModel: leia-o como JSON da propriedade body, e o código de status HTTP de status

Exemplos em Python

No nosso repositório de exemplos, a view pades_signature_rest_core.py usa o Rest PKI Core, para assinar um PDF com assinaturas em duas etapas. O endpoint e a chave de API são definidos em REST_PKI_CORE_ENDPOINT e REST_PKI_CORE_API_KEY, no sample/config.py.

Chamando a API diretamente

As APIs do Rest PKI Core são RESTful, recebem e retornam JSON e, por isso, são fáceis de chamar em qualquer linguagem de programação moderna. Se a aplicação usa uma linguagem sem biblioteca cliente, chame-as diretamente:

• URL: acrescente o caminho relativo da API ao endpoint. Por exemplo, api/signature-sessions na instância SaaS é https://core.pki.rest/api/signature-sessions
• Autenticação: passe a chave de API no header X-Api-Key de todas as requisições
• Corpo: envie JSON com o header Content-Type: application/json

Por exemplo:

POST https://core.pki.rest/api/signature-sessions
X-Api-Key: MyApp|0f3c...
Content-Type: application/json

Todas as APIs, com as requisições e respostas, estão descritas na referência da API. Numa instância própria, a referência fica no caminho swagger do endpoint, como https://restpki.suaempresa.com.br/swagger.

Códigos de status HTTP

A API responde com os seguintes códigos de status HTTP:

Código	Significado
200 (OK)	A requisição foi bem-sucedida. A resposta depende da API: veja a referência da API
400 (Bad Request)	A requisição está malformada; por exemplo, falta um campo obrigatório
401 (Unauthorized)	A chave de API está ausente, é inválida ou expirou
403 (Forbidden)	A chave de API é válida, mas a aplicação dela não tem um papel que permita a operação (veja Escolhendo os papéis)
422 (Unprocessable Entity)	A API rejeitou a requisição, normalmente por causa de um parâmetro que precisa ser corrigido. O corpo é um ErrorModel
500 (Internal Server Error)	Ocorreu um erro inesperado. O campo exceptionCode do corpo ajuda a diagnosticar o problema: informe-o ao entrar em contato com o suporte

ErrorModel

Quando a API responde com 422 (Unprocessable Entity), o corpo é um ErrorModel, chamado ErrorModelV2 na referência da API, com os seguintes campos:

Campo	Tipo	Descrição
code	string	O código de erro (veja os códigos de erro). Escreva o tratamento de erros com base neste campo
message	string	Descrição do erro, em inglês. Serve para os seus logs, não para os seus usuários, já que não é localizada
details	object	Informações adicionais sobre o erro, quando houver
validationResults	object	Quando o código é ValidationError, os resultados da validação do certificado ou da assinatura que falhou

Por exemplo:

{
	"code": "SignatureSessionNotFound",
	"message": "Signature session not found: 00000000-0000-0000-0000-000000000000"
}

Cultura

A API observa o header de requisição Accept-Language, que muda a cultura dos textos que a API retorna. As culturas suportadas são:

• en-US (ou apenas en)
• pt-BR (ou apenas pt)
• es-ES (ou apenas es)

observação

As mensagens de erro não são afetadas por esse header; por isso, devem ser registradas no log, e não exibidas aos seus usuários. Para mostrar um erro a um usuário, associe o code dele a uma mensagem própria.

Faça uma primeira chamada

Com as credenciais e a biblioteca cliente prontas, verifique se tudo funciona.

Primeiro, verifique o endpoint: abra o endereço api/system/info do endpoint num navegador, como https://core.pki.rest/api/system/info. Esse endereço não exige chave de API e retorna a versão da instância:

{"productName":"Lacuna Rest PKI Core","productVersion":"5.0.5 RTM","spaVersion":"...","timestamp":"..."}

Depois, verifique a chave de API criando uma sessão de assinatura. Em .NET:

using Lacuna.RestPki.Api.SignatureSessions;

var response = await restPkiService.CreateSignatureSessionAsync(new CreateSignatureSessionRequest() {
	ReturnUrl = "https://localhost:5001/signature-callback",
});

// Send the user to response.RedirectUrl

Chamando a API diretamente:

curl -X POST "https://core.pki.rest/api/signature-sessions" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "returnUrl": "https://localhost:5001/signature-callback" }'

A resposta traz o ID da sessão e a URL da página de assinatura dela:

{
	"sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
	"redirectUrl": "https://core.pki.rest/..."
}

Abra a redirectUrl num navegador para ver a página em que os seus usuários vão assinar. Se, em vez disso, a chamada falhar:

• 401: a chave de API não foi enviada ou está errada. Verifique se você copiou a chave inteira, incluindo o nome da aplicação antes do |
• 403: a aplicação não tem o papel Operador (veja Escolhendo os papéis)
• Endpoint inacessível: verifique o endereço do endpoint e se o seu servidor consegue acessá-lo

Próximos passos

• Sessões de assinatura: permita que os seus usuários assinem documentos numa página hospedada pelo Rest PKI Core
• Assinaturas em duas etapas: assine na sua própria página com o Web PKI, ou com uma chave guardada no servidor
• Sessões de biometria: prova de vida, cadastro, autenticação e identificação facial e captura de documento
• Webhooks: seja avisado quando um documento for assinado
• Contextos de segurança: escolha em quais certificados confiar
• Inspeção de assinaturas: liste e valide as assinaturas de um arquivo
• Carimbos em PDF: adicione um carimbo de tempo de documento a um PDF
• Referenciando arquivos: as formas de enviar documentos à API
• Utilitário cliente do Rest PKI: assine documentos pela linha de comando e a partir de aplicações desktop
• Solicitando carimbos de tempo: use o Rest PKI Core como provedor de carimbos de tempo
• Códigos de erro: os códigos que a API pode retornar

Demonstrações e exemplos

• Demonstração: Seus certificados no navegador
• Demonstração: Assinar um arquivo com o Rest PKI Core
• Autenticar com um certificado digital usando o Rest PKI Core: .NET · Java
• Assinar um PDF com o Rest PKI Core: .NET · Java · Node.js · PHP · Python · Ruby
• Assinar vários PDFs em lote com o Rest PKI Core: Node.js
• Assinar um PDF com uma chave do servidor usando o Rest PKI Core: .NET