Referência rápida do Amplia

O essencial da API do Amplia em uma página, com links para os artigos completos e os samples.

Para que serve

O Amplia é uma plataforma para criar e gerenciar Autoridades Certificadoras (ACs) ou Infraestruturas de Chaves Públicas (ICPs) completas, usada como serviço em nuvem da Lacuna (SaaS) ou como instância on-premises própria. Os operadores gerenciam ACs, modelos e pedidos em um dashboard web, e os seus sistemas criam pedidos de certificado e emitem certificados pela API REST.

Alternativa	Quando é a melhor escolha
Amplia Reg	Agentes de registro precisam validar e aprovar a identidade do titular antes da emissão. O Amplia Reg é a Autoridade de Registro (AR): a sua aplicação cria o pedido pela API do próprio Amplia Reg, e o Amplia só emite o certificado no final.
Lacuna PSC	Você precisa guardar e gerenciar certificados em nuvem por trás de uma interface DOC-ICP-17.01 (OAuth 2.0). O PSC é um sistema complementar que depende do Amplia.
GrantID	Você precisa de login, single sign-on ou múltiplos fatores de autenticação para as suas aplicações, e não de certificados. O próprio Amplia usa o GrantID para o login dos usuários.
PKI SDK	Você só precisa decodificar e validar certificados (ou decodificar, validar e emitir certificados de atributo) dentro de uma aplicação .NET, sem operar uma AC.
Rest PKI ou Signer	Você precisa assinar documentos. Os certificados emitidos pelo Amplia podem ser usados logo em seguida para assinar com eles.

Instalação

A API REST não exige pacote: qualquer cliente HTTP pode chamá-la, e a descrição OpenAPI dela (versão 5.0.1 da API) está em https://docs.lacunasoftware.com/openapi/amplia.json. Bibliotecas cliente:

Linguagem	Pacote	Major atual	Registro
.NET	Lacuna.Amplia.Client	5	NuGet
Java	com.lacunasoftware.amplia:amplia-client	1	Maven Central
Node.js	amplia-client	1	npm
PHP	lacuna/amplia-client	1	Packagist
Python	amplia-client	1	PyPI

• O cliente .NET é gerado a partir do mesmo código-fonte do Amplia: obtenha um IAmpliaService por injeção de dependência (services.AddAmplia(...)) ou de AmpliaServicesFactory.GetService(endpoint, apiKey); a classe mais antiga AmpliaClient está marcada como [Obsolete]. Ao contrário dos outros clientes, ele também envia o link de emissão por e-mail ou SMS e lê o QR code dele. Veja Cliente .NET.
• As majors dos clientes não acompanham a versão do Amplia: todo endpoint que os clientes 1.x chamam é atendido pelo Amplia 5.0.1.

Configuração e autenticação

• Chave de API: toda requisição envia a chave de API da sua aplicação no header X-Api-Key, no formato yourapp|xxxx…. Para obter uma, entre no dashboard do Amplia, crie uma aplicação em Aplicações, marque o papel dela, depois adicione uma chave em Chaves e copie-a, pois ela não pode ser recuperada depois: veja Criar uma aplicação e uma chave de API. Uma aplicação que executa o fluxo inteiro precisa do papel Operador (Worker). Uma aplicação com o papel Agente de Registro pode criar pedidos, pedir ao Amplia que envie o link de emissão por e-mail ou SMS e revogar, mas não pode ler o link de emissão nem emitir certificados.
• Endpoint: o endereço da instância do Amplia, prefixado a toda URL relativa da API. A instância em nuvem da Lacuna é https://amplia.lacunasoftware.com/, o endpoint padrão nos samples; com uma instância on-premises, use o domínio do dashboard que você escolheu. TODO(docs): nenhum endpoint separado de sandbox ou de teste está documentado.
• Idioma: a API observa o header Accept-Language (en-US ou pt-BR); as mensagens de erro não são afetadas por ele.
• Webhook: o Amplia pode avisar o seu sistema sempre que um certificado for emitido; o corpo da notificação é um WebhookEventModel cujo type é OrderCertificateIssued. Um Administrador ou Gerente define a URL e o tipo de autenticação (o header que o Amplia envia: Bearer, ApiKey, um Authorization próprio ou Basic) em Configurações > Configuração de webhook. O Amplia envia JSON com nomes de propriedade em PascalCase (Type, Order, Certificate) e considera entregue qualquer resposta 2xx; o valor Basic dele não segue a codificação padrão. Veja Webhook.

Os samples em Node.js guardam caId (a AC que emite os certificados), apiKey e endpoint (com / no final) em config/default.js, e criam o cliente a partir do endpoint e da chave de API:

const { AmpliaClient } = require("amplia-client");

class Util {
	static getAmpliaClient() {
		let CONFIG = Config.getInstance().get('amplia');
		let key = CONFIG['apiKey'];
		let endpoint = CONFIG['endpoint'];
		return new AmpliaClient({
			endpoint: endpoint,
			apiKey: key
		});
	}
}

Operações principais

Toda emissão começa com um pedido em uma AC; depois, ou o titular emite o certificado no próprio dispositivo, ou o seu servidor o emite. O código é Node.js, recortado dos samples do PKI Suite; os blocos seguintes usam o order criado no primeiro.

O guia de integração cobre cada fluxo em Java, Node.js, PHP e Python, com as chamadas REST por trás deles.

Criar um pedido de certificado

Um pedido guarda os dados do titular, a AC que emite o certificado e a validade dele. client.createOrder(request) envia para POST /api/orders/{format}, por exemplo /api/orders/pki-brazil para parâmetros ICP-Brasil. Guia: Criar pedidos de certificado. Sample completo: issue-cert-server-amplia.js.

const {PkiBrazilCertificateParameters, CreateOrderRequest, CertificateKinds} = require('amplia-client');

const CONFIG = Config.getInstance().get('amplia');
const client = Util.getAmpliaClient();
const request = new CreateOrderRequest({
	caId: CONFIG['caId'],
	validityEnd: Util.getTwoYearsFromNowDate(),
	kind: CertificateKinds.PUBLIC_KEY,
	parameters: new PkiBrazilCertificateParameters({
		name: req.body.subjectName,
		cpf: req.body.cpf
	})
});
let order = await client.createOrder(request);

Deixar o titular emitir na própria máquina

client.getOrderIssueLink(orderId, returnUrl) (GET /api/orders/{id}/issue-link?returnUrl=…) devolve um link para a página de emissão do Amplia, em que o par de chaves é gerado na máquina do usuário; depois, o Amplia volta para returnUrl. O sample também define phoneNumber nos parâmetros do pedido, de que esse fluxo precisa para verificar a identidade do titular. Guia: Emitir na máquina do titular. Sample completo: issue-cert-user-amplia.js.

const RETURN_URL = 'http://localhost:3000/issue-cert-user-amplia/complete';

let link = await client.getOrderIssueLink(order.getId(), RETURN_URL);
res.render('issue-cert-user-amplia/redirect', {
	redirectLink: link
});

O Amplia também pode entregar o link ele mesmo. POST /api/orders/{id}/send-issue-email-request o envia por e-mail ao endereço que está nos parâmetros do pedido, e POST /api/orders/{id}/send-issue-sms-request o envia por SMS ao telefone do pedido; como o seu sistema nunca vê o link, uma aplicação com o papel Agente de Registro pode usá-los. GET /api/orders/{id}/issue-qrcode-image devolve um QR code em PNG que leva à página de emissão, e issue-qrcode-data, a URL que ele contém. Detalhes: Outras formas de entregar o link de emissão.

Emitir a partir de um CSR gerado no seu servidor

client.issueCertificate(orderId, csr, keyMedia) (POST /api/v2/certificates, corpo orderId, csr, keyMedia) emite o pedido para um CSR que você gerou; o sample gera a chave e o CSR com o PKI Express. keyMedia é PC, CryptoDevice, Mobile ou Cloud. Guia: Emitir a partir de um CSR. Sample completo: issue-cert-server-amplia.js.

const {KeyGenerator} = require('pki-express');
const {KeyMedia } = require('amplia-client/lib/enums');

const keyGenerator = new KeyGenerator({
	keySize: req.body.keySize,
	genCsr: true
});
let genKey = await keyGenerator.generate();
let generatedKey = genKey.getKey();
let cert = await client.issueCertificate(order.getId(), genKey.getCsr(), KeyMedia.PC);
let certId = cert.getId();
// WARNING: It is highly RECOMMENDED to ENCRYPT the key before storing
// in your database.
StorageMock.storeSync(generatedKey, certId, '.json');
StorageMock.storeSync(cert.getContentRaw(), certId, '.cer');

Emitir um arquivo PKCS #12 (.pfx)

client.issuePkcs12Certificate(orderId, password, keySize) (POST /api/certificates/pkcs12) faz o Amplia gerar a chave e devolver um arquivo PKCS #12 protegido por senha. Guia: Emitir um arquivo PKCS #12. Sample completo: issue-pkcs12-cert-server-amplia.js.

let cert = await client.issuePkcs12Certificate(order.getId(), req.body.senha, 2048);
let certId = cert.getModel().id;
StorageMock.storeSync(cert.getPfxContent(), certId, '.pfx');

Emitir um certificado de atributo

Crie o pedido com kind igual a Attribute e parâmetros CIE (a Carteira de Identificação Estudantil), em uma AC configurada para certificados de atributo, que não é a AC que emite certificados de chave pública; depois, emita-o sem CSR, já que um certificado de atributo não tem par de chaves próprio. O endpoint de pedidos CIE é POST /api/orders/cie. Guia: Certificados de atributo. O único sample é em PHP: complete.php.

Revogar um certificado

O método client.revokeCertificate(certificateId) do cliente Node.js envia DELETE /api/certificates/{id}. O Amplia publica LCRs (CRLs) nos seus domínios de acesso e pode responder a requisições OCSP. A chamada não recebe motivo de revogação e não pode ser desfeita. Cada AC emite LCRs no seu próprio cronograma (a cada crlIssuePeriod), então uma revogação aparece na próxima LCR programada, sem código de motivo, enquanto o respondedor OCSP do Amplia a informa na hora. Guia: Revogar certificados.

Renovação: o Amplia pode renovar certificados, e o titular recebe um novo certificado no lugar do que está vencendo. TODO(docs): nenhum artigo documenta como renovar um certificado pela API.

Erros

A API responde com um código de status HTTP; nos erros de API, o corpo é um ErrorModel com code, message e details. As mensagens de erro não seguem o Accept-Language: registre-as no log em vez de mostrá-las aos usuários.

Status	Significado
400 Bad Request	Erro de sintaxe, por exemplo, um campo obrigatório ausente
401 Unauthorized	Chave de API não informada ou inválida
403 Forbidden	A chave de API é válida, mas a aplicação não tem permissão para a operação
422 Unprocessable Entity	Erro de API; o corpo é um ErrorModel
500 Internal Server Error	Erro inesperado; o exceptionCode no corpo ajuda o suporte da Lacuna

O cliente Node.js rejeita com AmpliaError em um 422 (a mensagem traz o code), com RestError nos demais erros HTTP e com RestUnreachableError quando o endpoint não pode ser acessado. O enum AmpliaErrorCodes do cliente cita códigos como OrderNotFound, OrderAlreadyFulfilled e CertificateAlreadyRevoked. O cliente .NET lança AmpliaException, cujo Code é o código de erro.

Códigos de erro lista os códigos que as chamadas de emissão devolvem e o que cada um significa. Uma permissão que falta à aplicação recebe 403 Forbidden, e não um código de erro.

Certificados e credenciais de teste

• Certificados de teste: arquivos PKCS #12 da ICP de testes da Lacuna, com senha 1234, só para desenvolvimento e homologação.
• O config/default.js do sample em Node.js vem com uma chave de API de avaliação (trial) para a instância em nuvem da Lacuna, que expira em 31/10/2026, e com o id de uma AC de exemplo; os modelos de configuração dos samples em Node.js e PHP pedem, em vez disso, a sua própria chave e o id da sua AC.
• Quando os samples deixam de funcionar, por exemplo depois que a chave deles expira, a configuração dos samples pede que você contate o suporte da Lacuna em suporte@lacunasoftware.com.

Experimente

Emita certificados de teste no site de demonstração ou rode os samples em Java, Node.js, PHP e Python:

Demonstrações e exemplos

• Demonstração: Issue an e-CNPJ certificate
• Demonstração: Issue an e-CPF certificate
• Demonstração: Issue an e-CPF with your face
• Demonstração: Issue an SSL/TLS certificate
• Issue a certificate with the key on the user's machine using Amplia: Java · Node.js · PHP · Python
• Issue a certificate with the key on the server using Amplia: Java · Node.js · PHP · Python
• Issue a PKCS #12 certificate using Amplia: Node.js
• Issue an attribute certificate using Amplia: PHP