Externt API och program

Använd den här sidan när du vill att ett enkelt externt program, skript, lokal server eller backend-tjänst ska styra ditt nuvarande Chastify-lås.

Det enklaste sättet är att skapa en användaromfattande DEV-token och sedan skicka den som en bärartoken till /api/apps/v1/*-slutpunkterna.

/api/apps/v1/* är endast för dina egna aktiva låssessioner. Om du bygger ett offentligt tillägg som används av andra Chastify-användare, använd en app-scoped Developer API-nyckel med /api/extensions/sessions/:sessionId/* och skicka iframe-filen mainToken i x-chastify-main-token.

Skapa en DEV-token

Öppna Chastify.
Gå till Developer API.
Hitta User-wide DEV API keys.
Skapa en nyckel.
Kopiera tokenet omedelbart. Det visas bara en gång.

Använd det i förfrågningar som denna:

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

DEV-tokens:

kräver inte att man skapar en tilläggsfil
upphör inte automatiskt
fungerar för ditt nuvarande aktiva lås och framtida aktiva låssessioner
Använd din roll på det aktiva låset, antingen bärare eller nyckelinnehavare
kan återkallas från sidan för utvecklar-API:et

Behandla en DEV-token som ett lösenord. Vem som helst med token kan anropa Developer API:et som du.

Första samtalet: Kontrollera det aktuella låset

Börja med:

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

Exempel:

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

Detta returnerar din nuvarande låskontext, roll, omfattningar, återstående tid och lockData.

Lås datahjälpare

GET /api/apps/v1/session inkluderar lockData, som är utformad för att vara enkel för program och regelmotorer att läsa.

Vanliga booleska värden:

frozen
unlockable
trusted
taskAssigned: true när det aktiva låset har ett öppet TaskRun

Vanliga nummer:

timeLockedSeconds
timeRemainingSeconds
maxTimeRemainingSeconds
taskPoints

Vanliga strängar:

lockTitle
bärarprofilfält
fält för nyckelhållarprofil

Integritetsmeddelande:

wearerLastSeenTimestamp och keyholderLastSeenTimestamp är null när användaren har inaktiverat onlinestatus.

Huvudlåsåtgärdens slutpunkter

Dessa slutpunkter är de som de flesta externa program använder för att ändra ett 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

Alla förfrågningar använder:

Authorization: Bearer YOUR_DEV_TOKEN
Content-Type: application/json

Lägg till eller ta bort tid

Använd den enkla tidsslutpunkten när du bara vill ändra återstående tid.

Lägg till 10 minuter:

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

Ta bort 5 minuter:

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 och tina upp

Frys in i 30 minuter:

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

Tina upp:

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

Allmän åtgärdsslutpunkt

Använda:

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

Kroppsform:

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

Exempel:

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

Namn på åtgärder som stöds

name stöder:

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

Åtgärdsbegränsningar:

Uppgiftsåtgärder kräver att modulen Uppgifter är aktiverad på låset.
hygienic_unlock.start kräver att Hygienisk öppning är aktiverad och att ingen hygiensession är aktiv.
Enhetskommandon kräver en ansluten enhet och behörigheter som stöds.

Användbara exempel på åtgärder

Ta bort 15 minuter:

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

Frys in i 5 minuter:

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

Växla frysning:

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

Tilldela en uppgift:

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

Detta skapar en TaskRun för det aktiva låset. Om en annan uppgiftskörning redan är öppen avbryter den aktuella implementeringen den gamla öppna körningen och skapar en ny.

Starta den aktiva uppgiftstimern:

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

Slutför den aktiva uppgiften:

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

Detta slutför den senaste öppna TaskRun för det aktiva låset.

Starta en hygienisk upplåsning:

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

Slut på aktiv skampåle:

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

Anpassad låslogg

Använd detta när ditt program gjorde något och du vill att det ska synas i låshistoriken.

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

Exempel:

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

Kroppsfält:

title: obligatorisk
description: valfritt
role: extension, wearer eller keyholder
icon: valfritt
color: valfri hexagonalfärg, till exempel #ffcc00

Enhetskommandon

Med enhetskommandon kan du utlösa stötar och vibrationer på bärarens anslutna enhet.

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

Fungerar med din DEV-token — inget sessions-ID behövs. Servern identifierar automatiskt låset och bäraren från din 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}}'

Begäran

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

command (sträng, obligatorisk) — enhetskommandot som ska köras.
params (objekt, valfritt) — kommandospecifika parametrar (se nedan).

Stödda kommandon och deras parametrar

`shock.start`

Startar en stöt på bärarens enhet.

Parameter	Typ	Intervall	Standard	Beskrivning
`intensityPct`	antal	1–100	50	Shock intensitet i procent
`durationSeconds`	nummer	1–300	60	Shock varaktighet i sekunder
`message`	sträng	—	—	Valfritt meddelande som visas för bäraren

anteckning

Bärarens konfigurerade maxspänning tillämpas alltid som en hård gräns, oavsett vad du skickar. För Lockink-enheter är detta spänningsgränsen per enhet. För QIUI-enheter är detta inställningen shockVolt (skala 1–4). Om du skickar intensityPct: 80 men bärarens gräns är 50 %, kommer enheten bara att leverera 50 %.

Exempel:

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`

Stoppar alla aktiva stötar på bärarens enhet. Inga parametrar krävs.

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`

Startar en vibration på bärarens enhet.

Parameter	Typ	Intervall	Standard	Beskrivning
`intensityPct`	nummer	1–100	50	Vibrationsintensitet i procent
`durationSeconds`	nummer	1–300	30	Vibrationsvaraktighet i sekunder
`frequencyPct`	nummer	1–100	50	Vibrationsfrekvens i procent
`message`	sträng	—	—	Valfritt meddelande som visas för bäraren

Exempel:

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`

Stoppar alla aktiva vibrationer. Inga parametrar krävs.

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`

Stoppar all enhetsaktivitet (stötar, vibrationer etc.). Inga parametrar krävs.

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`

Aktiverar eller inaktiverar slumpmässigt stötläge på bärarens enhet.

Parameter	Typ	Intervall	Standard	Beskrivning
`enabled`	booleskt	—	—	Aktivera (`true`) eller inaktivera (`false`) slumpmässigt läge
`minIntensityPct`	nummer	1–100	20	Lägsta stötintensitet i procent
`maxIntensityPct`	nummer	1–100	80	Maximal stötintensitet i procent
`message`	sträng	—	—	Valfritt meddelande som visas för bäraren

anteckning

Bärarens konfigurerade maxspänning är alltid den hårda kåpan. Om du ställer in maxIntensityPct: 80 men bärarens gräns är 50, kommer det faktiska maximumet att vara 50 %.

Exempel:

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`

Aktiverar eller inaktiverar berserkchock-läget på bärarens enhet.

Parameter	Typ	Intervall	Standard	Beskrivning
`enabled`	booleskt värde	—	—	Aktivera (`true`) eller inaktivera (`false`) berserkläge
`message`	sträng	—	—	Valfritt meddelande som visas för bäraren

Exempel:

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

Enhetskommandon beror på det aktiva låset, enhetens tillgänglighet och kommandopolicyn.

Enhetsval

Du behöver inte ange ett enhets-ID eller en enhetstyp. Varje bärare kan bara ha en aktiv enhet åt gången – servern riktar in sig på den automatiskt.

deviceType returneras i svaret så att du vet vilken enhet som tog emot kommandot.

Svar

Framgång (200)

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

Fält	Beskrivning
`ok`	`true` när kommandot accepterades
`command`	Kommandot som kördes
`result.success`	`true` om enheten bekräftade kommandot
`result.message`	Läsbart statusmeddelande
`result.deviceType`	Bärarens enhetstyp (t.ex. `lockink-aa-a1012`, `cellmate-pro-3`)
`active.shock`	Om en stöt för närvarande är aktiv på bärarens enhet
`active.vibration`	Om en vibration för närvarande är aktiv på bärarens enhet

Obs! shock.start och vibration.start väntar upp till 25 sekunder på att enheten ska bekräfta mottagandet. Stoppkommandona (shock.stop, vibration.stop, all.stop) returneras omedelbart.

Fel

Alla fel returnerar HTTP 4xx/5xx med en JSON-kropp:

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

Scenario	HTTP	`error`	`message`
Låset hittades inte eller inget aktivt lås	404	`lock_not_found`	`No active lock found`
Låset är inte längre aktivt	409	`lock_ended`	`The lock is no longer active`
Saknad bärarsession	400	`no_wearer`	`Missing wearer session`
Saknas eller är ogiltig `durationSeconds`	400	`invalid_params`	`durationSeconds is required for server-initiated shocks`
Slumpmässigt/berserk-läge på enhet som inte stöds	400	`unsupported_device`	`Random mode only supported on Lockink AA-A1012`
Användaren har inte gett sitt samtycke till chock	403	`not_authorized`	`User not eligible for shock commands (consent or device check failed)`
Ingen stöt-/vibrationskapabel enhet ihopparad	404	`no_device`	`No shock-capable device found for user`
Enheten är offline (ingen socket-anslutning)	404	`device_offline`	`No active device socket found for user`
Enheten bekräftade inte inom 25 sekunder	504	`device_timeout`	`Device verification timeout`
Okänt eller ohanterat fel	400	`command_failed`	`command_failed`

När det är tillgängligt inkluderas deviceType i svaret.

Vanliga felscenarier förklarade

varning

Enheten måste vara ansluten via mobilappen

Stötar och vibrationer kräver att bäraren har en kompatibel Bluetooth-enhet ihopparad och att Chastify-mobilappen aktivt körs på sin telefon. Appen upprätthåller realtidsanslutningen som levererar kommandon till enheten. Om appen är stängd eller telefonen inte har internet kommer kommandona att misslyckas.

no_device — Bäraren har inte parat ihop en stötkompatibel enhet (t.ex. CellMate Pro 3, Cagink Metal, Lockink AA-A1012) i Chastify-appen. Enheterna måste vara parade, aktiva och fullständigt konfigurerade innan API:et kan rikta in sig på dem.

device_offline — Bärarens enhet är parad, men den inbyggda stöttjänsten är inte aktiverad eller körs inte i Android-appen. Detta är det vanligaste felet — bäraren måste ha den inbyggda stöttjänsten aktiverad i Android-appens inställningar för att kommandon ska levereras tillförlitligt.

device_timeout — Kommandot skickades till mobilappen, men appen bekräftade inte att Bluetooth-enheten tog emot det inom 25 sekunder. Detta betyder vanligtvis att bärarens Bluetooth är avstängt, att enheten är utom räckhåll eller att enheten är avstängd. Lockink-enheter går in i viloläge efter bara 3 minuters inaktivitet om inte keep-alive-funktionen är aktiverad – och även då kan OEM-batterioptimeringar på telefonen begränsa bakgrunds-Bluetooth och förhindra att keep-alive fungerar tillförlitligt.

not_authorized — Bäraren har inte uttryckligen gett sitt samtycke till stötar i sina enhetsinställningar. Detta är ett säkerhetskrav – även med en ihopparad enhet måste bäraren välja att tillåta fjärrstyrda stöt-/vibrationskommandon.

unsupported_device — Slumpmässiga och berserk-lägen är endast tillgängliga på Lockink AA-A1012 (Beesting). Andra enheter som CellMate Pro 3 eller Cagink Metal stöder inte dessa lägen.

Vanliga fel

401 missing_token: skicka Authorization: Bearer YOUR_DEV_TOKEN.
401 invalid_token: token är felaktig eller kopierades felaktigt.
401 revoked_token: DEV-nyckeln återkallades.
403 insufficient_scope: nyckeln har inte det omfång som krävs.
409 no_active_lock_session: användaren har för närvarande inget aktivt lås.
409 lock_ended: det lösta låset är inte längre aktivt.

info

Förstå device_timeout (504)

device_timeout-felet innebär att servern skickade stötkommandot till bärarens Android-app, men appen bekräftade inte leveransen till Bluetooth-enheten inom 25 sekunder. Detta är det mest nyanserade felet – här är vad som händer på Android-sidan:

Server → App: Kommandot skickas via Socket.IO till den inbyggda Shock-tjänsten som körs på bärarens telefon.
App → Enhet: Appen ansluter till enheten via Bluetooth Low Energy (BLE) och skickar chockkommandot. För QIUI-enheter innebär detta att man först hämtar en token från enhetstillverkarens API och sedan skriver BLE-kommandot. För Lockink-enheter skickas BLE-kommandot direkt.
App → Server: Appen skickar en bekräftelse tillbaka till servern.

25-sekunders timeouten börjar vid steg 1. En timeout vid steg 2 kan inträffa eftersom:

Bluetooth är avstängt eller så är enheten utom räckhåll för bärarens telefon.
Buren sover. Lockink-enheter går in i djupt viloläge efter bara 3 minuters BLE-inaktivitet. Keep-alive-funktionen kan förhindra detta, men OEM-batterioptimeringar (Samsung, Xiaomi, Huawei, etc.) kan stoppa bakgrundsanslutningar till Bluetooth, vilket gör keep-alive opålitlig.
BLE-anslutningen misslyckades. Appen försöker BLE-anslutningen igen, men om enheten inte svarar får den timeout.
Säkerhetsblockering. Appen har ett inbyggt säkerhetssystem som blockerar stötar om bäraren upptäcks i rörelse (t.ex. bilkörning, cykling) baserat på aktivitetsidentifiering och GPS-hastighet. Om bäraren är i rörelse blockeras stöten tyst och rapporteras som misslyckad.
Hämtning av QIUI-token misslyckades. För CellMate Pro 3- och Cagink-enheter måste appen hämta en kommandotoken från QIUIs moln-API innan BLE-kommandot skickas. Om bärarens telefon inte har internet, eller om QIUIs API är långsamt/oåtkomligt, kan det här steget förbruka större delen av 25-sekundersfönstret.

Praktiskt mönster

De flesta externa program följer detta flöde:

Ring GET /api/apps/v1/session.
Läs lockData.
Bestäm vad som ska hända.
Anropa /api/apps/v1/action eller en av de enklare låsslutpunkterna.
Skriv valfritt en anpassad logg med /api/apps/v1/logs/custom.

Till exempel kan ett skript kontrollera timeRemainingSeconds, lägga till tidpunkt när en regel misslyckas och sedan skriva en anpassad logg som förklarar vad som hände.

Skapa en DEV-token​

Första samtalet: Kontrollera det aktuella låset​

Lås datahjälpare​

Huvudlåsåtgärdens slutpunkter​

Lägg till eller ta bort tid​

Frys och tina upp​

Allmän åtgärdsslutpunkt​

Namn på åtgärder som stöds​

Användbara exempel på åtgärder​

Anpassad låslogg​

Enhetskommandon​

Begäran​

Stödda kommandon och deras parametrar​

shock.start​

shock.stop​

vibration.start​

vibration.stop​

all.stop​

shock.random.set​

shock.berserk.set​

Enhetsval​

Svar​

Framgång (200)​

Fel​

Vanliga felscenarier förklarade​

Vanliga fel​

Praktiskt mönster​

Skapa en DEV-token

Första samtalet: Kontrollera det aktuella låset

Lås datahjälpare

Huvudlåsåtgärdens slutpunkter

Lägg till eller ta bort tid

Frys och tina upp

Allmän åtgärdsslutpunkt

Namn på åtgärder som stöds

Användbara exempel på åtgärder

Anpassad låslogg

Enhetskommandon

Begäran

Stödda kommandon och deras parametrar

`shock.start`

`shock.stop`

`vibration.start`

`vibration.stop`

`all.stop`

`shock.random.set`

`shock.berserk.set`

Enhetsval

Svar

Framgång (200)

Fel

Vanliga felscenarier förklarade

Vanliga fel

Praktiskt mönster