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, 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 para saber o que acontece durante a emissão.

dica

Certifique-se de que já realizou os Primeiros passos

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 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 para os demais formatos.

Em .NET:

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

POST /api/uploads

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

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

{
	"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:

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

Via API:

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:

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

Ver em Markdown

Antes de começar​

Criando o pedido​

Campos da requisição​

Documentos do titular​

Resposta​

Entregando o link de emissão ao titular​

Obtendo os links de emissão depois​

Acompanhando o pedido​

Outros formatos de certificado​

Erros comuns​

Veja também​