Перейти до змісту

Конфігурація профілю співробітника (Employee Profile Definition)

Конфігурація профілю — це схема, яка описує структуру Профілю співробітника V2: які блоки та поля компанія налаштувала у своїй анкеті, їхні типи, валідації та доступні варіанти значень.

Ендпоінт повертає активну версію конфігурації для компанії, до якої прив'язаний публічний токен. Використовуйте його, щоб дізнатися block_definition_id та field_definition_id, які потрібні для PUT/PATCH запитів до профілю співробітника, а також щоб коректно зіставити ваші дані з налаштуваннями компанії.

API ендпоінт

  • GET /api/public/v2/company/employee-profile-definition — отримати активну конфігурацію профілю для компанії токена.

Запис/оновлення конфігурації через публічне API не підтримується — ендпоінт доступний лише для читання.

Автентифікація

Запит потребує заголовок:

X-Vchasno-Public-Token: <ваш_токен>

Токен прив'язаний до конкретної компанії — ендпоінт повертає конфігурацію саме цієї компанії, без параметра company_id у шляху.

Детальніше про отримання токена: getting_started.md

Рекомендований процес використання

  1. Отримайте конфігурацію — виконайте GET /api/public/v2/company/employee-profile-definition, щоб дізнатися структуру блоків і полів компанії.
  2. Закешуйте результат — конфігурація рідко змінюється. Використовуйте version або version_identifier на рівні блоку/поля для інвалідації кешу.
  3. Використовуйте отримані block_definition_id та field_definition_id у запитах до профілю співробітника: PUT/PATCH /api/public/v2/employee/{employee_id}/profile.

Структура відповіді

Відповідь обгорнута в об'єкт ResponseModel:

{
  "detail": {
    "id": "…",
    "version": 3,
    "company_id": "…",
    "blocks": [ … ]
  }
}

Верхній рівень (detail)

Поле Тип Опис
id UUID Унікальний ідентифікатор активної конфігурації
version integer Номер версії конфігурації компанії (інкрементується при кожному оновленні)
company_id UUID ID компанії, якій належить конфігурація (збігається з компанією токена)
blocks array Масив визначень блоків у порядку відображення

Об'єкт блоку (blocks[])

Поле Тип Опис
id UUID ID визначення блоку (block_definition_id для запитів до профілю)
version_identifier UUID Стабільний ідентифікатор блоку, що зберігається між версіями
version integer Версія цього блоку
name string Назва блоку (напр. "Особисті дані", "Робоча інформація")
description string | null Опис блоку
icon string | null Іконка блоку
is_repeatable boolean Чи може блок мати декілька екземплярів у профілі
fields array Масив визначень полів у порядку відображення

Об'єкт поля (blocks[].fields[])

Поле Тип Опис
id UUID ID визначення поля (field_definition_id для запитів до профілю)
version_identifier UUID Стабільний ідентифікатор поля, що зберігається між версіями
version integer Версія цього поля
type enum Тип поля (див. нижче)
label string Підпис поля
placeholder string | null Підказка для введення
description string | null Опис поля
allow_custom_value boolean Чи дозволено довільне значення для полів вибору (select, radio, multiselect)
validation object | null Правила валідації (напр. min_length, max_length, min, max)
options array | null Доступні варіанти значень для полів вибору. Можуть мати is_archived: true — варіант більше не доступний для нових значень, але історичні значення можуть на нього посилатися.
default_value any | null Значення за замовчуванням

Типи полів (type)

Значення Опис
text Текстове поле
boolean Логічне значення (так/ні)
number Числове поле
date Дата
date_range Діапазон дат
select Вибір одного значення зі списку
radio Радіо-кнопки (один вибір)
multiselect Множинний вибір зі списку
checkbox Прапорець
file Файл
email Електронна пошта
phone Номер телефону
address Адреса

Приклад відповіді

{
  "detail": {
    "id": "b9f1a8c2-1234-4a8b-9c0d-0123456789ab",
    "version": 2,
    "company_id": "2e0c1a0f-aaaa-4bbb-8ccc-111111111111",
    "blocks": [
      {
        "id": "11111111-1111-4111-8111-111111111111",
        "version_identifier": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
        "version": 1,
        "name": "Особисті дані",
        "description": null,
        "icon": null,
        "is_repeatable": false,
        "fields": [
          {
            "id": "22222222-2222-4222-8222-222222222222",
            "version_identifier": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb",
            "version": 1,
            "type": "text",
            "label": "Улюблене хобі",
            "placeholder": null,
            "description": null,
            "allow_custom_value": false,
            "validation": {"max_length": 255},
            "options": null,
            "default_value": null
          }
        ]
      }
    ]
  }
}

Пов'язані сутності