Externe API & Programme

Verwenden Sie diese Seite, wenn Sie ein einfaches externes Programm, Skript, einen lokalen Server oder einen Backend-Dienst benötigen, um Ihr aktuelles Chastify-Schloss zu steuern.

Am einfachsten ist es, ein benutzerweites DEV-Token zu erstellen und dieses dann als Bearer-Token an die /api/apps/v1/*-Endpunkte zu senden.

/api/apps/v1/* ist ausschließlich für Ihre eigenen aktiven Sperrsitzungen vorgesehen. Wenn Sie eine öffentliche Erweiterung entwickeln, die von anderen Chastify-Benutzern verwendet wird, verwenden Sie einen anwendungsbezogenen Entwickler-API-Schlüssel mit /api/extensions/sessions/:sessionId/* und übergeben Sie den iFrame mainToken in x-chastify-main-token.

Erstellen Sie ein DEV-Token

Öffnen Sie Chastify.
Gehe zu Developer API.
Finde User-wide DEV API keys.
Einen Schlüssel erstellen.
Kopieren Sie das Token sofort. Es wird nur einmal angezeigt.

Verwenden Sie es in Anfragen wie dieser:

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

DEV-Token:

Es ist nicht erforderlich, eine Erweiterung zu erstellen.
laufen nicht automatisch ab
Funktioniert für Ihre aktuelle aktive Sperre und zukünftige aktive Sperrsitzungen
Verwenden Sie Ihre Rolle beim aktiven Schloss, entweder Träger oder Schlüsselhalter
kann über die Entwickler-API-Seite widerrufen werden.

Behandeln Sie ein DEV-Token wie ein Passwort. Jeder, der im Besitz dieses Tokens ist, kann die Entwickler-API in Ihrem Namen aufrufen.

Erster Anruf: Überprüfen Sie das aktuelle Schloss

Beginnen Sie mit:

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

Beispiel:

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

Dies gibt Ihren aktuellen Sperrkontext, Ihre Rolle, Ihre Bereiche, die verbleibende Zeit und lockData zurück.

Sperrdatenhelfer

GET /api/apps/v1/session beinhaltet lockData, das so konzipiert ist, dass es für Programme und Regelwerke leicht lesbar ist.

Gängige Boolesche Werte:

frozen
unlockable
trusted
taskAssigned: true wenn das aktive Schloss offen ist TaskRun

Gängige Zahlen:

timeLockedSeconds
timeRemainingSeconds
maxTimeRemainingSeconds
taskPoints

Häufige Zeichenketten:

lockTitle
Trägerprofilfelder
Schlüsselhalterprofilfelder

Datenschutzhinweis:

wearerLastSeenTimestamp und keyholderLastSeenTimestamp werden zu null, wenn der Benutzer den Online-Status deaktiviert hat.

Hauptsperr-Aktionsendpunkte

Diese Endpunkte werden von den meisten externen Programmen verwendet, um eine Sperre zu modifizieren.

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 Anfragen verwenden:

Authorization: Bearer YOUR_DEV_TOKEN
Content-Type: application/json

Zeit hinzufügen oder entfernen

Verwenden Sie den einfachen Zeitendpunkt, wenn Sie nur die verbleibende Zeit ändern möchten.

10 Minuten hinzufügen:

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

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

Einfrieren und Auftauen

30 Minuten einfrieren:

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

Auftauen:

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

Allgemeiner Aktionsendpunkt

Verwenden:

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

Körperform:

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

Beispiel:

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

Unterstützte Aktionsnamen

name unterstützt:

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

Handlungseinschränkungen:

Für die Ausführung von Aufgaben muss das Aufgabenmodul auf dem Schloss aktiviert sein.
Für hygienic_unlock.start muss die hygienische Öffnung aktiviert sein und es darf keine aktive Hygienesitzung vorliegen.
Gerätebefehle erfordern ein unterstütztes, angeschlossenes Gerät und entsprechende Berechtigungen.

Nützliche Aktionsbeispiele

15 Minuten entfernen:

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

5 Minuten einfrieren:

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

Einfrieren umschalten:

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

Eine Aufgabe zuweisen:

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

Dadurch wird ein TaskRun für die aktive Sperre erzeugt. Falls bereits ein anderer Tasklauf geöffnet ist, bricht die aktuelle Implementierung den alten Lauf ab und erstellt einen neuen.

Starten Sie den Timer für die aktive Aufgabe:

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

Schließen Sie die aktive Aufgabe ab:

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

Damit ist der letzte offene TaskRun-Vorgang für das aktive Schloss abgeschlossen.

Hygienisches Entsperren starten:

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

Ende des aktiven Prangers:

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

Benutzerdefiniertes Sperrprotokoll

Verwenden Sie diese Option, wenn Ihr Programm eine Aktion ausgeführt hat und diese im Sperrverlauf sichtbar sein soll.

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

Beispiel:

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

Körperfelder:

title: erforderlich
description: optional
role: extension, wearer oder keyholder
icon: optional
color: optionale Hexadezimalfarbe, z. B. #ffcc00

Gerätebefehle

Gerätebefehle ermöglichen es Ihnen, Stromschläge und Vibrationen am angeschlossenen Gerät des Trägers auszulösen.

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

Funktioniert mit Ihrem DEV-Token – keine Sitzungs-ID erforderlich. Der Server ermittelt automatisch Sperre und Träger anhand Ihres Tokens.

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

Anfragekörper

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

command (Zeichenkette, erforderlich) — der auszuführende Gerätebefehl.
params (Objekt, optional) — befehlsspezifische Parameter (siehe unten).

Unterstützte Befehle und ihre Parameter

`shock.start`

Löst einen Stromschlag am Gerät des Trägers aus.

Parameter	Typ	Bereich	Standardwert	Beschreibung
`intensityPct`	Zahl	1–100	50	Shock Intensität in Prozent
`durationSeconds`	Nummer	1–300	60	Shock Dauer in Sekunden
`message`	Zeichenkette	—	—	Optionale Nachricht, die dem Träger angezeigt wird

hinweis

Die vom Träger konfigurierte maximale Spannung wird unabhängig von der gesendeten Spannung immer als feste Obergrenze durchgesetzt. Bei Lockink-Geräten ist dies die gerätespezifische Spannungsgrenze. Bei QIUI-Geräten entspricht dies der Einstellung shockVolt (Skala 1–4). Wenn Sie intensityPct: 80 senden, die Grenze des Trägers aber bei 50 % liegt, liefert das Gerät nur 50 %.

Beispiel:

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`

Unterbricht alle aktiven Stromschläge am Gerät des Trägers. Keine Parameter erforderlich.

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`

Löst eine Vibration auf dem Gerät des Trägers aus.

Parameter	Typ	Bereich	Standardwert	Beschreibung
`intensityPct`	Nummer	1–100	50	Vibrationsintensität in Prozent
`durationSeconds`	Nummer	1–300	30	Vibrationsdauer in Sekunden
`frequencyPct`	Nummer	1–100	50	Schwingungsfrequenz in Prozent
`message`	Zeichenkette	—	—	Optionale Nachricht, die dem Träger angezeigt wird

Beispiel:

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`

Stoppt alle aktiven Vibrationen. Keine Parameter erforderlich.

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`

Unterbindet jegliche Geräteaktivität (Stöße, Vibrationen usw.). Keine Parameter erforderlich.

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`

Aktiviert oder deaktiviert den Zufallsschockmodus auf dem Gerät des Trägers.

Parameter	Typ	Bereich	Standardwert	Beschreibung
`enabled`	boolesch	—	—	Zufallsmodus aktivieren (`true`) oder deaktivieren (`false`)
`minIntensityPct`	Nummer	1–100	20	Minimale Schockintensität in Prozent
`maxIntensityPct`	Nummer	1–100	80	Maximale Schockintensität in Prozent
`message`	Zeichenkette	—	—	Optionale Nachricht, die dem Träger angezeigt wird

hinweis

Die vom Träger konfigurierte Maximalspannung ist immer der feste Grenzwert. Wenn Sie maxIntensityPct: 80 einstellen, der Grenzwert des Trägers aber 50 beträgt, liegt der tatsächliche Maximalwert bei 50 %.

Beispiel:

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`

Aktiviert oder deaktiviert den Berserker-Schockmodus auf dem Gerät des Trägers.

Parameter	Typ	Bereich	Standardwert	Beschreibung
`enabled`	boolesch	—	—	Berserkermodus aktivieren (`true`) oder deaktivieren (`false`)
`message`	Zeichenkette	—	—	Optionale Nachricht, die dem Träger angezeigt wird

Beispiel:

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

Gerätebefehle hängen von der aktiven Sperre, der Geräteverfügbarkeit und der Befehlsrichtlinie ab.

Geräteauswahl

Sie müssen keine Geräte-ID oder keinen Gerätetyp angeben. Jeder Träger kann jeweils nur ein aktives Gerät haben – der Server wählt das richtige Gerät automatisch aus.

In der Antwort wird der Code deviceType zurückgegeben, damit Sie wissen, welches Gerät den Befehl empfangen hat.

Antworten

Erfolg (200)

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

Feld	Beschreibung
`ok`	`true` wenn der Befehl akzeptiert wurde
`command`	Der ausgeführte Befehl
`result.success`	`true` wenn das Gerät den Befehl bestätigt hat
`result.message`	Für Menschen lesbare Statusmeldung
`result.deviceType`	Gerätetyp des Trägers (z. B. `lockink-aa-a1012`, `cellmate-pro-3`)
`active.shock`	Gibt an, ob auf dem Gerät des Trägers aktuell ein Schock aktiv ist
`active.vibration`	Gibt an, ob auf dem Gerät des Trägers aktuell eine Vibration aktiv ist

Hinweis: shock.start und vibration.start warten bis zu 25 Sekunden auf die Empfangsbestätigung des Geräts. Stoppbefehle (shock.stop, vibration.stop, all.stop) werden sofort zurückgegeben.

Versagen

Alle Fehler geben einen HTTP-4xx/5xx-Statuscode mit einem JSON-Body zurück:

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

Szenario	HTTP	`error`	`message`
Schloss nicht gefunden oder kein aktives Schloss	404	`lock_not_found`	`No active lock found`
Sperre nicht mehr aktiv	409	`lock_ended`	`The lock is no longer active`
Fehlende Trägersitzung	400	`no_wearer`	`Missing wearer session`
Fehlender oder ungültiger `durationSeconds`	400	`invalid_params`	`durationSeconds is required for server-initiated shocks`
Zufalls-/Berserker-Modus auf nicht unterstütztem Gerät	400	`unsupported_device`	`Random mode only supported on Lockink AA-A1012`
Nutzer hat keine Schock-Einwilligung erteilt	403	`not_authorized`	`User not eligible for shock commands (consent or device check failed)`
Kein stoß-/vibrationsfähiges Gerät gekoppelt	404	`no_device`	`No shock-capable device found for user`
Gerät ist offline (keine Socket-Verbindung)	404	`device_offline`	`No active device socket found for user`
Gerät hat nicht rechtzeitig bestätigt (25s)	504	`device_timeout`	`Device verification timeout`
Nicht erkannter oder nicht behandelter Fehler	400	`command_failed`	`command_failed`

Sofern verfügbar, wird deviceType in die Antwort aufgenommen.

Häufige Fehlerszenarien erklärt

vorsicht

Das Gerät muss über die mobile App verbunden sein.

Für die Nutzung von Shocks und Vibrationen muss der Träger ein kompatibles Bluetooth-Gerät gekoppelt haben und die Chastify-App muss auf seinem Smartphone aktiv ausgeführt werden. Die App hält die Echtzeit-Socket-Verbindung aufrecht, über die Befehle an das Gerät gesendet werden. Wenn die App geschlossen ist oder keine Internetverbindung besteht, schlagen die Befehle fehl.

no_device – Der Träger hat kein stoßfähiges Gerät (z. B. CellMate Pro 3, Cagink Metal, Lockink AA-A1012) in der Chastify-App gekoppelt. Geräte müssen gekoppelt, aktiv und vollständig konfiguriert sein, bevor die API sie ansprechen kann.

device_offline – Das Gerät des Trägers ist gekoppelt, aber der native Shock-Dienst ist in der Android-App nicht aktiviert oder wird nicht ausgeführt. Dies ist der häufigste Fehler. Der Träger muss den nativen Shock-Dienst in den Einstellungen der Android-App aktivieren, damit Befehle zuverlässig ausgeführt werden.

device_timeout – Der Befehl wurde an die mobile App gesendet, aber die App hat den Empfang durch das Bluetooth-Gerät nicht innerhalb von 25 Sekunden bestätigt. Dies bedeutet in der Regel, dass Bluetooth beim Träger deaktiviert ist, sich das Gerät außerhalb der Reichweite befindet oder ausgeschaltet ist. Geräte mit dem Code Lockink wechseln nach nur 3 Minuten Inaktivität in den Energiesparmodus, sofern die Keep-Alive-Funktion nicht aktiviert ist. Selbst dann können die Akkuoptimierungen des Smartphone-Herstellers die Bluetooth-Nutzung im Hintergrund einschränken und die zuverlässige Funktion von Keep-Alive beeinträchtigen.

not_authorized – Der Träger hat in den Geräteeinstellungen keine explizite Zustimmung zu Schockimpulsen erteilt. Dies ist eine Sicherheitsvorkehrung – selbst bei gekoppelten Geräten muss der Träger die Fernsteuerung von Schock-/Vibrationsimpulsen aktiv aktivieren.

unsupported_device – Die Modi „Zufallsmodus“ und „Berserkermodus“ sind nur auf dem Lockink AA-A1012 (Beesting) verfügbar. Andere Geräte wie CellMate Pro 3 oder Cagink Metal unterstützen diese Modi nicht.

Häufige Fehler

401 missing_token: send Authorization: Bearer YOUR_DEV_TOKEN.
401 invalid_token: Das Token ist falsch oder wurde fehlerhaft kopiert.
401 revoked_token: Der Schlüssel DEV wurde widerrufen.
403 insufficient_scope: Der Schlüssel hat nicht den erforderlichen Gültigkeitsbereich.
409 no_active_lock_session: Der Benutzer hat derzeit keine aktive Sperre.
409 lock_ended: Die aufgelöste Sperre ist nicht mehr aktiv.

info

device_timeout (504) verstehen

Der Fehler device_timeout bedeutet, dass der Server den Schockbefehl an die Android-App des Trägers gesendet hat, die App die Zustellung an das Bluetooth-Gerät jedoch nicht innerhalb von 25 Sekunden bestätigt hat. Dies ist der komplexeste Fehler – Folgendes geschieht auf der Android-Seite:

Server → App: Der Befehl wird über Socket.IO an den nativen Shock-Dienst gesendet, der auf dem Telefon des Trägers ausgeführt wird.
App → Gerät: Die App verbindet sich via Bluetooth Low Energy (BLE) mit dem Gerät und sendet den Schockbefehl. Bei QIUI-Geräten wird dazu zunächst ein Token von der API des Geräteherstellers abgerufen und anschließend der BLE-Befehl gesendet. Bei Lockink-Geräten wird der BLE-Befehl direkt gesendet.
App → Server: Die App sendet eine Bestätigung an den Server zurück.

Die 25-sekündige Zeitüberschreitung beginnt mit Schritt 1. Eine Zeitüberschreitung in Schritt 2 kann aus folgenden Gründen auftreten:

Bluetooth ist deaktiviert oder das Gerät befindet sich außerhalb der Reichweite des Telefons des Trägers.
Der Käfig schläft. Lockink-Geräte wechseln nach nur 3 Minuten Inaktivität im Bluetooth-Modus in den Tiefschlaf. Die Keep-Alive-Funktion kann dies verhindern, jedoch können Akkuoptimierungen der Hersteller (Samsung, Xiaomi, Huawei usw.) Hintergrund-Bluetooth-Verbindungen unterbrechen, wodurch Keep-Alive unzuverlässig wird.
BLE-Verbindung fehlgeschlagen. Die App versucht erneut, eine BLE-Verbindung herzustellen. Wenn das Gerät jedoch nicht reagiert, tritt ein Timeout auf.
Sicherheitssperre. Die App verfügt über ein integriertes Sicherheitssystem, das Stromschläge blockiert, wenn anhand der Aktivitätserkennung und der GPS-Geschwindigkeit festgestellt wird, dass sich der Träger bewegt (z. B. beim Autofahren oder Radfahren). Befindet sich der Träger in Bewegung, wird der Stromschlag stillschweigend blockiert und als fehlgeschlagen gemeldet.
Abruf des QIUI-Tokens fehlgeschlagen. Bei CellMate Pro 3- und Cagink-Geräten muss die App vor dem Senden des BLE-Befehls ein Befehlstoken von der Cloud-API von QIUI abrufen. Wenn das Smartphone des Nutzers keine Internetverbindung hat oder die API von QIUI langsam oder nicht erreichbar ist, kann dieser Schritt den Großteil des 25-Sekunden-Fensters in Anspruch nehmen.

Praktisches Muster

Die meisten externen Programme folgen diesem Ablauf:

Rufe GET /api/apps/v1/session an.
Lies lockData.
Entscheide, was geschehen soll.
Rufen Sie /api/apps/v1/action oder einen der einfacheren Sperrendpunkte auf.
Optional kann ein benutzerdefiniertes Protokoll mit /api/apps/v1/logs/custom geschrieben werden.

Ein Skript kann beispielsweise timeRemainingSeconds überprüfen, eine Zeitangabe hinzufügen, wenn eine Regel fehlschlägt, und anschließend ein benutzerdefiniertes Protokoll schreiben, das erklärt, was passiert ist.

Erstellen Sie ein DEV-Token​

Erster Anruf: Überprüfen Sie das aktuelle Schloss​

Sperrdatenhelfer​

Hauptsperr-Aktionsendpunkte​

Zeit hinzufügen oder entfernen​

Einfrieren und Auftauen​

Allgemeiner Aktionsendpunkt​

Unterstützte Aktionsnamen​

Nützliche Aktionsbeispiele​

Benutzerdefiniertes Sperrprotokoll​

Gerätebefehle​

Anfragekörper​

Unterstützte Befehle und ihre Parameter​

shock.start​

shock.stop​

vibration.start​

vibration.stop​

all.stop​

shock.random.set​

shock.berserk.set​

Geräteauswahl​

Antworten​

Erfolg (200)​

Versagen​

Häufige Fehlerszenarien erklärt​

Häufige Fehler​

Praktisches Muster​

Erstellen Sie ein DEV-Token

Erster Anruf: Überprüfen Sie das aktuelle Schloss

Sperrdatenhelfer

Hauptsperr-Aktionsendpunkte

Zeit hinzufügen oder entfernen

Einfrieren und Auftauen

Allgemeiner Aktionsendpunkt

Unterstützte Aktionsnamen

Nützliche Aktionsbeispiele

Benutzerdefiniertes Sperrprotokoll

Gerätebefehle

Anfragekörper

Unterstützte Befehle und ihre Parameter

`shock.start`

`shock.stop`

`vibration.start`

`vibration.stop`

`all.stop`

`shock.random.set`

`shock.berserk.set`

Geräteauswahl

Antworten

Erfolg (200)

Versagen

Häufige Fehlerszenarien erklärt

Häufige Fehler

Praktisches Muster