---
title: "Referência rápida do Amplia"
description: "O Amplia em uma página: para que serve, pacotes cliente, chave de API e endpoint, chamadas de pedido e emissão, erros e ambiente de teste."
canonical: "https://docs.lacunasoftware.com/articles/amplia/quick-reference"
locale: "pt-BR"
product: "Amplia"
last_updated: "2026-10-12"
---

# 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](https://docs.lacunasoftware.com/articles/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](https://docs.lacunasoftware.com/articles/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](https://docs.lacunasoftware.com/articles/grant-id) | 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](https://docs.lacunasoftware.com/articles/pki-sdk/quick-reference) | 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](https://docs.lacunasoftware.com/articles/rest-pki/quick-reference) ou [Signer](https://docs.lacunasoftware.com/articles/signer/quick-reference) | 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](https://www.nuget.org/packages/Lacuna.Amplia.Client) |
| Java | `com.lacunasoftware.amplia:amplia-client` | 1 | [Maven Central](https://central.sonatype.com/artifact/com.lacunasoftware.amplia/amplia-client) |
| Node.js | `amplia-client` | 1 | [npm](https://www.npmjs.com/package/amplia-client) |
| PHP | `lacuna/amplia-client` | 1 | [Packagist](https://packagist.org/packages/lacuna/amplia-client) |
| Python | `amplia-client` | 1 | [PyPI](https://pypi.org/project/amplia-client/) |

* 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](https://docs.lacunasoftware.com/articles/amplia/integration#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](https://docs.lacunasoftware.com/articles/amplia/integration#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](https://docs.lacunasoftware.com/articles/amplia/on-premises#dashboard-domain) 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](https://docs.lacunasoftware.com/articles/amplia/integration#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: 

```js
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](https://github.com/LacunaSoftware/PkiSuiteSamples); os blocos seguintes usam o `order` criado no primeiro.

O [guia de integração](https://docs.lacunasoftware.com/articles/amplia/integration) 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](https://docs.lacunasoftware.com/articles/amplia/integration/orders). Sample completo: [issue-cert-server-amplia.js](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/nodejs/expressmvc/routes/issue-cert-server-amplia.js).

```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](https://docs.lacunasoftware.com/articles/amplia/integration/issue-on-user-machine). Sample completo: [issue-cert-user-amplia.js](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/nodejs/expressmvc/routes/issue-cert-user-amplia.js).

```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](https://docs.lacunasoftware.com/articles/amplia/integration/issue-on-user-machine#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](https://docs.lacunasoftware.com/articles/amplia/integration/issue-from-csr). Sample completo: [issue-cert-server-amplia.js](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/nodejs/expressmvc/routes/issue-cert-server-amplia.js).

```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](https://docs.lacunasoftware.com/articles/amplia/integration/pkcs12). Sample completo: [issue-pkcs12-cert-server-amplia.js](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/nodejs/expressmvc/routes/issue-pkcs12-cert-server-amplia.js).

```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](https://docs.lacunasoftware.com/articles/amplia/integration/attribute-certificates). O único sample é em PHP: [complete.php](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/php/plain/public/issue-cert-attribute-amplia/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](https://docs.lacunasoftware.com/articles/amplia/on-premises#access-domains) e pode responder a requisições [OCSP](https://docs.lacunasoftware.com/articles/amplia/on-premises/configure-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](https://docs.lacunasoftware.com/articles/amplia/integration/revocation). 

**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](https://docs.lacunasoftware.com/articles/amplia/integration/errors#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](https://docs.lacunasoftware.com/articles/pki-guide/test-certs): 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](https://try.lacunasoftware.com/pt/amplia/issue-e-cnpj-certificate)
- Demonstração: [Issue an e-CPF certificate](https://try.lacunasoftware.com/pt/amplia/issue-e-cpf-certificate)
- Demonstração: [Issue an e-CPF with your face](https://try.lacunasoftware.com/pt/amplia/issue-an-ecpf-with-your-face)
- Demonstração: [Issue an SSL/TLS certificate](https://try.lacunasoftware.com/pt/amplia/issue-ssl-tls-certificate)
- Issue a certificate with the key on the user's machine using Amplia: [Java](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/java/springmvc/src/main/java/com/lacunasoftware/pkisuite/controller/IssueCertUserAmpliaController.java) · [Node.js](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/nodejs/expressmvc/routes/issue-cert-user-amplia.js) · [PHP](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/php/plain/public/issue-cert-user-amplia/index.php) · [Python](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/python/flask/sample/views/issue_cert_user_amplia.py)
- Issue a certificate with the key on the server using Amplia: [Java](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/java/springmvc/src/main/java/com/lacunasoftware/pkisuite/controller/IssueCertServerAmpliaController.java) · [Node.js](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/nodejs/expressmvc/routes/issue-cert-server-amplia.js) · [PHP](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/php/plain/public/issue-cert-server-amplia/index.php) · [Python](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/python/flask/sample/views/issue_cert_server_amplia.py)
- Issue a PKCS #12 certificate using Amplia: [Node.js](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/nodejs/expressmvc/routes/issue-pkcs12-cert-server-amplia.js)
- Issue an attribute certificate using Amplia: [PHP](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/php/plain/public/issue-cert-attribute-amplia/index.php)