---
title: "Criação de pedidos pré-aprovados - Amplia Reg"
description: "Como criar pedidos pré-aprovados no Amplia Reg, para autoridades de registro eletrônicas: o pedido nasce aprovado, sem validação nem conferência."
canonical: "https://docs.lacunasoftware.com/articles/amplia-reg/integration/preapproved-orders"
locale: "pt-BR"
product: "Amplia Reg"
last_updated: "2026-10-08"
---

# Criação de pedidos pré-aprovados - Amplia Reg

Um pedido pré-aprovado é um pedido que já nasce aprovado. Ele se destina a autoridades de registro eletrônicas: sistemas que validam a
identidade do titular por conta própria, fora do [Amplia Reg](https://docs.lacunasoftware.com/articles/amplia-reg), e só precisam que o certificado seja emitido.

Um pedido pré-aprovado não passa pela validação nem pela conferência. Ele começa em **Aguardando emissão** (`WaitingIssue`), e o titular
emite o certificado pelo link de emissão, como em qualquer outro pedido. Veja [Como funciona a emissão de certificados](https://docs.lacunasoftware.com/articles/amplia-reg/issuance#4-emissão)
para saber o que acontece durante a emissão.

> **Dica**
>
> Certifique-se de que já realizou os [Primeiros passos](https://docs.lacunasoftware.com/articles/amplia-reg/integration/get-started)

## Antes de começar

* **Papel**: a aplicação precisa ter o papel **Autoridade de registro eletrônica**. Esse papel cria pedidos pré-aprovados e obtém as
  chaves de emissão deles. Ele não cria pedidos comuns.
* **Autoridade de registro**: pedidos pré-aprovados são sempre criados em uma autoridade de registro, e o tipo de certificado precisa
  pertencer à mesma autoridade certificadora dessa autoridade de registro. Para escolher a autoridade de registro, informe o ID dela no
  header `X-Subscription` (em .NET, a opção `RegistrationAuthorityId`). Se a API devolver o erro `SubscriptionRequired`, a requisição não
  indicou uma autoridade de registro.
* **Tipo de certificado**: liste os tipos de certificado disponíveis como descrito em [Criação de pedido](https://docs.lacunasoftware.com/articles/amplia-reg/integration/create-order) e anote o
  código do tipo desejado.

## Criando o pedido

Os exemplos abaixo criam um pedido de e-CPF no padrão ICP-Brasil. Veja [Outros formatos de certificado](https://docs.lacunasoftware.com/articles/amplia-reg/integration/preapproved-orders#outros-formatos-de-certificado)
para os demais formatos.

Em .NET:

```cs
var response = await ampliaRegService.CreatePreApprovedOrderAsync(new CreatePreApprovedOrderOptions2<CreatePreApprovedOrderBrazilParameters>() {
	CertificateType = CertificateTypeReference.FromCode("ECPFA1"), // Código do tipo de certificado
	HolderType = HolderTypeReference.FromCode("PF"), // Código do tipo de titular (veja "Documentos do titular" abaixo)
	Validity = PeriodModel.FromYears(1), // Validade do certificado (o tipo de certificado precisa permiti-la)
	Parameters = new CreatePreApprovedOrderBrazilParameters() {
		Cpf = "07917307000", // CPF do titular, só dígitos
		Name = "Nome do Titular", // Nome completo do titular
	},
	Contact = new ContactData() {
		EmailAddress = "titular@example.com",
		Phone = "+5511999990000",
	},
	HolderFiles = new List<HolderFileReference2>() {
		new HolderFileReference2() {
			Type = "Identification",
			Subtype = HolderFileSubtypes.Cnh,
			DocumentPart = DocumentParts.FrontComplete,
			File = FileReference.FromFile(@"C:\AppData\Documents\cnh.pdf"),
		},
	},
	NotifySubject = true, // O Amplia Reg envia a chave de emissão 2 ao titular por e-mail e SMS
});
```

A client lib .NET faz o upload dos arquivos por você. Veja [Referenciando arquivos](https://docs.lacunasoftware.com/articles/amplia-reg/integration/file-referencing) para as formas de referenciar um
arquivo.

Via API, faça primeiro o upload de cada arquivo com uma requisição `multipart/form-data` contendo os campos `file`, `name` e
`contentType`:

```plaintext
POST /api/uploads
```

A resposta traz o `id` do upload. Em seguida, crie o pedido referenciando os arquivos enviados:

```js
POST /api/brazil/orders/pre-approved
X-Subscription: 3fa85f64-5717-4562-b3fc-2c963f66afa6 // ID da autoridade de registro
{
	"certificateType": {
		"code": "ECPFA1" // Código do tipo de certificado
	},
	"holderType": {
		"code": "PF" // Código do tipo de titular
	},
	"validity": {
		"years": 1 // Validade do certificado (o tipo de certificado precisa permiti-la)
	},
	"parameters": {
		"cpf": "07917307000", // CPF do titular, só dígitos
		"name": "Nome do Titular" // Nome completo do titular
	},
	"contact": {
		"emailAddress": "titular@example.com",
		"phone": "+5511999990000"
	},
	"holderFiles": [
		{
			"type": "Identification",
			"subtype": "Cnh",
			"documentPart": "FrontComplete",
			"file": {
				"id": "0195a9dc-c0f0-4f5c-83d3-bf562ae98ed9", // ID devolvido pelo upload
				"name": "cnh.pdf",
				"contentType": "application/pdf"
			}
		}
	],
	"notifySubject": true // O Amplia Reg envia a chave de emissão 2 ao titular por e-mail e SMS
}
```

### Campos da requisição

| Campo | Obrigatório | Descrição |
|---|---|---|
| `certificateType` | Sim | Tipo de certificado, por `code` ou `id` |
| `holderType` | Depende | Tipo de titular, por `code` ou `id`. Obrigatório quando o tipo de certificado tem a etapa de documentos habilitada e aceita mais de um tipo de titular. Não é permitido quando a etapa de documentos está desabilitada |
| `validity` | Depende | Validade do certificado. Obrigatória quando o tipo de certificado tem mais de uma opção de validade |
| `parameters` | Sim | Dados do titular. No padrão ICP-Brasil: `cpf` e `name` e, opcionalmente, `annotation` (até 100 caracteres), que entra em uma unidade organizacional do certificado quando o tipo de certificado está configurado para incluí-la |
| `contact` | Sim | `emailAddress` e `phone` do titular e, opcionalmente, `alternativeEmailAddress` e `alternativePhone` |
| `holderFiles` | Depende | Documentos do titular. Veja [Documentos do titular](https://docs.lacunasoftware.com/articles/amplia-reg/integration/preapproved-orders#documentos-do-titular) |
| `notifySubject` | Não | Se `true`, o Amplia Reg envia a chave de emissão 2 e o link de emissão ao titular por e-mail e SMS. O padrão é `false` |
| `number` | Não | Número do pedido de sua escolha (até 50 caracteres). Só é permitido se a instância tiver números de pedido personalizados habilitados; precisa ser único |
| `saleNumber` | Não | Número do pedido no seu sistema de vendas (até 50 caracteres). Permitido, ou obrigatório, conforme as configurações da instância. Não está disponível nas opções da client lib .NET |
| `csr` | Não | Requisição de certificado (PKCS #10), quando o par de chaves já foi gerado. O tamanho da chave precisa ser o do tipo de certificado. Com uma CSR, a página de emissão não gera um novo par de chaves |
| `csrFileName` | Não | Nome do arquivo da CSR |

> **Observação**
>
> O CPF deve ser informado sem pontuação (só dígitos) e com os zeros à esquerda, se houver.

### Documentos do titular

Quando o tipo de certificado tem a etapa de documentos habilitada, o pedido tem um tipo de titular, e é o tipo de titular que define
quais documentos são obrigatórios e quais são opcionais. Envie todos os documentos obrigatórios. Se o tipo de certificado também tiver a
etapa de biometria habilitada, um documento do tipo `Photo` também é obrigatório.

Cada documento tem:

* `type`: o tipo do documento, como `Identification`, `AddressProof` ou `Photo`. Tipos de documento personalizados, configurados na
  instância, levam o prefixo `@` (por exemplo, `@CustomDoc1`). Veja [Adicionando tipos de documento](https://docs.lacunasoftware.com/articles/amplia-reg/on-premises/add-doc-types).
* `subtype` e `documentPart` (opcionais): no padrão ICP-Brasil, um documento `Identification` pode indicar qual documento é (`Rg`, `Cnh`,
  `Dni`, `CTPS`, `Passport`, `RNE`, `CIN`, `OAB`, `CRC`, `CRM`, `ProfessionalLicense` ou `Undefined`). Quando `subtype` é informado,
  `documentPart` é obrigatório: `FrontComplete` ou `BackComplete` e, para todos os subtipos exceto `Rg`, `RNE` e `Undefined`, também
  `Digital`.
* `file`: o arquivo em si.

Quando o tipo de certificado tem a etapa de documentos desabilitada, não envie `holderFiles` nem `holderType`.

O Amplia Reg coloca os documentos no dossiê do pedido. Se a instância tiver um certificado de selo configurado, o Amplia Reg assina com
ele o dossiê e o termo de titularidade.

## Resposta

```js
{
	"orderNumber": "800-005-520",
	"issueKey1": "48210937",
	"issueKey2": "77302156",
	"issueLink": "https://ar.example.com/issue?o=800-005-520",
	"issueLinkWithKey1": "https://ar.example.com/issue?o=800-005-520&k1=48210937",
	"issueLinkWithKeys": "https://ar.example.com/issue?o=800-005-520&k1=48210937&k2=77302156"
}
```

| Campo | Descrição |
|---|---|
| `orderNumber` | Número do pedido criado |
| `issueKey1`, `issueKey2` | As duas chaves de emissão. Se a instância usar uma única chave de emissão, `issueKey1` é `null` |
| `issueLink` | Link de emissão sem chaves: o titular digita as duas chaves |
| `issueLinkWithKey1` | Link de emissão com a chave 1 preenchida: o titular digita só a chave 2 |
| `issueLinkWithKeys` | Link de emissão com as duas chaves preenchidas: o titular não digita nada |

### Entregando o link de emissão ao titular

O titular precisa do link de emissão e das duas chaves. Escolha como ele os recebe:

* **Divididos em dois canais (recomendado)**: defina `notifySubject` como `true`, para que o Amplia Reg envie a chave de emissão 2 por
  e-mail e SMS, e entregue ao titular o `issueLinkWithKey1` pelo seu próprio sistema. Quem interceptar um dos canais não consegue emitir o
  certificado sozinho.
* **Tudo pelo seu sistema**: deixe `notifySubject` como `false` e mostre ao titular o `issueLinkWithKeys`, ou o `issueLink` junto com as
  duas chaves.

> **Aviso**
>
> O `issueLinkWithKeys` basta para emitir o certificado. Trate-o como um segredo: mostre-o só ao titular, depois que ele se autenticar no seu
> sistema, e nunca o registre em log.

## Obtendo os links de emissão depois

Para obter de novo as chaves e os links de emissão de um pedido pré-aprovado, por exemplo para mostrá-los mais uma vez ao titular:

Em .NET:

```cs
var preApprovedOrder = await ampliaRegService.GetPreApprovedOrderAsync("800-005-520");
```

Via API:

```plaintext
GET /api/orders/800-005-520/pre-approved
```

A resposta tem os mesmos campos da resposta de criação.

Para que o Amplia Reg envie de novo a chave de emissão 2 e o link de emissão ao titular, chame `SendCertificateIssueInstructionsAsync` em
.NET, ou:

```plaintext
POST /api/orders/800-005-520/notifications/certificate-issuance
```

A notificação só é enviada enquanto o pedido estiver em **Aguardando emissão**, e no máximo uma vez a cada intervalo de espera (um minuto,
por padrão). Caso contrário, o campo `failure` da resposta indica o motivo (`NotWaitingIssue` ou `CoolingDown`, com `canResendIn` em
milissegundos).

## Acompanhando o pedido

Como qualquer pedido criado pela sua aplicação, um pedido pré-aprovado dispara [webhooks](https://docs.lacunasoftware.com/articles/amplia-reg/integration/webhooks) a cada mudança de status, de
**Aguardando emissão**, na criação, até **Emitido**, quando o titular emite o certificado.

Um pedido ainda não emitido pode ser cancelado pelo painel de controle ou pela [API de cancelamento](https://docs.lacunasoftware.com/articles/amplia-reg/integration/cancel-order). O papel Autoridade
de registro eletrônica não cancela pedidos: para cancelar pela API, a aplicação também precisa do papel **App de vendas**.

## Outros formatos de certificado

Os demais formatos de certificado funcionam da mesma forma, com outra rota e outra classe de parâmetros:

| Formato | Rota | Classe de parâmetros (.NET) |
|---|---|---|
| ICP-Brasil | `POST /api/brazil/orders/pre-approved` | `CreatePreApprovedOrderBrazilParameters` |
| Paraguai | `POST /api/paraguay/orders/pre-approved` | `CreatePreApprovedOrderParaguayParameters` |
| Cabo Verde | `POST /api/cabo-verde/orders/pre-approved` | `CreatePreApprovedOrderCaboVerdeParameters` |
| SSL | `POST /api/ssl/orders/pre-approved` | `CreatePreApprovedOrderSslParameters` |

Veja a [documentação da API](https://ar.lacunasoftware.com/swagger) para os campos de cada classe de parâmetros, ou fale conosco.

## Erros comuns

| Código | Causa |
|---|---|
| `SubscriptionRequired` | A requisição não indicou uma autoridade de registro |
| `CertificationAuthorityMismatch` | O tipo de certificado pertence a uma autoridade certificadora diferente da autoridade de registro |
| `HolderTypeIsRequired` | O tipo de certificado aceita mais de um tipo de titular e `holderType` não foi informado |
| `HolderTypeNotAllowed`, `CertificateTypeDoesNotAllowDocuments` | `holderType` ou `holderFiles` foram enviados para um tipo de certificado com a etapa de documentos desabilitada |
| `MissingRequiredHolderFileType` | Falta um documento obrigatório, ou a foto |
| `HolderFileTypeCannotBeAdded` | O tipo de titular não aceita algum dos tipos de documento enviados |
| `UnexpectedHolderFileSubtype`, `MissingRequiredDocumentPart` | `subtype` inválido, ou `subtype` sem `documentPart` |
| `ValidityIsRequired` | O tipo de certificado tem mais de uma opção de validade e `validity` não foi informada |
| `CustomNumberNotAllowed`, `OrderNumberAlreadyExists` | `number` foi enviado, mas os números personalizados estão desabilitados, ou o número já está em uso |
| `SaleNumberNotAllowed`, `SaleNumberIsRequired` | `saleNumber` não é permitido, ou é obrigatório, pelas configurações da instância |
| `InvalidCsr` | Não foi possível decodificar a CSR |

## Veja também

* [Primeiros passos para integração](https://docs.lacunasoftware.com/articles/amplia-reg/integration/get-started)
* [Como funciona a emissão de certificados](https://docs.lacunasoftware.com/articles/amplia-reg/issuance)
* [Referenciando arquivos](https://docs.lacunasoftware.com/articles/amplia-reg/integration/file-referencing)
* [Webhooks](https://docs.lacunasoftware.com/articles/amplia-reg/integration/webhooks)
* [Códigos de erro](https://docs.lacunasoftware.com/articles/amplia-reg/integration/error-codes)