Ekstern API og programmer

Brug denne side, når du ønsker et simpelt eksternt program, script, lokal server eller backend-tjeneste til at styre din nuværende Chastify-lås.

Den nemmeste måde er at oprette et brugeromfattende DEV-token og derefter sende det som et bearer-token til /api/apps/v1/*-slutpunkterne.

/api/apps/v1/* er kun til dine egne aktive låsesessioner. Hvis du bygger en offentlig udvidelse, der bruges af andre Chastify-brugere, skal du bruge en app-scoped Developer API-nøgle med /api/extensions/sessions/:sessionId/* og sende iframe'en mainToken i x-chastify-main-token.

Opret et DEV-token

Åbn Chastify.
Gå til Developer API.
Find User-wide DEV API keys.
Opret en nøgle.
Kopier tokenet med det samme. Det vises kun én gang.

Brug det i anmodninger som denne:

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

DEV-tokens:

kræver ikke oprettelse af en udvidelse
udløber ikke automatisk
fungerer for din nuværende aktive lås og fremtidige aktive låsesessioner
Brug din rolle på den aktive lås, enten som bærer eller nøgleholder
kan tilbagekaldes fra Developer API-siden

Behandl et DEV-token som en adgangskode. Enhver med tokenet kan kalde Developer API'en som dig.

Første opkald: Tjek den nuværende lås

Start med:

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

Eksempel:

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

Dette returnerer din nuværende låsekontekst, rolle, omfang, resterende tid og lockData.

Lås datahjælpere

GET /api/apps/v1/session inkluderer lockData, som er designet til at være let for programmer og regelmotorer at læse.

Almindelige boolske værdier:

frozen
unlockable
trusted
taskAssigned: true når den aktive lås har en åben TaskRun

Almindelige tal:

timeLockedSeconds
timeRemainingSeconds
maxTimeRemainingSeconds
taskPoints

Almindelige strenge:

lockTitle
bærerprofilfelter
felter i nøgleholderprofil

Privatlivsmeddelelse:

wearerLastSeenTimestamp og keyholderLastSeenTimestamp er null, når brugeren har deaktiveret onlinestatus.

Hovedlåsehandlingsslutpunkter

Disse slutpunkter er dem, som de fleste eksterne programmer bruger til at ændre en lås.

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

Alle anmodninger bruger:

Authorization: Bearer YOUR_DEV_TOKEN
Content-Type: application/json

Tilføj eller fjern tid

Brug det simple tidsslutpunkt, når du kun vil ændre den resterende tid.

Tilføj 10 minutter:

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

Fjern 5 minutter:

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

Frys og optø

Frys i 30 minutter:

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

Optø:

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

Generelt handlingsslutpunkt

Bruge:

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

Kropsform:

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

Eksempel:

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

Understøttede handlingsnavne

name understøtter:

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

Handlingsbegrænsninger:

Opgavehandlinger kræver, at Opgaver-modulet er aktiveret på låsen.
hygienic_unlock.start kræver, at Hygiejnisk Åbning er aktiveret, og at der ikke er nogen aktiv hygiejnesession.
Enhedskommandoer kræver en understøttet tilsluttet enhed og tilladelser.

Nyttige eksempler på handlinger

Fjern 15 minutter:

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

Frys i 5 minutter:

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

Slå frysning til/fra:

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

Tildel en opgave:

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

Dette opretter en TaskRun for den aktive lås. Hvis en anden opgavekørsel allerede er åben, annullerer den aktuelle implementering den gamle åbne kørsel og opretter en ny.

Start den aktive opgavetimer:

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

Færdiggør den aktive opgave:

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

Dette fuldfører den seneste åbne TaskRun for den aktive lås.

Start en hygiejnisk oplåsning:

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

Slut på aktiv gabestok:

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

Brugerdefineret låselog

Brug dette, når dit program har gjort noget, og du vil have det synligt i låsehistorikken.

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

Eksempel:

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

Kropfelter:

title: påkrævet
description: valgfri
role: extension, wearer eller keyholder
icon: valgfri
color: valgfri hex-farve, for eksempel #ffcc00

Enhedskommandoer

Enhedskommandoer giver dig mulighed for at udløse stød og vibrationer på brugerens tilsluttede enhed.

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

Fungerer med din DEV-token — intet sessions-ID nødvendigt. Serveren identificerer automatisk låsen og brugeren ud fra din token.

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

Anmodningstekst

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

command (streng, påkrævet) — den enhedskommando, der skal udføres.
params (objekt, valgfrit) — kommandospecifikke parametre (se nedenfor).

Understøttede kommandoer og deres parametre

`shock.start`

Starter et stød på bærerens enhed.

Parameter	Type	Interval	Standard	Beskrivelse
`intensityPct`	tal	1–100	50	Shock intensitet som en procentdel
`durationSeconds`	tal	1–300	60	Shock varighed i sekunder
`message`	streng	—	—	Valgfri besked vist til brugeren

note

Brugerens konfigurerede maksimale spænding håndhæves altid som en fast grænse, uanset hvad du sender. For Lockink-enheder er dette spændingsgrænsen pr. enhed. For QIUI-enheder er dette shockVolt-indstillingen (skala 1-4). Hvis du sender intensityPct: 80, men brugerens grænse er 50 %, leverer enheden kun 50 %.

Eksempel:

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`

Stopper alle aktive stød på brugerens enhed. Ingen parametre kræves.

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`

Starter en vibration på brugerens enhed.

Parameter	Type	Interval	Standard	Beskrivelse
`intensityPct`	tal	1–100	50	Vibrationsintensitet som en procentdel
`durationSeconds`	tal	1–300	30	Vibrationsvarighed i sekunder
`frequencyPct`	tal	1–100	50	Vibrationsfrekvens i procent
`message`	streng	—	—	Valgfri besked vist til brugeren

Eksempel:

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`

Stopper alle aktive vibrationer. Ingen parametre kræves.

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`

Stopper al enhedsaktivitet (stød, vibrationer osv.). Ingen parametre kræves.

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`

Aktiverer eller deaktiverer tilfældig stødtilstand på brugerens enhed.

Parameter	Type	Interval	Standard	Beskrivelse
`enabled`	boolsk	—	—	Aktiver (`true`) eller deaktiver (`false`) tilfældig tilstand
`minIntensityPct`	tal	1–100	20	Minimum stødintensitetsprocent
`maxIntensityPct`	tal	1–100	80	Maksimal stødintensitet i procent
`message`	streng	—	—	Valgfri besked vist til brugeren

note

Brugerens konfigurerede maksimale spænding er altid den faste hætte. Hvis du indstiller maxIntensityPct: 80, men brugerens grænse er 50, vil det faktiske maksimum være 50 %.

Eksempel:

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`

Aktiverer eller deaktiverer berserk shock-tilstand på brugerens enhed.

Parameter	Type	Interval	Standard	Beskrivelse
`enabled`	boolsk	—	—	Aktiver (`true`) eller deaktiver (`false`) bersærk-tilstand
`message`	streng	—	—	Valgfri besked vist til brugeren

Eksempel:

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

Enhedskommandoer afhænger af den aktive lås, enhedens tilgængelighed og kommandopolitikken.

Valg af enhed

Du behøver ikke at angive et enheds-ID eller enhedstype. Hver bruger kan kun have én aktiv enhed ad gangen – serveren målretter den automatisk.

deviceType returneres i svaret, så du ved, hvilken enhed der modtog kommandoen.

Svar

Succes (200)

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

Felt	Beskrivelse
`ok`	`true` da kommandoen blev accepteret
`command`	Den kommando, der blev udført
`result.success`	`true` hvis enheden bekræftede kommandoen
`result.message`	Statusmeddelelse, der kan læses af mennesker
`result.deviceType`	Brugerens enhedstype (f.eks. `lockink-aa-a1012`, `cellmate-pro-3`)
`active.shock`	Om et stød i øjeblikket er aktivt på brugerens enhed
`active.vibration`	Om en vibration i øjeblikket er aktiv på brugerens enhed

Bemærk: shock.start og vibration.start venter op til 25 sekunder på, at enheden bekræfter modtagelsen. Stopkommandoer (shock.stop, vibration.stop, all.stop) returneres med det samme.

Fiasko

Alle fejl returnerer HTTP 4xx/5xx med en JSON-brødtekst:

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

Scenarie	HTTP	`error`	`message`
Lås ikke fundet eller ingen aktiv lås	404	`lock_not_found`	`No active lock found`
Låsen er ikke længere aktiv	409	`lock_ended`	`The lock is no longer active`
Manglende bærersession	400	`no_wearer`	`Missing wearer session`
Manglende eller ugyldig `durationSeconds`	400	`invalid_params`	`durationSeconds is required for server-initiated shocks`
Tilfældig/bersærk-tilstand på ikke-understøttet enhed	400	`unsupported_device`	`Random mode only supported on Lockink AA-A1012`
Brugeren har ikke givet samtykke til stød	403	`not_authorized`	`User not eligible for shock commands (consent or device check failed)`
Ingen stød-/vibrationssikker enhed parret	404	`no_device`	`No shock-capable device found for user`
Enheden er offline (ingen socket-forbindelse)	404	`device_offline`	`No active device socket found for user`
Enheden blev ikke bekræftet i tide (25s)	504	`device_timeout`	`Device verification timeout`
Ugenkendt eller uhåndteret fejl	400	`command_failed`	`command_failed`

Når det er tilgængeligt, inkluderes deviceType i svaret.

Almindelige fejlscenarier forklaret

caution

Enheden skal være tilsluttet via mobilappen

Shocks og vibrationer kræver, at brugeren har en understøttet Bluetooth-enhed parret, og at Chastify mobilappen aktivt kører på deres telefon. Appen opretholder realtids-socketforbindelsen, der leverer kommandoer til enheden. Hvis appen er lukket, eller telefonen ikke har internet, vil kommandoer mislykkes.

no_device — Brugeren har ikke parret en stødsikker enhed (f.eks. CellMate Pro 3, Cagink Metal, Lockink AA-A1012) i Chastify-appen. Enheder skal være parret, aktive og fuldt konfigurerede, før API'en kan målrette dem.

device_offline — Brugerens enhed er parret, men den indbyggede Shock-tjeneste er ikke aktiveret eller kører ikke på Android-appen. Dette er den mest almindelige fejl — brugeren skal have den indbyggede Shock-tjeneste aktiveret i Android-appens indstillinger for at kommandoer kan leveres pålideligt.

device_timeout — Kommandoen blev sendt til mobilappen, men appen bekræftede ikke, at Bluetooth-enheden modtog den inden for 25 sekunder. Dette betyder normalt, at brugerens Bluetooth er slået fra, at enheden er uden for rækkevidde, eller at enheden er slukket. Lockink-enheder går i dvale efter kun 3 minutters inaktivitet, medmindre keep-alive-funktionen er aktiveret — og selv da kan OEM-batterioptimeringer på telefonen begrænse baggrunds-Bluetooth og forhindre keep-alive i at fungere pålideligt.

not_authorized — Brugeren har ikke givet udtrykkeligt samtykke til stød i sine enhedsindstillinger. Dette er et sikkerhedskrav — selv med en parret enhed skal brugeren tilmelde sig at tillade fjernstyrede stød-/vibrationskommandoer.

unsupported_device — Tilfældige og berserk-tilstande er kun tilgængelige på Lockink AA-A1012 (Beesting). Andre enheder som CellMate Pro 3 eller Cagink Metal understøtter ikke disse tilstande.

Almindelige fejl

401 missing_token: send Authorization: Bearer YOUR_DEV_TOKEN.
401 invalid_token: tokenet er forkert eller blev kopieret forkert.
401 revoked_token: DEV-nøglen blev tilbagekaldt.
403 insufficient_scope: nøglen har ikke det nødvendige omfang.
409 no_active_lock_session: brugeren har i øjeblikket ikke en aktiv lås.
409 lock_ended: den løste lås er ikke længere aktiv.

info

Forståelse af device_timeout (504)

device_timeout-fejlen betyder, at serveren sendte stødkommandoen til brugerens Android-app, men appen bekræftede ikke leveringen til Bluetooth-enheden inden for 25 sekunder. Dette er den mest nuancerede fejl – her er, hvad der sker på Android-siden:

Server → App: Kommandoen sendes via Socket.IO til den native Shock-tjeneste, der kører på brugerens telefon.
App → Enhed: Appen opretter forbindelse til enheden via Bluetooth Low Energy (BLE) og sender shock-kommandoen. For QIUI-enheder involverer dette først at hente et token fra enhedsproducentens API og derefter skrive BLE-kommandoen. For Lockink-enheder sendes BLE-kommandoen direkte.
App → Server: Appen sender en bekræftelse tilbage til serveren.

Timeout'en på 25 sekunder starter ved trin 1. En timeout ved trin 2 kan forekomme fordi:

Bluetooth er slukket, eller enheden er uden for rækkevidde på brugerens telefon.
Buret sover. Lockink-enheder går i dyb dvaletilstand efter kun 3 minutters BLE-inaktivitet. Keep-alive-funktionen kan forhindre dette, men OEM-batterioptimeringer (Samsung, Xiaomi, Huawei osv.) kan afbryde baggrunds-Bluetooth-forbindelser, hvilket gør keep-alive upålidelig.
BLE-forbindelse mislykkedes. Appen forsøger BLE-forbindelsen igen, men hvis enheden ikke svarer, får den timeout.
Sikkerhedsblokering. Appen har et indbygget sikkerhedssystem, der blokerer stød, hvis brugeren registreres i bevægelse (f.eks. kørsel, cykling) baseret på aktivitetsgenkendelse og GPS-hastighed. Hvis brugeren er i bevægelse, blokeres stødet lydløst og rapporteres som mislykket.
Hentning af QIUI-token mislykkedes. For CellMate Pro 3- og Cagink-enheder skal appen hente et kommandotoken fra QIUIs cloud-API, før BLE-kommandoen sendes. Hvis brugerens telefon ikke har internet, eller QIUIs API er langsom/uopnåelig, kan dette trin optage det meste af 25-sekundersvinduet.

Praktisk mønster

De fleste eksterne programmer følger denne proces:

Ring GET /api/apps/v1/session.
Læs lockData.
Beslut hvad der skal ske.
Kald /api/apps/v1/action eller et af de enklere låseslutpunkter.
Skriv eventuelt en brugerdefineret log med /api/apps/v1/logs/custom.

For eksempel kan et script tjekke timeRemainingSeconds, tilføje tidspunktet for en regels fejl og derefter skrive en brugerdefineret log, der forklarer, hvad der skete.

Opret et DEV-token​

Første opkald: Tjek den nuværende lås​

Lås datahjælpere​

Hovedlåsehandlingsslutpunkter​

Tilføj eller fjern tid​

Frys og optø​

Generelt handlingsslutpunkt​

Understøttede handlingsnavne​

Nyttige eksempler på handlinger​

Brugerdefineret låselog​

Enhedskommandoer​

Anmodningstekst​

Understøttede kommandoer og deres parametre​

shock.start​

shock.stop​

vibration.start​

vibration.stop​

all.stop​

shock.random.set​

shock.berserk.set​

Valg af enhed​

Svar​

Succes (200)​

Fiasko​

Almindelige fejlscenarier forklaret​

Almindelige fejl​

Praktisk mønster​

Opret et DEV-token

Første opkald: Tjek den nuværende lås

Lås datahjælpere

Hovedlåsehandlingsslutpunkter

Tilføj eller fjern tid

Frys og optø

Generelt handlingsslutpunkt

Understøttede handlingsnavne

Nyttige eksempler på handlinger

Brugerdefineret låselog

Enhedskommandoer

Anmodningstekst

Understøttede kommandoer og deres parametre

`shock.start`

`shock.stop`

`vibration.start`

`vibration.stop`

`all.stop`

`shock.random.set`

`shock.berserk.set`

Valg af enhed

Svar

Succes (200)

Fiasko

Almindelige fejlscenarier forklaret

Almindelige fejl

Praktisk mønster