Guia de integração - Amplia

O seu sistema pode criar pedidos de certificado e emitir certificados pela API REST do Amplia, enquanto os operadores gerenciam ACs, modelos e pedidos no dashboard. Este guia cobre as chamadas da API; para um resumo em uma página, veja a referência rápida do Amplia.

Antes de começar

Você precisa de três valores:

• 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, crie uma aplicação e uma chave de API no dashboard do Amplia.
• 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 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.
• Id da AC: o id da AC que emite os certificados, enviado como caId ao criar um pedido. Os samples o guardam na configuração, ao lado da chave de API; o sample de certificado de atributo usa uma segunda AC, já que certificados de atributo precisam de uma AC configurada para eles. Os comentários dos samples acrescentam que uma aplicação pode ter uma AC padrão e, nesse caso, caId pode ser omitido. TODO(docs): onde se define a AC padrão de uma aplicação.

A API observa o header Accept-Language (en-US ou pt-BR), que também define o idioma dos links de emissão que ela devolve; as mensagens de erro não são afetadas por ele.

Criar uma aplicação e uma chave de API

O seu sistema chama a API como uma aplicação de uma conta do Amplia, com um papel que define o que ela pode fazer:

1. Entre no dashboard do Amplia e clique em Aplicações no menu lateral, depois em Adicionar.
2. Preencha um nome, selecione a conta na qual os certificados são emitidos e marque o papel da aplicação (veja abaixo), depois clique em Criar.
3. Clique em Chaves, depois em Adicionar. Preencha uma descrição e uma expiração, depois clique em Criar.
4. Copie a chave de API: ela não pode ser recuperada depois.

Papel	Criar pedidos, pedir ao Amplia que envie o link de emissão por e-mail ou SMS, revogar	Obter o link de emissão ou o QR code, emitir certificados	Configuração de webhook
Operador (Worker)	Sim	Sim	Não
Agente de Registro (Registration Agent)	Sim	Não	Não
Gerente (Manager), Administrador (Admin)	Sim	Sim	Sim

Um sistema que executa o fluxo inteiro precisa do papel Operador, o mesmo que o Amplia Reg usa. Uma aplicação com o papel Agente de Registro pode criar pedidos e enviar o link de emissão ao titular por e-mail ou SMS, mas não pode ler o link nem emitir o certificado ela mesma.

Bibliotecas cliente

Qualquer cliente HTTP pode chamar a API, cuja descrição OpenAPI está em https://docs.lacunasoftware.com/openapi/amplia.json. A Lacuna publica bibliotecas cliente, que os samples usam:

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

As majors dos clientes não acompanham a versão do Amplia: todo endpoint que os clientes 1.x abaixo chamam é atendido pelo Amplia 5.0.1. O cliente .NET é descrito mais abaixo.

Os clientes Java (1.2.1), Node.js (1.3.3), PHP (1.3.0) e Python (1.0.0) encapsulam estas chamadas:

Operação	Node.js, Java, PHP	Python	Endpoint
Criar um pedido	createOrder	create_order	POST /api/orders/{format}
Ler um pedido	getOrder	get_order	GET /api/v2/orders/{id} (Java: GET /api/orders/{format}/{id})
Obter o link de emissão	getOrderIssueLink	get_order_issue_link	GET /api/orders/{id}/issue-link
Emitir a partir de um CSR	issueCertificate	issue_certificate	POST /api/v2/certificates
Emitir um arquivo PKCS #12	issuePkcs12Certificate (só Node.js)		POST /api/certificates/pkcs12
Revogar um certificado	revokeCertificate	revoke_certificate	DELETE /api/certificates/{id}

Nenhum dos quatro envia o link de emissão por e-mail ou SMS nem lê o QR code dele: chame esses endpoints diretamente, ou use o cliente .NET (veja Outras formas de entregar o link de emissão).

Cada sample cria o cliente a partir do endpoint e da chave de API:

Node.js

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

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

Java

import com.lacunasoftware.amplia.AmpliaClient;

public static AmpliaClient getAmpliaClient() {
	String apiKey = getProperties().getAmplia().getApiKey();
	String endpoint = getProperties().getAmplia().getEndpoint();
	if (endpoint == null || endpoint.length() == 0) {
		endpoint = "https://amplia.lacunasoftware.com/";
	}
	return new AmpliaClient(endpoint, apiKey);
}

PHP

use Lacuna\Amplia\AmpliaClient;

public static function getAmpliaClient()
{
    $config = getConfig();
    $ampliaApiKey = $config['amplia']['apiKey'];
    $ampliaEndpoint = $config['amplia']['endpoint'];
    return new AmpliaClient($ampliaEndpoint, $ampliaApiKey);
}

Python

from amplia_client import AmpliaClient

def get_amplia_client():
    api_key = current_app.config['AMPLIA_API_KEY']
    endpoint = current_app.config['AMPLIA_ENDPOINT']
    return AmpliaClient(endpoint, api_key)

Cliente .NET

O Lacuna.Amplia.Client 5.0.0 tem como alvo o .NET Standard 2.0 e é gerado a partir do mesmo código-fonte do Amplia 5.0.1. Obtenha um IAmpliaService por injeção de dependência, depois de services.AddAmplia(...), ou de AmpliaServicesFactory.GetService(endpoint, apiKey); a classe AmpliaClient ainda funciona, mas está marcada como [Obsolete].

using Lacuna.Amplia.Api;
using Lacuna.Amplia.Api.CertificateFormatting;
using Lacuna.Amplia.Api.Orders;
using Lacuna.Amplia.Client;

IAmpliaService amplia = AmpliaServicesFactory.GetService("https://amplia.lacunasoftware.com/", apiKey);

var order = await amplia.CreateOrderAsync(new CreateOrderRequest2<PkiBrazilCertificateParameters> {
	CAId = caId,
	Kind = CertificateKinds.PublicKey,
	ValidityEnd = DateTimeOffset.Now.AddYears(2),
	Parameters = new PkiBrazilCertificateParameters {
		Name = subjectName,
		Cpf = cpf,
		PhoneNumber = phoneNumber,
	},
});
string issueLink = await amplia.GetOrderIssueLinkAsync(order.Id, returnUrl);

No ASP.NET Core, services.AddAmplia(o => { o.Endpoint = …; o.ApiKey = …; }), ou services.AddAmplia().Configure(configuration.GetSection("Amplia")), registra o IAmpliaService; AmpliaOptions também tem Timeout, Culture (enviado como Accept-Language) e DefaultSubscriptionId.

Operação	Método .NET	Endpoint
Criar um pedido	CreateOrderAsync	POST /api/orders/{format} (POST /api/v2/orders para a requisição não genérica)
Ler um pedido	GetOrderAsync	GET /api/v2/orders/{id}
Obter o link de emissão	GetOrderIssueLinkAsync	GET /api/orders/{id}/issue-link
Enviar o link de emissão por e-mail ou SMS	SendIssueEmailAsync, SendIssueSmsAsync	POST /api/orders/{id}/send-issue-email-request, POST /api/v2/orders/{id}/send-issue-sms-request
Obter o QR code	GetOrderIssueQRCodeDataAsync, GetOrderIssueQRCodeImageAsync	GET /api/orders/{id}/issue-qrcode-data, issue-qrcode-image
Emitir a partir de um CSR	IssueCertificateAsync	POST /api/v2/certificates
Emitir um arquivo PKCS #12	IssuePkcs12CertificateAsync	POST /api/certificates/pkcs12
Ler um certificado	GetCertificateAsync	GET /api/v2/certificates/{id}
Revogar um certificado	RevokeCertificateAsync	DELETE /api/certificates/{id}

Erros de API (422) lançam AmpliaException, cujo Code é o código de erro, ou OrderLockedException quando o código é OrderLocked.

Como a emissão funciona

Todo certificado começa com um pedido em uma AC, que guarda os dados do titular e a validade do certificado. Depois, o pedido é atendido, emitindo um certificado, de uma destas formas:

Onde o par de chaves é gerado	Como emitir	Artigo
No computador do titular, pela página de emissão do Amplia	Envie ao titular um link de emissão	Emitir na máquina do titular
No seu servidor, ou no navegador do usuário com o Web PKI	Envie ao Amplia um CSR	Emitir a partir de um CSR
Pelo Amplia, que o devolve em um arquivo protegido por senha	Peça um PKCS #12 (.pfx)	Emitir um arquivo PKCS #12
Sem par de chaves: o certificado atesta um atributo do titular	Emita sem CSR	Certificados de atributo

Comece por Criar pedidos de certificado. Depois:

• Emitir na máquina do titular
• Emitir a partir de um CSR
• Emitir um arquivo PKCS #12
• Certificados de atributo
• Revogar certificados
• Erros

Webhook

O Amplia pode avisar o seu sistema sempre que um certificado for emitido: o corpo da notificação é um WebhookEventModel cujo type é OrderCertificateIssued, com o order e, depois da emissão, o certificate.

O webhook pertence à conta. Um usuário com o papel Administrador ou Gerente o define no dashboard, em Configurações > Configuração de webhook:

• Habilitar webhook, a URL para a qual o Amplia envia a notificação e o Tipo de autenticação, que define o header que o Amplia envia com cada notificação:

  Tipo de autenticação	Header
  NoAuth	Nenhum header de autenticação
  Bearer	Authorization: Bearer <token>
  ApiKey	X-Api-Key: <chave>
  CustomAuthorizationHeader	Authorization: <esquema> <valor>
  Basic	Authorization: Basic <valor> (veja o aviso abaixo)

• A aba Chamadas recentes lista as notificações enviadas, com o código de status e, nas chamadas que falharam, a resposta.

O Amplia envia um POST com um corpo JSON e considera entregue qualquer resposta 2xx. O JSON mantém os nomes de propriedade dos modelos do Amplia, em PascalCase (Type, Order, Certificate), com os enums por nome:

{
  "Type": "OrderCertificateIssued",
  "Order": { "Id": "…", "Status": "Issued", "CertificateId": "…" },
  "Certificate": { "Id": "…" }
}

Autenticação Basic

Com Basic, o dashboard codifica o nome de usuário e a senha separadamente e os une com dois-pontos, base64(usuário):base64(senha), em vez do padrão base64(usuário:senha). Um tratador de autenticação Basic padrão rejeita esse valor, então prefira Bearer, ApiKey ou CustomAuthorizationHeader.

TODO(docs): se e com que frequência o Amplia tenta de novo uma notificação que falhou.

Veja também

• Referência rápida do Amplia
• Guia de operação
• Changelog