> For the complete documentation index, see [llms.txt](https://docs.identomat.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.identomat.com/identomat-documentation-ukr/posibnik-dlya-rozrobnikiv.md).

# Посібник для розробників

[Identomat](https://www.identomat.com/) — це сервіс, розроблений для перевірки **особи людини** та **живості** через Інтернет. Цей посібник передбачає, що інтегруюча організація (далі — *«компанія»*) має вебсервер (далі — *«сервер компанії»*) за адресою `example.com`.

### Передумови

Перед інтеграцією компанія має отримати `company_key` — облікові дані, що використовуються для безпечної комунікації між сервером компанії та сервером Identomat (`widget.identomat.com`).

{% hint style="info" %}
Ще немає `company_key`? Дивіться [**Доступ до API**](/identomat-documentation-ukr/pochatok-roboti/dostup-do-api.md), щоб дізнатися, як згенерувати його з вашої панелі керування Identomat.
{% endhint %}

**Необов'язкові функції безпеки, що налаштовуються під час генерації ключа або в будь-який час пізніше:**

* **HMAC-авторизація** — `secret_key` використовується для генерації та перевірки HMAC-підписів, додаючи додатковий рівень верифікації для запитів, надісланих із вашим `company_key`.
* **Білий список IP-адрес** — Обмежте `company_key` конкретним набором IP-адрес. Після додавання IP-адрес приймаються лише запити з цим ключем із адреси, що входить до білого списку; запити з будь-якої іншої IP-адреси відхиляються. Якщо список залишити порожнім, ключ можна використовувати з будь-якої IP-адреси. Обидва налаштування можна додавати, редагувати чи видаляти в будь-який час у тому ж розділі вашої панелі керування, де було згенеровано ключ.

Для підвищення безпеки компанії можуть за бажанням реалізувати **HMAC-авторизацію**. У цьому випадку `secret_key` використовується для генерації та перевірки HMAC-підписів для безпечної комунікації.

## Процедура

Процедура інтеграції складається з трьох основних кроків:

{% stepper %}
{% step %}
[**Отримання `session_token`.**](#otrimannya-tokena-sesiyi)
{% endstep %}

{% step %}
[**Перенаправлення браузера користувача на `widget.identomat.com`.**](#perenapravlennya-na-vidzhet-identomat)
{% endstep %}

{% step %}
[**Перевірка результату.**](#perevirka-rezultatu)
{% endstep %}
{% endstepper %}

### **Отримання токена сесії**

Щоб отримати `session_token`, ваш бекенд має надіслати запит до ендпоінту `/begin/` із такими параметрами:

* `company_key` – Ваш унікальний ідентифікатор компанії.
* `flags` – Об'єкт JSON, що визначає глобальні налаштування для сесії верифікації.
* `steps` – Масив, що вказує кроки, які потрібно включити у потік верифікації. Кожен крок може мати власні прапорці (flags), специфічні для цього кроку.

> ⚠️ `session_token` дійсний протягом **15 хвилин** за замовчуванням.

**Ендпоінт:**

```nginx
POST https://widget.identomat.com/begin/
```

Запити можна надсилати як:

* **Параметри URL-запиту**
* **Дані форми, закодовані в URL**
* **Об'єкт JSON** у тілі запиту (рекомендовано)

#### **Структура Steps та Flags**

* `flags`: Визначає глобальну поведінку для всієї сесії.
* `steps`: Дозволяє повний контроль над процесом верифікації, надаючи можливість вказати **які кроки включити** (наприклад, `liveness`, `identity-document`) та налаштувати **прапорці, специфічні для кроку**, такі як `"allow_face_upload": true` для кроку `liveness`.

{% hint style="info" %}
Щоб забезпечити сумісність між старим та новим методами, які мають працювати разом, вам слід використовувати прапорці `'skip_face'` та `'skip_document'` при використанні steps.

Ці прапорці запобігають дублюванню кроків 'identity-document' та 'liveness', якщо вони вже існують у потоці.
{% endhint %}

**Використання конфігурації або власних кроків**

Ви можете ініціювати сесію двома способами:

* **Через попередньо визначену конфігурацію (рекомендовано):**
  * Ми наполегливо рекомендуємо використовувати **попередньо визначені конфігурації** через параметр `config_id`. Конфігурації забезпечують узгодженість, спрощують інтеграцію та зменшують ризик помилок. Використання конфігурацій також дозволяє нам у майбутньому припинити підтримку застарілої обробки власних кроків, допомагаючи клієнтам підтримувати чисту та стабільну інтеграцію.
* **Через власні кроки та прапорці**:\
  Використовуйте власні кроки та прапорці лише якщо у вас є дуже специфічні потреби, які неможливо задовольнити за допомогою конфігурацій. Із часом ми рекомендуємо переносити всі власні потоки на конфігурації.

{% hint style="warning" %}
**Чому конфігурації важливі:**

* **Спрощує створення сесії** — не потрібно вручну визначати кроки та прапорці.
* **Зменшує ризик помилок** у потоці верифікації.
* **Захищено від застарівання** — застаріла обробка власних кроків з часом буде припинена.
* Дозволяє Identomat ефективно **підтримувати**, **покращувати** та **оптимізувати потоки**.
* Полегшує **інтеграцію**.
  {% endhint %}

{% hint style="info" %}
📘 Для детальних визначень параметрів та прикладів див. [**Довідник API.**](/identomat-documentation-ukr/dovidnik-api.md)
{% endhint %}

### Перенаправлення на віджет Identomat

Щоб розпочати сесію верифікації, сервер компанії має перенаправити браузер користувача на:

```
https://widget.identomat.com/?session_token={session_token_here}
```

Замініть `{session_token_here}` на фактичний токен, отриманий від ендпоінту `/begin/`.

### Вбудовування в Iframe

Альтернативно, віджет можна вбудувати в iframe:

```html
<iframe
    height=“100dvh”
    width=“100%”
    src="https://widget.identomat.com/?session_token={session_token_here}"
    allow="camera">
</iframe>
```

{% hint style="warning" %}
Атрибут `allow="camera"` є обов'язковим для надання доступу до камери. Без нього кроки верифікації, що залежать від камери, не працюватимуть.
{% endhint %}

### **Перевірка результату**

Після завершення процесу верифікації результат можна визначити двома способами, залежно від того, як було інтегровано віджет:

* **Якщо використовується перенаправлення**\
  Якщо ви використовували підхід із перенаправленням (не вбудований в iframe), користувача буде перенаправлено на `return_url`, вказаний у налаштуваннях конфігурації чи прапорцях сесії, із доданим параметром запиту `session_token`.

```
https://yourapp.com/?session_token=abc123xyz
```

* **Якщо вбудовано в iframe**, завершення процесу можна визначити за допомогою JavaScript:

```javascript
addEventListener('message', function (e) {
    if (e.origin !== 'https://widget.identomat.com') return;
    if (e.data !== 'DONE') return;
    // Process completed, handle results here
});
```

{% hint style="success" %}
Обов'язково перевіряйте `origin` повідомлення, щоб уникнути ризиків безпеки.
{% endhint %}

***

## Швидкі посилання

Отримайте доступ до детальних посібників для розробників щодо потоків **KYC (Know Your Customer)** та **KYB (Know Your Business)**. Натисніть на картку нижче, щоб дослідити конфігурацію, кроки інтеграції та найкращі практики для кожного типу верифікації.

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>KYC (Know Your Customer)</strong><br><br>Дізнайтеся, як збирати та перевіряти дані окремих користувачів, налаштовувати кроки верифікації та інтегрувати потоки KYC.</td><td></td></tr><tr><td><p><strong>KYB (Know Your Business)</strong></p><p><br>Дізнайтеся, як збирати та перевіряти дані компанії, бенефіціарів та представників, за допомогою настроюваних кроків верифікації.</p></td><td></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.identomat.com/identomat-documentation-ukr/posibnik-dlya-rozrobnikiv.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.