Перейти до основного вмісту

Формат запитів до API

Всі запити до API шлюзу надсилаються за допомогою протоколу REST у форматі JSON методами POST та GET.

Заголовки​

У запитах обов'язково має бути заголовок Content-Type: application/json, інакше запит буде вважатися некоректним навіть при валідному JSON у ньому.

Для підтвердження запиту користувача API необхідно передавати заголовок API-Key в кожному запиті.

Для автентифікації користувача, який обробив запит API, потрібно передавати заголовок авторизації з токеном у форматі Bearer.

Наприклад: Authorization = "Bearer TOKEN".

Кожен запит, крім /account/login, /account/verify-2fa та /api/v2/account/verify-2fa-by-sign, повинен містити заголовок з токеном авторизації у форматі Bearer

Авторизація​

Метод для авторизації обов'язково має передавати заголовки API Key та Content-Type: application/json. Також він повинен містити авторизаційні дані:

Ім'яТипОбов'язковийОпис
emailstringТакЕлектронна пошта співробітника (логін для авторизації в Skarb Cloud)
passwordstringТакПароль співробітника для авторизації в Skarb Cloud

Приклад запиту​

Запит: /account/login/
{
    "email": "[email protected]",
    "password": "secret"
}

Формат відповідей​

Відповіді від API можуть містити об'єкт data з даними, так і можуть не містити об'єктів зовсім. Якщо під час виконання запиту виникла помилка, у відповіді від API міститься об'єкт errors з даними про помилку.

Структура об'єктів data і errors залежить від методу API і описана в документації кожного методу.

У відповідях методів авторизації додатково повертається поле expires_in — термін дії токена в секундах.

Відновлення після прострочення токена​

Якщо token у заголовку Authorization прострочився, API повертає помилку авторизації. У відповіді може бути поле url — посилання для повторної авторизації користувача в eHealth (recovery-сценарій).

Рекомендований алгоритм для клієнта:

  1. Відстежуйте expires_in після /account/login та після підтвердження 2FA.
  2. При отриманні помилки прострочення токена перевірте наявність data.url у відповіді.
  3. Перенаправте користувача за url, пройдіть авторизацію в eHealth.
  4. Продовжте роботу з API з оновленою сесією без повторного логіну та 2FA, якщо recovery успішний.

Приклад відповіді при простроченому токені​

401 Unauthorized

Прострочений API-токен
{
    "errors": {
        "message": "Токен прострочений"
    },
    "data": {
        "url": "https://...url for eHealth authorization..."
    }
}

Приклади запиту та відповіді​

Запити до API можуть містити як єдиний об'єкт data, так і можуть не містити об'єктів зовсім.

Приклад запиту​

/medication/reject-dispense
{
    "id": "9bc02652-382b-4ec3-861a-aa868d466408"
}

Приклад успішної відповіді​

200 OK

/medication/reject-dispense
{
  "data": {
    "message": "..."
  }
}

Приклад неуспішної відповіді​

Переглянути всі можливі помилки API можна у довіднику кодів помилок API

422 Unprocessable Entity (WebDAV) (RFC 4918)

/medication/reject-dispense
{
  "errors": {
    "eHealth": "...ehealth error text..."
  }
}