Authorization/Verify-2fa-by-sign

URI: /account/verify-2fa-by-sign/

Метод завершує вхід в систему Skarb Cloud через КЕП (кваліфікований електронний підпис). Використовуйте його після успішного /account/login/ замість /account/verify-2fa/, якщо підтвердження виконується підписом, а не OTP-кодом.

інформація

Метод /account/verify-2fa-by-sign призначений лише для клієнтів, які самостійно підписують рецепти

Запит виконується методом POST з тілом запиту у форматі JSON.

Детальніше про загальні вимоги до запитів — у розділі Формат запитів до API.

Заголовки

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

Для підтвердження запиту користувача API необхідно передавати заголовок API-Key (той самий ключ, що й для /account/login/).

попередження

На цьому кроці не передавайте заголовок Authorization. Для підтвердження використовуйте лише pre_auth_token у тілі запиту

інформація

Параметр pre_auth_token отримується методом /account/login/ після успішної перевірки email і пароля

попередження

Тимчасовий pre_auth_token дійсний лише 5 хвилин. Якщо час вичерпано, повторіть /account/login/

Параметри запиту

Ім'я	Тип	Обов'язковий	Опис
pre_auth_token	string	Так	Тимчасовий токен попередньої авторизації, отриманий після успішного /account/login/
signed_string	string	Так	Підписаний КЕП pre_auth_token, закодований у Base64 (внутрішній / Attached). Як сформувати signed_string — див. Отримання signed_string

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

Запит: /api/v2/account/verify-2fa-by-sign/

{
    "pre_auth_token": "xyz789...",
    "signed_string": "MIIG...base64..."
}

Параметри відповіді

Ім'я	Тип	Опис
data	object	Дані авторизації
data.token	string	Той самий токен, що отримано після /account/login/, з продовженим терміном дії
data.expires_in	integer	Оновлений термін дії токена в секундах
data.url	string	Посилання для авторизації в eHealth (якщо потрібно для вашого сценарію)

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

200 OK

Успішна відповідь: /api/v2/account/verify-2fa-by-sign/

{
    "data": {
        "token": "97jJdHs9vkl9TvfkDl0n6VY6QgFRVQQt",
        "expires_in": 2,
        "url": "https://..."
    }
}

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

У разі помилки API повертає об'єкт errors.

ДРФО користувача не співпадає

422 Unprocessable Entity

Неуспішна відповідь: /api/v2/account/verify-2fa-by-sign/

{
    "errors": {
        "message": "ДРФО користувача не співпадає"
    }
}

Підписані дані не співпадають з токеном

422 Unprocessable Entity

Неуспішна відповідь: /api/v2/account/verify-2fa-by-sign/

{
    "errors": {
        "message": "Підписані дані не співпадають з токеном"
    }
}

Отримання signed_string

Для авторизації через метод verify-2fa-by-sign необхідно передати параметр signed_string.

signed_string — це вкладений (attached / enveloped) підпис КЕП: дані і підпис містяться в одному контейнері (файл .p7s), закодованому в суцільний рядок Base64.

Підпис генерується кожного разу під час авторизації. Об'єктом підписання є pre_auth_token, отриманий на попередньому кроці.

Сервер перевіряє підпис і сертифікат, звіряє значення підписаного pre_auth_token, а також перевіряє РНОКПП (ДРФО / ІПН) власника підпису з обліковим записом користувача в Skarb Cloud.

Вимоги до signed_string

Незалежно від обраного способу формування підпису, необхідно дотримуватися таких вимог:

• підпис повинен створюватися кожного разу заново шляхом підписання актуального pre_auth_token;
• використовуйте кваліфікований електронний підпис (КЕП) фізичної особи;
• РНОКПП (ІПН / ДРФО) власника сертифіката повинен збігатися зі значенням taxId користувача у Skarb Cloud;
• підпис має бути вкладеним (attached / enveloped) — дані (значення pre_auth_token) знаходяться всередині контейнера разом із підписом;
• detached-підпис (дані та підпис окремо) не підтримується;
• у Base64 кодуйте весь файл контейнера (.p7s), без обрізання і без перенесень рядків.

Способи формування signed_string

Варіант 1. Вручну (через файл)

1. Створіть текстовий файл token.txt із вмістом отриманого pre_auth_token.
2. Підпишіть файл внутрішнім підписом (дані та підпис в одному файлі):
   • через czo.gov.ua/sign — оберіть КЕП і режим «Дані та підпис в одному файлі»;
   • або через програму «ІІТ Користувач ЦСК-1» — підпис файлу в режимі внутрішнього контейнера.
3. Отримайте файл token.txt.p7s.
4. Закодуйте його в Base64 (PowerShell одразу копіює результат у буфер обміну):

[Convert]::ToBase64String([IO.File]::ReadAllBytes('token.txt.p7s')) | Set-Clipboard

Варіант 2. Програмно (SDK ІІТ)

Автоматична генерація через офіційну бібліотеку EUSignCP (JS, .NET, Java, C/Delphi — див. iit.com.ua/downloads).

Після ініціалізації бібліотеки та завантаження особистого ключа КЕП викличте метод внутрішнього підпису з результатом у Base64.

Приклад для JavaScript:

// Передаємо значення pre_auth_token для підпису
// Метод повертає готовий рядок у форматі Base64
var signedString = euSign.SignDataInternal(true, preAuthToken, true);

Для .NET / Java використовуйте відповідні методи SignDataInternal або CtxSignData з увімкненим прапором внутрішнього підпису (Internal / Attached).

інформація

Бібліотеці потрібен доступ до мережі для зв’язку з серверами АЦСК (перевірка статусу сертифіката — OCSP / мітка часу — TSP).

Варіант 3. Використання будь-якого іншого засобу підписання CAdES

Можна використати інший засіб накладання КЕП з підтримкою вкладеного (attached / enveloped) підпису — ті самі вимоги, що в розділі Вимоги до signed_string.

Після підписання:

1. Отримайте результат підписання pre_auth_token (файл .p7s або масив байтів).
2. Закодуйте його повністю у Base64.
3. Передайте рядок у параметрі signed_string.

Формат запиту авторизації

Передайте отриманий рядок у полі signed_string разом із pre_auth_token:

{
  "pre_auth_token": "...",
  "signed_string": "MIIK...=="
}

Перевірка підпису

Перед інтеграцією рекомендується перевірити сформований контейнер на сервісі ЦЗО: https://czo.gov.ua/verify.

Під час перевірки переконайтеся, що:

• контейнер успішно проходить перевірку;
• у результатах розпакування контейнера відображається переданий pre_auth_token;
• у результатах відображається РНОКПП (ДРФО) підписувача;
• значення РНОКПП повністю збігається зі значенням taxId користувача, від імені якого виконується авторизація в Skarb Cloud.