# TruIdentidad Integration Guide
{{<tags>}}

Welcome to the **TruIdentidad** Integration Guide! Follow these steps to seamlessly integrate our face validation solution with **Registraduria** for secure and efficient user validation.

## Prerequisites

1. **Account Creation:** In order to perform an integration in any of our services, you must have a Truora account. Your Truora sales representative will provide you with one, or you can create one for free.
   - To create a free account please visit **https://account.truora.com/#/create-account**.
   - To log into your existing account at **https://account.truora.com/#/auth/login**.

2. **Create a Troura API Key:** In order to perform an integration in any of our services, you must have a Truora API key. Follow this guide to create your [**Truora API key**](/digital-identity/authentication/).

3. **Request Integration with Registraduria:** Contact your Truora sales representative to request access to Registraduria integration. If you do not have a sales representative please [**Contact Us**](https://wa.link/8tdr7i).

4. **Approval and Client ID:** Your request should be evaluated and approved before continuing.
-------------------------
## How are the Registraduria validations performed?
1. **Validation Initiation:** The user clicks the **Create Validation** button on your frontend to initiate a validation request.
2. **Backend Processing:** The validation request triggers backend processing to create the associated validation in the TruIdentidad API.
3. **TruIdentidad Web SDK:** Pass the obtained SessionID to the TruIdentidad Web SDK for Registraduria validation.
4. **Web Adapter Communication:** The TruIdentidad Web SDK sends a request to the TruIdentidad Web Adapter, which communicates with the TruIdentidad API.
   {{<img src="/images/illustrations/truidentidad/validations_performed_flow.png" alt="validators result" width="90%" class="rounded-md">}}
-------------------------
## Integration
The TruIdentidad solution will integrate via API, WEB, IOS and Android SDK allowing you to validate a user against Registraduria. For more details about integration, please visit the available guides.

### API - Create Validation
1. Create a `POST` request to **Create Validation** endpoint: `https://api.validations.truora.com/v1/validations`.
2. Add the next headers
   - `Truora-API-Key` : <<value>> [**Get a Truora API key**](/digital-identity/authentication/).
   - `Content-Type` : application/x-www-form-urlencoded
3. Add the following params in the request body with their respective values
   - `type` : government
   - `account_id` : <<value>> Note that only Account IDs following the regex pattern [a-zA-Z0-9_.-]+ are supported. 
      Please go to [Create an Account ID](/guides/account_id/) to learn more about it.
   - `redirect_url`: "https://www.truora.com/redirect" redirection URL once liveness is finished.
   - `user_authorized`: "true" user gave consent.
   - `nuip`: "1234567892" document number of the person to capture liveness.

4. After the Validation is created, you will receive a response similar to the following, in JSON format:
{{<code lang="json" lang_title="Response 200">}} 
  {
    "validation_id": "VLD_01HNN9P63DD0WXMRB3VR59DPFY",
    "account_id": "ACC_01HNN9P63DD0WXMRB3VPRMVAA6",
    "status": "pending",
    "reason": "processing",
    "creation_date": "2024-02-02T16:16:05.741624Z",
    "type": "government",
    "processing_date": "2024-02-02T16:19:27.004017Z",
    "details": {
        "session_id": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
        "nuip": "1234567892"
    }
}
{{</code>}}

**Note:** Please save the `validation_id` and `session_id` value from the response, as you will need it in subsequent steps.

### WEB SDK
1. Follow the steps explained in the [**Create Validation**](/guides/truidentidad/#api---create-validation) section.
2. Download and integrate the SDK using a script on your website. Below, we provide an example using HTML and JavaScript.

{{<code lang="html" lang_title="Example">}}
 <!DOCTYPE html>
    <html lang="en">
    <head>
    	<meta charset="UTF-8">
    	<meta name="viewport" content="width=device-width, initial-scale=1.0">
    	<title>SDK Integration</title>
    	<script type="module" src="https://sdk.truora.com/truorasdk.js"></script>
    	<link rel="stylesheet" crossorigin href="https://sdk.truora.com/truorasdk.css">
    </head>
    <body>
    	<div id="app"></div>
    
    	<script>
        	window.TruoraSDK.init({
            	element_id: 'app',
            	session_id: sessionID,
            	on_complete: (result) => {
                	console.log("on_complete", result);
            	},
            	on_expired: (result) => {
                	console.log("on_expired", result);
            	},
            	on_error: (err) => {
                	console.error("on_error", err);
            	}
        	});
    	</script>
    </body>
    </html>
{{</code>}}

  - **Note:** The `session_id` requested at this point refers to the `session_id` obtained in the previous section [**Create Validation**](/guides/truidentidad/#api---create-validation).

3. Use the `on_complete` and `on_expired` events to know when to check the validation result. For more information on how to obtain the results, please refer to the [**Getting Results**](/guides/truidentidad/#polling---get-validation) section later in this same guide.
   `on_error` triggers when an error occurs when trying to capture the liveness input.
-------------------------
## Result Retrieval

### General approach
- **Polling for Processing Status:** The frontend component should perform polling to obtain the processing status of the validation.
- **Result Retrieval:** Once processing is complete, your backend should make a call to obtain the result. 
- **Display Results:** Display success or failure views in your secure environment based on the obtained result.

### Getting Results
Fetch validation current state. The `validation_status` can either be `success` or `failure` at the end of the validation. In the meantime, it will be `pending`.

- Pending occurs when the validation is being processed. 
- Success occurs when the face was successfully recognized in the video. 
- Failure can occur due to an internal error, a timeout, or if the face recognition is declined.

**Note:** You need the validation_id from the  Create Validation request.

Results can be obtained by either Dashboard, or doing Polling; all processes are explained below.

#### Polling - Get Validation
1. Create a `GET` request to **Create Validation** endpoint: `https://api.validations.truora.com/v1/validations/{validation_id}`.
2. Add the next headers
    - `Truora-API-Key` : <<truora api key>> [**Get a Truora API key**](/digital-identity/authentication/).
    - `Content-Type` : application/x-www-form-urlencoded
3. Add the following path params in the request with their respective values
   - `validation_id` :  <<value>>

**Note:** The `validation_id` requested at this point refers to the `validation_id` obtained in the [**Create Validation**](/guides/truidentidad/#api---create-validation) request.

4. You will receive a response similar to the following, in JSON format:
{{<code lang="json" lang_title="Response 200">}}
   {
    "validation_id": "VLD_01HNN9P63DD0WXMRB3VR59DPFY",
    "account_id": "ACC_01HNN9P63DD0WXMRB3VPRMVAA6",
    "status": "pending",
    "reason": "processing",
    "creation_date": "2024-02-02T16:16:05.741624Z",
    "type": "government",
    "processing_date": "2024-02-02T16:19:27.004017Z",
    "details": {
        "nuip": "1234567892"
    }
}
{{</code>}}

- Please note that this validation will only inform you whether it is successful or not. No user information will be provided.

#### Front (Dashboard)
1. From the Truora’s Dashboard you can filter the results of a Validation by the validation_id. This is a unique identifier assigned to each Validation.
   {{<img src="/images/illustrations/truidentidad/products.png" alt="products" width="90%" class="rounded-md">}}
2. To see the result of each validation you need to go to **Digital Identity Verification** > **Validation Results**.
   {{<img src="/images/illustrations/truidentidad/di_dashboard.png" alt="di dashboard" width="90%" class="rounded-md">}}
3. This will redirect you to a dashboard where you can review the results of the validations performed by your users.
   {{<img src="/images/illustrations/truidentidad/validators_result.png" alt="validators result" width="90%" class="rounded-md">}}

### Declined and Expired reasons
Whenever a validation fails due to inconsistencies in the validation process or expires in the validation process, the API provides a reason to indicate why the validation was declined or expired:
- To learn more about the possible declined reasons, please visit the [**Declined Reasons**](/guides/declined_reasons_details/) guide.
- To learn more about the possible expired reason, please visit [**Expired Reasons**](/guides/expired_reasons_details/) guide.
-------------------------
## User Validation Journey
The following flow illustrates the steps a user must take once they access the identity validation required by your entity to access your products or services. The process consists of the following steps:
1. Introduction to provide clarity of the process to the user. 
2. Data Processing Policy screen.
   {{<img src="/images/illustrations/truidentidad/policy_screen.gif" alt="validators result" width="20%" class="rounded-md">}}
3. Permission acceptance to access geolocation data.
   {{<img src="/images/illustrations/truidentidad/geolocation_screen.gif" alt="validators result" width="20%" class="rounded-md">}}
4. Screens for acquiring video for the purpose of performing a liveness test.
   {{<img src="/images/illustrations/truidentidad/face_screen.gif" alt="validators result" width="20%" class="rounded-md">}}
5. Validation result screen.
      {{<img src="/images/illustrations/truidentidad/result_screen.gif" alt="validators result" width="20%" class="rounded-md">}}
- **Note:** In the case of Web SDK integration, the user will be given the option to complete the process from a desktop or a mobile device.