API e programmi esterni

Utilizza questa pagina se desideri un semplice programma esterno, script, server locale o servizio backend per controllare la tua serratura Chastify.

Il modo più semplice è creare un token DEV valido per tutto l'utente, quindi inviarlo come token bearer agli endpoint /api/apps/v1/*.

/api/apps/v1/* è valido solo per le tue sessioni di blocco attive. Se stai creando un'estensione pubblica utilizzata da altri utenti Chastify, usa una chiave API per sviluppatori con ambito app con /api/extensions/sessions/:sessionId/* e passa l'iframe mainToken in x-chastify-main-token.

Crea un token DEV

1. Apri Chastify.
2. Vai a Developer API.
3. Trova User-wide DEV API keys.
4. Crea una chiave.
5. Copia subito il token. Viene mostrato una sola volta.

Utilizzalo in richieste come questa:

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

Token DEV:

• non richiedono la creazione di un'estensione
• non scadono automaticamente
• funziona per il tuo blocco attivo attuale e per le future sessioni di blocco attivo
• Utilizza il tuo ruolo sulla serratura attiva, sia che tu la indossi o che tu sia il detentore della chiave.
• può essere revocato dalla pagina API per sviluppatori

Considera il token DEV come una password. Chiunque sia in possesso del token può chiamare l'API per sviluppatori con il tuo nome.

Prima chiamata: Controlla la serratura attuale

Inizia con:

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

Esempio:

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

Questo restituisce il contesto di blocco corrente, il ruolo, gli ambiti, il tempo rimanente e lockData.

Strumenti di supporto per i dati di blocco

GET /api/apps/v1/session include lockData, progettato per essere facilmente leggibile da programmi e motori di regole.

Valori booleani comuni:

• frozen
• unlockable
• trusted
• taskAssigned: true quando la serratura attiva ha un TaskRun aperto

Numeri comuni:

• timeLockedSeconds
• timeRemainingSeconds
• maxTimeRemainingSeconds
• taskPoints

Stringhe comuni:

• lockTitle
• campi del profilo dell'utilizzatore
• campi del profilo del responsabile

Informativa sulla privacy:

• wearerLastSeenTimestamp e keyholderLastSeenTimestamp diventano null quando l'utente ha disabilitato lo stato online.

Punti finali dell'azione di blocco principale

Questi endpoint sono quelli che la maggior parte dei programmi esterni utilizza per modificare un blocco.

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

Tutte le richieste utilizzano:

Authorization: Bearer YOUR_DEV_TOKEN
Content-Type: application/json

Aggiungi o rimuovi tempo

Utilizza l'endpoint temporale semplice quando desideri modificare solo il tempo rimanente.

Aggiungi 10 minuti:

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

Togli 5 minuti:

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

Congelare e scongelare

Congelare per 30 minuti:

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

Scongelare:

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

Punto finale dell'azione generale

Utilizzo:

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

Forma del corpo:

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

Esempio:

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

Nomi delle azioni supportate

name supporta:

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

Vincoli di azione:

• Le azioni relative alle attività richiedono che il modulo Attività sia abilitato sulla serratura.
• hygienic_unlock.start richiede che l'apertura igienica sia abilitata e che non sia presente alcuna sessione igienica attiva.
• I comandi del dispositivo richiedono un dispositivo connesso supportato e le relative autorizzazioni.

Esempi di azioni utili

Togli 15 minuti:

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

Congelare per 5 minuti:

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

Attiva/disattiva il blocco schermo:

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

Assegna un compito:

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

Questo crea un codice TaskRun per il blocco attivo. Se è già aperta un'altra esecuzione di attività, l'implementazione corrente annulla la vecchia esecuzione aperta e ne crea una nuova.

Avvia il timer dell'attività attiva:

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

Completa l'attività attiva:

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

Questo completa l'ultimo TaskRun aperto per la serratura attiva.

Avvia uno sblocco igienico:

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

Fine della gogna attiva:

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

Registro di blocco personalizzato

Utilizza questa opzione quando il tuo programma ha eseguito un'azione e desideri che sia visibile nella cronologia dei blocchi.

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

Esempio:

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

Campi del corpo:

• title: obbligatorio
• ZZQCODE0ZXQ: facoltativo
• role: extension, wearer o keyholder
• ZZQCODE0ZXQ: facoltativo
• color: colore esadecimale opzionale, ad esempio #ffcc00

Comandi del dispositivo

I comandi del dispositivo consentono di attivare scosse e vibrazioni sul dispositivo connesso indossato dall'utente.

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

Funziona con il tuo token DEV: non è necessario un ID di sessione. Il server identifica automaticamente il lucchetto e chi lo indossa tramite il tuo 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}}'

Corpo della richiesta

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

• command (stringa, obbligatorio) — il comando del dispositivo da eseguire.
• params (oggetto, facoltativo) — parametri specifici del comando (vedi sotto).

Comandi supportati e relativi parametri

shock.start

Avvia una scossa sul dispositivo di chi lo indossa.

Parametro	Tipo	Intervallo	Valore predefinito	Descrizione
intensityPct	numero	1–100	50	Shock intensità in percentuale
durationSeconds	numero	1–300	60	Shock durata in secondi
message	stringa	—	—	Messaggio opzionale mostrato a chi lo indossa

note

La tensione massima configurata per chi indossa il dispositivo viene sempre imposta come limite massimo, indipendentemente dal valore inviato. Per i dispositivi Lockink, questo è il limite di tensione per dispositivo. Per i dispositivi QIUI, questo è l'impostazione shockVolt (scala da 1 a 4). Se si invia intensityPct: 80 ma il limite impostato per chi indossa il dispositivo è del 50%, il dispositivo erogherà solo il 50%.

Esempio:

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

Blocca tutte le scosse attive sul dispositivo di chi lo indossa. Nessun parametro richiesto.

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

Avvia una vibrazione sul dispositivo di chi lo indossa.

Parametro	Tipo	Intervallo	Valore predefinito	Descrizione
intensityPct	numero	1–100	50	Intensità di vibrazione in percentuale
durationSeconds	numero	1–300	30	Durata della vibrazione in secondi
frequencyPct	numero	1–100	50	Frequenza di vibrazione in percentuale
message	stringa	—	—	Messaggio opzionale mostrato a chi lo indossa

Esempio:

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

Blocca tutte le vibrazioni attive. Non sono richiesti parametri.

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

Interrompe tutte le attività del dispositivo (urti, vibrazioni, ecc.). Non sono richiesti parametri.

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

Consente o disattiva la modalità di scossa casuale sul dispositivo dell'utilizzatore.

Parametro	Tipo	Intervallo	Valore predefinito	Descrizione
enabled	booleano	—	—	Abilita (true) o disabilita (false) la modalità casuale
minIntensityPct	numero	1–100	20	Percentuale di intensità minima dello shock
maxIntensityPct	numero	1–100	80	Percentuale di intensità massima della scossa
message	stringa	—	—	Messaggio opzionale mostrato a chi lo indossa

note

La tensione massima configurata per chi indossa il dispositivo è sempre il limite massimo. Se si imposta maxIntensityPct: 80 ma il limite per chi indossa il dispositivo è 50, il valore massimo effettivo sarà del 50%.

Esempio:

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

Attiva o disattiva la modalità di shock berserk sul dispositivo di chi lo indossa.

Parametro	Tipo	Intervallo	Valore predefinito	Descrizione
enabled	booleano	—	—	Abilita (true) o disabilita (false) la modalità berserk
message	stringa	—	—	Messaggio opzionale mostrato a chi lo indossa

Esempio:

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

I comandi del dispositivo dipendono dalla serratura attiva, dalla disponibilità del dispositivo e dalla politica dei comandi.

Selezione del dispositivo

Non è necessario specificare un ID dispositivo o un tipo di dispositivo. Ogni utente può avere un solo dispositivo attivo alla volta: il server lo individua automaticamente.

Il codice deviceType viene restituito nella risposta, in modo da poter identificare il dispositivo che ha ricevuto il comando.

Risposte

Successo (200)

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

Campo	Descrizione
ok	true quando il comando è stato accettato
command	Il comando eseguito
result.success	true se il dispositivo ha confermato il comando
result.message	Messaggio di stato leggibile dall'uomo
result.deviceType	Tipo di dispositivo dell'utilizzatore (ad es. lockink-aa-a1012, cellmate-pro-3)
active.shock	Indica se una scarica elettrica è attualmente attiva sul dispositivo dell'utilizzatore
active.vibration	Indica se la vibrazione è attualmente attiva sul dispositivo dell'utente

Nota: shock.start e vibration.start attendono fino a 25 secondi affinché il dispositivo confermi la ricezione. I comandi di arresto (shock.stop, vibration.stop, all.stop) vengono restituiti immediatamente.

Fallimento

Tutti gli errori restituiscono HTTP 4xx/5xx con un corpo JSON:

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

Scenario	HTTP	error	message
Lucchetto non trovato o nessun lucchetto attivo	404	lock_not_found	No active lock found
Il blocco non è più attivo	409	lock_ended	The lock is no longer active
Sessione utente mancante	400	no_wearer	Missing wearer session
durationSeconds mancante o non valido	400	invalid_params	durationSeconds is required for server-initiated shocks
Modalità casuale/berserk su dispositivo non supportato	400	unsupported_device	Random mode only supported on Lockink AA-A1012
L'utente non ha concesso il consenso per le scosse elettriche	403	not_authorized	User not eligible for shock commands (consent or device check failed)
Nessun dispositivo compatibile con urti/vibrazioni associato	404	no_device	No shock-capable device found for user
Il dispositivo è offline (nessuna connessione socket)	404	device_offline	No active device socket found for user
Il dispositivo non ha confermato in tempo (25 secondi)	504	device_timeout	Device verification timeout
Errore non riconosciuto o non gestito	400	command_failed	command_failed

Quando disponibile, il codice deviceType è incluso nella risposta.

Spiegazione dei casi di guasto più comuni.

attenzione

Il dispositivo deve essere connesso tramite l'app mobile.

Il dispositivo Shock e le sue vibrazioni richiedono che chi lo indossa abbia un dispositivo Bluetooth compatibile associato e l'app mobile Chastify in esecuzione sul proprio telefono. L'app mantiene la connessione in tempo reale che invia i comandi al dispositivo. Se l'app è chiusa o il telefono non ha connessione a Internet, i comandi non funzioneranno.

no_device — Chi indossa il dispositivo non ha associato un dispositivo compatibile con gli shock (ad esempio CellMate Pro 3, Cagink Metal, Lockink AA-A1012) nell'app Chastify. I dispositivi devono essere associati, attivi e completamente configurati prima che l'API possa utilizzarli.

device_offline — Il dispositivo dell'utente è associato, ma il Servizio nativo Shock non è abilitato o non è in esecuzione sull'app Android. Questo è l'errore più comune: l'utente deve abilitare il Servizio nativo Shock nelle impostazioni dell'app Android affinché i comandi vengano inviati correttamente.

device_timeout — Il comando è stato inviato all'app mobile, ma l'app non ha confermato la ricezione da parte del dispositivo Bluetooth entro 25 secondi. Questo di solito significa che il Bluetooth del dispositivo indossato è disattivato, il dispositivo è fuori portata o è spento. I dispositivi Lockink vanno in modalità di sospensione dopo soli 3 minuti di inattività, a meno che non sia abilitata la funzione keep-alive; anche in questo caso, le ottimizzazioni della batteria del produttore del telefono potrebbero limitare il Bluetooth in background e impedire il corretto funzionamento del keep-alive.

not_authorized — Chi indossa il dispositivo non ha dato esplicitamente il consenso all'attivazione della vibrazione/scossa elettrica nelle impostazioni del dispositivo stesso. Si tratta di un requisito di sicurezza: anche con un dispositivo associato, chi lo indossa deve autorizzare l'attivazione remota dei comandi di vibrazione/scossa elettrica.

unsupported_device — Le modalità casuale e berserk sono disponibili solo su Lockink AA-A1012 (Beesting). Altri dispositivi come CellMate Pro 3 o Cagink Metal non supportano queste modalità.

Errori comuni

• 401 missing_token: invia Authorization: Bearer YOUR_DEV_TOKEN.
• 401 invalid_token: il token non è corretto o è stato copiato in modo errato.
• 401 revoked_token: la chiave DEV è stata revocata.
• 403 insufficient_scope: la chiave non ha l'ambito richiesto.
• 409 no_active_lock_session: l'utente al momento non ha un lucchetto attivo.
• 409 lock_ended: il blocco risolto non è più attivo.

informazioni

Comprensione di device_timeout (504)

L'errore device_timeout indica che il server ha inviato il comando di scossa all'app Android dell'utente, ma l'app non ha confermato la ricezione al dispositivo Bluetooth entro 25 secondi. Questo è l'errore più complesso: ecco cosa succede dal lato Android:

1. Server → App: Il comando viaggia tramite Socket.IO al servizio nativo Shock in esecuzione sul telefono di chi lo indossa.
2. App → Dispositivo: L'app si connette al dispositivo tramite Bluetooth Low Energy (BLE) e invia il comando di scossa. Per i dispositivi QIUI, ciò comporta prima il recupero di un token dall'API del produttore del dispositivo, quindi l'invio del comando BLE. Per i dispositivi Lockink, il comando BLE viene inviato direttamente.
3. App → Server: L'app invia una conferma al server.

Il timeout di 25 secondi inizia al passaggio 1. Un timeout al passaggio 2 può verificarsi per i seguenti motivi:

• Il Bluetooth è disattivato oppure il dispositivo è fuori dalla portata del telefono di chi lo indossa.
• La gabbia è in modalità di sospensione. I dispositivi Lockink entrano in modalità di sospensione profonda dopo soli 3 minuti di inattività BLE. La funzione keep-alive può impedirlo, ma le ottimizzazioni della batteria dei produttori (Samsung, Xiaomi, Huawei, ecc.) potrebbero interrompere le connessioni Bluetooth in background, rendendo il keep-alive inaffidabile.
• Connessione BLE non riuscita. L'app tenta di ristabilire la connessione BLE, ma se il dispositivo non risponde, la connessione va in timeout.
• Blocco di sicurezza. L'app è dotata di un sistema di sicurezza integrato che blocca le scosse elettriche se viene rilevato un movimento dell'utente (ad esempio, alla guida o in bicicletta) in base al riconoscimento dell'attività e alla velocità GPS. Se l'utente è in movimento, la scossa viene bloccata silenziosamente e segnalata come fallita.
• Recupero del token QIUI non riuscito. Per i dispositivi CellMate Pro 3 e Cagink, l'app deve recuperare un token di comando dall'API cloud di QIUI prima di inviare il comando BLE. Se il telefono dell'utente non ha accesso a Internet o l'API di QIUI è lenta/irraggiungibile, questo passaggio può consumare la maggior parte dei 25 secondi disponibili.

Modello pratico

La maggior parte dei programmi esterni segue questo flusso:

1. Chiama GET /api/apps/v1/session.
2. Leggi lockData.
3. Decidi cosa deve succedere.
4. Chiama /api/apps/v1/action o uno degli endpoint di blocco più semplici.
5. Facoltativamente, è possibile scrivere un log personalizzato con /api/apps/v1/logs/custom.

Ad esempio, uno script può controllare timeRemainingSeconds, aggiungere un intervallo di tempo quando una regola fallisce e quindi scrivere un log personalizzato che spieghi cosa è successo.