---
title: "Criar pedidos de certificado"
description: "Como criar pedidos de certificado no Amplia pela API: endpoints por formato de certificado, campos comuns, parâmetros ICP-Brasil (e-CPF, e-CNPJ) e SSL/TLS, e leitura, alteração ou exclusão de pedidos."
canonical: "https://docs.lacunasoftware.com/articles/amplia/integration/orders"
locale: "pt-BR"
product: "Amplia"
last_updated: "2026-10-12"
---

# Criar pedidos de certificado

Todo certificado que o [Amplia](https://docs.lacunasoftware.com/articles/amplia) emite começa com um pedido: ele indica a AC que emite o certificado e guarda a validade do
certificado e os dados do titular. 
Um pedido gera um certificado: depois da emissão, o `status` do pedido é `Issued` e o `certificateId` dele aponta para o certificado. 
Veja [Antes de começar](https://docs.lacunasoftware.com/articles/amplia/integration#antes-de-começar) para a chave de API, o endpoint e o id da AC.

## Endpoints por formato de certificado

Cada formato de certificado tem o próprio endpoint, `POST /api/orders/{format}`, cujo corpo recebe os campos comuns abaixo mais um objeto
`parameters` daquele formato: 

| Formato | Endpoint | `parameters` |
|---|---|---|
| ICP-Brasil (e-CPF, e-CNPJ) | `POST /api/orders/pki-brazil` | `PkiBrazilCertificateParameters` |
| SSL/TLS | `POST /api/orders/ssl` | `SslCertificateParameters` |
| Carteira de Identificação Estudantil (CIE), um certificado de atributo | `POST /api/orders/cie` | `CieCertificateParameters` |
| PrivateID, um certificado de atributo | `POST /api/orders/private-id` | `PrivateIDCertificateParameters` |
| Paraguai | `POST /api/orders/pki-paraguay` | `PkiParaguayCertificateParameters` |
| Equador | `POST /api/orders/bce` | `EcuadorBceCertificateParameters` |
| Cabo Verde | `POST /api/orders/pki-cabo-verde` | `PkiCaboVerdeCertificateParameters` |
| Perfil personalizado | `POST /api/orders/custom` | `CustomCertificateParameters` |

A API também tem `POST /api/orders/latinus` e `POST /api/orders/br-laboral`, e um `POST /api/v2/orders` genérico, cujo `parameters` pode
ser de qualquer formato. 
TODO(docs): para que servem os formatos Latinus e BRLaboral.

As bibliotecas cliente escolhem o endpoint pela classe do objeto `parameters`. As quatro criam pedidos ICP-Brasil, SSL/TLS e CIE; o
cliente Node.js também cria pedidos do Paraguai, e o cliente Java, pedidos Latinus. Elas também enviam pedidos CNB e ARISP (e os clientes
Java e PHP, pedidos CNB CA) para `api/orders/cnb`, `api/orders/arisp` e `api/orders/cnb-ca`, que a descrição OpenAPI não lista. 
O Amplia 5.0.1 atende esses três endpoints, com `CnbCertificateParameters`, `CnbCACertificateParameters` e
`ArispCertificateParameters`. 
TODO(docs): os parâmetros dos pedidos CNB, CNB CA e ARISP (veja [Colégio Notarial do Brasil - Atribuição de OIDs](https://docs.lacunasoftware.com/articles/asn1-cnb) e [ARISP - Estruturas ASN.1](https://docs.lacunasoftware.com/articles/asn1-arisp) para esses certificados).

## Campos comuns

| Campo | Significado |
|---|---|
| `caId` | Id da AC que emite o certificado. |
| `templateId` | Id do modelo (perfil de certificado) a aplicar. |
| `kind` | `PublicKey` ou `Attribute`. |
| `parameters` | Os dados do titular, no formato do endpoint. Obrigatório. |
| `validityEnd`, `validityStart` | Datas até e a partir das quais o certificado é válido. |
| `validity` | Validade como intervalo de tempo: as chamadas gravadas das demos enviam `"365.00:00:00"` para um ano e `"90.00:00:00"` para 90 dias. |
| `digestAlgorithm` | `SHA1`, `SHA256`, `SHA384` ou `SHA512`. |
| `serialNumber` | Um número de série predefinido para o certificado. |
| `policyOid`, `policyStatementUrl`, `policyUserNotices`, `policies` | Políticas de certificado a incluir. |
| `issuePendingApproval` | Booleano; as chamadas gravadas das demos enviam `false`. |

* Os samples em Node.js e Python enviam `validityEnd` como data no padrão `MM-DD-YYYY`, dois anos depois da data atual. 
* Um pedido sem validade, em um modelo que não tem validade padrão, é recusado. 
* As bibliotecas cliente só enviam `caId`, `templateId`, `kind`, `parameters`, `validityEnd` e um campo para copiar de um certificado;
  para definir os demais campos, chame a API diretamente. O cliente Java formata `validityEnd` como `MM-dd-yyyy`. 
* TODO(docs): o que fazem `issuePendingApproval` e `copyFromCertificate`, e como um certificado pendente de aprovação é aprovado (`POST /api/certificates/{id}/approval`).

## Certificados ICP-Brasil (e-CPF e e-CNPJ)

`PkiBrazilCertificateParameters` exige `name` e `cpf`. Os demais campos incluem `emailAddress`, `birthDate`, `phoneNumber`, `cnpj` e
`companyName` para um e-CNPJ, os números de RG e OAB, `nis`, `cei`, `organization`, `organizationalUnits` e `country`. 

* `phoneNumber` é necessário quando o titular emite o certificado na página de emissão do Amplia, que envia a ele um código de confirmação
  por SMS. 
* O Amplia tira o subject do certificado desses parâmetros, nunca de um CSR: coloque a identidade aqui, com o CPF e o CNPJ sem máscara e
  os nomes sem acentos. 
* `normalizeCommonName` e `appendIdentifierToCommonName` normalizam o Common Name (CN=) e acrescentam a ele o CPF ou o CNPJ. 
* Nas chamadas gravadas das demos, um pedido com CPF volta com `certificateType` `e-CPF`, e um que também tem `cnpj` e `companyName`
  volta como `e-CNPJ`. 
* Os clientes Node.js, PHP e Python enviam as unidades organizacionais como `organizationUnits`, enquanto o campo da API é
  `organizationalUnits`; o cliente Java usa o nome da API. 

Os samples criam um pedido de e-CPF só com o nome e o CPF: 

**Node.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);
```

**Java**

```java
AmpliaClient client = Util.getAmpliaClient();
CreateOrderRequest<PkiBrazilCertificateParameters> createOrderRequest = new CreateOrderRequest<>();
createOrderRequest.setCAId(ApplicationProperties.getInstance().getAmplia().getCaId());
createOrderRequest.setValidityEnd(Util.getDateYearsFromNow(2));
createOrderRequest.setKind(CertificateKinds.PUBLIC_KEY);
PkiBrazilCertificateParameters parameters = new PkiBrazilCertificateParameters();
parameters.setName(request.getSubjectName());
parameters.setCpf(request.getCpf());
createOrderRequest.setParameters(parameters);
Order order = client.createOrder(createOrderRequest);
```

**PHP**

```php
use Lacuna\Amplia\CreateOrderRequest;
use Lacuna\Amplia\CertificateKinds;
use Lacuna\Amplia\PkiBrazilCertificateParameters;

$client = Util::getAmpliaClient();
$createOrderRequest = new CreateOrderRequest();
$createOrderRequest->caId = getConfig()['amplia']['caId'];
$createOrderRequest->validityEnd = Util::getDateYearsFromNow(2);
$createOrderRequest->kind = CertificateKinds::PUBLIC_KEY;
$parameters = new PkiBrazilCertificateParameters();
$parameters->name = $subjectName;
$parameters->cpf = $cpf;
$createOrderRequest->parameters = $parameters;
$order = $client->createOrder($createOrderRequest);
```

**Python**

```python
from amplia_client import CreateOrderRequest, CertificateKinds, PkiBrazilCertificateParameters

client = get_amplia_client()
req = CreateOrderRequest()
req.ca_id = current_app.config['AMPLIA_CA_ID']
req.validity_end = get_two_years_from_now_date()
req.kind = CertificateKinds.PUBLIC_KEY
parameters = PkiBrazilCertificateParameters()
parameters.name = request.form['subjectName']
parameters.cpf = request.form['cpf']
req.parameters = parameters
order = client.create_order(req)
```

Por HTTP, a demo de e-CPF envia este corpo para `POST /api/orders/pki-brazil` (dados pessoais mascarados). O cliente dela serializa os
enums como números (`"Format": 1`, `"Kind": 1`), enquanto a resposta os traz pelo nome (`"format": "PkiBrazil"`, `"kind": "PublicKey"`): 

```json
{
  "Parameters": {
    "Format": 1,
    "Name": "(DEMO) Diego Rocha Gomes",
    "EmailAddress": "someone@example.com",
    "Cpf": "***.***.***-**",
    "BirthDate": "1988-12-06T00:00:00",
    "OrganizationalUnits": [
      "Lab"
    ],
    "Organization": "Lacuna Software Demo",
    "Country": "BR",
    "PhoneNumber": "+55 ** *****-****"
  },
  "CAId": "00000000-0000-0000-0000-000000000000",
  "Kind": 1,
  "Validity": "365.00:00:00",
  "IssuePendingApproval": false
}
```

## Certificados SSL/TLS

`SslCertificateParameters` traz `dnsNames`, `subjectName`, `keyUsages`, `extendedKeyUsages`, `qualifiedStatements` e
`organizationIdentifier`.  Os certificados SSL/TLS do Amplia seguem as
diretrizes do CA/Browser Forum e aceitam nomes curinga (wildcard) e endereços IP além de nomes DNS comuns. 

Os nomes DNS e o subject vêm do pedido, nunca do CSR: a demo de SSL/TLS define explicitamente os nomes DNS, o subject, os usos de chave
`DigitalSignature` e `KeyEncipherment` e o uso estendido `ServerAuth`. Ela envia este corpo para `POST /api/orders/ssl` e depois
[emite o certificado a partir de um CSR](https://docs.lacunasoftware.com/articles/amplia/integration/issue-from-csr): 

```json
{
  "Parameters": {
    "Format": 2,
    "DnsNames": [
      "www.example.com"
    ],
    "SubjectName": {
      "Organization": "Lacuna Software Demo",
      "CommonName": "www.example.com",
      "OrganizationalUnits": [
        "Lab"
      ]
    },
    "KeyUsages": [
      3,
      7
    ],
    "ExtendedKeyUsages": [
      1
    ]
  },
  "CAId": "00000000-0000-0000-0000-000000000000",
  "Kind": 1,
  "Validity": "90.00:00:00",
  "IssuePendingApproval": false
}
```

A demo verifica os nomes DNS antes de chamar o Amplia (de 1 a 10 nomes, em minúsculas, `*` só como o rótulo inteiro mais à esquerda,
sem endereços IP) e traduz os códigos de erro `BadDnsName` e `BadCsr` do Amplia em mensagens próprias. 
Esses limites são da demo: o próprio Amplia aceita endereços IP. 
O `SslCertificateParameters` dos clientes Node.js e PHP só define `dnsNames`. 

## Ler, alterar e excluir pedidos

| Operação | Endpoint |
|---|---|
| Ler um pedido | `GET /api/orders/{id}`; `GET /api/v2/orders/{id}` também devolve o `parameters` dele |
| Ler um pedido com os parâmetros do formato | `GET /api/orders/{format}/{id}`, por exemplo `GET /api/orders/pki-brazil/{id}` |
| Alterar um pedido | `PUT /api/orders/{format}/{id}` |
| Excluir um pedido | `DELETE /api/orders/{id}` |
| Listar pedidos | `GET /api/orders`, com `Q`, `Limit`, `Offset`, `Cursor` e `Order` (`Asc`, `Desc`) |

* O `status` de um pedido é `Pending`, `Locked` ou `Issued`, e `canEdit` e `canDelete` dizem se ele ainda pode ser alterado ou excluído;
  um pedido já emitido não pode ser excluído. 
* `keyMediaConstraints` lista as [mídias da chave](https://docs.lacunasoftware.com/articles/amplia/integration/issue-from-csr#mídia-da-chave) em que o pedido pode ser emitido. 
* Pedidos bloqueados podem ser vistos e desbloqueados no dashboard, e a API tem `PUT /api/orders/{id}/unlock-request`. 
  TODO(docs): o que bloqueia um pedido e o que a requisição de desbloqueio faz.

## Próximos passos

* [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)