Eksternt API og programmer

Bruk denne siden når du ønsker et enkelt eksternt program, skript, lokal server eller backend-tjeneste for å kontrollere din nåværende Chastify-lås.

Den enkleste måten er å opprette et brukeromfattende DEV-token, og deretter sende det som et bærertoken til /api/apps/v1/*-endepunktene.

/api/apps/v1/* er kun for dine egne aktive låseøkter. Hvis du bygger en offentlig utvidelse som brukes av andre Chastify-brukere, bruk en app-scoped Developer API-nøkkel med /api/extensions/sessions/:sessionId/* og send iframe mainToken i x-chastify-main-token.

Opprett et DEV-token

Åpne Chastify.
Gå til Developer API.
Finn User-wide DEV API keys.
Lag en nøkkel.
Kopier tokenet umiddelbart. Det vises bare én gang.

Bruk det i forespørsler som dette:

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

DEV-tokener:

ikke krever å opprette en utvidelse
ikke utløper automatisk
fungere for din nåværende aktive lås og fremtidige aktive låseøkter
bruk rollen din på den aktive låsen, enten bruker eller nøkkelholder
kan tilbakekalles fra Developer API-siden

Behandle et DEV-token som et passord. Alle med tokenet kan kalle Developer API-et som deg.

Første samtale: Sjekk gjeldende 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 nåværende låsekontekst, rolle, omfang, gjenværende tid og lockData.

Lås datahjelpere

GET /api/apps/v1/session inkluderer lockData, som er utformet for å være enkel for programmer og regelmotorer å lese.

Vanlige boolske verdier:

frozen
unlockable
trusted
taskAssigned: true når den aktive låsen har en åpen TaskRun

Vanlige tall:

timeLockedSeconds
timeRemainingSeconds
maxTimeRemainingSeconds
taskPoints

Vanlige strenger:

lockTitle
brukerprofilfelt
nøkkelholderprofilfelt

Personvernerklæring:

wearerLastSeenTimestamp og keyholderLastSeenTimestamp er null når brukeren har deaktivert online-status.

Hovedlåshandlingens endepunkter

Disse endepunktene er de fleste eksterne programmer bruker til å endre 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 forespørsler bruker:

Authorization: Bearer YOUR_DEV_TOKEN
Content-Type: application/json

Legg til eller fjern tid

Bruk det enkle tidssluttpunktet når du bare vil endre gjenværende tid.

Legg til 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 tining

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

Tin opp:

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

Generelt handlingsendepunkt

Bruk:

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

Kroppsform:

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

Støttede handlingsnavn

name støtter:

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

Handlingsbegrensninger:

Oppgavehandlinger krever at Oppgaver-modulen er aktivert på låsen.
hygienic_unlock.start krever at Hygienisk åpning er aktivert og at det ikke er noen aktiv hygieneøkt.
Enhetskommandoer krever en støttet tilkoblet enhet og tillatelser.

Nyttige eksempler på handlinger

Fjern 15 minutter:

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

Frys i 5 minutter:

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

Slå av/på frys:

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

Tildel en oppgave:

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

Dette oppretter en TaskRun for den aktive låsen. Hvis en annen oppgavekjøring allerede er åpen, avbryter den gjeldende implementeringen den gamle åpne kjøringen og oppretter en ny.

Start den aktive oppgavetimeren:

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

Fullfør den aktive oppgaven:

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

Dette fullfører den siste åpne TaskRun for den aktive låsen.

Start en hygienisk opplåsing:

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

Slutt på aktiv gapestokk:

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

Tilpasset låslogg

Bruk dette når programmet ditt gjorde noe og du vil at det skal være synlig 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"}'

Kroppsfelt:

title: obligatorisk
description: valgfritt
role: extension, wearer eller keyholder
icon: valgfritt
color: valgfri heksadesimal farge, for eksempel #ffcc00

Enhetskommandoer

Med enhetskommandoer kan du utløse støt og vibrasjoner på brukerens tilkoblede enhet.

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

Fungerer med DEV-tokenet ditt – ingen økt-ID nødvendig. Serveren løser automatisk låsen og brukeren fra tokenet ditt.

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

Forespørselstekst

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

command (streng, obligatorisk) – enhetskommandoen som skal utføres.
params (objekt, valgfritt) — kommandospesifikke parametere (se nedenfor).

Støttede kommandoer og deres parametere

`shock.start`

Starter et støt på brukerens enhet.

Parameter	Type	Område	Standard	Beskrivelse
`intensityPct`	tall	1–100	50	Shock intensitet som en prosentandel
`durationSeconds`	tall	1–300	60	Shock varighet i sekunder
`message`	streng	—	—	Valgfri melding vist til brukeren

note

Brukerens konfigurerte maksspenning håndheves alltid som en hard grense, uavhengig av hva du sender. For Lockink-enheter er dette spenningsgrensen per enhet. For QIUI-enheter er dette shockVolt-innstillingen (skala 1–4). Hvis du sender intensityPct: 80, men brukerens grense er 50 %, vil enheten bare levere 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øt på brukerens enhet. Ingen parametere kreves.

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 vibrasjon på brukerens enhet.

Parameter	Type	Område	Standard	Beskrivelse
`intensityPct`	tall	1–100	50	Vibrasjonsintensitet i prosent
`durationSeconds`	tall	1–300	30	Vibrasjonsvarighet i sekunder
`frequencyPct`	tall	1–100	50	Vibrasjonsfrekvens i prosent
`message`	streng	—	—	Valgfri melding vist til brukeren

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 vibrasjoner. Ingen parametere kreves.

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 all enhetsaktivitet (støt, vibrasjoner osv.). Ingen parametere kreves.

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 tilfeldig sjokkmodus på brukerens enhet.

Parameter	Type	Område	Standard	Beskrivelse
`enabled`	boolsk	—	—	Aktiver (`true`) eller deaktiver (`false`) tilfeldig modus
`minIntensityPct`	tall	1–100	20	Minimum støtintensitet i prosent
`maxIntensityPct`	tall	1–100	80	Maksimal støtintensitet i prosent
`message`	streng	—	—	Valgfri melding vist til brukeren

note

Brukerens konfigurerte maksspenning er alltid den harde hetten. Hvis du angir maxIntensityPct: 80, men brukerens grense er 50, vil det faktiske maksimumet 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 berserksjokk-modus på brukerens enhet.

Parameter	Type	Område	Standard	Beskrivelse
`enabled`	boolsk	—	—	Aktiver (`true`) eller deaktiver (`false`) berserkmodus
`message`	streng	—	—	Valgfri melding vist til brukeren

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

Enhetskommandoer avhenger av den aktive låsen, enhetens tilgjengelighet og kommandopolicyen.

Enhetsvalg

Du trenger ikke å angi en enhets-ID eller enhetstype. Hver bruker kan bare ha én aktiv enhet om gangen – serveren målretter den automatisk.

deviceType returneres i svaret, slik at du vet hvilken enhet som mottok kommandoen.

Svar

Suksess (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 ble akseptert
`command`	Kommandoen som ble utført
`result.success`	`true` hvis enheten bekreftet kommandoen
`result.message`	Statusmelding som kan leses av mennesker
`result.deviceType`	Brukerens enhetstype (f.eks. `lockink-aa-a1012`, `cellmate-pro-3`)
`active.shock`	Om et støt er aktivt på brukerens enhet
`active.vibration`	Om en vibrasjon er aktiv på brukerens enhet

Merk: shock.start og vibration.start venter opptil 25 sekunder på at enheten bekrefter mottak. Stoppkommandoer (shock.stop, vibration.stop, all.stop) returneres umiddelbart.

Feil

Alle feil returnerer HTTP 4xx/5xx med en JSON-innhold:

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

Scenario	HTTP	`error`	`message`
Lås ikke funnet eller ingen aktiv lås	404	`lock_not_found`	`No active lock found`
Låsen er ikke lenger aktiv	409	`lock_ended`	`The lock is no longer active`
Manglende brukerøkt	400	`no_wearer`	`Missing wearer session`
Manglende eller ugyldig `durationSeconds`	400	`invalid_params`	`durationSeconds is required for server-initiated shocks`
Tilfeldig/berserk-modus på enhet som ikke støttes	400	`unsupported_device`	`Random mode only supported on Lockink AA-A1012`
Brukeren har ikke gitt samtykke til sjokk	403	`not_authorized`	`User not eligible for shock commands (consent or device check failed)`
Ingen støt-/vibrasjonssikker enhet paret	404	`no_device`	`No shock-capable device found for user`
Enheten er frakoblet (ingen socket-tilkobling)	404	`device_offline`	`No active device socket found for user`
Enheten bekreftet ikke innen tidsfristen (25 sekunder)	504	`device_timeout`	`Device verification timeout`
Ukjent eller uhåndtert feil	400	`command_failed`	`command_failed`

Når tilgjengelig, inkluderes deviceType i svaret.

Vanlige feilscenarier forklart

caution

Enheten må være tilkoblet via mobilappen

Shock-lyder og vibrasjoner krever at brukeren har en støttet Bluetooth-enhet paret og at Chastify-mobilappen aktivt kjører på telefonen. Appen opprettholder sanntids-socket-tilkoblingen som leverer kommandoer til enheten. Hvis appen er lukket eller telefonen ikke har internett, vil kommandoene mislykkes.

no_device – Brukeren har ikke paret en støtsikker enhet (f.eks. CellMate Pro 3, Cagink Metal, Lockink AA-A1012) i Chastify-appen. Enhetene må være paret, aktive og fullstendig konfigurert før API-et kan målrette dem.

device_offline – Brukerens enhet er paret, men den native Shock-tjenesten er ikke aktivert eller kjører ikke på Android-appen. Dette er den vanligste feilen – brukeren må ha den native Shock-tjenesten aktivert i Android-appens innstillinger for at kommandoer skal leveres pålitelig.

device_timeout – Kommandoen ble sendt til mobilappen, men appen bekreftet ikke at Bluetooth-enheten mottok den innen 25 sekunder. Dette betyr vanligvis at brukerens Bluetooth er slått av, at enheten er utenfor rekkevidde, eller at enheten er slått av. Lockink-enheter går i dvale etter bare 3 minutter med inaktivitet med mindre keep-alive-funksjonen er aktivert – og selv da kan OEM-batterioptimaliseringer på telefonen begrense bakgrunns-Bluetooth og forhindre at keep-alive fungerer pålitelig.

not_authorized — Brukeren har ikke gitt uttrykkelig samtykke til støt i enhetsinnstillingene. Dette er et sikkerhetskrav – selv med en paret enhet må brukeren velge å tillate eksterne støt-/vibrasjonskommandoer.

unsupported_device — Tilfeldige og berserk-moduser er bare tilgjengelige på Lockink AA-A1012 (Beesting). Andre enheter som CellMate Pro 3 eller Cagink Metal støtter ikke disse modusene.

Vanlige feil

401 missing_token: send Authorization: Bearer YOUR_DEV_TOKEN.
401 invalid_token: tokenet er feil eller ble kopiert feil.
401 revoked_token: DEV-nøkkelen ble tilbakekalt.
403 insufficient_scope: nøkkelen har ikke det nødvendige omfanget.
409 no_active_lock_session: brukeren har ikke en aktiv lås for øyeblikket.
409 lock_ended: den løste låsen er ikke lenger aktiv.

info

Forstå device_timeout (504)

device_timeout-feilen betyr at serveren sendte sjokkkommandoen til brukerens Android-app, men appen bekreftet ikke levering til Bluetooth-enheten innen 25 sekunder. Dette er den mest nyanserte feilen – her er hva som skjer på Android-siden:

Server → App: Kommandoen går via Socket.IO til den innebygde Shock-tjenesten som kjører på brukerens telefon.
App → Enhet: Appen kobler seg til enheten via Bluetooth Low Energy (BLE) og sender sjokkkommandoen. For QIUI-enheter innebærer dette å hente et token fra enhetsprodusentens API først, og deretter skrive BLE-kommandoen. For Lockink-enheter sendes BLE-kommandoen direkte.
App → Server: Appen sender en bekreftelse tilbake til serveren.

25-sekunders timeouten starter ved trinn 1. En timeout ved trinn 2 kan oppstå fordi:

Bluetooth er av eller enheten er utenfor rekkevidde på brukerens telefon.
Buret sover. Lockink-enheter går inn i dyp søvn etter bare 3 minutter uten BLE-aktivitet. Keep-alive-funksjonen kan forhindre dette, men OEM-batterioptimaliseringer (Samsung, Xiaomi, Huawei osv.) kan drepe bakgrunnstilkoblinger for Bluetooth, noe som gjør keep-alive upålitelig.
BLE-tilkoblingen mislyktes. Appen prøver BLE-tilkoblingen på nytt, men hvis enheten ikke svarer, får den tidsavbrudd.
Sikkerhetsblokkering. Appen har et innebygd sikkerhetssystem som blokkerer støt hvis brukeren registreres i bevegelse (f.eks. kjøring, sykling) basert på aktivitetsgjenkjenning og GPS-hastighet. Hvis brukeren er i bevegelse, blokkeres støtet stille og rapporteres som mislykket.
Henting av QIUI-token mislyktes. For CellMate Pro 3- og Cagink-enheter må appen hente et kommandotoken fra QIUIs sky-API før BLE-kommandoen sendes. Hvis brukerens telefon ikke har internett, eller QIUIs API er treg/utilgjengelig, kan dette trinnet bruke opp mesteparten av 25-sekundersvinduet.

Praktisk mønster

De fleste eksterne programmer følger denne flyten:

Ring GET /api/apps/v1/session.
Les lockData.
Bestem hva som skal skje.
Kall /api/apps/v1/action eller et av de enklere låseendepunktene.
Skriv eventuelt en egendefinert logg med /api/apps/v1/logs/custom.

For eksempel kan et skript sjekke timeRemainingSeconds, legge til tidspunkt når en regel feiler, og deretter skrive en tilpasset logg som forklarer hva som skjedde.

Opprett et DEV-token​

Første samtale: Sjekk gjeldende lås​

Lås datahjelpere​

Hovedlåshandlingens endepunkter​

Legg til eller fjern tid​

Frys og tining​

Generelt handlingsendepunkt​

Støttede handlingsnavn​

Nyttige eksempler på handlinger​

Tilpasset låslogg​

Enhetskommandoer​

Forespørselstekst​

Støttede kommandoer og deres parametere​

shock.start​

shock.stop​

vibration.start​

vibration.stop​

all.stop​

shock.random.set​

shock.berserk.set​

Enhetsvalg​

Svar​

Suksess (200)​

Feil​

Vanlige feilscenarier forklart​

Vanlige feil​

Praktisk mønster​

Opprett et DEV-token

Første samtale: Sjekk gjeldende lås

Lås datahjelpere

Hovedlåshandlingens endepunkter

Legg til eller fjern tid

Frys og tining

Generelt handlingsendepunkt

Støttede handlingsnavn

Nyttige eksempler på handlinger

Tilpasset låslogg

Enhetskommandoer

Forespørselstekst

Støttede kommandoer og deres parametere

`shock.start`

`shock.stop`

`vibration.start`

`vibration.stop`

`all.stop`

`shock.random.set`

`shock.berserk.set`

Enhetsvalg

Svar

Suksess (200)

Feil

Vanlige feilscenarier forklart

Vanlige feil

Praktisk mønster