Внешние API и программы

Используйте эту страницу, если вам нужна простая внешняя программа, скрипт, локальный сервер или серверная служба для управления текущим замком Chastify.

Самый простой способ — создать токен DEV, доступный для всех пользователей, а затем отправить его в качестве токена носителя на конечные точки /api/apps/v1/*.

/api/apps/v1/* предназначен только для ваших собственных активных сеансов блокировки. Если вы разрабатываете общедоступное расширение, используемое другими пользователями Chastify, используйте ключ API разработчика с областью действия приложения с /api/extensions/sessions/:sessionId/* и передайте iframe mainToken в x-chastify-main-token.

Создайте токен DEV

Откройте Chastify.
Перейдите по адресу Developer API.
Найдите User-wide DEV API keys.
Создайте ключ.
Скопируйте токен немедленно. Он отображается только один раз.

Используйте это в запросах следующим образом:

curl https://chastify.net/api/apps/v1/session \
  -H "Authorization: Bearer YOUR_DEV_TOKEN"

Токены DEV:

не требуют создания расширения
не истекают автоматически
работает для вашей текущей активной блокировки и будущих активных сессий блокировки.
Используйте свою роль на активном замке: либо владелец замка, либо держатель ключа.
Отозвать можно на странице API для разработчиков.

Рассматривайте токен DEV как пароль. Любой, у кого есть этот токен, может вызывать API для разработчиков от вашего имени.

Первый звонок: проверьте текущий замок.

Начните с:

GET https://chastify.net/api/apps/v1/session

Пример:

curl https://chastify.net/api/apps/v1/session \
  -H "Authorization: Bearer YOUR_DEV_TOKEN"

Эта функция возвращает текущий контекст блокировки, роль, области действия, оставшееся время и код блокировки lockData.

Вспомогательные функции блокировки данных

GET /api/apps/v1/session включает lockData, который разработан таким образом, чтобы его было легко читать программам и механизмам правил.

Обычные логические значения:

frozen
unlockable
trusted
taskAssigned: true, когда активный замок открыт. TaskRun

Распространенные числа:

timeLockedSeconds
timeRemainingSeconds
maxTimeRemainingSeconds
taskPoints

Общие строки:

lockTitle
поля профиля пользователя
поля профиля владельца ключа

Уведомление о конфиденциальности:

wearerLastSeenTimestamp и keyholderLastSeenTimestamp становятся null, когда у пользователя отключен онлайн-статус.

Основные конечные точки действий блокировки

Эти конечные точки — те, которые чаще всего используют внешние программы для изменения блокировки.

POST https://chastify.net/api/apps/v1/action
POST https://chastify.net/api/apps/v1/lock/apply-time
POST https://chastify.net/api/apps/v1/lock/freeze
POST https://chastify.net/api/apps/v1/lock/unfreeze
POST https://chastify.net/api/apps/v1/logs/custom

Для всех запросов используйте:

Authorization: Bearer YOUR_DEV_TOKEN
Content-Type: application/json

Добавить или удалить время

Используйте простой временной параметр, если вам нужно изменить только оставшееся время.

Добавьте 10 минут:

curl -X POST https://chastify.net/api/apps/v1/lock/apply-time \
  -H "Authorization: Bearer YOUR_DEV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"deltaSeconds":600}'

Удалите 5 минут:

curl -X POST https://chastify.net/api/apps/v1/lock/apply-time \
  -H "Authorization: Bearer YOUR_DEV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"deltaSeconds":-300}'

Заморозить и разморозить

Заморозьте на 30 минут:

curl -X POST https://chastify.net/api/apps/v1/lock/freeze \
  -H "Authorization: Bearer YOUR_DEV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"durationSeconds":1800}'

Разморозить:

curl -X POST https://chastify.net/api/apps/v1/lock/unfreeze \
  -H "Authorization: Bearer YOUR_DEV_TOKEN"

Конечная точка общего действия

Использовать:

POST https://chastify.net/api/apps/v1/action

Форма тела:

{
  "name": "add_time",
  "params": 600
}

Пример:

curl -X POST https://chastify.net/api/apps/v1/action \
  -H "Authorization: Bearer YOUR_DEV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"add_time","params":600}'

Поддерживаемые названия действий

name поддерживает:

add_time
remove_time
freeze
pillory
unfreeze
toggle_freeze
settings.patch
task.assign
task.start_timer
task.complete
hygienic_unlock.start
pillory.end

Ограничения действий:

Для выполнения задач необходимо включить модуль «Задачи» на замке.
Для работы hygienic_unlock.start необходимо включить функцию «Гигиеническое открытие» и не запускать активную гигиеническую сессию.
Для выполнения команд устройства требуется подключенное поддерживаемое устройство и соответствующие разрешения.

Примеры полезных действий

Удалите 15 минут:

{
  "name": "remove_time",
  "params": 900
}

Заморозьте на 5 минут:

{
  "name": "freeze",
  "params": {
    "durationSeconds": 300
  }
}

Включить/выключить режим заморозки:

{
  "name": "toggle_freeze",
  "params": {
    "durationSeconds": 300
  }
}

Назначить задачу:

{
  "name": "task.assign",
  "params": {
    "actor": "extension",
    "taskText": "Drink water",
    "points": 5,
    "verificationRequired": false,
    "durationSeconds": 900
  }
}

Это создает код TaskRun для активной блокировки. Если уже открыт другой запуск задачи, текущая реализация отменяет старый открытый запуск и создает новый.

Запустить таймер активной задачи:

{
  "name": "task.start_timer",
  "params": {}
}

Выполните текущее задание:

{
  "name": "task.complete",
  "params": {
    "successful": true
  }
}

На этом завершается открытие последнего файла TaskRun для активного замка.

Начните гигиеническую разблокировку:

{
  "name": "hygienic_unlock.start",
  "params": {
    "durationSeconds": 900
  }
}

Завершить активный позорный столб:

{
  "name": "pillory.end",
  "params": {}
}

Журнал пользовательских замков

Используйте это, когда ваша программа выполнила какое-либо действие, и вы хотите, чтобы оно было видно в истории блокировок.

POST https://chastify.net/api/apps/v1/logs/custom

Пример:

curl -X POST https://chastify.net/api/apps/v1/logs/custom \
  -H "Authorization: Bearer YOUR_DEV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Program check completed","description":"The external rule script ran successfully.","role":"extension"}'

Поля тела:

title: обязательно
description: необязательно
role: extension, wearer или keyholder
icon: необязательно
color: необязательный шестнадцатеричный код цвета, например, #ffcc00

Команды устройства

Команды устройства позволяют запускать электрические разряды и вибрации на подключенном устройстве пользователя.

POST https://chastify.net/api/apps/v1/device-command

Работает с вашим токеном DEV — идентификатор сессии не требуется. Сервер автоматически определяет блокировку и владельца по вашему токену.

curl -X POST https://chastify.net/api/apps/v1/device-command \
  -H "Authorization: Bearer YOUR_DEV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"command":"shock.start","params":{"intensityPct":75,"durationSeconds":10}}'

Текст запроса

{
  "command": "<command>",
  "params": { ... }
}

command (строка, обязательно) — команда устройства для выполнения.
params (объект, необязательный) — параметры, специфичные для команды (см. ниже).

Поддерживаемые команды и их параметры

`shock.start`

Вызывает электрический разряд на устройстве пользователя.

Параметр	Тип	Диапазон	Значение по умолчанию	Описание
`intensityPct`	число	1–100	50	Shock интенсивность в процентах
`durationSeconds`	число	1–300	60	Shock длительность в секундах
`message`	строка	—	—	Дополнительное сообщение, отображаемое пользователю

примечание

Настраиваемое пользователем максимальное напряжение всегда устанавливается в качестве жесткого ограничения, независимо от того, что вы отправляете. Для устройств Lockink это предел напряжения для каждого устройства. Для устройств QIUI это значение параметра shockVolt (шкала от 1 до 4). Если вы отправляете intensityPct: 80, но предел для пользователя составляет 50%, устройство будет выдавать только 50%.

Пример:

curl -X POST https://chastify.net/api/apps/v1/device-command \
  -H "Authorization: Bearer YOUR_DEV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"command":"shock.start","params":{"intensityPct":75,"durationSeconds":10,"message":"Extension shock"}}'

`shock.stop`

Останавливает все активные электрические разряды на устройстве пользователя. Параметры не требуются.

curl -X POST https://chastify.net/api/apps/v1/device-command \
  -H "Authorization: Bearer YOUR_DEV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"command":"shock.stop"}'

`vibration.start`

Запускает вибрацию на устройстве пользователя.

Параметр	Тип	Диапазон	Значение по умолчанию	Описание
`intensityPct`	число	1–100	50	Интенсивность вибрации в процентах
`durationSeconds`	число	1–300	30	Длительность вибрации в секундах
`frequencyPct`	число	1–100	50	Частота вибрации в процентах
`message`	строка	—	—	Дополнительное сообщение, отображаемое пользователю

Пример:

curl -X POST https://chastify.net/api/apps/v1/device-command \
  -H "Authorization: Bearer YOUR_DEV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"command":"vibration.start","params":{"intensityPct":60,"durationSeconds":15,"frequencyPct":40}}'

`vibration.stop`

Останавливает все активные вибрации. Параметры не требуются.

curl -X POST https://chastify.net/api/apps/v1/device-command \
  -H "Authorization: Bearer YOUR_DEV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"command":"vibration.stop"}'

`all.stop`

Останавливает всю активность устройства (удары, вибрации и т. д.). Параметры не требуются.

curl -X POST https://chastify.net/api/apps/v1/device-command \
  -H "Authorization: Bearer YOUR_DEV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"command":"all.stop"}'

`shock.random.set`

Включает или отключает режим случайного электрического разряда на устройстве пользователя.

Параметр	Тип	Диапазон	Значение по умолчанию	Описание
`enabled`	логическое значение	—	—	Включить (`true`) или выключить (`false`) режим случайного выбора
`minIntensityPct`	число	1–100	20	Минимальный процент интенсивности удара
`maxIntensityPct`	число	1–100	80	Процент максимальной интенсивности удара
`message`	строка	—	—	Дополнительное сообщение, отображаемое пользователю

примечание

Настраиваемое пользователем максимальное напряжение всегда является жестким ограничением. Если вы установите maxIntensityPct: 80, но ограничение для пользователя равно 50, фактическое максимальное значение составит 50%.

Пример:

curl -X POST https://chastify.net/api/apps/v1/device-command \
  -H "Authorization: Bearer YOUR_DEV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"command":"shock.random.set","params":{"enabled":true,"minIntensityPct":25,"maxIntensityPct":75}}'

`shock.berserk.set`

Включает или отключает режим "берсерк-шок" на устройстве пользователя.

Параметр	Тип	Диапазон	Значение по умолчанию	Описание
`enabled`	логическое значение	—	—	Включить (`true`) или отключить (`false`) режим берсерка
`message`	строка	—	—	Дополнительное сообщение, отображаемое пользователю

Пример:

curl -X POST https://chastify.net/api/apps/v1/device-command \
  -H "Authorization: Bearer YOUR_DEV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"command":"shock.berserk.set","params":{"enabled":true}}'

Команды устройства зависят от активной блокировки, доступности устройства и политики управления.

Выбор устройства

Указывать идентификатор устройства или тип устройства не требуется. Каждый пользователь может одновременно использовать только одно активное устройство — сервер автоматически выбирает его.

В ответе возвращается значение deviceType, чтобы вы знали, какое устройство получило команду.

Ответы

Успех (200)

{
  "ok": true,
  "command": "shock.start",
  "result": {
    "success": true,
    "message": "Shock command sent (10s)",
    "deviceType": "lockink-aa-a1012"
  },
  "active": {
    "shock": true,
    "vibration": false
  }
}

Поле	Описание
`ok`	`true` при принятии команды
`command`	Выполненная команда
`result.success`	`true`, если устройство подтвердило команду
`result.message`	Человекочитаемое сообщение о состоянии
`result.deviceType`	Тип устройства пользователя (например, `lockink-aa-a1012`, `cellmate-pro-3`)
`active.shock`	Активен ли в данный момент удар током на устройстве пользователя
`active.vibration`	Активна ли в данный момент вибрация на устройстве пользователя

Примечание: shock.start и vibration.start ожидают подтверждения получения устройством до 25 секунд. Команды остановки (shock.stop, vibration.stop, all.stop) возвращают управление немедленно.

Отказ

Все ошибки возвращают HTTP-код 4xx/5xx с телом в формате JSON:

{
  "success": false,
  "error": "no_device",
  "message": "No shock-capable device found for user"
}

Сценарий	HTTP	`error`	`message`
Блокировка не найдена или нет активной блокировки	404	`lock_not_found`	`No active lock found`
Блокировка больше не активна	409	`lock_ended`	`The lock is no longer active`
Пропала сессия пользователя	400	`no_wearer`	`Missing wearer session`
Отсутствует или недействителен `durationSeconds`	400	`invalid_params`	`durationSeconds is required for server-initiated shocks`
Случайный/безумный режим на неподдерживаемом устройстве	400	`unsupported_device`	`Random mode only supported on Lockink AA-A1012`
Пользователь не дал согласия на шоковую терапию	403	`not_authorized`	`User not eligible for shock commands (consent or device check failed)`
Нет сопряженного устройства, способного выдерживать удары/вибрацию	404	`no_device`	`No shock-capable device found for user`
Устройство отключено (нет подключения к разъему)	404	`device_offline`	`No active device socket found for user`
Устройство не подтвердилось вовремя (25 с)	504	`device_timeout`	`Device verification timeout`
Нераспознанный или необработанный сбой	400	`command_failed`	`command_failed`

Если код deviceType доступен, он включается в ответ.

Объяснение распространенных сценариев отказов

предупреждение

Устройство необходимо подключить через мобильное приложение.

Для работы Shock и вибрации пользователю необходимо иметь подключенное поддерживаемое Bluetooth-устройство и активно работающее мобильное приложение Chastify на телефоне. Приложение поддерживает соединение в режиме реального времени, передавая команды устройству. Если приложение закрыто или телефон не подключен к интернету, команды не будут выполняться.

no_device — Пользователь не подключил устройство с функцией защиты от ударов (например, CellMate Pro 3, Cagink Metal, Lockink AA-A1012) к приложению Chastify. Для того чтобы API мог использовать устройство, оно должно быть сопряжено, активно и полностью настроено.

device_offline — Устройство пользователя сопряжено, но собственная служба Shock не включена или не запущена в приложении Android. Это наиболее распространенная ошибка — для надежной доставки команд необходимо включить собственную службу Shock в настройках приложения Android.

device_timeout — Команда была отправлена в мобильное приложение, но приложение не подтвердило её получение устройством Bluetooth в течение 25 секунд. Обычно это означает, что Bluetooth на устройстве выключен, устройство находится вне зоны действия или выключено. Устройства Lockink переходят в спящий режим всего через 3 минуты бездействия, если функция поддержания соединения не включена — и даже в этом случае оптимизация батареи производителем телефона может ограничивать фоновую работу Bluetooth и препятствовать надёжной работе функции поддержания соединения.

not_authorized — Пользователь не дал явного согласия на использование электрошока в настройках своего устройства. Это требование безопасности — даже при сопряженном устройстве пользователь должен дать согласие на использование удаленных команд электрошока/вибрации.

unsupported_device — Режимы случайного воспроизведения и «берсерка» доступны только на Lockink AA-A1012 (Beesting). Другие устройства, такие как CellMate Pro 3 или Cagink Metal, эти режимы не поддерживают.

Распространенные ошибки

401 missing_token: отправить Authorization: Bearer YOUR_DEV_TOKEN.
401 invalid_token: токен неверен или был скопирован неправильно.
401 revoked_token: ключ DEV был аннулирован.
403 insufficient_scope: ключ не имеет требуемой области действия.
409 no_active_lock_session: у пользователя в данный момент нет активной блокировки.
409 lock_ended: разрешенная блокировка больше не активна.

к сведению

Разбор ошибки device_timeout (504)

Ошибка device_timeout означает, что сервер отправил команду на шоковое воздействие в приложение Android на устройстве пользователя, но приложение не подтвердило доставку на Bluetooth-устройство в течение 25 секунд. Это наиболее сложная ошибка — вот что происходит на стороне Android:

Сервер → Приложение: Команда передается через Socket.IO в собственную службу Shock, работающую на телефоне пользователя.
Приложение → Устройство: Приложение подключается к устройству через Bluetooth Low Energy (BLE) и отправляет команду на удар. Для устройств QIUI это включает в себя сначала получение токена из API производителя устройства, а затем отправку команды BLE. Для устройств Lockink команда BLE отправляется напрямую.
Приложение → Сервер: Приложение отправляет подтверждающее сообщение на сервер.

Тайм-аут в 25 секунд начинается с шага 1. Тайм-аут на шаге 2 может произойти по следующим причинам:

Bluetooth отключен или устройство находится вне зоны действия телефона пользователя.
Клетка спит. Устройства Lockink переходят в глубокий сон всего через 3 минуты бездействия BLE. Функция поддержания соединения может предотвратить это, но оптимизации батареи от производителей (Samsung, Xiaomi, Huawei и др.) могут разрывать фоновые соединения Bluetooth, что делает функцию поддержания соединения ненадежной.
Сбой BLE-соединения. Приложение повторяет попытку BLE-соединения, но если устройство не отвечает, происходит таймаут.
Блокировка безопасности. В приложении встроена система безопасности, которая блокирует разряды, если обнаружено, что пользователь находится в движении (например, за рулем, на велосипеде) на основе распознавания активности и скорости GPS. Если пользователь находится в движении, разряд блокируется беззвучно, и сообщается о сбое.
Не удалось получить токен QIUI. Для устройств CellMate Pro 3 и Cagink приложению необходимо получить командный токен из облачного API QIUI перед отправкой команды BLE. Если телефон пользователя не подключен к интернету или API QIUI работает медленно/недоступен, этот шаг может занять большую часть 25-секундного окна.

Практичный образец

Большинство внешних программ следуют этой схеме:

Позвоните по номеру GET /api/apps/v1/session.
Прочитайте lockData.
Решите, что должно произойти.
Вызовите /api/apps/v1/action или одну из более простых конечных точек блокировки.
При желании можно записать собственный лог с кодом /api/apps/v1/logs/custom.

Например, скрипт может проверить timeRemainingSeconds, добавить время, когда правило не выполняется, а затем записать пользовательский лог с объяснением произошедшего.

Создайте токен DEV​

Первый звонок: проверьте текущий замок.​

Вспомогательные функции блокировки данных​

Основные конечные точки действий блокировки​

Добавить или удалить время​

Заморозить и разморозить​

Конечная точка общего действия​

Поддерживаемые названия действий​

Примеры полезных действий​

Журнал пользовательских замков​

Команды устройства​

Текст запроса​

Поддерживаемые команды и их параметры​

shock.start​

shock.stop​

vibration.start​

vibration.stop​

all.stop​

shock.random.set​

shock.berserk.set​

Выбор устройства​

Ответы​

Успех (200)​

Отказ​

Объяснение распространенных сценариев отказов​

Распространенные ошибки​

Практичный образец​

Создайте токен DEV

Первый звонок: проверьте текущий замок.

Вспомогательные функции блокировки данных

Основные конечные точки действий блокировки

Добавить или удалить время

Заморозить и разморозить

Конечная точка общего действия

Поддерживаемые названия действий

Примеры полезных действий

Журнал пользовательских замков

Команды устройства

Текст запроса

Поддерживаемые команды и их параметры

`shock.start`

`shock.stop`

`vibration.start`

`vibration.stop`

`all.stop`

`shock.random.set`

`shock.berserk.set`

Выбор устройства

Ответы

Успех (200)

Отказ

Объяснение распространенных сценариев отказов

Распространенные ошибки

Практичный образец