Наш каталог інтеграцій

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

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

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

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

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

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

2. Адреса точки доступу для перевірки “життя” вашого додатка

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

4. Короткий опис

5. Набір конфігураційних полів, що мають бути заповнені при встановленні

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

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

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

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

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

{
  "event": "application_install",
  "company_id": "69ff6d01-92ca-4015-84cb-a91b7c1d7386",
  "account_api_key": "account_api_key",
  "data": {
    "your_app_api_key": "xxx"
  }
}

До прикладу користувач має передати дані про API ключ вашого сервісу для обміну даними з Керуй. В цей момент ви отримуєте запит типу подія application_instalз інформацією про компанію company_id та account_api_key котрий вам слід зберегти у секретному сховищі та використовувати для комунікації з нашим GraphQL API

У розділі data може бути буль яка конфігураційна інформація, що допоможе вам краще комунікувати з Керуй API

Обов’язково зверніть увагу на заголовки вхідного запиту

{
  "content-type": "application/json",
  "x-keruj-app-token": "your_application_secret_token"
}

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

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

Оновлення

Якщо користувач має потребу оновити конфігурацію, то ви отримаєте POST запит типу подія application_update

{
  "event": "application_update",
  "company_id": "69ff6d01-92ca-4015-84cb-a91b7c1d7386",
  "data": {
    "api_key": "xxx"
  }
}

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

Видалення

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

{
  "event": "application_uninstall",
  "company_id": "69ff6d01-92ca-4015-84cb-a91b7c1d7386"
}

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

Обробка помилок

При отриманні повідомлення у вас може виникнути необхідність перевірити вхідні дані та відповісти помилкою на певні ключі. Для цього варто відповісти статусом 422 та даними

{
  "errors": {
    "__base__": ["any generic errors", "can be here"],
    "api_key": ["invalid key", "other_error"]
  }
}

Відповідні помилки будуть показані користувачеві

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

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

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