Externe API's en programma's

Gebruik deze pagina wanneer u een eenvoudig extern programma, script, lokale server of backend-service wilt gebruiken om uw huidige Chastify-vergrendeling te beheren.

De eenvoudigste manier is om een gebruikersbreed DEV-token aan te maken en dit vervolgens als bearer-token naar de /api/apps/v1/*-eindpunten te verzenden.

/api/apps/v1/* is alleen bedoeld voor uw eigen actieve vergrendelingssessies. Als u een openbare extensie bouwt die door andere Chastify-gebruikers wordt gebruikt, gebruik dan een app-specifieke Developer API-sleutel met /api/extensions/sessions/:sessionId/* en geef de iframe mainToken door in x-chastify-main-token.

Maak een DEV-token aan.

Open Chastify.
Ga naar Developer API.
Zoek User-wide DEV API keys.
Maak een sleutel aan.
Kopieer het token direct. Het wordt slechts één keer weergegeven.

Gebruik het in verzoeken zoals deze:

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

DEV-tokens:

Het is niet nodig om een extensie aan te maken.
verlopen niet automatisch
werk voor uw huidige actieve vergrendeling en toekomstige actieve vergrendelingssessies
Gebruik je rol op het actieve slot, ofwel drager ofwel sleutelhouder.
kan worden ingetrokken via de pagina voor ontwikkelaars-API.

Behandel een DEV-token als een wachtwoord. Iedereen met het token kan de ontwikkelaars-API namens jou aanroepen.

Eerste stap: controleer het huidige slot.

Begin met:

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

Voorbeeld:

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

Dit geeft je huidige vergrendelingscontext, rol, scopes, resterende tijd en lockData weer.

Lock Data Helpers

GET /api/apps/v1/session omvat lockData, dat is ontworpen om gemakkelijk leesbaar te zijn voor programma's en regelengines.

Veelgebruikte booleaanse waarden:

frozen
unlockable
trusted
taskAssigned: true wanneer het actieve slot een open TaskRun heeft

Veelvoorkomende getallen:

timeLockedSeconds
timeRemainingSeconds
maxTimeRemainingSeconds
taskPoints

Veelvoorkomende tekenreeksen:

lockTitle
dragerprofielvelden
Profielvelden voor sleutelhouder

Privacyverklaring:

wearerLastSeenTimestamp en keyholderLastSeenTimestamp worden null wanneer de gebruiker zijn online status heeft uitgeschakeld.

Eindpunten voor acties van het hoofdslot

Deze eindpunten worden door de meeste externe programma's gebruikt om een vergrendeling te wijzigen.

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 verzoeken maken gebruik van:

Authorization: Bearer YOUR_DEV_TOKEN
Content-Type: application/json

Tijd toevoegen of verwijderen

Gebruik het eenvoudige tijd-eindpunt als u alleen de resterende tijd wilt wijzigen.

Voeg 10 minuten toe:

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

Verwijder 5 minuten:

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

Invriezen en ontdooien

Laat 30 minuten invriezen:

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

Ontdooien:

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

Algemeen actie-eindpunt

Gebruik:

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

Lichaamsvorm:

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

Voorbeeld:

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

Ondersteunde actienamen

name ondersteunt:

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

Actiebeperkingen:

Voor taakuitvoeringen is het vereist dat de module 'Taken' op het slot is ingeschakeld.
hygienic_unlock.start vereist dat Hygiënische Opening is ingeschakeld en dat er geen actieve hygiënesessie is.
Apparaatopdrachten vereisen een ondersteund, aangesloten apparaat en de juiste machtigingen.

Nuttige actievoorbeelden

Verwijder 15 minuten:

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

Laat 5 minuten bevriezen:

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

Vriesfunctie in-/uitschakelen:

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

Een taak toewijzen:

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

Dit genereert een TaskRun voor het actieve slot. Als er al een andere taak is geopend, annuleert de huidige implementatie de oude geopende taak en maakt een nieuwe aan.

Start de timer voor de actieve taak:

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

Voltooi de actieve taak:

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

Hiermee is de laatst geopende TaskRun voor het actieve slot voltooid.

Start een hygiënische ontgrendeling:

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

Beëindig de actieve schandpaal:

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

Aangepast vergrendelingslogboek

Gebruik dit wanneer uw programma iets heeft gedaan en u wilt dat dit zichtbaar is in de vergrendelingsgeschiedenis.

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

Voorbeeld:

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

Lichaamsvelden:

title: vereist
description: optioneel
role: extension, wearer of keyholder
icon: optioneel
color: optionele hexadecimale kleur, bijvoorbeeld #ffcc00

Apparaatcommando's

Met apparaatcommando's kunt u schokken en trillingen activeren op het aangesloten apparaat van de drager.

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

Werkt met uw DEV-token — geen sessie-ID nodig. De server bepaalt automatisch het slot en de gebruiker aan de hand van uw 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}}'

Verzoektekst

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

command (tekenreeks, verplicht) — de apparaatopdracht die moet worden uitgevoerd.
params (object, optioneel) — opdrachtspecifieke parameters (zie hieronder).

Ondersteunde commando's en hun parameters

`shock.start`

Activeert een elektrische schok op het apparaat van de drager.

Param	Type	Bereik	Standaardwaarde	Beschrijving
`intensityPct`	nummer	1–100	50	Shock intensiteit als percentage
`durationSeconds`	nummer	1–300	60	Shock duur in seconden
`message`	tekenreeks	—	—	Optioneel bericht dat aan de drager wordt getoond

notitie

De door de gebruiker ingestelde maximale spanning wordt altijd als een harde limiet gehandhaafd, ongeacht wat u verzendt. Voor Lockink-apparaten is dit de spanningslimiet per apparaat. Voor QIUI-apparaten is dit de shockVolt-instelling (schaal van 1-4). Als u intensityPct: 80 verzendt, maar de limiet van de gebruiker 50% is, zal het apparaat slechts 50% leveren.

Voorbeeld:

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`

Schakelt alle actieve schokken op het apparaat van de drager uit. Geen parameters vereist.

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`

Activeert een trilling op het apparaat van de drager.

Param	Type	Bereik	Standaardwaarde	Beschrijving
`intensityPct`	nummer	1–100	50	Trillingsintensiteit als percentage
`durationSeconds`	nummer	1–300	30	Trillingsduur in seconden
`frequencyPct`	nummer	1–100	50	Trillingsfrequentie als percentage
`message`	tekenreeks	—	—	Optioneel bericht dat aan de drager wordt getoond

Voorbeeld:

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`

Stopt alle actieve trillingen. Geen parameters vereist.

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`

Stopt alle apparaatactiviteit (schokken, trillingen, enz.). Geen parameters vereist.

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`

Hiermee kunt u de modus voor willekeurige schokken op het apparaat van de gebruiker in- of uitschakelen.

Param	Type	Bereik	Standaardwaarde	Beschrijving
`enabled`	boolean	—	—	Schakel de willekeurige modus in (`true`) of uit (`false`)
`minIntensityPct`	nummer	1–100	20	Minimum schokintensiteitspercentage
`maxIntensityPct`	nummer	1–100	80	Maximaal schokintensiteitspercentage
`message`	tekenreeks	—	—	Optioneel bericht dat aan de drager wordt getoond

notitie

De door de gebruiker ingestelde maximale spanning is altijd de harde limiet. Als u maxIntensityPct: 80 instelt, maar de limiet van de gebruiker is 50, dan zal het werkelijke maximum 50% zijn.

Voorbeeld:

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`

Hiermee kunt u de berserk-schokmodus op het apparaat van de gebruiker in- of uitschakelen.

Param	Type	Bereik	Standaardwaarde	Beschrijving
`enabled`	boolean	—	—	Berserk-modus inschakelen (`true`) of uitschakelen (`false`)
`message`	tekenreeks	—	—	Optioneel bericht dat aan de drager wordt getoond

Voorbeeld:

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

Apparaatopdrachten zijn afhankelijk van het actieve slot, de beschikbaarheid van het apparaat en het opdrachtbeleid.

Apparaatselectie

U hoeft geen apparaat-ID of apparaattype op te geven. Elke gebruiker kan slechts één actief apparaat tegelijk hebben; de server selecteert dit automatisch.

De code deviceType wordt in het antwoord teruggestuurd, zodat u weet welk apparaat de opdracht heeft ontvangen.

Reacties

Succes (200)

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

Veld	Beschrijving
`ok`	`true` toen het commando werd geaccepteerd
`command`	Het uitgevoerde commando
`result.success`	`true` als het apparaat de opdracht heeft bevestigd
`result.message`	Menselijk leesbaar statusbericht
`result.deviceType`	Het type apparaat van de drager (bijv. `lockink-aa-a1012`, `cellmate-pro-3`)
`active.shock`	Of er momenteel een schok actief is op het apparaat van de drager
`active.vibration`	Of er momenteel een vibratie actief is op het apparaat van de drager

Let op: shock.start en vibration.start wachten maximaal 25 seconden totdat het apparaat de ontvangst bevestigt. Stopcommando's (shock.stop, vibration.stop, all.stop) keren direct terug.

Mislukking

Alle fouten retourneren HTTP 4xx/5xx met een JSON-body:

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

Scenario	HTTP	`error`	`message`
Slot niet gevonden of geen actief slot	404	`lock_not_found`	`No active lock found`
Vergrendeling is niet langer actief	409	`lock_ended`	`The lock is no longer active`
Sessie van ontbrekende drager	400	`no_wearer`	`Missing wearer session`
Ontbrekende of ongeldige `durationSeconds`	400	`invalid_params`	`durationSeconds is required for server-initiated shocks`
Willekeurige/berserk-modus op niet-ondersteund apparaat	400	`unsupported_device`	`Random mode only supported on Lockink AA-A1012`
Gebruiker heeft geen toestemming gegeven voor elektrische schokken	403	`not_authorized`	`User not eligible for shock commands (consent or device check failed)`
Geen apparaat met schok-/trillingsfunctionaliteit gekoppeld	404	`no_device`	`No shock-capable device found for user`
Apparaat is offline (geen socketverbinding)	404	`device_offline`	`No active device socket found for user`
Apparaat heeft niet op tijd bevestigd (25s)	504	`device_timeout`	`Device verification timeout`
Niet-herkende of niet-afgehandelde storing	400	`command_failed`	`command_failed`

Indien beschikbaar, wordt deviceType in het antwoord opgenomen.

Veelvoorkomende faalscenario's uitgelegd

pas op

Het apparaat moet via de mobiele app verbonden zijn.

Voor de Shocks en vibraties is het vereist dat de drager een gekoppeld Bluetooth-apparaat heeft en dat de Chastify mobiele app actief op de telefoon draait. De app onderhoudt de realtime socketverbinding die commando's naar het apparaat stuurt. Als de app gesloten is of de telefoon geen internetverbinding heeft, zullen de commando's niet werken.

no_device — De drager heeft geen apparaat met schokdetectiefunctie (bijv. CellMate Pro 3, Cagink Metal, Lockink AA-A1012) gekoppeld in de Chastify-app. Apparaten moeten gekoppeld, actief en volledig geconfigureerd zijn voordat de API ze kan benaderen.

device_offline — Het apparaat van de drager is gekoppeld, maar de Native Shock Service is niet ingeschakeld of draait niet in de Android-app. Dit is de meest voorkomende fout — de drager moet de Native Shock Service inschakelen in de instellingen van de Android-app om commando's betrouwbaar te kunnen verzenden.

device_timeout — Het commando werd naar de mobiele app verzonden, maar de app bevestigde niet binnen 25 seconden dat het Bluetooth-apparaat het had ontvangen. Dit betekent meestal dat Bluetooth op de telefoon is uitgeschakeld, dat het apparaat buiten bereik is of dat het apparaat is uitgeschakeld. Lockink-apparaten gaan na slechts 3 minuten inactiviteit in slaapstand, tenzij de keep-alive-functie is ingeschakeld. Zelfs dan kunnen de batterijoptimalisaties van de fabrikant op de telefoon Bluetooth op de achtergrond beperken en ervoor zorgen dat de keep-alive-functie niet betrouwbaar werkt.

not_authorized — De drager heeft in de apparaatinstellingen geen expliciete toestemming gegeven voor schokken. Dit is een veiligheidsvereiste — zelfs bij een gekoppeld apparaat moet de drager expliciet toestemming geven voor het gebruik van schok-/trillingscommando's op afstand.

unsupported_device — De willekeurige en berserk-modi zijn alleen beschikbaar op de Lockink AA-A1012 (Beesting). Andere apparaten zoals de CellMate Pro 3 of de Cagink Metal ondersteunen deze modi niet.

Veelvoorkomende fouten

401 missing_token: verzend Authorization: Bearer YOUR_DEV_TOKEN.
401 invalid_token: het token is onjuist of is verkeerd gekopieerd.
401 revoked_token: de sleutel DEV is ingetrokken.
403 insufficient_scope: de sleutel heeft niet het vereiste bereik.
409 no_active_lock_session: de gebruiker heeft momenteel geen actief slot.
409 lock_ended: het opgeloste slot is niet langer actief.

info

device_timeout (504) begrijpen

De foutmelding device_timeout betekent dat de server het schokcommando naar de Android-app van de gebruiker heeft verzonden, maar dat de app de ontvangst niet binnen 25 seconden aan het Bluetooth-apparaat heeft bevestigd. Dit is de meest subtiele foutmelding — dit is wat er aan de kant van de Android gebeurt:

Server → App: Het commando wordt via Socket.IO naar de native Shock-service verzonden die op de telefoon van de gebruiker draait.
App → Apparaat: De app maakt via Bluetooth Low Energy (BLE) verbinding met het apparaat en verzendt het schokcommando. Voor QIUI-apparaten moet hiervoor eerst een token worden opgehaald via de API van de fabrikant, waarna het BLE-commando wordt verzonden. Voor Lockink-apparaten wordt het BLE-commando direct verzonden.
App → Server: De app stuurt een bevestiging terug naar de server.

De time-out van 25 seconden begint bij stap 1. Een time-out bij stap 2 kan optreden omdat:

Bluetooth is uitgeschakeld of het apparaat bevindt zich buiten het bereik van de telefoon van de gebruiker.
De kooi slaapt. Lockink-apparaten gaan na slechts 3 minuten BLE-inactiviteit in een diepe slaapstand. De keep-alive-functie kan dit voorkomen, maar batterijoptimalisaties van fabrikanten (Samsung, Xiaomi, Huawei, enz.) kunnen Bluetooth-verbindingen op de achtergrond verbreken, waardoor de keep-alive-functie onbetrouwbaar wordt.
BLE-verbinding mislukt. De app probeert de BLE-verbinding opnieuw tot stand te brengen, maar als het apparaat niet reageert, treedt er een time-out op.
Veiligheidsblokkering. De app heeft een ingebouwd veiligheidssysteem dat schokken blokkeert als de drager in beweging is (bijvoorbeeld tijdens het autorijden of fietsen) op basis van activiteitsherkenning en GPS-snelheid. Als de drager in beweging is, wordt de schok stilzwijgend geblokkeerd en als mislukt gerapporteerd.
Het ophalen van het QIUI-token is mislukt. Voor CellMate Pro 3- en Cagink-apparaten moet de app een commandotoken ophalen van de cloud-API van QIUI voordat het BLE-commando kan worden verzonden. Als de telefoon van de gebruiker geen internetverbinding heeft of als de API van QIUI traag/onbereikbaar is, kan deze stap het grootste deel van het beschikbare tijdsvenster van 25 seconden in beslag nemen.

Praktisch patroon

De meeste externe programma's volgen deze procedure:

Bel GET /api/apps/v1/session.
Lees lockData.
Beslis wat er moet gebeuren.
Roep /api/apps/v1/action aan of een van de eenvoudigere vergrendelings-eindpunten.
Schrijf optioneel een aangepast logbestand met /api/apps/v1/logs/custom.

Een script kan bijvoorbeeld timeRemainingSeconds controleren, een tijdstempel toevoegen wanneer een regel niet wordt nageleefd en vervolgens een aangepast logbestand schrijven waarin wordt uitgelegd wat er is gebeurd.

Maak een DEV-token aan.​

Eerste stap: controleer het huidige slot.​

Lock Data Helpers​

Eindpunten voor acties van het hoofdslot​

Tijd toevoegen of verwijderen​

Invriezen en ontdooien​

Algemeen actie-eindpunt​

Ondersteunde actienamen​

Nuttige actievoorbeelden​

Aangepast vergrendelingslogboek​

Apparaatcommando's​

Verzoektekst​

Ondersteunde commando's en hun parameters​

shock.start​

shock.stop​

vibration.start​

vibration.stop​

all.stop​

shock.random.set​

shock.berserk.set​

Apparaatselectie​

Reacties​

Succes (200)​

Mislukking​

Veelvoorkomende faalscenario's uitgelegd​

Veelvoorkomende fouten​

Praktisch patroon​

Maak een DEV-token aan.

Eerste stap: controleer het huidige slot.

Lock Data Helpers

Eindpunten voor acties van het hoofdslot

Tijd toevoegen of verwijderen

Invriezen en ontdooien

Algemeen actie-eindpunt

Ondersteunde actienamen

Nuttige actievoorbeelden

Aangepast vergrendelingslogboek

Apparaatcommando's

Verzoektekst

Ondersteunde commando's en hun parameters

`shock.start`

`shock.stop`

`vibration.start`

`vibration.stop`

`all.stop`

`shock.random.set`

`shock.berserk.set`

Apparaatselectie

Reacties

Succes (200)

Mislukking

Veelvoorkomende faalscenario's uitgelegd

Veelvoorkomende fouten

Praktisch patroon