Külső API és programok

Ezt az oldalt akkor használd, ha egy egyszerű külső programra, szkriptre, helyi szerverre vagy háttérszolgáltatásra van szükséged a jelenlegi Chastify zár vezérléséhez.

A legegyszerűbb módja egy felhasználószintű DEV token létrehozása, majd tulajdonosi tokenként történő elküldése a /api/apps/v1/* végpontoknak.

A /api/apps/v1/* csak a saját aktív zárolási munkameneteidhez használható. Ha más Chastify felhasználók által használt nyilvános bővítményt építesz, használj alkalmazásszintű fejlesztői API-kulcsot a /api/extensions/sessions/:sessionId/*-val, és add át a mainToken iframe-et a x-chastify-main-token-ban.

Hozz létre egy DEV tokent

Nyissa meg a Chastify függvényt.
Menj a Developer API oldalra.
Keresd meg a User-wide DEV API keys kódot.
Hozz létre egy kulcsot.
Másolja le azonnal a tokent. Csak egyszer jelenik meg.

Használja az ilyen kérésekben:

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

DEV tokenek:

nem igényel bővítmény létrehozását
nem jár le automatikusan
működik az aktuális aktív zároláshoz és a jövőbeli aktív zárolási munkamenetekhez
használd a szerepkörödet az aktív záron, akár viselőjeként, akár kulcstartóként
visszavonható a fejlesztői API oldalról

A DEV tokent jelszóként kezeld. Bárki, aki rendelkezik a tokennel, meghívhatja a fejlesztői API-t a te nevedben.

Első hívás: Ellenőrizze a jelenlegi zárat

Kezdje ezzel:

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

Példa:

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

Ez visszaadja az aktuális zárolási kontextust, szerepkört, hatóköröket, hátralévő időt és a lockData értéket.

Zárolási adatsegítők

A GET /api/apps/v1/session tartalmazza a lockData kódot, amelyet úgy terveztek, hogy a programok és a szabálymotorok könnyen olvashatók legyenek.

Gyakori logikai értékek:

frozen
unlockable
trusted
taskAssigned: true, amikor az aktív zár nyitott TaskRun-val van ellátva.

Gyakori számok:

timeLockedSeconds
timeRemainingSeconds
maxTimeRemainingSeconds
taskPoints

Gyakori karakterláncok:

lockTitle
viselői profilmezők
kulcstulajdonos profilmezők

Adatvédelmi megjegyzés:

A wearerLastSeenTimestamp és a keyholderLastSeenTimestamp kódok null kóddá alakulnak, ha a felhasználó letiltotta az online állapotot.

Főzárműködtetési végpontok

Ezeket a végpontokat használják a legtöbb külső program a zárolás módosítására.

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

Minden kérés a következőket használja:

Authorization: Bearer YOUR_DEV_TOKEN
Content-Type: application/json

Idő hozzáadása vagy eltávolítása

Használja az egyszerű idő végpontot, ha csak a fennmaradó időt szeretné módosítani.

Adj hozzá 10 percet:

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 perc levonása:

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

Fagyasztás és feloldás

Fagyaszd le 30 percig:

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

Kiolvaszt:

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

Általános cselekvési végpont

Használat:

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

Testalkat:

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

Példa:

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

Támogatott műveletnevek

A name támogatja a következőket:

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

Műveleti korlátok:

A feladatműveletekhez engedélyezni kell a Feladatok modult a záron.
A hygienic_unlock.start kódhoz engedélyezni kell a higiénikus nyitást, és nem lehet aktív higiéniai munkamenet.
Az eszközparancsokhoz támogatott csatlakoztatott eszköz és engedélyek szükségesek.

Hasznos cselekvési példák

15 perc eltávolítása:

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

Fagyaszd le 5 percig:

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

Befagyasztás be-/kikapcsolása:

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

Feladat hozzárendelése:

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

Ez egy TaskRun kódot hoz létre az aktív zároláshoz. Ha egy másik feladat futtatása már meg van nyitva, a jelenlegi implementáció megszakítja a régi megnyitott futtatást, és egy újat hoz létre.

Indítsa el az aktív feladat időzítőjét:

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

Végezze el az aktív feladatot:

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

Ezzel befejeződött az aktív zár legújabb nyitott TaskRun kódja.

Higiénikus feloldás indítása:

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

Vége az aktív pellengérnek:

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

Egyéni zárolási napló

Használd ezt, ha a programod csinált valamit, és azt látni szeretnéd a zárolási előzményekben.

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

Példa:

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

Testmezők:

title: kötelező
description: opcionális
role: extension, wearer vagy keyholder
icon: opcionális
color: opcionális hexadecimális szín, például #ffcc00

Eszközparancsok

Az eszközparancsok lehetővé teszik ütések és rezgések kiváltását a viselő csatlakoztatott eszközén.

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

Működik a DEV tokennel — nincs szükség munkamenet-azonosítóra. A szerver automatikusan feloldja a zárat és a viselőt a tokenből.

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

Kérelem törzse

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

command (karakterlánc, kötelező) — a végrehajtandó eszközparancs.
params (objektum, opcionális) — parancsspecifikus paraméterek (lásd alább).

Támogatott parancsok és paramétereik

`shock.start`

Sokkot indít a viselő eszközén.

Paraméter	Típus	Tartomány	Alapértelmezett	Leírás
`intensityPct`	szám	1–100	50	Shock intenzitás százalékban
`durationSeconds`	szám	1–300	60	Shock időtartam másodpercben
`message`	karakterlánc	—	—	A viselőnek megjelenített opcionális üzenet

megjegyzés

A viselő beállított maximális feszültsége mindig merev korlátozásként van érvényben, függetlenül attól, hogy mit küldesz. Lockink eszközök esetén ez az eszközönkénti feszültségkorlát. QIUI eszközök esetén ez a shockVolt beállítás (1–4 skála). Ha intensityPct: 80 értéket küldesz, de a viselő korlátja 50%, az eszköz csak 50%-ot fog leadni.

Példa:

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`

Leállítja a viselő eszközén lévő összes aktív sokkot. Nincs szükség paraméterekre.

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`

Rezgést indít a viselő eszközén.

Paraméter	Típus	Tartomány	Alapértelmezett	Leírás
`intensityPct`	szám	1–100	50	Rezgésintenzitás százalékban
`durationSeconds`	szám	1–300	30	Rezgés időtartama másodpercben
`frequencyPct`	szám	1–100	50	Rezgési frekvencia százalékban
`message`	karakterlánc	—	—	A viselőnek megjelenített opcionális üzenet

Példa:

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`

Leállítja az összes aktív rezgést. Nincs szükség paraméterekre.

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`

Leállítja az eszköz összes tevékenységét (ütések, rezgések stb.). Nincs szükség paraméterekre.

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`

Engedélyezi vagy letiltja a véletlenszerű sokk módot a viselő eszközén.

Paraméter	Típus	Tartomány	Alapértelmezett	Leírás
`enabled`	logikai érték	—	—	Véletlenszerű mód engedélyezése (`true`) vagy letiltása (`false`)
`minIntensityPct`	szám	1–100	20	Minimális ütésintenzitás százalékban
`maxIntensityPct`	szám	1–100	80	Maximális ütésintenzitás százalékban
`message`	karakterlánc	—	—	A viselőnek megjelenített opcionális üzenet

megjegyzés

A viselő beállított maximális feszültsége mindig a fix feszültségkorlát. Ha a maxIntensityPct: 80 értéket állítja be, de a viselő határértéke 50, akkor a tényleges maximum 50% lesz.

Példa:

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`

Engedélyezi vagy letiltja a Berserk Shock módot a viselő eszközén.

Paraméter	Típus	Tartomány	Alapértelmezett	Leírás
`enabled`	logikai	—	—	Berserk mód engedélyezése (`true`) vagy letiltása (`false`)
`message`	karakterlánc	—	—	A viselőnek megjelenített opcionális üzenet

Példa:

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

Az eszközparancsok az aktív zárolástól, az eszköz elérhetőségétől és a parancsirányelvtől függenek.

Eszközválasztás

Nem kell megadnia az eszköz azonosítóját vagy típusát. Minden viselőnek egyszerre csak egy aktív eszköze lehet – a szerver automatikusan azt célozza meg.

A deviceType kódot a rendszer visszaadja a válaszban, így tudni fogja, melyik eszköz kapta a parancsot.

Válaszok

Siker (200)

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

Mező	Leírás
`ok`	`true` a parancs elfogadásakor
`command`	A végrehajtott parancs
`result.success`	`true`, ha az eszköz megerősítette a parancsot
`result.message`	Ember által olvasható állapotüzenet
`result.deviceType`	A viselő eszközének típusa (pl. `lockink-aa-a1012`, `cellmate-pro-3`)
`active.shock`	Aktív sokk van-e jelenleg a viselő eszközén
`active.vibration`	Azt jelzi, hogy a viselő eszközén jelenleg aktív-e a rezgés

Megjegyzés: A shock.start és a vibration.start parancsok legfeljebb 25 másodpercig várnak, amíg az eszköz visszaigazolja a vételt. A leállítási parancsok (shock.stop, vibration.stop, all.stop) azonnal visszatérnek.

Hiba

Minden hiba HTTP 4xx/5xx értéket ad vissza JSON törzstel:

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

Forgatókönyv	HTTP	`error`	`message`
Nem található zár, vagy nincs aktív zár	404	`lock_not_found`	`No active lock found`
A zár már nem aktív	409	`lock_ended`	`The lock is no longer active`
Hiányzó viselői munkamenet	400	`no_wearer`	`Missing wearer session`
Hiányzó vagy érvénytelen `durationSeconds`	400	`invalid_params`	`durationSeconds is required for server-initiated shocks`
Véletlenszerű/berserk mód nem támogatott eszközön	400	`unsupported_device`	`Random mode only supported on Lockink AA-A1012`
A felhasználó nem adott hozzájárulást a sokkhoz	403	`not_authorized`	`User not eligible for shock commands (consent or device check failed)`
Nincs párosítva ütés-/rezgésálló eszköz	404	`no_device`	`No shock-capable device found for user`
Az eszköz offline állapotban van (nincs socket kapcsolat)	404	`device_offline`	`No active device socket found for user`
Az eszköz nem erősítette meg időben (25 másodperc)	504	`device_timeout`	`Device verification timeout`
Felismeretlen vagy kezeletlen hiba	400	`command_failed`	`command_failed`

Ha elérhető, a deviceType szerepel a válaszban.

Gyakori meghibásodási forgatókönyvek ismertetése

figyelem

Az eszközt mobilalkalmazáson keresztül kell csatlakoztatni

A Shocks funkciókhoz és a rezgésekhez a viselőnek párosított Bluetooth-eszközzel kell rendelkeznie, és a Chastify mobilalkalmazásnak aktívan futnia a telefonján. Az alkalmazás valós idejű socket-kapcsolatot tart fenn, amely parancsokat küld az eszköznek. Ha az alkalmazás be van zárva, vagy a telefonnak nincs internetkapcsolata, a parancsok nem fognak működni.

no_device — A viselő nem párosított sokkra alkalmas eszközt (pl. CellMate Pro 3, Cagink Metal, Lockink AA-A1012) a Chastify alkalmazásban. Az eszközöknek párosítottnak, aktívnak és teljesen konfiguráltnak kell lenniük, mielőtt az API megcélozhatná őket.

device_offline – A viselő eszköze párosítva van, de a Natív Shock szolgáltatás nincs engedélyezve, vagy nem fut a Android alkalmazásban. Ez a leggyakoribb hiba – a parancsok megbízható kézbesítéséhez a viselőnek engedélyeznie kell a natív Shock szolgáltatást a Android alkalmazás beállításaiban.

device_timeout — A parancs elküldésre került a mobilalkalmazásnak, de az alkalmazás nem erősítette meg, hogy a Bluetooth-os eszköz 25 másodpercen belül megkapta-e. Ez általában azt jelenti, hogy a viselő Bluetooth-ja ki van kapcsolva, az eszköz hatótávolságon kívül van, vagy az eszköz ki van kapcsolva. A Lockink eszközök mindössze 3 perc tétlenség után alvó üzemmódba kapcsolnak, kivéve, ha a keepalive funkció engedélyezve van – és még ebben az esetben is a telefonon található OEM akkumulátor-optimalizálások korlátozhatják a háttérben futó Bluetooth-t, és megakadályozhatják a keepalive megbízható működését.

not_authorized — A viselő nem adott kifejezett hozzájárulást a sokkhoz az eszközbeállításaiban. Ez biztonsági követelmény – még párosított eszköz esetén is a viselőnek engedélyeznie kell a távoli sokk/rezgés parancsokat.

unsupported_device — A Véletlenszerű és a Berserk módok csak a Lockink AA-A1012 (Beesting) készüléken érhetők el. Más eszközök, mint például a CellMate Pro 3 vagy a Cagink Metal, nem támogatják ezeket a módokat.

Gyakori hibák

401 missing_token: küldje el a Authorization: Bearer YOUR_DEV_TOKEN kódot.
401 invalid_token: a token hibás, vagy helytelenül lett másolva.
401 revoked_token: a DEV kulcsot visszavonták.
403 insufficient_scope: a kulcs nem rendelkezik a szükséges hatókörrel.
409 no_active_lock_session: a felhasználónak jelenleg nincs aktív zárolása.
409 lock_ended: a feloldott zárolás már nem aktív.

információ

A device_timeout (504) kódrészlet értelmezése

A device_timeout hiba azt jelenti, hogy a szerver elküldte a sokkparancsot a viselő Android alkalmazásának, de az alkalmazás nem erősítette meg a kézbesítést a Bluetooth-eszköznek 25 másodpercen belül. Ez a legárnyaltabb hiba – íme, mi történik a Android oldalon:

Szerver → Alkalmazás: A parancs Socket.IO-n keresztül jut el a viselő telefonján futó natív Shock szolgáltatáshoz.
Alkalmazás → Eszköz: Az alkalmazás Bluetooth Low Energy (BLE) kapcsolaton keresztül csatlakozik az eszközhöz, és elküldi a sokkparancsot. A QIUI eszközök esetében ez először egy tokenek lekérését jelenti az eszköz gyártójának API-jából, majd a BLE parancs megírását. A Lockink eszközök esetében a BLE parancs közvetlenül kerül elküldésre.
Alkalmazás → Szerver: Az alkalmazás visszaigazolást küld a szervernek.

A 25 másodperces időtúllépés az 1. lépésnél kezdődik. A 2. lépésnél az időtúllépés a következők miatt történhet:

A Bluetooth ki van kapcsolva, vagy az eszköz hatótávolságon kívül van a viselő telefonján.
A ketrec alszik. A Lockink eszközök mindössze 3 perc BLE inaktivitás után mély alvási módba lépnek. A keep-alive funkció ezt megakadályozhatja, de az OEM akkumulátor-optimalizálások (Samsung, Xiaomi, Huawei stb.) megszakíthatják a háttérben lévő Bluetooth-kapcsolatokat, így a keep-alive funkció megbízhatatlanná válhat.
BLE-kapcsolat sikertelen. Az alkalmazás újrapróbálkozik a BLE-kapcsolattal, de ha az eszköz nem válaszol, időtúllépés történik.
Biztonsági blokk. Az alkalmazás beépített biztonsági rendszerrel rendelkezik, amely blokkolja az áramütéseket, ha a viselő mozgását érzékeli (pl. vezetés, kerékpározás) az aktivitásfelismerés és a GPS-sebesség alapján. Ha a viselő mozgásban van, a rendszer csendben blokkolja az áramütést, és sikertelenként jelenti.
A QIUI token lekérése sikertelen. A CellMate Pro 3 és Cagink eszközök esetében az alkalmazásnak le kell kérnie egy parancs tokent a QIUI felhőalapú API-járól, mielőtt elküldené a BLE parancsot. Ha a viselő telefonjának nincs internetkapcsolata, vagy a QIUI API-ja lassú/nem elérhető, ez a lépés a 25 másodperces ablak nagy részét igénybe veheti.

Gyakorlati minta

A legtöbb külső program ezt a folyamatot követi:

Hívja a GET /api/apps/v1/session kódot.
Olvasd el a lockData kódot.
Döntsd el, mi történjen.
Hívja meg a /api/apps/v1/action kódot, vagy az egyik egyszerűbb zárolási végpontot.
Opcionálisan egyéni naplót is írhat a /api/apps/v1/logs/custom kóddal.

Például egy szkript ellenőrizheti a timeRemainingSeconds kódot, hozzáadhatja az időpontot, amikor egy szabály meghiúsul, majd egyéni naplót írhat, amely elmagyarázza a történteket.

Hozz létre egy DEV tokent​

Első hívás: Ellenőrizze a jelenlegi zárat​

Zárolási adatsegítők​

Főzárműködtetési végpontok​

Idő hozzáadása vagy eltávolítása​

Fagyasztás és feloldás​

Általános cselekvési végpont​

Támogatott műveletnevek​

Hasznos cselekvési példák​

Egyéni zárolási napló​

Eszközparancsok​

Kérelem törzse​

Támogatott parancsok és paramétereik​

shock.start​

shock.stop​

vibration.start​

vibration.stop​

all.stop​

shock.random.set​

shock.berserk.set​

Eszközválasztás​

Válaszok​

Siker (200)​

Hiba​

Gyakori meghibásodási forgatókönyvek ismertetése​

Gyakori hibák​

Gyakorlati minta​

Hozz létre egy DEV tokent

Első hívás: Ellenőrizze a jelenlegi zárat

Zárolási adatsegítők

Főzárműködtetési végpontok

Idő hozzáadása vagy eltávolítása

Fagyasztás és feloldás

Általános cselekvési végpont

Támogatott műveletnevek

Hasznos cselekvési példák

Egyéni zárolási napló

Eszközparancsok

Kérelem törzse

Támogatott parancsok és paramétereik

`shock.start`

`shock.stop`

`vibration.start`

`vibration.stop`

`all.stop`

`shock.random.set`

`shock.berserk.set`

Eszközválasztás

Válaszok

Siker (200)

Hiba

Gyakori meghibásodási forgatókönyvek ismertetése

Gyakori hibák

Gyakorlati minta