Vanjski API-ji i programi

Koristite ovu stranicu kada želite jednostavan vanjski program, skriptu, lokalni poslužitelj ili pozadinsku uslugu za kontrolu vaše trenutne Chastify brave.

Najlakši način je stvoriti korisnički DEV token, a zatim ga poslati kao nositeljski token krajnjim točkama /api/apps/v1/*.

/api/apps/v1/* je samo za vaše aktivne sesije zaključavanja. Ako gradite javno proširenje koje koriste drugi Chastify korisnici, koristite ključ API-ja razvojnog programera s opsegom aplikacije s /api/extensions/sessions/:sessionId/* i proslijedite iframe mainToken u x-chastify-main-token.

Kreirajte token DEV

Otvorite Chastify.
Idite na Developer API.
Pronađite User-wide DEV API keys.
Izradite ključ.
Odmah kopirajte token. Prikazuje se samo jednom.

Koristite ga u zahtjevima poput ovog:

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

DEV tokeni:

ne zahtijevaju izradu proširenja
ne istječu automatski
raditi za vašu trenutnu aktivnu bravu i buduće sesije aktivne brave
koristite svoju ulogu na aktivnoj bravi, bilo da je nositelj ili vlasnik ključa
može se opozvati sa stranice Developer API-ja

Tretirajte token DEV kao lozinku. Svatko tko ima token može pozvati Developer API u vaše ime.

Prvi poziv: Provjerite trenutnu bravu

Započnite s:

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

Primjer:

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

Ovo vraća vaš trenutni kontekst zaključavanja, ulogu, opsege, preostalo vrijeme i lockData.

Pomoćnici za zaključavanje podataka

GET /api/apps/v1/session uključuje lockData, koji je dizajniran da ga programi i mehanizmi za pravila lako čitaju.

Uobičajene logičke vrijednosti:

frozen
unlockable
trusted
taskAssigned: true kada aktivna brava ima otvoren TaskRun

Uobičajeni brojevi:

timeLockedSeconds
timeRemainingSeconds
maxTimeRemainingSeconds
taskPoints

Uobičajeni nizovi:

lockTitle
polja profila korisnika
polja profila vlasnika ključa

Napomena o privatnosti:

wearerLastSeenTimestamp i keyholderLastSeenTimestamp su null kada je taj korisnik onemogućio online status.

Krajnje točke akcije glavnog zaključavanja

Ove krajnje točke su one koje većina vanjskih programa koristi za izmjenu brave.

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

Svi zahtjevi koriste:

Authorization: Bearer YOUR_DEV_TOKEN
Content-Type: application/json

Dodaj ili ukloni vrijeme

Koristite jednostavnu vremensku krajnju točku kada želite promijeniti samo preostalo vrijeme.

Dodajte 10 minuta:

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

Uklonite 5 minuta:

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

Zamrzavanje i odmrzavanje

Zamrznite 30 minuta:

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

Odmrzavanje:

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

Opća krajnja točka radnje

Koristiti:

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

Oblik tijela:

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

Primjer:

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

Podržani nazivi radnji

name podržava:

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

Ograničenja djelovanja:

Za radnje zadataka potrebno je da modul Zadaci bude omogućen na bravi.
hygienic_unlock.start zahtijeva da Higijensko otvaranje bude omogućeno i da nema aktivne higijenske sesije.
Naredbe uređaja zahtijevaju podržani povezani uređaj i dozvole.

Korisni primjeri radnji

Uklonite 15 minuta:

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

Zamrznite 5 minuta:

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

Uključi/isključi zamrzavanje:

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

Dodijelite zadatak:

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

Ovo stvara TaskRun za aktivnu bravu. Ako je već otvoreno drugo izvođenje zadatka, trenutna implementacija poništava staro otvoreno izvođenje i stvara novo.

Pokrenite aktivni mjerač vremena zadatka:

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

Dovršite aktivni zadatak:

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

Ovim je dovršeno najnovije otvaranje TaskRun za aktivnu bravu.

Pokrenite higijensko otključavanje:

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

Kraj aktivnog srama:

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

Prilagođeni zapisnik zaključavanja

Koristite ovo kada vaš program nešto učini i želite da to bude vidljivo u povijesti zaključavanja.

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

Primjer:

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

Polja tijela:

title: obavezno
description: opcionalno
role: extension, wearer ili keyholder
icon: opcionalno
color: opcionalna heksadecimalna boja, na primjer #ffcc00

Naredbe uređaja

Naredbe uređaja omogućuju vam pokretanje udaraca i vibracija na povezanom uređaju korisnika.

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

Radi s vašim DEV tokenom — nije potreban ID sesije. Poslužitelj automatski razlučuje bravu i korisnika iz vašeg tokena.

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

Tijelo zahtjeva

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

command (niz znakova, obavezno) — naredba uređaja koju treba izvršiti.
params (objekt, opcionalno) — parametri specifični za naredbu (vidi dolje).

Podržane naredbe i njihovi parametri

`shock.start`

Pokreće elektrošok na uređaju korisnika.

Parametar	Vrsta	Raspon	Zadano	Opis
`intensityPct`	broj	1–100	50	Shock intenzitet kao postotak
`durationSeconds`	broj	1–300	60	Shock trajanje u sekundama
`message`	niz znakova	—	—	Dodatna poruka prikazana korisniku

note

Konfigurirani maksimalni napon korisnika uvijek se primjenjuje kao fiksno ograničenje, bez obzira na to što šaljete. Za uređaje Lockink, ovo je ograničenje napona po uređaju. Za uređaje QIUI, ovo je postavka shockVolt (skala 1-4). Ako pošaljete intensityPct: 80, ali je ograničenje korisnika 50%, uređaj će isporučiti samo 50%.

Primjer:

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`

Zaustavlja sve aktivne šokove na uređaju korisnika. Nisu potrebni parametri.

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`

Pokreće vibraciju na uređaju korisnika.

Parametar	Vrsta	Raspon	Zadano	Opis
`intensityPct`	broj	1–100	50	Intenzitet vibracija kao postotak
`durationSeconds`	broj	1–300	30	Trajanje vibracije u sekundama
`frequencyPct`	broj	1–100	50	Frekvencija vibracija kao postotak
`message`	niz znakova	—	—	Dodatna poruka prikazana korisniku

Primjer:

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`

Zaustavlja sve aktivne vibracije. Nisu potrebni parametri.

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`

Zaustavlja sve aktivnosti uređaja (udarce, vibracije itd.). Nisu potrebni parametri.

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`

Omogućuje ili onemogućuje način rada s nasumičnim šokovima na uređaju korisnika.

Parametar	Vrsta	Raspon	Zadano	Opis
`enabled`	boolean	—	—	Omogući (`true`) ili onemogući (`false`) slučajni način rada
`minIntensityPct`	broj	1–100	20	Minimalni postotak intenziteta udara
`maxIntensityPct`	broj	1–100	80	Maksimalni postotak intenziteta udara
`message`	niz znakova	—	—	Dodatna poruka prikazana korisniku

note

Konfigurirani maksimalni napon korisnika uvijek je fiksni limit. Ako postavite maxIntensityPct: 80, ali je limit korisnika 50, stvarni maksimum bit će 50%.

Primjer:

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`

Omogućuje ili onemogućuje način rada berserk shock na uređaju korisnika.

Parametar	Vrsta	Raspon	Zadano	Opis
`enabled`	boolean	—	—	Omogući (`true`) ili onemogući (`false`) način rada berserk
`message`	niz znakova	—	—	Dodatna poruka prikazana korisniku

Primjer:

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

Naredbe uređaja ovise o aktivnoj bravi, dostupnosti uređaja i pravilima naredbi.

Odabir uređaja

Ne morate navesti ID uređaja ili vrstu uređaja. Svaki korisnik može imati samo jedan aktivan uređaj istovremeno - poslužitelj ga automatski cilja.

U odgovoru se vraća deviceType tako da znate koji je uređaj primio naredbu.

Odgovori

Uspjeh (200)

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

Polje	Opis
`ok`	`true` kada je naredba prihvaćena
`command`	Naredba koja je izvršena
`result.success`	`true` ako je uređaj potvrdio naredbu
`result.message`	Poruka o statusu čitljiva ljudima
`result.deviceType`	Vrsta uređaja korisnika (npr. `lockink-aa-a1012`, `cellmate-pro-3`)
`active.shock`	Je li šok trenutno aktivan na uređaju korisnika
`active.vibration`	Je li vibracija trenutno aktivna na uređaju korisnika

Napomena: shock.start i vibration.start čekaju do 25 sekundi da uređaj potvrdi prijem. Naredbe zaustavljanja (shock.stop, vibration.stop, all.stop) vraćaju se odmah.

Neuspjeh

Svi neuspješni rezultati vraćaju HTTP 4xx/5xx s JSON tijelom:

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

Scenarij	HTTP	`error`	`message`
Brava nije pronađena ili nema aktivne brave	404	`lock_not_found`	`No active lock found`
Brava više nije aktivna	409	`lock_ended`	`The lock is no longer active`
Nedostaje sesija korisnika	400	`no_wearer`	`Missing wearer session`
Nedostaje ili je nevažeći `durationSeconds`	400	`invalid_params`	`durationSeconds is required for server-initiated shocks`
Slučajni/berserk način rada na nepodržanom uređaju	400	`unsupported_device`	`Random mode only supported on Lockink AA-A1012`
Korisnik nije dao privolu za elektrošok	403	`not_authorized`	`User not eligible for shock commands (consent or device check failed)`
Nije uparen nijedan uređaj otporan na udarce/vibracije	404	`no_device`	`No shock-capable device found for user`
Uređaj je izvan mreže (nema utičnice)	404	`device_offline`	`No active device socket found for user`
Uređaj nije potvrdio na vrijeme (25 s)	504	`device_timeout`	`Device verification timeout`
Neprepoznat ili neobrađen kvar	400	`command_failed`	`command_failed`

Kada je dostupan, deviceType je uključen u odgovor.

Objašnjenje uobičajenih scenarija kvara

caution

Uređaj mora biti povezan putem mobilne aplikacije

Za korištenje Shock uređaja i vibracija, korisnik mora imati uparen podržani Bluetooth uređaj i aktivno pokrenutu mobilnu aplikaciju Chastify na svom telefonu. Aplikacija održava vezu u stvarnom vremenu koja isporučuje naredbe uređaju. Ako je aplikacija zatvorena ili telefon nema internet, naredbe neće uspjeti.

no_device — Korisnik nije upario uređaj koji može podnositi elektrošokove (npr. CellMate Pro 3, Cagink Metal, Lockink AA-A1012) u aplikaciji Chastify. Uređaji moraju biti upareni, aktivni i potpuno konfigurirani prije nego što ih API može ciljati.

device_offline — Uređaj korisnika je uparen, ali Native Shock Service nije omogućen ili ne radi na aplikaciji Android. Ovo je najčešći kvar — korisnik mora imati omogućenu Native Shock Service u postavkama aplikacije Android da bi se naredbe pouzdano isporučivale.

device_timeout — Naredba je poslana mobilnoj aplikaciji, ali aplikacija nije potvrdila da ju je Bluetooth uređaj primio unutar 25 sekundi. To obično znači da je Bluetooth korisnika isključen, da je uređaj izvan dometa ili da je uređaj isključen. Lockink uređaji prelaze u stanje mirovanja nakon samo 3 minute neaktivnosti, osim ako nije omogućena funkcija keep-alive - a čak i tada, OEM optimizacije baterije na telefonu mogu ograničiti Bluetooth u pozadini i spriječiti pouzdan rad keep-alive funkcije.

not_authorized — Korisnik nije dao izričitu suglasnost za elektrošok u postavkama uređaja. To je sigurnosni zahtjev — čak i s uparenim uređajem, korisnik mora dopustiti daljinske naredbe za elektrošok/vibraciju.

unsupported_device — Random i berserk načini rada dostupni su samo na Lockink AA-A1012 (Beesting). Drugi uređaji poput CellMate Pro 3 ili Cagink Metal ne podržavaju ove načine rada.

Uobičajene pogreške

401 missing_token: pošalji Authorization: Bearer YOUR_DEV_TOKEN.
401 invalid_token: token je pogrešan ili je neispravno kopiran.
401 revoked_token: ključ DEV je opozvan.
403 insufficient_scope: ključ nema potreban opseg.
409 no_active_lock_session: korisnik trenutno nema aktivno zaključavanje.
409 lock_ended: riješena brava više nije aktivna.

info

Razumijevanje device_timeout (504)

Pogreška device_timeout znači da je poslužitelj poslao naredbu za šok aplikaciji Android korisnika, ali aplikacija nije potvrdila isporuku na Bluetooth uređaj u roku od 25 sekundi. Ovo je najnijansiranija pogreška - evo što se događa na strani Android:

Poslužitelj → Aplikacija: Naredba putuje putem Socket.IO do izvorne Shock usluge koja se izvodi na telefonu korisnika.
Aplikacija → Uređaj: Aplikacija se povezuje s uređajem putem Bluetooth Low Energy (BLE) veze i šalje naredbu za šok. Za uređaje QIUI to uključuje prvo dohvaćanje tokena s API-ja proizvođača uređaja, a zatim pisanje BLE naredbe. Za uređaje Lockink, BLE naredba se šalje izravno.
Aplikacija → Poslužitelj: Aplikacija šalje potvrdu natrag poslužitelju.

Vremensko ograničenje od 25 sekundi počinje u koraku 1. Vremensko ograničenje u koraku 2 može se dogoditi iz sljedećih razloga:

Bluetooth je isključen ili je uređaj izvan dometa telefona korisnika.
Kavez je u stanju mirovanja. Uređaji Lockink ulaze u duboko stanje mirovanja nakon samo 3 minute neaktivnosti BLE-a. Funkcija keep-alive može to spriječiti, ali OEM optimizacije baterije (Samsung, Xiaomi, Huawei itd.) mogu prekinuti pozadinske Bluetooth veze, što keep-alive čini nepouzdanim.
BLE veza nije uspjela. Aplikacija ponovno pokušava uspostaviti BLE vezu, ali ako uređaj ne odgovori, dolazi do isteka vremena.
Sigurnosna blokada. Aplikacija ima ugrađeni sigurnosni sustav koji blokira šokove ako se otkrije da se korisnik kreće (npr. vozi, vozi bicikl) na temelju prepoznavanja aktivnosti i brzine GPS-a. Ako se korisnik kreće, šok se tiho blokira i prijavljuje se kao neuspješan.
Dohvaćanje tokena QIUI nije uspjelo. Za uređaje CellMate Pro 3 i Cagink, aplikacija mora dohvatiti token naredbe iz QIUI-ovog API-ja u oblaku prije slanja BLE naredbe. Ako telefon korisnika nema internetsku vezu ili je QIUI-ov API spor/nedostupan, ovaj korak može potrošiti veći dio prozora od 25 sekundi.

Praktični uzorak

Većina vanjskih programa slijedi ovaj tok:

Nazovite GET /api/apps/v1/session.
Pročitajte lockData.
Odlučite što bi se trebalo dogoditi.
Pozovite /api/apps/v1/action ili jednu od jednostavnijih krajnjih točaka zaključavanja.
Po želji napišite prilagođeni zapisnik sa /api/apps/v1/logs/custom.

Na primjer, skripta može provjeriti timeRemainingSeconds, dodati vrijeme kada pravilo ne uspije, a zatim napisati prilagođeni zapisnik s objašnjenjem što se dogodilo.

Kreirajte token DEV​

Prvi poziv: Provjerite trenutnu bravu​

Pomoćnici za zaključavanje podataka​

Krajnje točke akcije glavnog zaključavanja​

Dodaj ili ukloni vrijeme​

Zamrzavanje i odmrzavanje​

Opća krajnja točka radnje​

Podržani nazivi radnji​

Korisni primjeri radnji​

Prilagođeni zapisnik zaključavanja​

Naredbe uređaja​

Tijelo zahtjeva​

Podržane naredbe i njihovi parametri​

shock.start​

shock.stop​

vibration.start​

vibration.stop​

all.stop​

shock.random.set​

shock.berserk.set​

Odabir uređaja​

Odgovori​

Uspjeh (200)​

Neuspjeh​

Objašnjenje uobičajenih scenarija kvara​

Uobičajene pogreške​

Praktični uzorak​

Kreirajte token DEV

Prvi poziv: Provjerite trenutnu bravu

Pomoćnici za zaključavanje podataka

Krajnje točke akcije glavnog zaključavanja

Dodaj ili ukloni vrijeme

Zamrzavanje i odmrzavanje

Opća krajnja točka radnje

Podržani nazivi radnji

Korisni primjeri radnji

Prilagođeni zapisnik zaključavanja

Naredbe uređaja

Tijelo zahtjeva

Podržane naredbe i njihovi parametri

`shock.start`

`shock.stop`

`vibration.start`

`vibration.stop`

`all.stop`

`shock.random.set`

`shock.berserk.set`

Odabir uređaja

Odgovori

Uspjeh (200)

Neuspjeh

Objašnjenje uobičajenih scenarija kvara

Uobičajene pogreške

Praktični uzorak