# VIA Integration

VIA is a communication management system designed for SMS and email permission management. It allows users to configure and oversee these services by integrating Netmera's platform with external messaging APIs. For more details about VIA, visit their website [here](https://via.iletiys.com.tr/).

### **VIA Services Netmera Panel Configuration**

1. Navigate to **Netmera Panel > Connectors > Installed > IYS**.
2. Set the correct IYS configuration:
   * Fill in the **Brand** and **IYS Codes** fields with the values obtained from IYS.
3. Enable the VIA feature by selecting the **Via Enabled** checkbox.

<div align="left"><figure><img src="https://2578508252-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0bOAscrXzPSujyzq8DEz%2Fuploads%2FhWHArzE70hAqKUNNxYHQ%2FScreenshot%202025-01-23%20at%2017.30.43.png?alt=media&#x26;token=e22db51f-0b91-48db-8c4a-aa2e559b05a7" alt="" width="298"><figcaption><p>Connectors</p></figcaption></figure> <figure><img src="https://2578508252-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0bOAscrXzPSujyzq8DEz%2Fuploads%2Fhco74Ux4oQLDgMRhCsyQ%2FScreenshot%202025-01-15%20at%2015.35.03.png?alt=media&#x26;token=d25330d7-cbcc-40b8-9cd6-8ad191122266" alt="" width="375"><figcaption></figcaption></figure></div>

{% hint style="info" %}
**Incorrect Configuration:**

If the configuration is incorrect or the checkbox is not enabled, REST service responses will return with the following errors:

**Error Code: 400 - Bad Request**

```json
validationError: IYS config is invalid for appKey
validationError: Via service is inactive for appKey
```

{% endhint %}

## SMS & Email Permission Management with VIA Integration

You can obtain user consent or decline for SMS and email preferences in two ways when using VIA integration:

**1. Consent Management via Short URL**

* Use the form created in the IYS panel to send a short URL to users, allowing them to manage their SMS or email preferences.

**2. Consent Management via One-Time Password (OTP)**

* Use the form created in the IYS panel to send an OTP to users, enabling them to confirm their SMS or email preferences.

{% hint style="danger" %}
**IYS Form Creation**

1. **Create Separate Forms**

   While you can obtain SMS and email permissions simultaneously through the same OTP or short URL, forms for **Short URL** and **OTP Consent** must be created independently. A single combined form that includes both Short URL and OTP is **not permitted**.
2. **Use the IYS Panel for Form Generation**

   Forms must be generated directly through the **IYS panel**. Netmera does not support form creation, as this process is exclusively managed by IYS.
   {% endhint %}

## <mark style="color:green;">Short URL Consent Flow</mark>

<figure><img src="https://2578508252-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0bOAscrXzPSujyzq8DEz%2Fuploads%2Fx6neFK6gyyNViUkPIard%2FScreenshot%202025-01-27%20at%2016.21.12.png?alt=media&#x26;token=8fff27cf-7924-45e1-b4d1-b76beb1ee09e" alt=""><figcaption></figcaption></figure>

For a full version, please see the board [here](https://miro.com/app/board/uXjVLpw19Ro=/?share_link_id=564915471499).

{% stepper %}
{% step %}

#### **Prepare the Short URL Consent Form**

Prepare a Short URL consent form using your IYS Panel. Once the form is ready, submit it to IYS for approval.
{% endstep %}

{% step %}

#### Obtain IYS Approval

After IYS approves the form, it will be available for use in API calls. The form ID provided by IYS will serve as the `formId` value in your requests.
{% endstep %}

{% step %}

#### Send the Consent Form to the User

Send the consent form link to your users via email or SMS. Use the API endpoint  `https://restapi.netmera.com/via/consent` to share the link with your users.
{% endstep %}

{% step %}

#### User Submits Their Consent

When the user receives the link, they can open the form, select their SMS or email permissions, and submit their approval.
{% endstep %}

{% step %}

#### Confirmation Information Sent to the User

After the user submits their consent, they will receive a confirmation via email or SMS informing them of the permissions they selected and their submission status.
{% endstep %}

{% step %}

#### Consent Data Saved in Netmera

Netmera saves the user permissions in the Netmera Panel. This synchronization occurs every 10 minutes to ensure the latest user preferences are reflected.
{% endstep %}
{% endstepper %}

## <mark style="color:green;">OTP Consent Flow</mark>

<figure><img src="https://2578508252-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0bOAscrXzPSujyzq8DEz%2Fuploads%2FpN5OY1SSW5vR6UNj3JNk%2FScreenshot%202025-01-23%20at%2017.56.44.png?alt=media&#x26;token=111bc75f-cbad-4a59-baee-9fd58cab3e38" alt=""><figcaption></figcaption></figure>

For a full version, please see the board[ ](https://miro.com/app/board/uXjVLp-u5qA=/?share_link_id=530031837291)[here](https://miro.com/app/board/uXjVLp-u5qA=/?share_link_id=530031837291).

{% stepper %}
{% step %}

#### **Prepare the OTP Consent Form**

Create an OTP consent form using your IYS Panel. Once the form is ready, submit it to IYS for approval.
{% endstep %}

{% step %}

#### Obtain IYS Approval

After IYS approves the form, it will be ready for use in API calls. The form ID provided by IYS will serve as the `formId` value in your requests.
{% endstep %}

{% step %}

#### Send the Consent Form to the User

Send an email or SMS to the user containing the OTP code. Use the API endpoint `https://restapi.netmera.com/via/consent` to share the code with the user.
{% endstep %}

{% step %}

#### User Submits Their Consent

The user enters the OTP code they received. Use the API endpoint `https://restapi.netmera.com/via/confirm` to submit the OTP.
{% endstep %}

{% step %}

#### Confirmation Information Sent to the User

The user will receive a confirmation via email or SMS, detailing the permissions they selected and the status of their submission.
{% endstep %}

{% step %}

#### Consent Data Saved in Netmera

Netmera automatically saves the user’s permissions in the Netmera Panel. Synchronization occurs every 10 minutes to ensure the latest user preferences are reflected.
{% endstep %}
{% endstepper %}

## VIA Consent API Parameters&#x20;

**Request Body Field Parameters**

<table><thead><tr><th width="202">Field</th><th>Required</th><th width="389">Description</th></tr></thead><tbody><tr><td><code>title</code></td><td>Yes</td><td>Describes the type of consent being requested. For ETK consent, use ETK.</td></tr><tr><td><code>types</code></td><td>Yes</td><td>Specifies the communication channels from which consent will be requested:</td></tr><tr><td></td><td></td><td>For ETK: <code>"ARAMA"</code>, <code>"MESAJ"</code>, <code>["ARAMA", "MESAJ"]</code>, <code>["MESAJ", "ARAMA"]</code>, <code>"EPOSTA"</code></td></tr><tr><td></td><td></td><td>For KVKK: <code>"AYDINLATMA_METNI"</code>, <code>"ACIK_RIZA_METNI"</code>, <code>"YURTDISI_AKTARIM"</code></td></tr><tr><td><code>recipientType</code></td><td>Yes</td><td>Specifies the type of user from whom consent is being obtained: <code>BİREYSEL</code> or <code>TACIR</code>.</td></tr><tr><td><code>formId</code></td><td>Yes</td><td>The ID of the consent form to be sent to the recipient, it must obtained from the VIA Management interface.</td></tr><tr><td><code>recipient</code></td><td>Yes</td><td>The recipient’s phone number (must be with format: +90...) or email address where the consent request is sent.</td></tr><tr><td><code>verificationType</code></td><td>Yes</td><td>Specifies the method for obtaining consent and it could be set as:<code>"SMS_OTP"</code>, <code>"EPOSTA_OTP"</code>, <code>"EPOSTA_SHORTURL"</code>, <code>"SMS_SHORTURL"</code>, <code>"EPOSTA_APPROVALURL"</code>.</td></tr><tr><td><code>referenceID</code></td><td>Yes</td><td>This identifier is used to create or update user records in the Netmera system.</td></tr><tr><td><code>name</code></td><td>Required for KVKK</td><td>Recipient’s first and last name.</td></tr><tr><td><code>recipientIdNumber</code></td><td>Required for KVKK</td><td>The recipient’s Turkish Identity Number (TC Kimlik).</td></tr><tr><td><code>address</code></td><td>Required for KVKK</td><td>Recipient's address details.</td></tr><tr><td><code>personData</code></td><td>Required for KVKK</td><td>Object containing the recipient’s <code>name</code> and <code>recipientIdNumber</code>.</td></tr></tbody></table>

**Response Body Fields**

<table><thead><tr><th width="194">HTTP Code</th><th width="150">Field</th><th>Description</th></tr></thead><tbody><tr><td><strong>200</strong></td><td><code>requestId</code></td><td>Used to query the status of the request or confirm the OTP scenario.</td></tr><tr><td><strong>400</strong></td><td><code>message</code></td><td>Error message detailing the issue.</td></tr><tr><td></td><td><code>code</code></td><td>Error code returned by the IYS system.</td></tr><tr><td></td><td><code>value</code></td><td>The problematic value, depending on the error type.</td></tr><tr><td><strong>500</strong></td><td><code>message</code></td><td>Error while parsing the data.</td></tr></tbody></table>

## User Update or Create with ReferenceID

The `ReferenceID` is a **mandatory** **field** provided you, used to uniquely identify and differentiate users within the system. It plays a crucial role in user creation and ensures proper user management within the platform.

{% hint style="info" %}
**If the Reference ID is not provided:**

If the `ReferenceID` is not provided in a request, the system will return a **400 Bad Request** with the message: *“ReferenceID is empty”*.

```json
{
  "message": "referenceId is empty",
  "status": 400
}
```

{% endhint %}

**User Lookup with Email**

* The system first attempts to locate a user using only the **email address** (without the `ReferenceID`). This helps to identify previously existing users within the Netmera platform.
* If the user is found, their **consent status** is **updated** based on the information in the response (e.g., “Onay verildi” or “Onay verilmedi” indicating consent granted or not).

**User Lookup with MSISDN**

* If the user is not found using the email, the system then attempts to locate the user using their **MSISDN** (mobile number).
* If no user is found by MSISDN, the system will resort to searching by **ReferenceID**.

**ReferenceID Handling**

* If the **ReferenceID** is found, it indicates that the user has already been created, likely through the **Via channel** (e.g., as an email user). The system will then update the user’s **MSISDN** and **consent status** accordingly.

**When a User Does Not Exist with `ReferenceID`**

If no user is found for the given **ReferenceID**, the system will create a new user using the identifier provided with permission (either **email** or **MSISDN**).

* If only **email** is provided, the system will create a user with an email and set MSISDN as **false**.
* If only **MSISDN** is provided, the system will create a user with an MSISDN and set email as **false**.
* If both are provided, the system will create a user **with both identifiers.**
* The system will then store  the `ReferenceID` as a **profile attribute**.

<details>

<summary>User Creation Flow: Possible Scenarios and Outcomes</summary>

**1. Email User Creation**\
If the user has never been an email user in Netmera and grants email permission, a new email user is created.

**2. MSISDN User Creation**\
If the user has never been an MSISDN user in Netmera and grants MSISDN permission, a new MSISDN user is created.

**3. New Email User Creation When Only MSISDN Permission is Granted**\
If the user was previously an email user in Netmera but only grants MSISDN permission, a new email user is created. (Since there is no reference ID to determine which user corresponds to which, scenario 6 applies if email permission is granted later.)

**4. New Email User Creation When Only Email Permission is Granted**\
If the user was previously an MSISDN user in Netmera but only grants email permission, a new email user is created. (Since there is no reference ID to determine which user corresponds to which, scenario 6 applies if MSISDN permission is granted later.)

**5. Single User Creation for Both Email and MSISDN Permissions**\
If the user has never been an email or MSISDN user in Netmera and grants both email and MSISDN permissions, a single user is created to store both permissions.

**6. Merging Users When Email Exists and MSISDN is Newly Granted**\
If the user was previously an email user but not an MSISDN user, and both email and MSISDN permissions are granted (with the MSISDN request arriving first), the user is merged into a single entity. (There is no duplication of the existing email user.)

**7. Updating Permissions for Existing Email Users**\
If the user was previously an email user and only grants email permission, the existing user’s permissions are updated instead of creating a new user.

**8. Updating Permissions for Existing MSISDN Users**\
If the user was previously an MSISDN user and only grants MSISDN permission, the existing user’s permissions are updated instead of creating a new user.

</details>