API et programmes externes

Utilisez cette page lorsque vous souhaitez qu'un programme externe simple, un script, un serveur local ou un service backend contrôle votre verrou Chastify actuel.

La méthode la plus simple consiste à créer un jeton DEV pour l'ensemble de l'utilisateur, puis à l'envoyer comme jeton porteur aux points de terminaison /api/apps/v1/*.

/api/apps/v1/* est réservé à vos sessions de verrouillage actives. Si vous développez une extension publique utilisée par d'autres utilisateurs de Chastify, utilisez une clé API développeur à portée d'application avec /api/extensions/sessions/:sessionId/* et transmettez l'iframe mainToken dans x-chastify-main-token.

Créer un jeton DEV

1. Ouvrez Chastify.
2. Allez à Developer API.
3. Trouvez User-wide DEV API keys.
4. Créez une clé.
5. Copiez immédiatement le jeton. Il n'est affiché qu'une seule fois.

Utilisez-le dans des requêtes comme celle-ci :

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

jetons DEV :

• ne nécessitent pas la création d'une extension
• ne pas expirer automatiquement
• travail pour votre session de verrouillage active actuelle et vos futures sessions de verrouillage actives
• Indiquez votre rôle sur la serrure active, que vous soyez le porteur ou le détenteur de la clé. Utilisez ce rôle pour indiquer si vous êtes le porteur ou le détenteur de la clé.
• peut être révoquée depuis la page API développeur

Considérez le jeton DEV comme un mot de passe. Toute personne possédant ce jeton peut appeler l'API développeur en votre nom.

Premier appel : Vérifier le verrou actuel

Commencez par :

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

Exemple:

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

Ceci renvoie votre contexte de verrouillage actuel, votre rôle, vos étendues, le temps restant et lockData.

Assistants de données de verrouillage

GET /api/apps/v1/session inclut lockData, conçu pour être facile à lire par les programmes et les moteurs de règles.

Booléens courants :

• frozen
• unlockable
• trusted
• taskAssigned : true lorsque le verrou actif est ouvert TaskRun

Nombres courants :

• timeLockedSeconds
• timeRemainingSeconds
• maxTimeRemainingSeconds
• taskPoints

Chaînes de caractères courantes :

• lockTitle
• champs du profil de l'utilisateur
• champs du profil du titulaire de clés

Note relative à la confidentialité :

• wearerLastSeenTimestamp et keyholderLastSeenTimestamp deviennent null lorsque cet utilisateur a désactivé son statut en ligne.

Points de terminaison d'action de verrouillage principal

Ces points de terminaison sont ceux que la plupart des programmes externes utilisent pour modifier un verrou.

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

Toutes les requêtes utilisent :

Authorization: Bearer YOUR_DEV_TOKEN
Content-Type: application/json

Ajouter ou supprimer de l'heure

Utilisez le point de terminaison de temps simple lorsque vous souhaitez uniquement modifier le temps restant.

Ajoutez 10 minutes :

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

Retirez 5 minutes :

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

Congeler et décongeler

Congeler pendant 30 minutes :

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

Dégeler:

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

Point de terminaison d'action générale

Utiliser:

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

Morphologie :

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

Exemple:

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

Noms d'actions pris en charge

name prend en charge :

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

Contraintes d'action :

• Les actions liées aux tâches nécessitent l'activation du module Tâches sur le verrou.
• hygienic_unlock.start nécessite que l'ouverture hygiénique soit activée et qu'aucune session d'hygiène ne soit active.
• Les commandes de l'appareil nécessitent un appareil connecté compatible et des autorisations.

Exemples d'actions utiles

Retirez 15 minutes :

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

Congeler pendant 5 minutes :

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

Activer/désactiver le gel :

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

Attribuer une tâche :

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

Cela crée un code TaskRun pour le verrou actif. Si une autre tâche est déjà en cours d'exécution, l'implémentation actuelle annule l'exécution en cours et en crée une nouvelle.

Démarrer le minuteur de la tâche active :

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

Terminez la tâche active :

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

Ceci complète la dernière ouverture TaskRun pour le verrou actif.

Démarrez un déconfinement hygiénique :

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

Fin du pilori actif :

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

Journal de verrouillage personnalisé

Utilisez cette fonction lorsque votre programme a effectué une action et que vous souhaitez la voir visible dans l'historique des verrous.

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

Exemple:

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

Champs du corps :

• title : requis
• description : optionnel
• role : extension, wearer ou keyholder
• icon : optionnel
• color : couleur hexadécimale optionnelle, par exemple #ffcc00

Commandes de l'appareil

Les commandes de l'appareil permettent de déclencher des chocs et des vibrations sur l'appareil connecté de l'utilisateur.

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

Fonctionne avec votre jeton DEV — aucun identifiant de session n’est requis. Le serveur associe automatiquement le verrou et le porteur à partir de votre jeton.

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

Corps de la requête

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

• command (chaîne de caractères, obligatoire) — la commande du périphérique à exécuter.
• params (objet, facultatif) — paramètres spécifiques à la commande (voir ci-dessous).

Commandes prises en charge et leurs paramètres

shock.start

Déclenche une décharge électrique sur l'appareil de l'utilisateur.

Paramètre	Type	Plage	Valeur par défaut	Description
intensityPct	nombre	1–100	50	Shock intensité en pourcentage
durationSeconds	nombre	1–300	60	Shock durée en secondes
message	chaîne	—	—	Message optionnel affiché à celui qui le porte

remarque

La tension maximale configurée pour l'utilisateur est toujours appliquée comme une limite stricte, quelle que soit la valeur envoyée. Pour les appareils Lockink, il s'agit de la limite de tension par appareil. Pour les appareils QIUI, il s'agit du paramètre shockVolt (échelle de 1 à 4). Si vous envoyez intensityPct: 80 alors que la limite de l'utilisateur est de 50 %, l'appareil ne fournira que 50 % de sa capacité.

Exemple:

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

Interrompt tous les chocs actifs sur l'appareil de l'utilisateur. Aucun paramètre requis.

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

Déclenche une vibration sur l'appareil de l'utilisateur.

Paramètre	Type	Plage	Valeur par défaut	Description
intensityPct	nombre	1–100	50	Intensité de vibration en pourcentage
durationSeconds	numéro	1–300	30	Durée de vibration en secondes
frequencyPct	nombre	1–100	50	Fréquence de vibration en pourcentage
message	chaîne	—	—	Message optionnel affiché à celui qui le porte

Exemple:

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

Arrête toutes les vibrations actives. Aucun paramètre requis.

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

Arrête toute activité de l'appareil (chocs, vibrations, etc.). Aucun paramètre requis.

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

Active ou désactive le mode de choc aléatoire sur l'appareil de l'utilisateur.

Paramètre	Type	Plage	Valeur par défaut	Description
enabled	booléen	—	—	Activer (true) ou désactiver (false) le mode aléatoire
minIntensityPct	nombre	1–100	20	Pourcentage d'intensité de choc minimale
maxIntensityPct	nombre	1–100	80	Pourcentage d'intensité de choc maximale
message	chaîne	—	—	Message optionnel affiché à celui qui le porte

remarque

La tension maximale configurée pour l'utilisateur correspond toujours à la limite maximale admissible. Si vous définissez maxIntensityPct: 80 mais que la limite de l'utilisateur est de 50, la tension maximale réelle sera de 50 %.

Exemple:

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

Active ou désactive le mode choc berserk sur l'appareil de l'utilisateur.

Paramètre	Type	Plage	Valeur par défaut	Description
enabled	booléen	—	—	Activer (true) ou désactiver (false) le mode berserk
message	chaîne	—	—	Message optionnel affiché à celui qui le porte

Exemple:

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

Les commandes du périphérique dépendent du verrou actif, de la disponibilité du périphérique et de la politique de commande.

Sélection de l'appareil

Il n'est pas nécessaire de spécifier un identifiant ou un type d'appareil. Chaque utilisateur ne peut avoir qu'un seul appareil actif à la fois ; le serveur le sélectionne automatiquement.

Le code deviceType est renvoyé dans la réponse afin que vous sachiez quel appareil a reçu la commande.

Réponses

Succès (200)

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

Champ	Description
ok	true lorsque la commande a été acceptée
command	La commande exécutée
result.success	true si l'appareil a confirmé la commande
result.message	Message d'état lisible par l'homme
result.deviceType	Type d'appareil de l'utilisateur (ex. : lockink-aa-a1012, cellmate-pro-3)
active.shock	Indique si un choc est actuellement actif sur l'appareil de l'utilisateur
active.vibration	Indique si une vibration est actuellement active sur l'appareil de l'utilisateur

Remarque : Les commandes shock.start et vibration.start nécessitent un délai de 25 secondes maximum pour que l’appareil confirme la réception. Les commandes d’arrêt (shock.stop, vibration.stop, all.stop) sont exécutées immédiatement.

Échec

Toutes les erreurs renvoient un code HTTP 4xx/5xx avec un corps JSON :

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

Scénario	HTTP	error	message
Verrou introuvable ou aucun verrou actif	404	lock_not_found	No active lock found
Le verrou n'est plus actif	409	lock_ended	The lock is no longer active
Session du porteur manquante	400	no_wearer	Missing wearer session
durationSeconds manquant ou invalide	400	invalid_params	durationSeconds is required for server-initiated shocks
Mode aléatoire/berserk sur un appareil non pris en charge	400	unsupported_device	Random mode only supported on Lockink AA-A1012
L'utilisateur n'a pas autorisé les chocs électriques	403	not_authorized	User not eligible for shock commands (consent or device check failed)
Aucun appareil sensible aux chocs/vibrations n'a été associé	404	no_device	No shock-capable device found for user
Appareil hors ligne (aucune connexion socket)	404	device_offline	No active device socket found for user
L'appareil n'a pas confirmé à temps (25 s)	504	device_timeout	Device verification timeout
Panne non reconnue ou non gérée	400	command_failed	command_failed

Lorsque disponible, deviceType est inclus dans la réponse.

Explication des scénarios de défaillance courants

attention

L'appareil doit être connecté via l'application mobile.

Le Shock et ses vibrations nécessitent que l'utilisateur dispose d'un appareil Bluetooth compatible connecté et que l'application mobile Chastify soit ouverte sur son téléphone. L'application maintient la connexion socket en temps réel qui transmet les commandes à l'appareil. Si l'application est fermée ou si le téléphone n'est pas connecté à Internet, les commandes ne fonctionneront pas.

no_device — L'utilisateur n'a pas jumelé d'appareil résistant aux chocs (par exemple, CellMate Pro 3, Cagink Metal, Lockink AA-A1012) dans l'application Chastify. Les appareils doivent être jumelés, actifs et entièrement configurés pour que l'API puisse les cibler.

device_offline — L'appareil de l'utilisateur est jumelé, mais le service natif Shock n'est pas activé ou n'est pas en cours d'exécution dans l'application Android. Il s'agit de la panne la plus fréquente : l'utilisateur doit activer le service natif Shock dans les paramètres de l'application Android pour que les commandes soient transmises correctement.

device_timeout — La commande a été envoyée à l'application mobile, mais celle-ci n'a pas confirmé sa réception par l'appareil Bluetooth dans les 25 secondes. Cela signifie généralement que le Bluetooth de l'utilisateur est désactivé, que l'appareil est hors de portée ou qu'il est éteint. Les appareils Lockink se mettent en veille après seulement 3 minutes d'inactivité, sauf si la fonction de maintien de la connexion est activée. Même dans ce cas, les optimisations de la batterie du fabricant du téléphone peuvent limiter l'activité Bluetooth en arrière-plan et empêcher le bon fonctionnement de cette fonction.

not_authorized — L’utilisateur n’a pas explicitement autorisé les chocs électriques dans les paramètres de son appareil. Il s’agit d’une mesure de sécurité : même avec un appareil connecté, l’utilisateur doit autoriser les commandes de choc/vibration à distance.

unsupported_device — Les modes aléatoire et frénétique sont uniquement disponibles sur le Lockink AA-A1012 (Beesting). D'autres appareils comme le CellMate Pro 3 ou le Cagink Metal ne prennent pas en charge ces modes.

Erreurs courantes

• 401 missing_token : envoyer Authorization: Bearer YOUR_DEV_TOKEN.
• 401 invalid_token : le jeton est incorrect ou a été copié incorrectement.
• 401 revoked_token : la clé DEV a été révoquée.
• 403 insufficient_scope : la clé n’a pas la portée requise.
• 409 no_active_lock_session : l’utilisateur ne possède actuellement aucun verrou actif.
• 409 lock_ended : le verrou résolu n’est plus actif.

info

Comprendre device_timeout (504)

L'erreur device_timeout signifie que le serveur a envoyé la commande de choc à l'application Android de l'utilisateur, mais que celle-ci n'a pas confirmé la réception sur l'appareil Bluetooth dans les 25 secondes. Il s'agit de l'erreur la plus complexe ; voici ce qui se passe du côté du Android :

1. Serveur → App : La commande transite via Socket.IO vers le service natif Shock exécuté sur le téléphone de l'utilisateur.
2. Application → Appareil : L’application se connecte à l’appareil via Bluetooth Low Energy (BLE) et envoie la commande de choc. Pour les appareils QIUI, cela implique d’abord de récupérer un jeton auprès de l’API du fabricant, puis d’envoyer la commande BLE. Pour les appareils Lockink, la commande BLE est envoyée directement.
3. App → Serveur : L’application renvoie une confirmation au serveur.

Le délai d'attente de 25 secondes commence à l'étape 1. Un délai d'attente à l'étape 2 peut survenir pour les raisons suivantes :

• Le Bluetooth est désactivé ou l'appareil est hors de portée du téléphone de l'utilisateur.
• Le boîtier est en veille. Les appareils Lockink passent en veille profonde après seulement 3 minutes d'inactivité BLE. La fonction de maintien de la connexion peut empêcher cela, mais les optimisations de batterie des fabricants (Samsung, Xiaomi, Huawei, etc.) peuvent interrompre les connexions Bluetooth en arrière-plan, rendant ainsi le maintien de la connexion peu fiable.
• Échec de la connexion BLE. L'application tente de rétablir la connexion BLE, mais si l'appareil ne répond pas, la connexion expire.
• Blocage de sécurité. L'application intègre un système de sécurité qui bloque les chocs électriques si l'utilisateur est en mouvement (par exemple, en voiture ou à vélo), grâce à la reconnaissance d'activité et à la vitesse GPS. Si l'utilisateur est en mouvement, le choc est bloqué silencieusement et signalé comme ayant échoué.
• Échec de la récupération du jeton QIUI. Pour les appareils CellMate Pro 3 et Cagink, l'application doit récupérer un jeton de commande auprès de l'API cloud de QIUI avant d'envoyer la commande BLE. Si le téléphone de l'utilisateur n'a pas de connexion Internet ou si l'API de QIUI est lente ou inaccessible, cette étape peut consommer la majeure partie du délai de 25 secondes.

Modèle pratique

La plupart des programmes externes suivent ce flux :

1. Appelez GET /api/apps/v1/session.
2. Lire lockData.
3. Décidez de ce qui doit se passer.
4. Appelez /api/apps/v1/action ou l'un des points de terminaison de verrouillage plus simples.
5. Écrire éventuellement un journal personnalisé avec /api/apps/v1/logs/custom.

Par exemple, un script peut vérifier timeRemainingSeconds, ajouter du temps lorsqu'une règle échoue, puis écrire un journal personnalisé expliquant ce qui s'est passé.