外部APIとプログラム

このページは、シンプルな外部プログラム、スクリプト、ローカルサーバー、またはバックエンドサービスを使用して、現在のChastifyロックを制御したい場合に使用します。

最も簡単な方法は、ユーザー全体で使用できるDEVトークンを作成し、それをベアラートークンとして/api/apps/v1/*エンドポイントに送信することです。

/api/apps/v1/* は、ご自身のアクティブなロックセッション専用です。他の Chastify ユーザーが使用する公開拡張機能を作成する場合は、/api/extensions/sessions/:sessionId/* でアプリスコープの開発者 API キーを使用し、x-chastify-main-token で iframe mainToken を渡してください。

DEVトークンを作成する

1. Chastifyを開きます。
2. Developer APIへ移動してください。
3. User-wide DEV API keys を検索します。
4. キーを作成します。
5. トークンはすぐにコピーしてください。一度しか表示されません。

次のようなリクエストで使用してください。

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: オプションの16進数カラーコード。例: #ffcc00

デバイスコマンド

デバイスコマンドを使用すると、装着者の接続されたデバイスに衝撃や振動を与えることができます。

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

DEVトークンで動作します。セッションIDは不要です。サーバーはトークンからロックと着用者を自動的に解決します。

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}}'

デバイスコマンドは、アクティブなロック、デバイスの可用性、およびコマンドポリシーに依存します。

デバイスの選択

デバイスIDやデバイスの種類を指定する必要はありません。各ユーザーは同時に1つのデバイスしかアクティブにできません。サーバーが自動的にデバイスをターゲットにします。

応答には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) はすぐに戻ります。

失敗

すべてのエラーは、JSONボディを含むHTTP 4xx/5xxエラーを返します。

{
  "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	ZXQコード0ZXQ	ZXQコード1ZXQ

利用可能な場合、deviceTypeが応答に含まれます。

よくある故障シナリオについて解説します

注意

デバイスはモバイルアプリ経由で接続する必要があります

Shocksと振動機能を使用するには、装着者が対応するBluetoothデバイスをペアリングし、スマートフォンでChastifyモバイルアプリをアクティブに実行している必要があります。アプリは、デバイスにコマンドを送信するリアルタイムのソケット接続を維持します。アプリが閉じている場合、またはスマートフォンがインターネットに接続されていない場合、コマンドは失敗します。

no_device — 装着者が、Chastifyアプリで衝撃感知機能付きデバイス（例：CellMate Pro 3、Cagink Metal、Lockink AA-A1012）をペアリングしていません。APIがデバイスをターゲットにするには、デバイスがペアリングされ、アクティブ化され、完全に設定されている必要があります。

device_offline — 装着者のデバイスはペアリングされていますが、ネイティブ Shock サービス が有効になっていないか、Android アプリで実行されていません。これは最も一般的なエラーです。コマンドを確実に送信するには、装着者は Android アプリの設定でネイティブ Shock サービスを有効にする必要があります。

device_timeout — コマンドはモバイルアプリに送信されましたが、アプリは25秒以内にBluetoothデバイスがそれを受信したことを確認しませんでした。これは通常、装着者のBluetoothがオフになっているか、デバイスが通信範囲外にあるか、デバイスの電源がオフになっていることを意味します。Lockinkデバイスは、キープアライブ機能が有効になっていない限り、3分間操作がないとスリープ状態になります。また、キープアライブ機能が有効になっている場合でも、スマートフォンのOEMバッテリー最適化によってバックグラウンド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アプリにショックコマンドを送信したが、アプリが25秒以内にBluetoothデバイスへの配信を確認しなかったことを意味します。これは最も微妙なエラーです。Android側で何が起こるかは次のとおりです。

1. サーバー → アプリ: コマンドは Socket.IO を介して、装着者のスマートフォンで実行されているネイティブ Shock サービスに送信されます。
2. アプリ → デバイス: アプリはBluetooth Low Energy（BLE）を介してデバイスに接続し、ショックコマンドを送信します。QIUIデバイスの場合、まずデバイスメーカーのAPIからトークンを取得し、次にBLEコマンドを書き込みます。Lockinkデバイスの場合、BLEコマンドは直接送信されます。
3. アプリ → サーバー: アプリはサーバーに確認応答を送信します。

25秒のタイムアウトはステップ1から始まります。ステップ2でタイムアウトが発生する理由は以下のとおりです。

• Bluetoothがオフになっているか、デバイスが装着者のスマートフォンの通信範囲外にあります。
• ケージがスリープ状態です。 Lockink デバイスは、BLE が 3 分間非アクティブ状態になるとディープスリープに入ります。キープアライブ機能でこれを防ぐことができますが、OEM のバッテリー最適化 (Samsung、Xiaomi、Huawei など) によりバックグラウンドの Bluetooth 接続が切断され、キープアライブが信頼できなくなる場合があります。
• BLE接続に失敗しました。 アプリはBLE接続を再試行しますが、デバイスが応答しない場合はタイムアウトします。
• 安全ブロック アプリには、アクティビティ認識とGPS速度に基づいて、装着者が移動中（運転中、自転車に乗っているなど）であることを検知した場合にショックをブロックする安全システムが内蔵されています。装着者が移動中の場合、ショックは静かにブロックされ、失敗として報告されます。
• QIUIトークンの取得に失敗しました。 CellMate Pro 3およびCaginkデバイスの場合、アプリはBLEコマンドを送信する前に、QIUIのクラウドAPIからコマンドトークンを取得する必要があります。装着者のスマートフォンにインターネット接続がない場合、またはQIUIのAPIが遅い、もしくはアクセスできない場合、この手順に25秒のウィンドウのほとんどが費やされる可能性があります。

実用的なパターン

ほとんどの外部プログラムは、以下の流れに従います。

1. GET /api/apps/v1/sessionを呼び出してください。
2. lockDataを読み取ります。
3. 何が起こるべきかを決定してください。
4. /api/apps/v1/action、またはよりシンプルなロックエンドポイントのいずれかを呼び出してください。
5. 必要に応じて、/api/apps/v1/logs/custom を含むカスタムログを書き込みます。

例えば、スクリプトはtimeRemainingSecondsをチェックし、ルールが失敗した場合に時間を加算し、何が起こったかを説明するカスタムログを書き込むことができます。