TOTP-токени для електронного підтвердження візитів (EVV)

Ми рекомендуємо використовувати апаратні TOTP токени для електронного підтвердження візитів (Electronic Visit Verification, EVV). Рішення Protectimus для EVV, засноване на алгоритмі TOTP (Time-Based One-Time Password), дозволяє визначати точний час візитів за допомогою одноразових паролів з TOTP токенів.

TOTP токени для електронного підтвердження візитів (EVV) — це надзвичайно простий та ефективний метод EVV як для медичних працівників, так і для людей, які отримують допомогу вдома.

Апаратні TOTP токени для EVV виглядають як брелоки і не потребують інсталяції, інтернет-з’єднання чи електрики для роботи. Просто передайте TOTP токен отримувачу допомоги і попросіть медичного працівника записувати одноразові коди з токена на початку та в кінці кожного візиту. Потім ці коди передаються в рішення Protectimus EVV через API, і система визначає точний час, коли кожен код був згенерований.

Ця інструкція показує, як інтегрувати рішення Protectimus EVV з вашою системою електронного підтвердження візитів.

1. Як працюють TOTP токени Protectimus для електронного підтвердження візитів (EVV)

Алгоритм генерації одноразових паролів на основі часу (TOTP) дозволяє обчислити точний час, коли був згенерований кожен одноразовий код, з точністю до 30 або 60 секунд, залежно від типу TOTP токена, який ви оберете. Ми настійно рекомендуємо використовувати TOTP токени з 60-секундним інтервалом для EVV через проблему збігу OTP, яка виникає при використанні токенів з 30-секундним інтервалом. Цю проблему ми детально опишемо нижче.

Алгоритм TOTP для EVV працює наступним чином:

• Пацієнт отримує апаратний TOTP токен. Токен TOTP має вбудовані годинник та унікальний попередньо запрограмований секретний ключ.
• Той самий секретний ключ відомий і системі Protectimus EVV, яка перевіряє одноразові паролі (OTP) та обчислює час, коли ці OTP були згенеровані.

Отже, сценарій використання TOTP токенів Protectimus для електронного підтвердження візитів (EVV) виглядає наступним чином:

1. Працівник, який доглядає за пацієнтом, відвідує пацієнта і записує два одноразові паролі з OTP токена: до та після візиту.
2. Потім працівник вводить ці одноразові коди в систему електронного підтвердження візитів, щоб підтвердити, що він провів візит.
3. Система електронного підтвердження візитів звертається до сервера Protectimus EVV для обчислення часу візиту.
4. Знаючи секретний ключ, сервер Protectimus EVV генерує одноразові паролі для попереднього дня/тижня/місяця та обчислює час генерування певних OTP. Таким чином, ми дізнаємося, коли медпрацівник відвідав пацієнта.

2. Проблема збігу одноразових паролів у EVV

ЗВЕРНІТЬ УВАГУ! Ми рекомендуємо використовувати 8-значні TOTP токени з 60-секундним інтервалом для електронного підтвердження візитів (EVV).

Існує обмеження на кількість комбінацій, що складаються з 6 цифр. І це обмеження не є дуже великим.

Протягом тривалого періоду (тиждень або місяць) числові значення одноразових паролів неминуче будуть повторюватися. Два одноразові паролі, згенеровані в різний час, можуть збігатися. Це може ускладнити визначення точного часу генерації OTP.

Щоб зменшити цю проблему, краще використовувати TOTP токени з більшою кількістю символів та більшими інтервалами часу. Ми рекомендуємо 8-значні TOTP токени з 60-секундними інтервалами для електронного підтвердження візитів (EVV).

3. Як інтегрувати Protectimus EVV з вашою системою електронного підтвердження візитів

3.1. Зареєструйтесь та додайте токени до хмарного сервісу або до локальної платформи Protectimus

1. Зареєструйтеся в хмарному сервісі Protectimus і активуйте API або встановіть локальну платформу Protectimus.
2. Додайте токени. Для цього увійдіть у свій акаунт у хмарному сервісі Protectimus або на локальній платформі та перейдіть на сторінку Токени.

3. Натисніть кнопку Додати токен (Add Token).

4. Виберіть токен Protectimus Two.

5. Завантажте файл, який буде надіслано вам після замовлення TOTP токенів для EVV.

3.2. Використайте API Protectimus для інтеграції Protectimus з вашою системою електронного підтвердження візитів

ЗВЕРНІТЬ УВАГУ! Ви можете використати нашу Postman Collection для швидшої інтеграції. Колекція Postman доступна за запитом. Будь ласка, зверніться до нашої служби підтримки.

Дизайн API Protectimus базується на принципах REST. Дані передаються у форматі XML або JSON. Значення параметрів однакові в обох форматах. За замовчуванням відповіді передаються у форматі XML.

Для докладних інструкцій перегляньте наш Посібник з інтеграції з Protectimus API.

3.2.1. Авторизація

API Protectimus доступний лише авторизованим користувачам. Наша система використовує базову аутентифікацію. Логін (ім’я користувача) адміністратора, який надсилає запит, використовується як ім’я користувача, а токен аутентифікації — як пароль.

Токен аутентифікації — це хеш рядка, який складається з таких елементів:

<ApiKey>:<YYYYMMDD>:<HH>

Де:

• ApiKey – це унікальний для кожного адміністратора API-ключ, який надається та може бути змінений на сторінці управління профілем за адресою https://service.protectimus.com/profile.
• YYYYMMDD – це поточна дата в зазначеному форматі.
• НН – це час UTC у форматі HH (лише години в 24-годинному форматі, без хвилин чи секунд).

Приклад:

The administrator’s profile contains the following information:
ApiKey – MySecureApiKey; Date - 30 January 2014; Time - 17:42 (UTC).

String for hash: MySecureApiKey:20140130:17

Hash SHA256 for this text: 62704fb3a9dcf7b5b3cf7bda6ac9d0b0aa37c6fce8d0fae6b466c91ba68894f5

3.2.2. Надсилання запиту

Протокол для передачі всіх запитів до API Protectimus — це HTTPS.

Формат запиту:

<НТТР-method>
https://service.protectimus.com/multipass-web-api/v<API_version>/<API_section>/<API_method>.<respo
nse_format>

Вищезазначені параметри мають такі значення:

• HTTP-метод — це метод, характерний для поточного запиту.
• API_version — це версія API, яку ви хочете використовувати. Наразі доступна лише перша версія, тому ця частина запиту виглядатиме так: “v1”.
• API_section — це розділ, до якого належить метод, який ви викликаєте. Доступні наступні розділи: auth-service, resource-service, token-service та user-service. Опис методів API поділяється за розділами, до яких ці методи належать.
• API_method — це метод, який ви викликаєте.
• response_format — це формат, у якому ви хочете отримати відповідь: XML або JSON. За замовчуванням вибрано формат XML.

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

Список помилок та їх опис наведено в розділі Error Message Інструкцій з інтеграції Protectimus API.

3.2.3. Метод API Protectimus EVV

Використовуйте цей API метод для отримання часу, коли було згенеровано одноразовий пароль.

Опція 1. CURL

curl --request POST 'https://api.protectimus.com/api/v1/token-service/otp-time' \

--header 'Authorization: Basic ZGFueWxvLmRlaW5la29AZ21haWwuY29tOmNTI=' \

--header 'Content-Type: application/x-www-form-urlencoded' \



--data-urlencode 'tokenId=123' \

--data-urlencode 'otp=825043'

Опція 2. HTTP

POST /api/v1/token-service/otp-time HTTP/1.1
Host: api.protectimus.com
Authorization: Basic ZGFueWxvLmRlaW5la29AZ21haWwuY29tOmNTI=
Content-Type: application/x-www-form-urlencoded
Content-Length: 22


tokenId=123&otp=825043

Якщо у вас є питання, будь ласка, звертайтесь до служби підтримки клієнтів Protectimus.