Uanataca RA API allows the generation and distribution of digital certificates, either by integrating the issuance and management into a business application.

The Registration Authority is composed of people and processes, with the main function of identifying applicants of digital certificates and sending verified data for the issuance of the certificate.

Digital certificates are created and used as part of a life-cycle that includes three fundamental stages:

• Registration including documentation
• Data validation
• Certificate issuance

The complete flow is explained in the next section Flow chart

As part of the paperless procedure, every Request has its own digital contract that has to be electronically signed by the RA Operator (in charge of approving the Request) and the certificate subscriber, each one with their respective digital certificates.

List of entities and names used to describe UANATACA's services

Certification Authority (CA)

The CA is the issuer of the certificates requested by the Registration Authority.

Registration Authority (RA)

The RA manages the entire life-cycle of digital identities, from the certificate issuance to suspension, reactivation, renewal and revocation of the PKI credentials. Reuests are generated and verified by a Registration Authority Officer.

Registration Authority Officer (RAO)

The RAO follows strict guidelines and policies defined to ensure the trust of the CA. RAO is responsible for managing the requests for digital certificates and verifying the content of the requests as well as identifying people requesting them.

API User

The Account having access to the APIs provided by the system. It is generally used for a server to server interaction.

Certificate Request (Request)

It is a request to issue a new certificate. A request can be associated with only one RA and has a status attribute to monitor the progress of the application:

CREATED: The request has been created and associated to an RA, but the content of the request has not been validated yet. In this state, data can also be inconsistent, the system will not throw an error. The content of the request can be edited at any moment to make it valid.

ENROLLREADY: The certificates are ready to be issued. The request arrives at this stage, if it has been approved and signed by a RAO, who is part of the RA in charge of the request.

ISSUED: The certificate is issued by the user's self-service page on the platform. The user must first set a PIN code or a password regarding the secure element.

RENEWED: The certificate is renewed by the user's self-service page on the platform.

CANCELLED: The request is cancelled and the digital certificate can not be issued.

Scratchcard

It is a virtual scratch card containing the secret codes of the user.

The card contains:

• A serial number: it uniquely identifies the user
• An enrollment code: secret code, that is sent to the user by email

It is important to notice that a scratchcard can be used only once. Every request must be associated with a different scratchcard.

1. An end user requests a digital certificate to the Registration Authority (RA)
2. A Registration Authority Officer (RAO) identifies the user and requests the required documentation
3. The user sends the required documentation according to the certificate profile
4. The RAO creates a digital certificate request
5. The response returns a request ID
6. The RAO uploads the required documentation according to the request
7. The RAO verifies all request data and documentation
8. The RAO checks declaration and signs service contract.
9. The RAO approves the digital certificate request to allow the certificate issue
10. The user receives an email with a link to start the certificate generation process
11. The user access to the online digital certificate generation process
12. During the process, the service contract is shown to the user
13. An OTP code is sent to the user via sms
14. The user inserts the OTP code and creates a custom PIN
15. The certificate is generated and the service contract is signed by the user
16. Finally, the user receives the signed contract and an email with the certificate credentials and instructions

The common digital certificate generation process involves the following steps:

1) CREATION OF A REQUEST

2) UPLOAD DOCUMENTS

3) REQUEST APPROVAL

STEP 1: CREATION OF A REQUEST

API Reference: Get First Unused Scratchcard

This call simply requires a Registration Authority (RA) id number. Scratchcards must be available for this RA for successful response.

curl -i -X GET https://api.uanataca.com/api/v1/scratchcards/get_first_unused/ \
-H 'Content-Type: application/json' \
--cert 'cer.pem' --key 'key.pem'
-d '{
  "ra": "121"
}'

The response is a JSON object containing the single-use Scratchcard associated data. The scratchcard number sn must be added to the Create Request call.

{
  "pk": 1193,
  "sn": "1256948",
  "secrets": "{\"erc\": \"6292998123\", \"enrollment_code\": \"_,463vt:\", \"pin\": \"08695572\", \"puk\": \"52351291\"}",
  "registration_authority": 121
}

API reference: Create Request

This call must include enough information to identify the requester user. The full description of the arguments accepted by this endpoint can be found in the API call detailed documentation.

curl -i -X POST 'https://api.uanataca.com/api/v1/requests/' \
-H 'Content-Type: application/json' \
--cert 'cer.pem' --key 'key.pem'
-d '{
  "profile": "PFnubeAFCiudadano",
  "scratchcard": "5053311",
  "secure_element": "2",
  "registration_authority": "116",
  "country_name": "ES",
  "serial_number": "12345678A",
  "id_document_country": "ES",
  "id_document_type": "IDC",
  "given_name": "Name",
  "surname_1": "Surname1",
  "surname_2" "Surname2"
  "email": "mail@domain.com",
  "mobile_phone_number": "+34611223344",
  "paperless_mode": 1
}'

The response is a JSON containing info from the created request. 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.

{
  "pk": 11223,
  "given_name": "Name",
  "surname_1": "Surname1",
  "surname_2": "Surname2",
  "sex": null,
  "id_document_type": "IDC",
  "id_document_country": "ES",
  "serial_number": "12345678A",
  "country_name": "ES",
  "citizenship": null,
  "residence": null,
  "organization_email": null,
  "email": "mail@domain.com",
  "title": null,
  "organization_name": null,
  "organizational_unit_1": null,
  ...
}

STEP 2: UPLOAD DOCUMENTS

API reference: Upload Document

The created request needs documents, so we can query with an HTTP POST request to upload the files.

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 of the requester ID card
extra_document : If necessary, it is possibile to upload extra documents that represents additional requester information

Additionally a selfie of the requester showing the ID card under the chin can be uploaded as an evidence under the type document_owner.

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

curl -i -X POST 'https://api.uanataca.com/api/v1/requests/11223/pl_upload_document/' \
--cert 'cer.pem' --key 'key.pem'
  -H 'Content-Type: multipart/form-data' \
  -F document=@/idc_front.jpg \
  -F type=document_front

The response contains the uploaded document unique identifier associated to the request.

{
  "pk": 11314,
  "type": "document_front"
}

STEP 3: REQUEST APPROVAL

If all information is correct, the RAO will approve the request by signing the receipt and contract with his or her own cloud certificate. These calls are shown below:

API Reference: Generate RAO Declaration

curl -i -X POST https://api.uanataca.com/api/v1/requests/25139/generates_tbs_receipt/ \
-H 'Content-Type: application/json' \
-d '{
  "rao": "1400",
  "type": "APPROVE"
}'

The following JSON object contains the receipt:

{
  "serial_number": "3ef3696d2939241d",
  "receipt": "El operador RAO_Name RAO_Surname1 con número de identificación 12345678P\r\nactuando en calidad de operador autorizado de registro del prestador de servicios\r\n
  de confianza UANATACA, S.A. con NIF A66721499, (UANATACA en lo sucesivo)\r\n\r\nDECLARA\r\n\r\nQue previa verificación de acuerdo a la Declaración de Prácticas de
  UANATACA\r\npublicadas en www.uanataca.com, la información detallada a continuación es\r\ncorrecta y será incluida (donde aplicable) en la solicitud de 
  certificados\r\ncualificados:\r\n\r\n- Datos de Identificación de la solicitud de certificados: 36893\r\n- Nombre y Apellidos del Firmante: Name Surname1 Surname2\r\n- DNI/
  NIE/PASAPORTE del Firmante: 11111111B\r\n- Dirección de correo electrónico del Firmante: mail@domain.com\r\n\r\n\r\n18/03/
  2021\r\n\r\n\r\n\r\n--------------------------------------------------------------------\r\nFdo. User Admin\r\nOperador autorizado de registro"
}

Similarly, it is necessary to retrieve the service contract and present it to the RAO before approval.

API Reference: Generate Contract (type: contract)

curl -i -X POST https://api.uanataca.com/api/v1/requests/25139/pl_get_document/ \
-H 'Content-Type: application/json' \
-d '{
  "type": "contract"
  "rao_id": "1400"    
}'

The response consists in a JSON structure containing the contract in Base64 format.

[
  {
    "document": "JVBERi0xLjQKJZOMi54gUmVwb3J0TGFiIEdlbmVyYXRlZCBQREYgZG9jdW1lbnQgaHR0cDovL3d3\ndy5yZXBvcnRsYWIuY29tCjEgMCBvYmoKPDwKL0YxIDIgMCBSCj4 (...)\n",
    "type": "contract"
  }
]

API reference: Approve Request

A Registration Authority Officer must first validate the request data and documentation. If the information is correct, the RAO will approve the request by signing the receipt and contract with his or her own cloud certificate.

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

curl -i -X POST 'https://api.uanataca.com/api/v1/requests/' \
-H 'Content-Type: application/json' \
--cert 'cer.pem' --key 'key.pem'
-d '{
  "username": "1000279",
  "password": "3DPTm:N4",
  "pin": "23bYQq9a",
  "rao_id": 123
}'

STEP 4: CLOUD/SOFTWARE ENROLLMENT

In this step, the service contract must be presented to the signer before enrollment.

API Reference: Generate Contract (Body type: contract)

There are different endpoints to enroll a request depending on the secure element chosen. The next action involves sending an otp code to the requester using the calls shown below. Software and cloud certificates use the same call to send the otp code, as cloud-qscd certificates use a different one.

API Reference: Generate OTP (Cloud or Software)

API Reference: Generate OTP (Cloud or QSCD)

SOFTWARE

API reference: Software Enroll

For the Software enrollemnt the parameters required are the secret OTP code send to the requester and the p12password set by the requester to import the generated p12:

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

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

CLOUD

API reference: Cloud Enroll

For the cloud enrollemnt the parameters required are the secret OTP code send to the requester and the PIN code set by the requester to use the generated certificate:

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

At the end of the enrollment the server replies with a JSON containing all requesta data.

CLOUD-QSCD

API reference: Cloud-QSCD Enroll

For the cloud enrollemnt the parameters required are the secret OTP code send to the requester and the PIN code set by the requester to use the generated certificate:

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

At the end of enrollment the server replies with a JSON containing all request data.

PROCESS COMPLETION

For correct process completion, the following information must be delivered to the requester:

• The certificate in .p12 format (Software Enroll)

• The certificate set of credentials (Cloud Enroll)

• The contract signed by both parties. Available when executing the Get Signed Contract call (Body type: signed_contract)

OPTIONAL

API Reference: Get Request

This workflow defines the complete process of issuing eIDAS certificates.

This certificate generation process involves the following steps:

1) CREATION OF A REQUEST

2) VIDEO IDENTIFICATION

3) VALIDATION OF VIDEO IDENTIFICATION EVIDENCES

4) UPDATE OF REQUEST (OPTIONAL)

5) DOCUMENTS UPLOAD (OPTIONAL)

6) REQUEST APPROVAL

STEP 1: CREATION OF A REQUEST

API Reference: Get First Unused Scratchcard

This call simply requires a Registration Authority (RA) id number. Scratchcards must be available for this RA for successful response.

curl -i -X GET https://api.uanataca.com/api/v1/scratchcards/get_first_unused/ \
-H 'Content-Type: application/json' \
--cert 'cer.pem' --key 'key.pem'
-d '{
  "ra": "121"
}'

The response is a JSON object containing the single-use Scratchcard associated data. The scratchcard number sn must be added to the Create Request call.

{
  "pk": 1193,
  "sn": "1256948",
  "secrets": "{\"erc\": \"6292998123\", \"enrollment_code\": \"_,463vt:\", \"pin\": \"08695572\", \"puk\": \"52351291\"}",
  "registration_authority": 121
}

API Reference: Create Request

This call must include this parameters to success. The full description of the arguments accepted by this endpoint can be found in the call detailed documentation.

curl -i -X POST 'https://api.uanataca.com/api/v1/requests/' \
-H 'Content-Type: application/json' \
--cert 'cer.pem' --key 'key.pem'
-d '{
  "profile": "PFnubeAFCiudadano",
  "scratchcard": "5053311",
  "secure_element": "2",
  "registration_authority": "116",
  "email": "mail@domain.com",
  "mobile_phone_number": "+34611223344",
  "videoid_mode": 1
}'

The response is the a JSON containing info from the created request in VIDEOPENDING status. 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.

{
  "pk": 25139,
  "given_name": "Name",
  "surname_1": "Surname1",
  "surname_2": "Surname2",
  "sex": null,
  "id_document_type": "IDC",
  "id_document_country": "ES",
  "serial_number": "A9999999E",
  "country_name": "ES",
  "citizenship": null,
  "residence": null,
  "organization_email": null,
  "email": "mail@domain.com",
  "title": null,
  "organization_name": null,
  "organizational_unit_1": null,
  (...)
}

At this point, the workflow progress will depend on the video-identification process performed by end user. Its successful completion will change request status to VIDEOREVIEW.

⚠ In case the process is not totally completed or has failed for any reason, the request will change to VIDEOINCOMPLETE or VIDEOERROR respectively.

To inform business app and validation RAO about this change at the time it takes place, we recommend the implementation of a Webhook. Check our documentation for Webhook Configuration.

If a request needs to be cancelled, use the Cancel Request call.

STEP 2: VIDEO IDENTIFICATION

This process is performed by end user in Uanataca platform. It can be start from a link received in an email sent to the end user.

Through Video Identification process, evidences from the certificate subscriber such as name, surname or data related to subscriber ID card are obtained.

STEP 3: VALIDATION OF VIDEO IDENTIFICATION EVIDENCES

With the information gathered in the above mentioned process, a UANATACA Certified Operator will be in charge of validating every evidence.

In case of Natural Person profiles, the request gets approved in this step, meaning that the user will receive an email to complete the certificate issuance.

After this step the request status will change to ENROLLREADY for Natural Person profiles or CREATED for the rest of them.

STEP 4: UPDATE OF THE REQUEST

⚠ This step is required for all profiles except Natural Person

RAO entity compliments every field that does not belong to subscriber identification. Be aware that the fields filled in with information obtained from the video identification process cannot be modified in any way.

Check the required fields for each certificate profile in eIDAS Certificate Profiles list.

API Reference: Update Request

curl -i -X PUT https://api.uanataca.com/api/v1/requests/{ID}/ \
-H 'Content-Type: application/json' \
-d '{
  "given_name": "Name",
  "surname_1": "Surname1",
  "scratchcard": "1234567890",
  "country_name": "ES",
  "email": "mail@domain.com",
  "profile": "PFnubeAFCiudadano",
  "registration_authority": 64
}'

STEP 5: DOCUMENTS UPLOAD

⚠ This step is required for all profiles except Natural Person

RAO entity uploads required documentation subject to the type of profile being issued.

API Reference: Upload documents

curl -i -X PUT https://api.uanataca.com/api/v1/requests/{request}/upload_videoid_evidence/ \
-H 'Content-Type: multipart/form-data' \
-F document=@sample_folder/sample.pdf \
-F label=test label

STEP 6: REQUEST APPROVAL

To complete a request, the RAO must be sure to validate both additional documents and fields. Before approval, you will be shown a preview of RAO declaration.

API Reference: Generate RAO Declaration

curl -i -X POST https://api.uanataca.com/api/v1/requests/25139/generates_tbs_receipt/ \
-H 'Content-Type: application/json' \
-d '{
  "rao": "1400",
  "type": "APPROVE"
}'

The following JSON object contains the receipt:

{
  "serial_number": "3ef3696d2939241d",
  "receipt": "El operador RAO_Name RAO_Surname1 con número de identificación 12345678P\r\nactuando en calidad de operador autorizado de registro del prestador de servicios\r\n
  de confianza UANATACA, S.A. con NIF A66721499, (UANATACA en lo sucesivo)\r\n\r\nDECLARA\r\n\r\nQue previa verificación de acuerdo a la Declaración de Prácticas de
  UANATACA\r\npublicadas en www.uanataca.com, la información detallada a continuación es\r\ncorrecta y será incluida (donde aplicable) en la solicitud de 
  certificados\r\ncualificados:\r\n\r\n- Datos de Identificación de la solicitud de certificados: 36893\r\n- Nombre y Apellidos del Firmante: Name Surname1 Surname2\r\n- DNI/
  NIE/PASAPORTE del Firmante: 11111111B\r\n- Dirección de correo electrónico del Firmante: mail@domain.com\r\n\r\n\r\n18/03/
  2021\r\n\r\n\r\n\r\n--------------------------------------------------------------------\r\nFdo. User Admin\r\nOperador autorizado de registro"
}

API Reference: Approve Request

This call makes the request ready for enrollment. Its status changes to ENROLLREADY after executing this call.

curl -i -X POST 'https://api.uanataca.com/api/v1/requests/' \
-H 'Content-Type: application/json' \
--cert 'cer.pem' --key 'key.pem'
-d '{
  "username": "1000279",
  "password": "3DPTm:N4",
  "pin": "23bYQq9a",
  "rao_id": "1400",
  "lang": "ES"
}'

The response is a JSON object with added request approval information.

{
  "secrets": {
    "puk": "38812452",
    "enrollment_code": ".R4P9qgA",
    "pin": "31945152",
    "erc": "3417062505"
  },
  "request": {
    "pk": 25139,
    "given_name": "Name",
    "surname_1": "Surname1",
    "surname_2": "Surname2",
    "sex": null,
    "id_document_type": "IDC",
    "id_document_country": "ES",
    "serial_number": "A9999999E",
    (...)
    "approving_rao": {
      "pk": 1400,
      "given_name": "RAO_Name",
      "surname_1": "RAO_Surname1",
      "surname_2": "RAO_Surname2",
      (...)
    }
  }
}

The External-Mode Video ID certificate generation process involves the following steps:

1) CREATION OF A REQUEST

2) UPLOAD EVIDENCES

3) REQUEST VALIDATION

4) REQUEST APPROVAL

5) CLOUD/SOFTWARE ENROLLMENT

STEP 1: CREATION OF A REQUEST

API Reference: Get First Unused Scratchcard

This call simply requires a Registration Authority (RA) id number. Scratchcards must be available for this RA for successful response.

curl -i -X GET https://api.uanataca.com/api/v1/scratchcards/get_first_unused/ \
-H 'Content-Type: application/json' \
--cert 'cer.pem' --key 'key.pem'
-d '{
  "ra": "121"
}'

The response is a JSON object containing the single-use Scratchcard associated data. The scratchcard number sn must be added to the Create Request call.

{
  "pk": 1193,
  "sn": "1256948",
  "secrets": "{\"erc\": \"6292998123\", \"enrollment_code\": \"_,463vt:\", \"pin\": \"08695572\", \"puk\": \"52351291\"}",
  "registration_authority": 121
}

API Reference: Create Request

This call must include enough information to identify the end user. The full description of the arguments accepted by this endpoint can be found in the call detailed documentation.

curl -i -X POST 'https://api.uanataca.com/api/v1/requests/' \
-H 'Content-Type: application/json' \
--cert 'cer.pem' --key 'key.pem'
-d '{
  "profile": "PFnubeAFCiudadano",
  "scratchcard": "5053311",
  "secure_element": "2",
  "registration_authority": "116",
  "country_name": "ES",
  "serial_number": "12345678A",
  "id_document_country": "ES",
  "id_document_type": "IDC",
  "given_name": "Name",
  "surname_1": "Surname1",
  "surname_2" "Surname2"
  "email": "mail@domain.com",
  "mobile_phone_number": "+34611223344",
  "videoid_mode": 1
}'

The response is the a JSON containing info from the created request in VIDEOPENDING status. 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.

{
  "pk": 25139,
  "given_name": "Name",
  "surname_1": "Surname1",
  "surname_2": "Surname2",
  "sex": null,
  "id_document_type": "IDC",
  "id_document_country": "ES",
  "serial_number": "A9999999E",
  "country_name": "ES",
  "citizenship": null,
  "residence": null,
  "organization_email": null,
  "email": "mail@domain.com",
  "title": null,
  "organization_name": null,
  "organizational_unit_1": null,
  (...)
}

If request data needs to be modified, use the Update Request call. Check API Reference.

If request data needs to be retrieved, use the Get Request call. Check API Reference.

STEP 2: UPLOAD EVIDENCES

A previously created Video ID Request needs a set of information defined as evidences. The succesful upload of ALL this information will change the request status to VIDEOREVIEW.

Data and images are uploaded by using the following call:

API Reference: Upload Data Evidence

Data objects in detail:

acceptance : Client acceptance parameters (e.g. Terms & Conditions, Privacy Policy). This is a customizable JSON object.
data : Set of pictures associated to the client's ID document plus a selfie of him/her.
ocr_data : Text information extracted from the client's ID document via Optical Character Recognition (OCR).
security_checks : Set of validation fields associated to the client's identity (underaging, matching info, liveliness, etc)
similarity_level : Similarity between the client's selfie and the picture is shown on his/her ID document.

curl -i -X PUT https://api.uanataca.com/api/v1/videoid/45836/evidences \
    -H 'Content-Type: application/json' \
    -d '{
        "acceptance": {
            "description": "User Accepted Terms and Conditions and Privacy Policy",
            "url-doc-privacypolicy": "https://www.uanataca.com/public/pki/privacidad-PSC/",
            "ip": "186.0.91.53",
            "url-web-videoid": "https://cms.access.bit4id.org:13035/lcmpl/videoid/46b92251-4ba8-4930-a5aa-8631ec4666b6",
            "user-agent": "Mozilla/5.0 (Linux; Android 11; AC2003)",
            "date": 1622823879708,
            "url-doc-termsconditions": "https://www.uanataca.com/public/pki/terminos-VID/"
        },
        "videoid_data": {
            "images": {
                "document_front": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAIBAQEBAQIBAQECAgICAgQDAgICAgUEBAM (...)",
                "document_rear": "/I7ye60+aOKS0mVGVSD9RVfyXukjmnS3cAEbpMVm6M1ncWqS3FszptO1lPRRDJ+orI8b (...)",
                "document_photo": "AkjOOwFfHFrrNlpXxcbU9QuIIIkvR56yddgHpX3GEj1PmanmdS/xV1ySVlv/AIbXLPO (...)",
                "document_owner": "SSVnovgCZ4Lhk+R3lJPUDJr5t/Z/wBV1DWfjRbeI75B5iQytcykc7yMEAV2/iwC0T34 (...)"
            },
            "ocr_data": {
                "given_name": "Name",
                "surname_1": "Surname 1",
                "surname_2": "Surname 2",
                "mobile_phone_number": "+34999999999",
                "email": "mail@domain",
                "serial_number": "A9999999E",
                "id_document_type": "IDC",
                "id_document_country": ES
            },
            "security_checks": {
                "otp_validation": true,
                "documents_match": true,
                "data_integrity": true,
                "document_notcopy": true,
                "document_notexpired": true,
                "document_notunderage": true,
                "liveliness": true
            },
            "similarity_level": "high"
        }
    }

Successful response status

{
  "status": "200 OK"
}

In the same way, MP4-format Video evidence is uploaded by using the following call:

API Reference: Upload Video

curl -i -X POST https://api.uanataca.com/v1/upload/video/30e57b02819a430d8386fd85be9f499f/ \
-H 'Content-Type: multipart/form-data' \
-F video=@sample_folder/sample_video.mp4 

Successful response status

{
  "status": "200 OK"
}

If the uploaded video needs to be retrieved, use Download Video call.

STEP 3: REQUEST VALIDATION 2-step mode only

API Reference: Validate Video ID Request

A Registration Authority Officer must validate the request data and evidences before approval. This call is used only for 2-step mode.

curl -i -X POST https://api.uanataca.com/api/v1/requests/25139/validate_videoid \
-H 'Content-Type: application/json' \
--cert 'cer.pem' --key 'key.pem'
-d '{
  "username": "5012345",
  "password": "Gy6F37xK",
  "pin": "belorado74",
  "rao_id": "1400"
}'

The validation successful response changes the request to CREATED status as a JSON object containing full request information is returned.

{
  "secrets": {
    "puk": "38812452",
    "enrollment_code": ".R4P9qgA",
    "pin": "31945152",
    "erc": "3417062505"
  },
  "request": {
    "pk": 25139,
    "given_name": "Name",
    "surname_1": "Surname1",
    "surname_2": "Surname2",
    "sex": null,
    "id_document_type": "IDC",
    "id_document_country": "ES",
    "serial_number": "A9999999E",
    (...)
  }
}

For unsuccessful validations leading to a request refusal, the corresponding call is Refuse Request. Check API Reference.

STEP 4: REQUEST APPROVAL

If all information is correct, the RAO will approve the request by signing the receipt and contract with his or her own cloud certificate. These calls are shown below:

API Reference: Generate RAO Declaration

curl -i -X POST https://api.uanataca.com/api/v1/requests/25139/generates_tbs_receipt/ \
-H 'Content-Type: application/json' \
-d '{
  "rao": "1400",
  "type": "APPROVE"
}'

The following JSON object contains the receipt:

{
  "serial_number": "3ef3696d2939241d",
  "receipt": "El operador RAO_Name RAO_Surname1 con número de identificación 12345678P\r\nactuando en calidad de operador autorizado de registro del prestador de servicios\r\n
  de confianza UANATACA, S.A. con NIF A66721499, (UANATACA en lo sucesivo)\r\n\r\nDECLARA\r\n\r\nQue previa verificación de acuerdo a la Declaración de Prácticas de
  UANATACA\r\npublicadas en www.uanataca.com, la información detallada a continuación es\r\ncorrecta y será incluida (donde aplicable) en la solicitud de 
  certificados\r\ncualificados:\r\n\r\n- Datos de Identificación de la solicitud de certificados: 36893\r\n- Nombre y Apellidos del Firmante: Name Surname1 Surname2\r\n- DNI/
  NIE/PASAPORTE del Firmante: 11111111B\r\n- Dirección de correo electrónico del Firmante: mail@domain.com\r\n\r\n\r\n18/03/
  2021\r\n\r\n\r\n\r\n--------------------------------------------------------------------\r\nFdo. User Admin\r\nOperador autorizado de registro"
}

Similarly, it is necessary to retrieve the service contract and present it to the RAO before approval.

API Reference: Generate Contract (use type: contract in body)

curl -i -X POST https://api.uanataca.com/api/v1/requests/25139/pl_get_document/ \
-H 'Content-Type: application/json' \
-d '{
  "type": "contract"
  "rao_id": "1400"    
}'

The response consists in a JSON structure containing the contract in Base64 format.

[
  {
    "document": "JVBERi0xLjQKJZOMi54gUmVwb3J0TGFiIEdlbmVyYXRlZCBQREYgZG9jdW1lbnQgaHR0cDovL3d3\ndy5yZXBvcnRsYWIuY29tCjEgMCBvYmoKPDwKL0YxIDIgMCBSCj4 (...)\n",
    "type": "contract"
  }
]

API Reference: Approve Request

This call makes the request ready for enrollment. Its status changes to ENROLLREADY. In 1-step mode, both validation and approval occur when executing this call.

curl -i -X POST 'https://api.uanataca.com/api/v1/requests/' \
-H 'Content-Type: application/json' \
--cert 'cer.pem' --key 'key.pem'
-d '{
  "username": "1000279",
  "password": "3DPTm:N4",
  "pin": "23bYQq9a",
  "rao_id": 123,
  "lang": "ES"
}'

The response is a JSON object with added request approval information.

{
  "secrets": {
    "puk": "38812452",
    "enrollment_code": ".R4P9qgA",
    "pin": "31945152",
    "erc": "3417062505"
  },
  "request": {
    "pk": 25139,
    "given_name": "Name",
    "surname_1": "Surname1",
    "surname_2": "Surname2",
    "sex": null,
    "id_document_type": "IDC",
    "id_document_country": "ES",
    "serial_number": "A9999999E",
    (...)
    "approving_rao": {
      "pk": 1400,
      "given_name": "RAO_Name",
      "surname_1": "RAO_Surname1",
      "surname_2": "RAO_Surname2",
      (...)
    }
  }
}

In case of not approving a request for any reason, the call Cancel Request must be executed. Check API Reference.

STEP 4: CLOUD/SOFTWARE ENROLLMENT

In this step, the service contract must be presented to the signer before enrollment.

API Reference: Generate Contract (use type: contract in body)

There are different endpoints to enroll a request depending on the secure element chosen. The next action involves sending an otp code to the requester using the calls shown below. Software and cloud certificates use the same call to send the otp code, as cloud-qscd certificates use a different one.

API Reference: Generate OTP (Cloud or Software)

API Reference: Generate OTP (Cloud or QSCD)

Software

API Reference: Software Enroll

For the Software enrollemnt the parameters required are the secret OTP code send to the requester and the p12password set by the requester to import the generated p12:

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

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

Cloud

API Reference: Cloud Enroll

For the cloud enrollemnt the parameters required are the secret OTP code send to the requester and the PIN code set by the requester to use the generated certificate:

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

At the end of the enrollment the server replies with a JSON containing all requesta data.

Cloud-QSCD

API Reference: Cloud-QSCD Enroll

For the cloud enrollemnt the parameters required are the secret OTP code send to the requester and the PIN code set by the requester to use the generated certificate:

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

After this call, the server replies with a JSON object containing all request data.

PROCESS COMPLETION

For correct process completion, the following information must be delivered to the requester:

• The certificate in .p12 format (Software Enroll)

• The certificate set of credentials (Cloud Enroll)

• The contract signed by both parties. Available when executing the Get Signed Contract call (use type: signed_contract in body)

OPTIONAL

API Reference: Get Request

API Reference: Download video

One-Shot API requires a Webhook implemented on customer business side to manage our service callbacks. Every request status change will trigger a simple event-notification via HTTP POST, consisting on a JSON object to an URL that must be explicitly included as a required parameter in the Create Video ID Request call when using Uanataca 1-step or 2-step mode.

The following is a sample view of the JSON object that is sent as a callback at every status change:

{
    "status": "VIDEOINCOMPLETE", 
    "date": "2021-07-20T08:08:21.132394", 
    "previous_status": "VIDEOPENDING", 
    "request": 46760, 
    "registration_authority": 455
}

Where:

Status is the most recent status, this is, the status that triggered the notification.
Date is the date of the request status change in datetime format.
Previous_status is the status inmediately previous to last change.
Request is the request unique id.
Registration_authority is the Registration Authority id number the request is associated.

Sample code

In this sample, every JSON object is stored in a file named 'videoid'.

The webhook parameter used in the Create Video ID Request call is defined as:

{host}/videoid

where {host} is the IP or domain from the server exposing the webhook.

Python

import web
import datetime

urls = (
        '/videoid, 'videoid',
        )

app = web.application(urls, globals())
app = app.wsgifunc()

class video:
    def POST(self):
        data = web.data()
        f = open("status.json",'a+')
        f.write(data)
        f.close()
        return ''

if __name__ == "__main__":
    app.run()

PHP

<?php

//videoid.json

$post = file_get_contents('php://input',true);
$file_handle = fopen('/videoid/status.json', 'w');
fwrite($file_handle, $post);
fclose($file_handle);

?>

Uanataca expose its API on urls composed as follows:

https://{uanatacahost}/api/{version}/{resource}/

⚠ Make sure the URL always ends with a forward slash ("/")

Uanatacahost

The host changes according to the environment:

• access.bit4id.org:13035 for test environment
• api.uanataca.com for production environment

⚠ In test environment you need to trust the certificate Bit4idCA.crt

Version

It is the api version (currently v1)

Resource

It is the name of the resource of our interest.

Each resource can also have path parameters and sub-resources that are defined in the API Reference below:

This is an example of endpoint exposed by Uanataca:

https://api.uanataca.com/api/v1/requests/123/cloud_enroll/

The API authentication is perfomed providing to the server the certificate and the key of an enabled API User.

This is an example HTTP POST request perfomed with cURL:

1 | curl --key key.pem --cert cert.pem -H "Content-Type: application/json" -d @params.json -X POST https://api.uanataca.com/api/v1/requests/

and a Python with requests package example:

1 | import requests
2 | requests.get(
3 |     'https://api.uanataca.com/api/v1/scratchcards/',
4 |     cert = ('/path/to/cert.pem', '/path/to/key.pem')
5 | )

Every response body returned by Uanataca is JSON object.

If the response is successful, the content of the JSON depends on the API queried.

Instead, the error response is always composed of these keys:

In the API Reference are described the response structures for each API call.

A successful response:

1 | [
2 |     {
3 |         "data": "MIIHyTCCBbGgAwIBAgIIcO...",
4 |         "profile": "PFnubeAF",
5 |         "subject": "CN=RAO COFTenerife API, 2.5.4.5=TINIT-TSTAPI74S23C129Y, 2.5.4.42=RAO, 2.5.4.4=API, C=ES",
6 |         "issuer": "2.5.4.97=VATES-A66721499, CN=UANATACA CA1 2016, OU=AC-UANATACA, O=UANATACA S.A., L=Barcelona (see current address at www.uanataca.com/address), C=ES",
7 |         "valid_from": "2018-10-16T16:41:00",
8 |         "valid_to": "2020-10-15T16:41:00",
9 |         "serial_number": "70e07489bfccd478",
10|         "status": 0,
11|         "pk": 1980,
12|         "revokation_reason": null,
13|         "type": "FIRSTISSUE"
14|     }
15| ]

An error response:

1 | {
2 |     "code": "500",
3 |     "id": "8e782cdcdb600a90",
4 |     "error": "Invalid ScratchCard"
5 | }

Some endpoints works with the mechanism of pagination.

This means that when an API returns the content requested, the JSON is composed with the keys:

Every page contains at most 10 objects.

Examples

Here are display a couple of JSON returned by Uanataca.

A list of Scratchcards:

1 | {
2 |     "count": 40,
3 |     "next": "https://api.uanataca.com/api/v1/scratchcards/?page=2®istration_authority=8",
4 |     "previous": null,
5 |     "results": [
6 |         {
7 |             "pk": 801,
8 |             "sn": "2000100",
9 |             ...
10|         },
11|         {
12|             "pk": 800,
13|             "sn": "2000099",
14|             ...
15|         },
16|         ...
17|     ]
18| }

A list of Requests:

1 | {
2 |     "count": 643,
3 |     "next": "https://api.uanataca.com/api/v1/requests/?page=2",
4 |     "previous": null,
5 |     "results": [
6 |         {
7 |             "pk": 788,
8 |             ...
9 |         },
10|         {
11|             "pk": 789,
12|             ...
13|         },
14|         ....
15|     ]
16| }

Uanataca provides different certificate profiles for different purpose.

Each profile has their set of fields and each field can be mandatory or not.

Certificate of a natural person issued on a cryptographic container in P12 format and intended for authentication and electronic signature.

Certificate of a natural person issued on a smartcard or a cryptographic token and intended for authentication and electronic signature.

Certificate of a natural person issued in the centralized custody system of Uanataca certificates and intended for authentication and electronic signature.

Certificate of a natural person issued in the centralized custody system of Uanataca certificates and intended for authentication and qualified electronic signature.

Certificate of a natural person belonging to an organization or company issued on cryptographic token in P12 format and intended for authentication and electronic signature.

Certificate of a natural person belonging to an organization or company issued on a smartcard or cryptographic token and intended for authentication and eltronic signature.

Certificate of a natural person belonging to an organization or company issued in the centralized custody system of Uanataca certificates and intended for authentication and electronic signature.

Certificate of a natural person belonging to an organization or company issued in the centralized custody system of Uanataca certificates and intended for authentication and qualified eltronic signature.

Certificate of a registered individual, for authentication and electronic signature issued in cryptographic container format P12.

Certificate of a registered individual, for authentication and electronic signature issued on a cryptographic card or token.

Certificate of a registered individual, for authentication and electronic signature issued in the centralized custody system of Uanataca certificates.

Certificate of a registered individual, for authentication and qualified electronic signature issued in the centralized custody system of Uanataca certificates.

Certificate of legal entity representative, suitable for the relationship between Spanish or European companies, for authentication and electronic signature issued in cryptographic container format P12.

Certificate of legal entity representative, suitable for the relationship between Spanish or European companies, for the electronic signature issued on a cryptographic card or token.

Certificate of representative of legal entity, suitable for the relationship between Spanish or European companies, for the qualified electronic signature, and issued in the centralized custody system of Uanataca certificates.

Certificate of the legal entity representative issued on a cryptographic container in P12 format and intended for authentication and electronic signature.

Certificate of the legal entity representative issued in the centralized custody system of Uanataca certificates and intended for authentication and electronic signature.

Certificate of the legal entity representative issued on a smartcard or on a cryptographic token and intended for authentication and electronic signature.

Certificate of representative of legal entity, suitable to interact with Spanish Public Administrations, issued in the centralized custody system of Uanataca certificates and intended for authentication and qualified electronic signature.

Certificate of public employee of a Spanish Public Administration, issued on a cryptographic container in P12 format and intended for authentication and electronic signature.

Certificate of public employee of a Spanish Public Administration, issued on a smartcard or a cryptographic token and intended for electronic signature.

Certificate of public employee of a Spanish Public Administration, issued in the centralized custody system of Uanataca certificates and intended for the qualified electronic signature.

Certificate of representative of entity without legal license issued on a cryptographic container in P12 format and intended for authentication and electronic signature.

Certificate of representative of entity without legal license issued in the centralized custody system of Uanataca certificates and intended for authentication and electronic signature.

Certificate of representative of entity without legal license issued on a smartcard or on a cryptographic token and intended for authentication and electronic signature.