Custom

Custom — це універсальний метод автентифікації, який дозволяє розробнику самостійно визначити набір полів, необхідних для доступу до API. Цей блок використовується тоді, коли стандартних методів (Bearer, Basic, API Key) недостатньо — наприклад, якщо сервіс вимагає одночасно API Key, Secret Key.  

Навігація

1. Призначення, розташування та особливість
2. Налаштування блоку
3. Типи полів
4. Розширені опції полів (More options)
5. Додавання акаунту та ініціалізація запуску
6. Методи використання даних (Передача в HTTP)
7. FAQ

Призначення, розташування та особливість

─────────────────────────────────────────────────────────────-

Блок використовується виключно у флоу Authentication. Його головна задача — створити інтерфейс підключення акаунту для кінцевого користувача. Все, що ви налаштуєте всередині блоку, користувач побачить як поля для заповнення у вікні New access.

Як це працює:

1. Ви додаєте блок у Authentication і описуєте, які саме дані має ввести користувач (API key, secret, region, server тощо).
2. Система активує поле для вводу у Flow Test (кінцевий користувач буде  заповнювати ці поля під час підключення акаунту).
3. Ви використовуєте ці значення вручну або напівавтоматично в HTTP Request чи Static Headers.

Налаштування блоку

─────────────────────────────────────────────────────────────-

Блок Custom має гнучкі налаштування, які дозволяють створювати будь-яку структуру полів.

1 -> Type: Технічний тип поля вводу даних (Text, Text (large), List).

2 -> Key: Унікальний ідентифікатор поля, наприклад, api_secret. Саме за цим ім'ям ви будете звертатися до даних у наступних блоках (підтримує перемикання режиму поля TXT / EXP).

3 -> Label: Назва поля, яку побачить користувач, наприклад, "API Secret"   (підтримує перемикання режиму поля TXT / EXP).

4 -> Add Item: Додає нове поле.

5 -> Скрол для переміщення полів: Дозволяє перетягувати поля вище/нижче.    

6 -> More options: Відкриває розширені опції, де можна зробити поле обов'язковим, захищеним, тощо.  

7 -> Перемикач режиму полів TXT / EXP:

Простий варіант (TXT режим) - все обробляється як текст.

Просунутий варіант (EXP режим) - вміст обробляється як повноцінний вираз (Expression). Дозволяє застосувати логічні оператори та функції безпосередньо в полі вибору. Наприклад, «/» у режимі TXT - це роздільник, а в режимі EXP - ділення.

Типи полів

─────────────────────────────────────────────────────────────-

Ви можете обрати тип поля залежно від ваших задач:

Text: Стандартний рядок.

Text (large): Багаторядкове поле (для довгих ключів або сертифікатів).

List: Випадаючий список. При виборі цього типу з'являється розділ Options, де потрібно вказати Key (технічне значення) та Title (назва для користувача).  

Візуальний вигляд всіх типів полів:

Розширені опції полів (More options)

─────────────────────────────────────────────────────────────-

Біля кожного поля є кнопка More options, яка дозволяє деталізувати налаштування:  

1 -> Mandatory (yes/no): Якщо обрано "yes", користувач не зможе зберегти акаунт, не заповнивши це поле.

2 -> Protected (yes/no): Визначає, чи приховувати значення (для секретів, паролів, ключів). Якщо обрано "yes", значення в полі буде маскуватися, як пароль.

3 -> Label note: Підказка під полем. Тут можна написати, де користувачу знайти цей ключ, наприклад: "Шукайте в налаштуваннях профілю, розділ API" (підтримує перемикання режиму поля TXT / EXP).  

Додавання акаунту та ініціалізація запуску (Flow Test)

─────────────────────────────────────────────────────────────-

Після того, як ви налаштували блок Custom як метод автентифікації, необхідно створити реальне підключення та ініціалізувати тестовий запуск, щоб система «побачила» ці дані.

Цей порядок є обовʼязковим для коректної роботи Custom-автентифікації.

Покрокова інструкція підключення:

1 -> Кнопка Flow Test: У нижній лівій частині екрану натисніть кнопку Flow Test. Відкриється панель налаштування тесту, де проводиться підключення акаунту та запуск інтеграції.

2 -> Кнопка Add New Account: Натисніть Add New Account, щоб додати нове підключення для авторизації.

3 -> Заповнення даних: У вікні, що з'явилося, заповніть наступні поля:

• 4 -> Name: вкажіть зрозуміле ім'я для вашого підключення (наприклад, "Prod auth"), для майбутньої швидкої ідентифікації.
• 5 -> Власну форму створену в блоці Custom:  з'являться всі поля, які ви створили (з вашими Labels та Label notes). Заповніть значення відповідно до вимог API.

6 -> Save: Натисніть кнопку Save всередині спливаючого вікна, щоб зберегти введені дані нового акаунту.

7 -> Вибір акаунту: У списку акаунтів оберіть щойно створений акаунт.

8 -> Кнопка Save (у Flow Test): Натисніть Save на панелі Flow Test. Це закріпить обраний акаунт за поточною сесією розробки.

9 -> Кнопка Run Test: Натисніть Run Test, щоб ініціалізувати запуск інтеграції. Це критично важливий крок: саме на цьому етапі платформа  робить введені дані акаунта доступними для інших флоу ( Account Validation, Main Action тощо).

Методи використання даних (Передача в HTTP)

─────────────────────────────────────────────────────────────-

Оскільки Custom не додає авторизацію автоматично, існує три основні способи використання його значень в HTTP Request.

1. Автоматичне додавання в Headers через блок Static Headers (Рекомендовано)

Найкращий спосіб зробити дані доступними для всіх запитів інтеграції.

• Додайте блок Static Headers одразу після блоку Custom.
• У полі Name пропишіть назву хедера (наприклад, X-API-KEY).
• У полі Value вставте динамічну змінну з блоку Custom. Змінні знаходяться Globals - ACCOUNT

Результат: Тепер у кожен HTTP Request цієї інтеграції (в межах дії) автоматично додаватиметься цей заголовок.

2. Ручне додавання в Headers блоку HTTP Request

Використовується, якщо заголовок потрібен лише в конкретному запиті.

• У налаштуваннях блоку HTTP Request перейдіть у вкладку Headers.
• Пропишіть назву хедера та вставте змінну (наприклад,
  Auth-Secret: {{api_secret}} ).

 
3. Передача в URL (Query Params)

Якщо API вимагає передачу ключів безпосередньо в адресі (url).

• У полі URL блоку HTTP Request пропишіть шлях та додайте змінні з Global - ACCOUNT.
• Приклад: https://api.example.com/{{version_api}}/data?api_key={{api_key}}&api_secret={{api_secret}}

FAQ

─────────────────────────────────────────────────────────────

1. Чи можу я змінити Label або Type поля після того, як акаунти вже були створені?
Так, ви можете змінювати візуальну частину (Label, Label note). Однак зміна Key призведе до того, що старі підключення перестануть працювати, оскільки змінні в наступних блоках (наприклад, у Static Headers) посилатимуться на старий ключ, для виправлення необхідно перепризначити змінні.

2. Навіщо використовувати блок Custom, якщо є блок API Key?
API Key підтримує лише один ключ. Custom варто обирати, якщо для авторизації потрібно 2 або більше параметрів (наприклад: Username, Password, Company_ID та API_Key одночасно).

3. Чи можна використовувати Custom разом зі Static Headers?
Так. Це рекомендований підхід для автоматичного додавання заголовків.  

4. Що буде, якщо я не додам Static Headers?
Дані просто зберігатимуться в акаунті, але не передаватимуться в API. Ваші запити будуть повертати помилку авторизації (401), доки ви вручну не підставите ці змінні в HTTP Request.