Creating preapproved orders - Amplia Reg

A preapproved order is an order that is already approved when it is created. It is meant for electronic registration authorities: systems that validate the holder's identity on their own, outside Amplia Reg, and only need the certificate to be issued.

A preapproved order skips validation and confirmation. It starts at Waiting issue (WaitingIssue), and the holder issues the certificate with the issue link, as with any other order. See How certificate issuance works for what happens during issuance.

tip

Make sure you have completed the Getting started steps

Before you start

Role: the application must have the Electronic registration authority role. This role creates preapproved orders and retrieves their issue keys. It does not create regular orders.
Registration authority: preapproved orders are always created at a registration authority, and the certificate type must belong to the same certification authority as that registration authority. To choose the registration authority, pass its ID in the X-Subscription header (in .NET, the RegistrationAuthorityId option). If the API returns the SubscriptionRequired error, the request did not name a registration authority.
Certificate type: list the certificate types available to you as described in Create an order, and take note of the code of the one you want.

Creating the order

The examples below create an ICP-Brasil e-CPF order. See Other certificate formats for the other formats.

In .NET:

var response = await ampliaRegService.CreatePreApprovedOrderAsync(new CreatePreApprovedOrderOptions2<CreatePreApprovedOrderBrazilParameters>() {
	CertificateType = CertificateTypeReference.FromCode("ECPFA1"), // Certificate type code
	HolderType = HolderTypeReference.FromCode("PF"), // Holder type code (see "Holder documents" below)
	Validity = PeriodModel.FromYears(1), // Certificate validity (the certificate type must allow it)
	Parameters = new CreatePreApprovedOrderBrazilParameters() {
		Cpf = "07917307000", // Holder's CPF, digits only
		Name = "Holder Name", // Holder's full name
	},
	Contact = new ContactData() {
		EmailAddress = "holder@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, // Amplia Reg emails and texts issue key 2 to the holder
});

The .NET client uploads the files for you. See Referencing files for the ways to reference a file.

Via API, upload each file first with a multipart/form-data request containing the fields file, name and contentType:

POST /api/uploads

The response contains the id of the upload. Then create the order, referencing the uploaded files:

POST /api/brazil/orders/pre-approved
X-Subscription: 3fa85f64-5717-4562-b3fc-2c963f66afa6 // Registration authority ID
{
	"certificateType": {
		"code": "ECPFA1" // Certificate type code
	},
	"holderType": {
		"code": "PF" // Holder type code
	},
	"validity": {
		"years": 1 // Certificate validity (the certificate type must allow it)
	},
	"parameters": {
		"cpf": "07917307000", // Holder's CPF, digits only
		"name": "Holder Name" // Holder's full name
	},
	"contact": {
		"emailAddress": "holder@example.com",
		"phone": "+5511999990000"
	},
	"holderFiles": [
		{
			"type": "Identification",
			"subtype": "Cnh",
			"documentPart": "FrontComplete",
			"file": {
				"id": "0195a9dc-c0f0-4f5c-83d3-bf562ae98ed9", // ID returned by the upload
				"name": "cnh.pdf",
				"contentType": "application/pdf"
			}
		}
	],
	"notifySubject": true // Amplia Reg emails and texts issue key 2 to the holder
}

Request fields

Field	Required	Description
`certificateType`	Yes	Certificate type, by `code` or `id`
`holderType`	Sometimes	Holder type, by `code` or `id`. Required when the certificate type has the documents step enabled and allows more than one holder type. Not allowed when the documents step is disabled
`validity`	Sometimes	Certificate validity. Required when the certificate type has more than one validity option
`parameters`	Yes	Holder data. For ICP-Brasil: `cpf` and `name`, and optionally `annotation` (up to 100 characters), which goes into an organizational unit of the certificate when the certificate type is set up to include it
`contact`	Yes	Holder's `emailAddress` and `phone`, and optionally `alternativeEmailAddress` and `alternativePhone`
`holderFiles`	Sometimes	Holder documents. See Holder documents
`notifySubject`	No	If `true`, Amplia Reg sends issue key 2 and the issue link to the holder by email and SMS. Defaults to `false`
`number`	No	Order number of your choice (up to 50 characters). Only allowed if the instance has custom order numbers enabled; must be unique
`saleNumber`	No	Order number in your sales system (up to 50 characters). Only allowed, or required, according to the instance settings. Not available in the .NET client options
`csr`	No	Certificate request (PKCS #10) for the certificate, when the key pair was generated beforehand. Its key size must match the certificate type. With a CSR, the issue page does not generate a new key pair
`csrFileName`	No	File name of the CSR

note

CPF must be provided without punctuation (digits only) and with leading zeros, if any.

Holder documents

When the certificate type has the documents step enabled, the order has a holder type, and the holder type defines which documents are required and which are optional. Send every required document. If the certificate type also has the biometrics step enabled, a document of type Photo is required too.

Each document has:

type: the document type, such as Identification, AddressProof or Photo. Custom document types configured on the instance are prefixed with @ (for example, @CustomDoc1). See Add document types.
subtype and documentPart (optional): in ICP-Brasil, an Identification document can state which document it is (Rg, Cnh, Dni, CTPS, Passport, RNE, CIN, OAB, CRC, CRM, ProfessionalLicense or Undefined). When subtype is given, documentPart is required: FrontComplete or BackComplete, and also Digital for every subtype except Rg, RNE and Undefined.
file: the file itself.

When the certificate type has the documents step disabled, do not send holderFiles or holderType.

Amplia Reg puts the documents into the order's dossier. If the instance has a seal certificate configured, Amplia Reg signs the dossier and the holder's agreement with it.

Response

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

Field	Description
`orderNumber`	Number of the order created
`issueKey1`, `issueKey2`	The two issue keys. If the instance uses a single issue key, `issueKey1` is `null`
`issueLink`	Issue link without keys: the holder types both keys
`issueLinkWithKey1`	Issue link with key 1 filled in: the holder types only key 2
`issueLinkWithKeys`	Issue link with both keys filled in: the holder types nothing

Delivering the issue link to the holder

The holder needs the issue link and both keys. Choose how they get them:

Split across two channels (recommended): set notifySubject to true, so that Amplia Reg sends issue key 2 by email and SMS, and give the holder issueLinkWithKey1 through your own system. Whoever intercepts one of the channels cannot issue the certificate alone.
All in your system: leave notifySubject as false and show the holder issueLinkWithKeys, or issueLink together with both keys.

warning

issueLinkWithKeys is enough to issue the certificate. Treat it as a secret: show it only to the holder, after they authenticate in your system, and never log it.

Retrieving the issue links later

To get the keys and the issue links of a preapproved order again, for example to show them to the holder once more:

In .NET:

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

Via API:

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

The response has the same fields as the creation response.

To have Amplia Reg send issue key 2 and the issue link to the holder again, call SendCertificateIssueInstructionsAsync in .NET, or:

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

The notification is sent only while the order is at Waiting issue, and not more than once per cooldown period (one minute by default). Otherwise, the response's failure field says why (NotWaitingIssue or CoolingDown, with canResendIn in milliseconds).

Following the order

Like any order created by your application, a preapproved order triggers webhooks on every status change, from Waiting issue at creation to Issued once the holder issues the certificate.

An order that has not been issued yet can be canceled in the control panel or through the cancellation API. The Electronic registration authority role cannot cancel orders: to cancel through the API, the application also needs the Sales app role.

Other certificate formats

The other certificate formats work the same way, with a different route and parameters class:

Format	Route	Parameters class (.NET)
ICP-Brasil	`POST /api/brazil/orders/pre-approved`	`CreatePreApprovedOrderBrazilParameters`
Paraguay	`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`

See the API documentation for the fields of each parameters class, or contact us.

Common errors

Code	Cause
`SubscriptionRequired`	The request did not name a registration authority
`CertificationAuthorityMismatch`	The certificate type belongs to a different certification authority than the registration authority
`HolderTypeIsRequired`	The certificate type allows more than one holder type and `holderType` was not given
`HolderTypeNotAllowed`, `CertificateTypeDoesNotAllowDocuments`	`holderType` or `holderFiles` were sent for a certificate type with the documents step disabled
`MissingRequiredHolderFileType`	A required document, or the photo, is missing
`HolderFileTypeCannotBeAdded`	A document type is not accepted by the holder type
`UnexpectedHolderFileSubtype`, `MissingRequiredDocumentPart`	Invalid `subtype`, or `subtype` without `documentPart`
`ValidityIsRequired`	The certificate type has more than one validity option and `validity` was not given
`CustomNumberNotAllowed`, `OrderNumberAlreadyExists`	`number` was sent but custom numbers are disabled, or the number is already in use
`SaleNumberNotAllowed`, `SaleNumberIsRequired`	`saleNumber` is not allowed, or is required, by the instance settings
`InvalidCsr`	The CSR could not be decoded

Before you start​

Creating the order​

Request fields​

Holder documents​

Response​

Delivering the issue link to the holder​

Retrieving the issue links later​

Following the order​

Other certificate formats​

Common errors​

See also​