Керуй має власний каталог інтеграцій для популярних українських та міжнародних сервісів. Додати власний застосунок у каталог допомагає інтегрувати Керуй зі сторонніми сервісами та автоматизувати роботу.

Знайти каталог застосунків можна в меню Налаштування - Автоматизація - Інтеграції

У розділі Інтеграції натиснувши "Додати" відкривається каталог доступних застосунків

Каталог постійно удосконалюється та доповнюється

Що таке застосунок інтеграції?

Це будь-який зовнішній бекенд сервіс, що вміє приймати та виконувати HTTP запити. Для розміщення вашого додатка у каталог зверніться на пошту volo@keruj.com.

Від вас потрібно

1. Адреса точки доступу куди Керуй буде слати усі запити (endpoint)

2. Адреса точки доступу для перевірки "життя" вашого додатка (healthcheck)

3. Лого для каталогу

4. Короткий опис інтеграції та, що отримує користувач

Від нас ви отримуєте

1. Спеціальний secret token вашого додатка, щоб бути певними, що це саме Керуй присилає вам дані

2. Безмежну вдячність за допомогу в розвитку українського продукту 🇺🇦 ❤️

Життєвий цикл інтеграції

Інтеграція Керуй із зовнішнім сервісом відбувається за допомогою обміну повідомленнями у форматі application/json. Є два види повідомлень

• Системі - надсилаються в момент встановлення/оновлення/видалення інтеграції

• Користувацькі - ви самі можете вказувати, що і як ви хочете отримати від Керуй

Уся взаємодія відбувається за принципом подія + відповідь

Встановлення

Сторонній сервіс, котрий надає свій API ключ і користувач повинен надати його через встановлення застосунку.

В момент встановлення застосунку в каталогу ви отримуєте POST запит

{
  "event":"application_install", 
  "company_id":"9b6116b7-20fc-438e-bbbc-96502f8e5a8d",
  "account_id":"df2ee18d-8beb-436b-9663-2f449ebd23a8",
  "account_api_key":"dDZRdjBoNTlqd2NIbnFWODFDNWJ0dz09"
}

• event - назва події

• company_id - унікальний ідентифікатор компанії в Керуй

• account_id - унікальний ідентифікатор інтеграції в Керуй

• account_api_key - ключ доступу до API від імені застосунку-інтеграції

Наполегливо рекомендуємо зберегти цю інформацію у своїй захищеній базі даних, а значення account_api_keyзберігати тільки у закодованому вигляді

Після успішної відповіді 2xx користувача буде перенаправлено на сторінку налаштування

Налаштування

У момент перенаправлення користувача на сторінку налаштування ви отримаєте POST запит

{
  "event": "application_setup",
  "company_id": "9b6116b7-20fc-438e-bbbc-96502f8e5a8d",
  "account_id": "df2ee18d-8beb-436b-9663-2f449ebd23a8"    
}

Залежно від вашої відповіді можливі 2 дії

• статус 2xx та порожній body - успішне завершення встановлення

• статус 2xx на JSON схема - попросити Керуй виконати якусь дію

До прикладу, ви хочете запропонувати користувачеві заповнити форму з API ключем та іншими полями від вашого сервісу.

В такому випадку вам слід відповісти статусом 2xx та JSON схему

{
   "reply": "provide_api_key",
   "render": {
      "elements": [{
         "type": "paragraph",
         "format": "markdown",
         "content": "Read details at..."
      }, {
         "type": "form",
         "id": "config",
         "fields": [{
            "name": "api_key",
            "type": "text",
            "label": "API Key",
            "required": true
         }, {
            "name": "topic",
            "type": "select",
            "label": "Тема",
            "required": true,
            "options": [{
               "label": "Технічна підтримка",
               "value": "tech_support"
            }, {
               "label": "Відгук",
               "value": "feedback"
            }, {
               "label": "Питання",
               "value": "question"
            }, {
               "label": "Інше",
               "value": "other"
            }]
         }, {
            "name": "newsletter",
            "type": "checkbox",
            "label": "Підписатись на новини"
         }],
         "submit": {
            "text": "Connect",
            "icon": "check"
         }
      }]
   }
}

Користувач побачить форму налаштування з відповідними елементами

Коли користувач заповнить дані та натисне "Надіслати" ви отримаєте повідомлення POST запит

{
  "event": "provide_api_key",
  "company_id": "9b6116b7-20fc-438e-bbbc-96502f8e5a8d",
  "account_id": "df2ee18d-8beb-436b-9663-2f449ebd23a8",
  "data": {
    "config": {
      "api_key": "my apu key",
      "topic": "tech_support",
      "newsletter": true
    }
  }
}

• event - назва події яку ви вказали у reply

• company_id - унікальний ідентифікатор компанії в Керуй

• account_id - унікальний ідентифікатор інтеграції в Керуй

• data - дані з заповнених користувачем елементів

Після цього у вас є знову 2 варіанти відповіді:

• статус 2xx та порожній body - успішне завершення встановлення

• статус 2xx на JSON схема - попросити Керуй виконати ще якусь дію і таким чином ви можете збудувати покроковий діалог з користувачем допоки у вас не буде усіх потрібних даних і ви будете готові завершити встановлення відповівши 2xx та порожній body

Успішне завершення сповістить користувача, що інтеграція завершена і скоро буде магія

Видалення

Коли користувач виявить бажання видалити інтеграцію, про це вас повідомить POST запит

{
  "event": "application_uninstall",
  "company_id": "69ff6d01-92ca-4015-84cb-a91b7c1d7386",
  "account_id": "df2ee18d-8beb-436b-9663-2f449ebd23a8"
}

Очікується відповідь зі статусом 2xx та, що ви видалите усю інформацію про цю компанію.

Авторизація

Усі запити від Керуй містять HTTP заголовок x-keruj-app-token. Обов'язково перевіряйте чи збігається він з вашим secret token

Перевірка здоров’я (healthcheck)

Ваш додаток буде додано до нашої статус сторінки https://status.keruj.app/

У разі тривалої недоступності ваших точок доступу додаток буде відключено.