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

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

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

Аппаратные TOTP-токены для EVV выглядят как обычные брелки и не требуют установки, подключения к интернету или электропитания. Всё, что нужно — передать токен человеку, который получает помощь на дому, и попросить медицинского работника фиксировать одноразовые коды в начале и конце каждого визита. Эти коды затем передаются в систему Protectimus EVV через API, которая автоматически определяет точное время их генерации.

Эта инструкция показывает, как интегрировать решения Protectimus EVV с системой электронного подтверждения визитов.

1. Как работают TOTP токены Protectimus для электронного подтверждения визитов (EVV)

Алгоритм генерации одноразовых паролей на основе времени (TOTP) позволяет вычислить точное время, когда был сгенерирован каждый одноразовый код, с точностью до 30 или 60 секунд, в зависимости от типа выбранного TOTP токена. Мы настоятельно рекомендуем использовать для EVV TOTP токены с 60-секундным интервалом из-за проблемы совпадения 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-токены с большим количеством символов и увеличенным интервалом времени. Для электронного подтверждения визитов (EVV) мы рекомендуем 8-значные TOTP-токены с интервалом 60 секунд.

3. Как интегрировать Protectimus EVV с системой электронного подтверждения визитов

3.1. Зарегистрируйтесь и добавьте токены в облачный сервис или локальную платформу Protectimus

1. Зарегистрируйтесь в Облачном сервисе Protectimus и активируйте API или установите Локальную платформу Protectimus.


2. Добавьте токены. Для этого войдите в свой аккаунт в облачном сервисе Protectimus или на локальной платформе и перейдите на страницу Токены.

3. Нажмите на кнопку Добавить токен.

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

5. Загрузите файл с секретными ключами, который будет выслан вам после заказа TOTP токенов для EVV.

3.2. Используйте API Protectimus для интеграции Protectimus с системой электронного подтверждения визитов

ВНИМАНИЕ! Вы можете использовать нашу Postman Collection для быстрой интеграции. Коллекция Postman доступна по запросу. Пожалуйста, свяжитесь с нашей службой поддержки.

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

Подробные инструкции вы найдете в нашем Руководстве по интеграции с API Protectimus.

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>

Вышеуказанные параметры имеют следующие значения:

• НТТР-method – это метод, характерный для текущего запроса.
• API_version — версия API, которую вы хотите использовать. Доступна только первая версия, поэтому эта часть запроса будет выглядеть так: “v1”.
• API_section — это раздел, к которому относится вызываемый вами метод. Доступны следующие разделы: auth-service, resource-service, token-service и user-service. Описания методов API сгруппированы по соответствующим разделам.
• API_method – это метод, который вы вызываете.
• response_format — это формат, в котором вы хотите получить ответ: XML или JSON. По умолчанию используется формат XML.

В случае ошибки обработка запроса прекращается, и возвращается сообщение об ошибке.

Список ошибок и их описание приведены в разделе Error Message в Инструкции по интеграции с API Protectimus.

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.