Ulkoinen API ja ohjelmat

Käytä tätä sivua, kun haluat yksinkertaisen ulkoisen ohjelman, komentosarjan, paikallisen palvelimen tai taustapalvelun hallitsemaan nykyistä Chastify-lukkoasi.

Helpoin tapa on luoda käyttäjäkohtainen DEV-token ja lähettää se sitten haltija-tokenina /api/apps/v1/*-päätepisteisiin.

/api/apps/v1/* on tarkoitettu vain omille aktiivisille lukitusistunnoillesi. Jos olet rakentamassa julkista laajennusta, jota muut Chastify-käyttäjät käyttävät, käytä sovelluslaajuista Developer API -avainta /api/extensions/sessions/:sessionId/*:n kanssa ja välitä iframe mainToken x-chastify-main-token:ssa.

Luo DEV-token

Avaa Chastify.
Siirry osoitteeseen Developer API.
Etsi koodi User-wide DEV API keys.
Luo avain.
Kopioi tunnus välittömästi. Se näytetään vain kerran.

Käytä sitä tällaisissa pyynnöissä:

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

DEV-tokenit:

ei vaadi laajennuksen luomista
eivät vanhene automaattisesti
toimivat nykyisen aktiivisen lukituksesi ja tulevien aktiivisten lukitusistuntojen aikana
käytä rooliasi aktiivisessa lukossa, joko käyttäjänä tai avaimenhaltijana
voidaan peruuttaa kehittäjän API-sivulta

Käsittele DEV-tokenia salasanana. Kuka tahansa, jolla on token, voi kutsua kehittäjän API:a sinuna.

Ensimmäinen puhelu: Tarkista nykyinen lukko

Aloita:

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

Esimerkki:

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

Tämä palauttaa nykyisen lukituskontekstin, roolin, laajuusalueet, jäljellä olevan ajan ja lockData:n.

Lukitse datan apuohjelmat

GET /api/apps/v1/session sisältää lockData:n, joka on suunniteltu helposti luettavaksi ohjelmille ja sääntömoottoreille.

Yleisiä totuusarvoja:

frozen
unlockable
trusted
taskAssigned: true, kun aktiivisessa lukossa on avoin TaskRun

Yleisiä numeroita:

timeLockedSeconds
timeRemainingSeconds
maxTimeRemainingSeconds
taskPoints

Yleisiä merkkijonoja:

lockTitle
käyttäjäprofiilikentät
avaimenhaltijan profiilikentät

Tietosuojahuomautus:

wearerLastSeenTimestamp ja keyholderLastSeenTimestamp ovat null, kun käyttäjä on poistanut online-tilan käytöstä.

Päälukkojen toiminnan päätepisteet

Näitä päätepisteitä useimmat ulkoiset ohjelmat käyttävät lukon muokkaamiseen.

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

Kaikissa pyynnöissä käytetään:

Authorization: Bearer YOUR_DEV_TOKEN
Content-Type: application/json

Lisää tai poista aika

Käytä yksinkertaista aikapäätepistettä, kun haluat muuttaa vain jäljellä olevaa aikaa.

Lisää 10 minuuttia:

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

Poista 5 minuuttia:

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

Jäädytä ja sulata

Pakasta 30 minuuttia:

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

Vapauttaa:

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

Yleinen toimintapiste

Käyttää:

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

Kehon muoto:

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

Esimerkki:

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

Tuetut toimintojen nimet

name tukee:

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

Toimintorajoitukset:

Tehtävätoiminnot edellyttävät, että Tehtävät-moduuli on käytössä lukossa.
hygienic_unlock.start edellyttää, että hygieeninen avaus on käytössä eikä aktiivista hygieniasessio ole käynnissä.
Laitekomennot vaativat tuetun yhdistetyn laitteen ja käyttöoikeudet.

Hyödyllisiä toimintaesimerkkejä

Poista 15 minuuttia:

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

Pakasta 5 minuuttia:

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

Jäädytys päälle/pois:

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

Määritä tehtävä:

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

Tämä luo aktiiviselle lukolle TaskRun-koodin. Jos toinen tehtäväajo on jo käynnissä, nykyinen toteutus peruuttaa vanhan avoimen ajon ja luo uuden.

Käynnistä aktiivisen tehtävän ajastin:

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

Suorita aktiivinen tehtävä loppuun:

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

Tämä täydentää aktiivisen lukon uusimman avoimen TaskRun:n.

Aloita hygieeninen lukituksen avaus:

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

Aktiivisen häpeäpaalun loppu:

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

Mukautettu lukitusloki

Käytä tätä, kun ohjelmasi teki jotain ja haluat sen näkyvän lukitushistoriassa.

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

Esimerkki:

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

Kehon kentät:

title: pakollinen
description: valinnainen
role: extension, wearer tai keyholder
icon: valinnainen
color: valinnainen heksadesimaaliväri, esimerkiksi #ffcc00

Laitekomennot

Laitekomennoilla voit laukaista iskuja ja tärinää käyttäjän yhdistetyssä laitteessa.

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

Toimii DEV-tokenisi kanssa — istuntotunnusta ei tarvita. Palvelin selvittää lukon ja käyttäjän automaattisesti tunnuksestasi.

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

Pyynnön runko

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

command (merkkijono, pakollinen) — suoritettava laitekomento.
params (objekti, valinnainen) — komentokohtaiset parametrit (katso alla).

Tuetut komennot ja niiden parametrit

`shock.start`

Käynnistää iskun käyttäjän laitteessa.

Parametri	Tyyppi	Alue	Oletusarvo	Kuvaus
`intensityPct`	lukumäärä	1–100	50	Shock intensiteetti prosentteina
`durationSeconds`	numero	1–300	60	Shock kesto sekunteina
`message`	merkkijono	—	—	Käyttäjälle näytettävä valinnainen viesti

note

Käyttäjän määritettyä enimmäisjännitettä noudatetaan aina kiinteänä rajoituksena riippumatta siitä, mitä lähetät. Lockink-laitteilla tämä on laitekohtainen jänniteraja. QIUI-laitteilla tämä on shockVolt-asetus (skaala 1–4). Jos lähetät intensityPct: 80, mutta käyttäjän raja on 50 %, laite toimittaa vain 50 %.

Esimerkki:

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`

Pysäyttää kaikki käyttäjän laitteen aktiiviset iskut. Parametreja ei tarvita.

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`

Käynnistää käyttäjän laitteen värinän.

Parametri	Tyyppi	Alue	Oletusarvo	Kuvaus
`intensityPct`	numero	1–100	50	Tärinän voimakkuus prosentteina
`durationSeconds`	numero	1–300	30	Tärinän kesto sekunteina
`frequencyPct`	numero	1–100	50	Tärinätaajuus prosentteina
`message`	merkkijono	—	—	Käyttäjälle näytettävä valinnainen viesti

Esimerkki:

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`

Pysäyttää kaikki aktiiviset värähtelyt. Parametreja ei tarvita.

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`

Pysäyttää kaiken laitteen toiminnan (iskut, tärinät jne.). Parametreja ei tarvita.

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`

Ottaa käyttöön tai poistaa käytöstä satunnaisen iskun tilan käyttäjän laitteessa.

Parametri	Tyyppi	Alue	Oletusarvo	Kuvaus
`enabled`	totuusarvo	—	—	Ota satunnaistila käyttöön (`true`) tai poista se käytöstä (`false`)
`minIntensityPct`	numero	1–100	20	Iskun vähimmäisintensiteetin prosenttiosuus
`maxIntensityPct`	numero	1–100	80	Suurin iskunvoimakkuusprosentti
`message`	merkkijono	—	—	Käyttäjälle näytettävä valinnainen viesti

note

Käyttäjän määritetty maksimijännite on aina kiinteä rajoitus. Jos asetat maxIntensityPct: 80:n, mutta käyttäjän raja on 50, todellinen maksimi on 50 %.

Esimerkki:

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`

Ottaa käyttöön tai poistaa käytöstä käyttäjän laitteen berserk-shokkitilan.

Parametri	Tyyppi	Alue	Oletusarvo	Kuvaus
`enabled`	totuusarvo	—	—	Ota käyttöön (`true`) tai poista käytöstä (`false`) berserk-tila
`message`	merkkijono	—	—	Käyttäjälle näytettävä valinnainen viesti

Esimerkki:

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

Laitekomennot riippuvat aktiivisesta lukituksesta, laitteen saatavuudesta ja komentokäytännöstä.

Laitteen valinta

Laitetunnusta tai laitetyyppiä ei tarvitse määrittää. Jokaisella käyttäjällä voi olla vain yksi aktiivinen laite kerrallaan – palvelin kohdistaa sen automaattisesti.

Vastauksessa palautetaan deviceType, jotta tiedät, mikä laite vastaanotti komennon.

Vastaukset

Menestys (200)

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

Kenttä	Kuvaus
`ok`	`true` kun komento hyväksyttiin
`command`	Suoritettu komento
`result.success`	`true`, jos laite vahvisti komennon
`result.message`	Ihmisen luettavissa oleva tilaviesti
`result.deviceType`	Käyttäjän laitetyyppi (esim. `lockink-aa-a1012`, `cellmate-pro-3`)
`active.shock`	Onko käyttäjän laitteessa parhaillaan aktiivinen isku
`active.vibration`	Onko käyttäjän laitteessa tällä hetkellä värinätoiminto aktiivinen

Huomautus: shock.start ja vibration.start odottavat laitteen vahvistavan vastaanoton jopa 25 sekuntia. Pysäytyskomennot (shock.stop, vibration.stop, all.stop) palautuvat välittömästi.

Epäonnistuminen

Kaikki virheet palauttavat HTTP 4xx/5xx -koodin JSON-rungolla:

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

Skenaario	HTTP	`error`	`message`
Lukkoa ei löydy tai aktiivista lukkoa ei ole	404	`lock_not_found`	`No active lock found`
Lukitus ei ole enää aktiivinen	409	`lock_ended`	`The lock is no longer active`
Puuttuva käyttäjäistunto	400	`no_wearer`	`Missing wearer session`
Puuttuva tai virheellinen `durationSeconds`	400	`invalid_params`	`durationSeconds is required for server-initiated shocks`
Satunnainen/riehakas tila ei-tuetulla laitteella	400	`unsupported_device`	`Random mode only supported on Lockink AA-A1012`
Käyttäjä ei ole antanut suostumustaan shokkiin	403	`not_authorized`	`User not eligible for shock commands (consent or device check failed)`
Ei isku-/tärinänkestävää laitetta paritettuna	404	`no_device`	`No shock-capable device found for user`
Laite on offline-tilassa (ei sokettiyhteyttä)	404	`device_offline`	`No active device socket found for user`
Laite ei vahvistanut ajoissa (25 s)	504	`device_timeout`	`Device verification timeout`
Tunnistamaton tai käsittelemätön vika	400	`command_failed`	`command_failed`

Jos deviceType on saatavilla, se sisällytetään vastaukseen.

Yleisten vikatilanteiden selitys

caution

Laite on yhdistettävä mobiilisovelluksen kautta

Shocks ja värinänvaimennus edellyttävät, että käyttäjällä on paritettuna tuettu Bluetooth-laite ja Chastify-mobiilisovellus on aktiivisesti käynnissä puhelimessaan. Sovellus ylläpitää reaaliaikaista pistorasiayhteyttä, joka välittää komentoja laitteelle. Jos sovellus on suljettu tai puhelimessa ei ole internetiä, komennot epäonnistuvat.

no_device — Käyttäjä ei ole yhdistänyt iskua antavaa laitetta (esim. CellMate Pro 3, Cagink Metal, Lockink AA-A1012) Chastify-sovellukseen. Laitteiden on oltava yhdistettyjä, aktiivisia ja täysin konfiguroituja, ennen kuin API voi kohdistaa niihin defibrillaation.

device_offline — Käyttäjän laite on paritettu, mutta Native Shock Service ei ole käytössä tai se ei ole käynnissä Android-sovelluksessa. Tämä on yleisin virhe — käyttäjällä on oltava Native Shock Service käytössä Android-sovelluksen asetuksissa, jotta komennot toimitetaan luotettavasti.

device_timeout — Komento lähetettiin mobiilisovellukseen, mutta sovellus ei vahvistanut, että Bluetooth-laite vastaanotti sen 25 sekunnin kuluessa. Tämä tarkoittaa yleensä, että käyttäjän Bluetooth on pois päältä, laite on kantaman ulkopuolella tai laite on sammutettu. Lockink-laitteet menevät lepotilaan vain kolmen minuutin käyttämättömyyden jälkeen, ellei keepalive-toimintoa ole otettu käyttöön – ja silloinkin puhelimen alkuperäisen laitteen akun optimoinnit saattavat rajoittaa taustalla toimivaa Bluetoothia ja estää keepalive-toiminnon luotettavan toiminnan.

not_authorized — Käyttäjä ei ole antanut nimenomaista suostumusta iskuun laiteasetuksissaan. Tämä on turvallisuusvaatimus – jopa paritetun laitteen kanssa käyttäjän on sallittava etädettävät iskut/värähtelykomennot.

unsupported_device — Satunnainen ja riehakas tilat ovat käytettävissä vain Lockink AA-A1012 (Beesting) -mallissa. Muut laitteet, kuten CellMate Pro 3 tai Cagink Metal, eivät tue näitä tiloja.

Yleisiä virheitä

401 missing_token: lähetä Authorization: Bearer YOUR_DEV_TOKEN.
401 invalid_token: token on väärä tai se on kopioitu väärin.
401 revoked_token: avain DEV on peruutettu.
403 insufficient_scope: avaimella ei ole vaadittua laajuutta.
409 no_active_lock_session: käyttäjällä ei ole tällä hetkellä aktiivista lukitusta.
409 lock_ended: ratkaistu lukitus ei ole enää aktiivinen.

info

Ymmärrystä koodista device_timeout (504)

device_timeout-virhe tarkoittaa, että palvelin lähetti iskukomennon käyttäjän Android-sovellukseen, mutta sovellus ei vahvistanut toimitusta Bluetooth-laitteelle 25 sekunnin kuluessa. Tämä on vivahteikkain virhe – Android-puolella tapahtuu seuraavaa:

Palvelin → Sovellus: Komento kulkee Socket.IO:n kautta käyttäjän puhelimessa käynnissä olevaan Native Shock -palveluun.
Sovellus → Laite: Sovellus muodostaa yhteyden laitteeseen Bluetooth Low Energy (BLE) -yhteyden kautta ja lähettää shokkikomennon. QIUI-laitteilla tämä tarkoittaa ensin tunnuksen hakemista laitteen valmistajan API:sta ja sitten BLE-komennon kirjoittamista. Lockink-laitteilla BLE-komento lähetetään suoraan.
Sovellus → Palvelin: Sovellus lähettää vahvistuksen takaisin palvelimelle.

25 sekunnin aikakatkaisu alkaa vaiheesta 1. Aikakatkaisu vaiheessa 2 voi tapahtua seuraavista syistä:

Bluetooth on pois päältä tai laite on kantaman ulkopuolella käyttäjän puhelimessa.
Häkki on lepotilassa. Lockink-laitteet siirtyvät syvään lepotilaan vain 3 minuutin BLE-käytön jälkeen. Keep-alive-ominaisuus voi estää tämän, mutta alkuperäisten laitevalmistajien (Samsung, Xiaomi, Huawei jne.) akun optimoinnit saattavat katkaista taustalla olevat Bluetooth-yhteydet, mikä tekee keep-alive-toiminnosta epäluotettavan.
BLE-yhteys epäonnistui. Sovellus yrittää BLE-yhteyttä uudelleen, mutta jos laite ei vastaa, se aikakatkaistaan.
Turvaesto. Sovelluksessa on sisäänrakennettu turvajärjestelmä, joka estää iskut, jos käyttäjän havaitaan liikkuvan (esim. ajavan tai pyöräilevän) aktiivisuuden tunnistuksen ja GPS-nopeuden perusteella. Jos käyttäjä on liikkeessä, isku estetään äänettömästi ja ilmoitetaan epäonnistuneeksi.
QIUI-tunnuksen haku epäonnistui. CellMate Pro 3- ja Cagink-laitteissa sovelluksen on noudettava komentotoken QIUI:n pilvi-API:sta ennen BLE-komennon lähettämistä. Jos käyttäjän puhelimessa ei ole internetiä tai QIUI:n API on hidas/saavutettavissa, tämä vaihe voi viedä suurimman osan 25 sekunnin ikkunasta.

Käytännön malli

Useimmat ulkoiset ohjelmat noudattavat tätä kaavaa:

Soita numeroon GET /api/apps/v1/session.
Lue koodi lockData.
Päätä, mitä pitäisi tapahtua.
Kutsu /api/apps/v1/action:ta tai jotakin yksinkertaisempaa lukituspäätepistettä.
Voit halutessasi kirjoittaa mukautetun lokin koodilla /api/apps/v1/logs/custom.

Esimerkiksi komentosarja voi tarkistaa timeRemainingSeconds:n, lisätä ajan, jolloin sääntö epäonnistuu, ja sitten kirjoittaa mukautetun lokin, jossa selitetään, mitä tapahtui.

Luo DEV-token​

Ensimmäinen puhelu: Tarkista nykyinen lukko​

Lukitse datan apuohjelmat​

Päälukkojen toiminnan päätepisteet​

Lisää tai poista aika​

Jäädytä ja sulata​

Yleinen toimintapiste​

Tuetut toimintojen nimet​

Hyödyllisiä toimintaesimerkkejä​

Mukautettu lukitusloki​

Laitekomennot​

Pyynnön runko​

Tuetut komennot ja niiden parametrit​

shock.start​

shock.stop​

vibration.start​

vibration.stop​

all.stop​

shock.random.set​

shock.berserk.set​

Laitteen valinta​

Vastaukset​

Menestys (200)​

Epäonnistuminen​

Yleisten vikatilanteiden selitys​

Yleisiä virheitä​

Käytännön malli​

Luo DEV-token

Ensimmäinen puhelu: Tarkista nykyinen lukko

Lukitse datan apuohjelmat

Päälukkojen toiminnan päätepisteet

Lisää tai poista aika

Jäädytä ja sulata

Yleinen toimintapiste

Tuetut toimintojen nimet

Hyödyllisiä toimintaesimerkkejä

Mukautettu lukitusloki

Laitekomennot

Pyynnön runko

Tuetut komennot ja niiden parametrit

`shock.start`

`shock.stop`

`vibration.start`

`vibration.stop`

`all.stop`

`shock.random.set`

`shock.berserk.set`

Laitteen valinta

Vastaukset

Menestys (200)

Epäonnistuminen

Yleisten vikatilanteiden selitys

Yleisiä virheitä

Käytännön malli