---
title: "Guia de integração - Amplia"
description: "Guia de integração da API do Amplia: chave de API, endpoint e bibliotecas cliente, depois os fluxos de emissão (link de emissão, CSR, PKCS #12, certificados de atributo), revogação e erros."
canonical: "https://docs.lacunasoftware.com/articles/amplia/integration"
locale: "pt-BR"
product: "Amplia"
last_updated: "2026-10-12"
---

# Guia de integração - Amplia

O seu sistema pode criar pedidos de certificado e emitir certificados pela API REST do [Amplia](https://docs.lacunasoftware.com/articles/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](https://docs.lacunasoftware.com/articles/amplia/quick-reference).

## 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](https://docs.lacunasoftware.com/articles/amplia/integration#criar-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](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.
* **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*.
1. 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*.
1. Clique em **Chaves**, depois em *Adicionar*. Preencha uma descrição e uma expiração, depois clique em *Criar*.
1. 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](https://docs.lacunasoftware.com/articles/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](https://www.nuget.org/packages/Lacuna.Amplia.Client) |
| Java | `com.lacunasoftware.amplia:amplia-client` | [Maven Central](https://central.sonatype.com/artifact/com.lacunasoftware.amplia/amplia-client) |
| Node.js | `amplia-client` | [npm](https://www.npmjs.com/package/amplia-client) |
| PHP | `lacuna/amplia-client` | [Packagist](https://packagist.org/packages/lacuna/amplia-client) |
| Python | `amplia-client` | [PyPI](https://pypi.org/project/amplia-client/) |

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](https://docs.lacunasoftware.com/articles/amplia/integration#cliente-net).

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](https://docs.lacunasoftware.com/articles/amplia/integration/issue-on-user-machine#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**

```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**

```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**

```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**

```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]`. 

```csharp
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](https://docs.lacunasoftware.com/articles/amplia/integration/issue-on-user-machine) |
| No seu servidor, ou no navegador do usuário com o Web PKI | Envie ao Amplia um CSR | [Emitir a partir de um CSR](https://docs.lacunasoftware.com/articles/amplia/integration/issue-from-csr) |
| Pelo Amplia, que o devolve em um arquivo protegido por senha | Peça um PKCS #12 (.pfx) | [Emitir um arquivo PKCS #12](https://docs.lacunasoftware.com/articles/amplia/integration/pkcs12) |
| Sem par de chaves: o certificado atesta um atributo do titular | Emita sem CSR | [Certificados de atributo](https://docs.lacunasoftware.com/articles/amplia/integration/attribute-certificates) |

Comece por [Criar pedidos de certificado](https://docs.lacunasoftware.com/articles/amplia/integration/orders). Depois:

* [Emitir na máquina do titular](https://docs.lacunasoftware.com/articles/amplia/integration/issue-on-user-machine)
* [Emitir a partir de um CSR](https://docs.lacunasoftware.com/articles/amplia/integration/issue-from-csr)
* [Emitir um arquivo PKCS #12](https://docs.lacunasoftware.com/articles/amplia/integration/pkcs12)
* [Certificados de atributo](https://docs.lacunasoftware.com/articles/amplia/integration/attribute-certificates)
* [Revogar certificados](https://docs.lacunasoftware.com/articles/amplia/integration/revocation)
* [Erros](https://docs.lacunasoftware.com/articles/amplia/integration/errors)

## 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: 

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

> **Cuidado: 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](https://docs.lacunasoftware.com/articles/amplia/quick-reference)
* [Guia de operação](https://docs.lacunasoftware.com/articles/amplia/operation)
* [Changelog](https://docs.lacunasoftware.com/articles/amplia/changelog)