Paperless Mode

The paperless mode is a new feature added to Uanataca that permits the generation of digital certificates without the use of eventual papery contracts. In this way every Request has its own digital contract that will be signed by the two sides of the transaction, the RAO that will approve the Request and the certificate holder, with their respective digital certificates.

This document will guide you through:

  • Request creation in paperless mode
  • Managing documents
  • Approval
  • Cloud/Software Enrollment

Create a paperless Request

In order to create a new Request in paperless mode, we need to set the parameter paperless_mode to 1:


            {
                "secure_element": "2",
                "profile": "PFnubeAFCiudadano",
                "validity_time": "365",
                "scratchcard": "120000804",
                "registration_authority": "41",
                "country_name": "IT",
                "id_document_type" : "TIN",
                "id_document_country": "IT",
                "serial_number": "TSTAPI74S23C129Y",
                "id_document_description": "IDC",
                "id_document_issuer": "IKANSD",
                "id_document_number": "12345678A",
                "given_name": "Test",
                "surname_1": "Paperless",
                "surname_2": "Api",
                "email": "email@uanataca.com",
                "mobile_phone_number": "+393331122333",
                "paperless_mode": 1
            }

and query the same endpoint with an HTTP POST request:

/api/v1/requests/

The return response is the same: a JSON containing the info of the Request just created. One of the most important parameters from this JSON is the "pk" which represents the Request unique identifier and is used for every operation related to this Request.


Upload documents

The Request created needs documents, so we can query with an HTTP POST request this endpoint to upload the files:

/api/v1/pl_upload_document/

The required documents for every Request are: document_front (the photo of the front side of the requester ID card), document_rear (the photo of the rear side if the requester ID card) and document_owner (the photo of the requester with the ID card under the chin).

If necessary it is possibile to upload extra documents that represents additional requester informations. This documents goes under the type of extra_document.

It is also possible to upload optional documents that are not strictly related to the requester informations, like a tbs document or the raw document.

The tbs, to-be-signed, document (in pdf format) will be signed with the certificate that will be enrolled. Instead the raw document is a simple txt file that contain an hash to be signed. The output of the sign process for this file, is a new file containing the original hash and the signature generated.

So to be able to upload documents, the query must contain a multipart/form-data header and the parameters: "type", the type of the document (document_front, document_rear, extra_document, ...) and "document", the actual file to upload.

Note that this endpoint has to be queried for every document that the Request needs.

Another important aspect, is that the Request must be in the status CREATED in order to be able to upload documents.


Retrieving documents

The documents associated to a Request, can always be retrieved, even if the Request is not in the status CREATED.

It is possibile to retrieve documents by type or just all of them together.

By querying with this json


            {
                "type": "signed_raw"
            }
            

the endpoint:

/api/v1/requests/{pk}/pl_get_document/

we will get the documents that have as type "signed_raw".

Instead to get all the documents as a list, we can query the endpoint:

/api/v1/requests/{pk}/pl_get_documents/

which will return the documents and their unique identifier number.

In all the cases, the document is returned encoded in Base64.


Delete documents

In order to delete a document, the Request must be in the status CREATED.

The only parameter needed by the endpoint

/api/v1/requests/{pk}/pl_delete_document/

is the document unique identifier:


            {
                "docpk": 123
            }
            

If the removal is successful the response by the server is:


            {
                "status": "Document deleted successfully"
            }
            

Approve Requests

In order to approve a Request, this must be in the status of CREATED and must have at least the required documents (document_front, document_rear, document_owner).

A Request can only be approved by a RAO which have associated a cloud user. In fact an example of the parameters accepted is this:


            {
                "username": "2000279",
                "password": "3DPTm:N4",
                "pin": "belorado74",
                "rao_id": 233
            }

where "username", "password" and "pin" are the cloud user credentials, "rao_id" the unique identifier of the RAO that will approve the Request.

/api/v1/requests/{pk}/pl_approve/

Prepare for enrollment

The enrollment for paperless Requests, needs a secret (OTP; One Time Password) that will be sent via SMS to the mobile phone number of Request (So when a new Request is created make sure it contains the correct number with the internation prefix number).

The generation of the OTP code, changes according to the Request profile. If the Request has a standard profile, it is necessary to query this endpoint with a POST request passing the correct scratchcard number:


            {
                "scratchcard": "110003051"
            }
            
/api/v1/requests/{pk}/generate_otp/

Instead in case that the Request has a qualified profile (see Profiles), the generation of the otp changes. It must be performed with the endpoint:

/api/v1/requests/{pk}/generate_otp_for_qs/

that accepts as parameters the pin and puk that will be assigned to the cloud identity.

For both of the endpoints, if it is the first time that an OTP is generated for the specified Request, than it is simply sent to the mobile phone number registered. Instead if these endpoints are queried in less than one minute since the previous generated OTP, it will not generate a new OTP, but the previous one is still valid.

Once received the secret, it can be used for the next phase: the Request Enrollment.


Enrollment

Depending on the secure element choosen during the creation, or on the Request profile, there are different endpoints to enroll a Request:

/api/v1/requests/{pk}/pl_p12_enroll/
/api/v1/requests/{pk}/pl_cloud_enroll/
/api/v1/requests/{pk}/plq_cloud_enroll/

The first one is used for the Software Requests and accept as parameters the secret and the p12password to set to the generated p12:


            {
                "secret": "000000",
                "p12password": "belorado74"
            }
            

At the end of the enrollment the server reply with the P12 generated in PEM format.

Instead the second one is for Cloud Requests. In addition to the secret it is necessary a pin code (the puk is generated in a cryptographic secure way by the server) assigned to the generated remote token:


            {
                "secret": "000000",
                "pin": "belorado74"
            }
            

The last one instead is used to enroll Cloud Requests that have a qualified profile.

The parameters accepted are the same as pl_cloud_enroll:


            {
                "secret": "000000",
                "pin": "belorado74"
            }
            

with the only difference that the pin parameter must coincide with the one passed to generate_otp_for_qs endpoint.

If no error occures the server reply with a JSON containing a key "status" valued to "OK".