UANATACA RA API DOCUMENTATION (v1)

1 UANATACA RA API DOCUMENTATION (v1)
2 What it is
3 How it works
4 Glossary
5 Classic Workflow
6 Video ID Workflows
- 6.1 eIDAS VideoID
- 6.2 External Mode
7 Webhook Configuration
8 Endpoint URLs
9 Authentication
10 Responses
- 10.1 HTTP Status Codes
- 10.2 Pagination
11 Certificate Profiles
- 11.1 Europe (eIDAS)
  - 11.1.1 PFSoftAFCiudadano
- 11.2 PFqscdCiudadano
- 11.3 PFnubeAFCiudadano
- 11.4 PFnubeQAFCiudadano
- 11.5 PFSoftAFEmpresa
- 11.6 PFqscdEmpresa
- 11.7 PFnubeAFEmpresa
- 11.8 PFnubeQAFEmpresa
- 11.9 PFSoftAFColegiado
- 11.10 PFqscdColegiado
- 11.11 PFnubeAFColegiado
- 11.12 PFnubeQAFColegiado
- 11.13 REPsoft
- 11.14 REPqscd
- 11.15 REPnubeQ
- 11.16 REPPJsoft
- 11.17 REPPJnube
- 11.18 REPPJqscd
- 11.19 REPPJnubeQ
- 11.20 EMPUBsoft
- 11.21 EMPUBqscd
- 11.22 EMPUBnubeQ
- 11.23 REPESPJsoft
- 11.24 REPESPJnube
- 11.25 REPESPJqscd
- 11.26 REPESPJnubeQ
- 11.27 SELLOPJnube
- 11.28 SELLOPJsoft
- 11.29 SELLOPJnubeQ
- 11.30 SELLOPJqscd
- 11.31 SELLOMedio
- 11.32 SELLOAlto
- 11.33 SelloOrganoAltoNubeQ
- 11.34 Peru
- 11.35 PEPNCiudadano
- 11.36 PEPNPerteneciente
- 11.37 PEPNRepresentante
- 11.38 PEPNColegiado
- 11.39 PEFacturacion
- 11.40 PESElectronico
- 11.41 Global
- 11.42 PFSoftNC
- 11.43 PFnubeNC
- 11.44 SELLOsoftNC
- 11.45 SELLOnubeNC
- 11.46 REPnubeNC
- 11.47 REPsoftNC
12 Postman collection
13 API Reference

What it is

The Registration Authority (RA) solution to manage the entire digital certificates life cycle.

The service facilitates the automation of processes through integration via API, allowing you to incorporate the process of issuing digital certificates into your business flows or procedures.

The issuance of digital certificates generates 100% paperless. All information related with the registration and contract issuance is electronically signed and saved in the system to avoid storing physical documentation for years.

How it works

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.

Glossary

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.

Classic Workflow

The following image summarizes the common digital certificate request and issue flow:

An end user requests a digital certificate to the Registration Authority (RA)
A Registration Authority Officer (RAO) identifies the user and requests the required documentation
The user sends the required documentation according to the certificate profile
The RAO creates a digital certificate request
The response returns a request ID
The RAO uploads the required documentation according to the request
The RAO verifies all request data and documentation
The RAO checks declaration and signs service contract.
The RAO approves the digital certificate request to allow the certificate issue
The user receives an email with a link to start the certificate generation process
The user access to the online digital certificate generation process
During the process, the service contract is shown to the user
An OTP code is sent to the user via sms
The user inserts the OTP code and creates a custom PIN
The certificate is generated and the service contract is signed by the user
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:

CREATION OF A REQUEST
UPLOAD DOCUMENTS
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

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.

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

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
}'

Video ID Workflows

eIDAS VideoID

This workflow defines the complete process of issuing eIDAS certificates.

This certificate generation process involves the following steps:

CREATION OF A REQUEST
VIDEO IDENTIFICATION
VALIDATION OF VIDEO IDENTIFICATION EVIDENCES
UPDATE OF REQUEST (OPTIONAL)
DOCUMENTS UPLOAD (OPTIONAL)
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"
}

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 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",
      (...)
    }
  }
}

External Mode

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

CREATION OF A REQUEST
UPLOAD EVIDENCES
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 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 \
    -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://lima.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 APPROVAL

For unsuccessful validations leading to a request refusal, the corresponding call is Refuse Request. Check API Reference. 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.

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.

OPTIONAL

API Reference: Get Request to consult any information about the request.

API Reference: Download video to download the video recorded and uploaded in the identification part.

Webhook Configuration

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 parameter in the Create Video ID Request call. Keep in mind that the webhook via parameter is just for demo purposes. You will have to contact your officer to set a webhook in your RA.

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);

?>

Endpoint URLs

Uanataca expose its API on urls composed as follows:

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

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

Uanataca host

The host changes according to the environment:

api.sandbox.uanataca.com for sandbox environment
lima.sandbox.uanataca.com for sandbox environment(only for external videoid flow)
api.uanataca.com for production environment
lima.uanataca.com for production environment(only for external videoid flow)

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/

Authentication

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

Responses

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:

key	Description

key	Description
error	A string that describe the error occured
code	The HTTP response code related. See table descriptions
id	The unique identifier of the error generated by Uanataca

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

HTTP Status Codes

Code	Description

Code	Description
200	Everything went OK. The server elaborated correctly the request and returned the response to the client.
201	The object is successfully Created with the parameters sent by the client.
202	The request sent by the client has been Accepted and is under process.
204	No Content. The operation was successful but no content is provided in the response body.
400	Bad Request. The parameters sent, are not well formatted or are missing.
401	Unauthorized. The user used for making the request is not authorized to consume that resource.
403	Forbidden.The user used for making the request has no permissions to do it.
404	The resource requested is Not Found.
405	Method not allowed. The endpoint called has not the method specified.
412	Precondition Failed. The operation has some requirements that are not satisfied. For example if a Request is in a wrong state for the operation requested.
429	Too Many Requests.
500	Internal Server Error. An error occured during the elaboration of the request.
502	Bad Gateway.
503	Service Unavailable.

Pagination

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:

Key	Description

Key	Description
count	Represents the number of object found
next	Represents the url of the next page (it is null if there are no more pages)
previous	Represents the url of the previous page (it is null if there are no more pages)
result	Contains a list of objects found

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

Certificate Profiles

Uanataca provides different certificate profiles for different purpose.

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

Europe (eIDAS)

Profile	Description	Element

Profile	Description	Element
PFSoftAFCiudadano	Natural person	Software
PFqscdCiudadano	Natural person	Smartcard/Token
PFnubeAFCiudadano	Natural person	Cloud
PFnubeQAFCiudadano	Natural person	Cloud-QSCD
PFSoftAFEmpresa	Natural person belonging to an organization	Software
PFqscdEmpresa	Natural person belonging to an organization	Smartcard/Token
PFnubeAFEmpresa	Natural person belonging to an organization	Cloud
PFnubeQAFEmpresa	Natural person belonging to an organization	Cloud-QSCD
PFSoftAFColegiado	Natural person belonging to a professional association	Software
PFqscdColegiado	Natural person belonging to a professional association	Smartcard/Token
PFnubeAFColegiado	Natural person belonging to a professional association	Cloud
PFnubeQAFColegiado	Natural person belonging to a professional association	Cloud-QSCD
REPsoft	Natural person representative	Software
REPqscd	Natural person representative (signature only)	Smartcard/Token
REPnubeQ	Natural person representative (signature only)	Cloud-QSCD
REPPJsoft	Natural person representative of legal person with the administration	Software
REPPJnube	Natural person representative of legal person with the administration	Cloud
REPPJqscd	Natural person representative of legal person with the administration	Smartcard/Token
REPPJnubeQ	Natural person representative of legal person with the administration	Cloud-QSCD
EMPUBsoft	Public employee - Medium level	Cloud/Software
EMPUBqscd	Public employee signature - High level	Smartcard/Token
EMPUBnubeQ	Public employee signature - High level	Cloud-QSCD
REPESPJsoft	Natural person representative of entity without legal personality with the administrations	Software
REPESPJnube	Natural person representative of entity without legal personality with the administrations	Cloud
REPESPJqscd	Natural person representative of entity without legal personality with the administrations	Smartcard/Token
REPESPJnubeQ	Natural person representative of entity without legal personality with the administrations	Cloud-QSCD
SELLOPJnube	Electronic seal	Cloud
SELLOPJsoft	Electronic seal	Software
SELLOPJnubeQ	Electronic seal	Cloud-QSCD
SELLOPJqscd	Electronic seal	Smartcard/Token
SELLOMedio	Electronic seal – Medium Level APE	Cloud/Software
SELLOAlto	Electronic seal – High Level APE	Smartcard/Token
SelloOrganoAltoNubeQ	Electronic seal – High Level APE	Cloud-QSCD

PFSoftAFCiudadano

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

Field	Value	Description	Mandatory

Field	Value	Description	Mandatory
secure_element	1	Represents the device where the keys will be enrolled and can assume the values of 0, 1 or 2 that respectively are Software, Smartcard and Cloud. This profile only allows the smartcard element.	Yes
profile	PFqscdCiudadano	Represents the profile of the request	Yes
validity_time	[1,3,365,730,1095,1825]	It's the certificate validity expressed in days	Yes
registration_authority		The Registration Authority id	Yes
scratchcard		The scratchcard serial number that will be associated to the Request	Yes
smartcard_sn		The smartcard serial number	Yes
id_document_type	[IDC,PAS,PNO,TIN]	The cardholder Id Document Type. IDC - Identification based on national identity card number. PAS - Identification based on passport number. PNO - Identification based on (national) personal number (national civic registration number). TIN - Tax Identification Number according to the European Commission.	Yes
id_document_country	ISO 3166-1 alpha-2	The cardholder id document country	Yes
serial_number		The cardholder serial number	Yes
given_name		The cardholder given name	Yes
surname_1		The cardholder first surname	Yes
surname_2		The cardholder second surname	No
email		The cardholder email	Yes
mobile_phone_number		The cardholder mobile phone number	Yes
id_document_description		The cardholder document description	No
id_document_issuer		The cardholder document issuer	No
id_document_number		The cardholder document number	No
residence_address		The cardholder address of residence	No
residence_city		The cardholder city of residence	No
residence_province		The cardholder province of residence	No
residence		The cardholder country of residence	No
residence_postal_code		The cardholder postal code of residence

Uanataca-BES

UANATACA REGISTRATION AUTHORITY API

UANATACA RA API DOCUMENTATION (v1)

What it is

How it works

Glossary

Classic Workflow

Video ID Workflows

eIDAS VideoID

External Mode

Webhook Configuration

Endpoint URLs

Authentication

Responses

HTTP Status Codes

Pagination

Certificate Profiles

Europe (eIDAS)

PFSoftAFCiudadano