Externí API a programy

Tuto stránku použijte, pokud chcete, aby váš aktuální zámek Chastify ovládal jednoduchý externí program, skript, lokální server nebo backendová služba.

Nejjednodušší způsob je vytvořit uživatelský token DEV a poté jej odeslat jako nosičský token do koncových bodů /api/apps/v1/*.

/api/apps/v1/* je určen pouze pro vaše vlastní aktivní relace zámků. Pokud vytváříte veřejné rozšíření používané jinými uživateli Chastify, použijte klíč vývojářského API s rozsahem aplikace s /api/extensions/sessions/:sessionId/* a předejte iframe mainToken v x-chastify-main-token.

Vytvořte token DEV

Otevřete Chastify.
Přejděte na Developer API.
Najděte User-wide DEV API keys.
Vytvořte klíč.
Token ihned zkopírujte. Zobrazí se pouze jednou.

Použijte to v požadavcích, jako je tento:

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

Tokeny DEV:

nevyžadují vytvoření rozšíření
nepropadají automaticky
fungovat pro váš aktuální aktivní zámek a budoucí relace aktivního zámku
použijte svou roli u aktivního zámku, ať už uživatele nebo držitele klíče
lze zrušit na stránce API pro vývojáře

S tokenem DEV zacházejte jako s heslem. Kdokoli s tokenem může volat vývojářské API vaším jménem.

První volání: Zkontrolujte aktuální zámek

Začněte s:

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

Příklad:

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

Vrátí aktuální kontext zámku, roli, rozsahy, zbývající čas a lockData.

Pomocníci pro uzamčení dat

GET /api/apps/v1/session zahrnuje lockData, který je navržen tak, aby byl snadno čitelný pro programy a nástroje pro tvorbu pravidel.

Běžné booleovské hodnoty:

frozen
unlockable
trusted
taskAssigned: true, když je aktivní zámek otevřený TaskRun

Běžná čísla:

timeLockedSeconds
timeRemainingSeconds
maxTimeRemainingSeconds
taskPoints

Běžné řetězce:

lockTitle
pole profilu nositele
pole profilu držitele klíčů

Poznámka k ochraně osobních údajů:

wearerLastSeenTimestamp a keyholderLastSeenTimestamp jsou null, pokud daný uživatel zakázal online stav.

Koncové body akcí hlavního zámku

Tyto koncové body jsou ty, které většina externích programů používá k úpravě zámku.

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

Všechny požadavky používají:

Authorization: Bearer YOUR_DEV_TOKEN
Content-Type: application/json

Přidat nebo odebrat čas

Jednoduchý časový koncový bod použijte, pokud chcete změnit pouze zbývající čas.

Přidejte 10 minut:

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

Odeberte 5 minut:

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

Zmrazit a rozmrazit

Zmrazte na 30 minut:

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

Uvolnit:

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

Koncový bod obecné akce

Použití:

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

Tvar těla:

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

Příklad:

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

Názvy podporovaných akcí

name podporuje:

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

Omezení akcí:

Akce úkolů vyžadují, aby byl na zámku povolen modul Úkoly.
hygienic_unlock.start vyžaduje povolení hygienického otevírání a žádnou aktivní hygienickou relaci.
Příkazy zařízení vyžadují podporované připojené zařízení a oprávnění.

Užitečné příklady akcí

Odeberte 15 minut:

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

Zmrazte na 5 minut:

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

Přepnout zmrazení:

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

Zadat úkol:

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

Tím se pro aktivní zámek vytvoří TaskRun. Pokud je již otevřeno jiné spuštění úlohy, aktuální implementace zruší staré otevřené spuštění a vytvoří nové.

Spusťte aktivní časovač úlohy:

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

Dokončete aktivní úkol:

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

Tím je dokončeno poslední otevření TaskRun pro aktivní zámek.

Spusťte hygienické odemykání:

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

Konec aktivního pranýře:

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

Vlastní protokol zámků

Použijte to, když váš program něco provedl a chcete, aby to bylo viditelné v historii zámků.

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

Příklad:

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

Tělesná pole:

title: povinné
description: volitelné
role: extension, wearer nebo keyholder
icon: volitelné
color: volitelná hexadecimální barva, například #ffcc00

Příkazy zařízení

Příkazy zařízení umožňují spouštět otřesy a vibrace na připojeném zařízení nositele.

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

Funguje s vaším tokenem DEV – není potřeba žádné ID relace. Server automaticky rozezná zámek a uživatele z vašeho tokenu.

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

Tělo požadavku

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

command (řetězec, povinný) — příkaz zařízení, který se má spustit.
params (objekt, volitelné) — parametry specifické pro příkaz (viz níže).

Podporované příkazy a jejich parametry

`shock.start`

Spustí šok na zařízení nositele.

Parametr	Typ	Rozsah	Výchozí	Popis
`intensityPct`	číslo	1–100	50	intenzita Shock v procentech
`durationSeconds`	číslo	1–300	60	Shock doba trvání v sekundách
`message`	řetězec	—	—	Volitelná zpráva zobrazená uživateli

note

Maximální napětí nastavené uživatelem je vždy vynucováno jako pevný limit, bez ohledu na to, co odesíláte. Pro zařízení Lockink se jedná o limit napětí pro každé zařízení. Pro zařízení QIUI se jedná o nastavení shockVolt (stupnice 1–4). Pokud odešlete intensityPct: 80, ale limit uživatele je 50 %, zařízení dodá pouze 50 %.

Příklad:

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`

Zastaví všechny aktivní výboje na zařízení uživatele. Nejsou vyžadovány žádné parametry.

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`

Spustí vibrace na zařízení nositele.

Parametr	Typ	Rozsah	Výchozí	Popis
`intensityPct`	číslo	1–100	50	Intenzita vibrací v procentech
`durationSeconds`	číslo	1–300	30	Délka vibrací v sekundách
`frequencyPct`	číslo	1–100	50	Frekvence vibrací v procentech
`message`	řetězec	—	—	Volitelná zpráva zobrazená uživateli

Příklad:

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`

Zastaví všechny aktivní vibrace. Nejsou vyžadovány žádné parametry.

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`

Zastaví veškerou aktivitu zařízení (otřesy, vibrace atd.). Nejsou vyžadovány žádné parametry.

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`

Povolí nebo zakáže režim náhodných výbojů na zařízení uživatele.

Parametr	Typ	Rozsah	Výchozí	Popis
`enabled`	boolean	—	—	Povolit (`true`) nebo zakázat (`false`) náhodný režim
`minIntensityPct`	číslo	1–100	20	Minimální procento intenzity rázů
`maxIntensityPct`	číslo	1–100	80	Maximální procento intenzity rázů
`message`	řetězec	—	—	Volitelná zpráva zobrazená uživateli

note

Maximální napětí nastavené uživatelem je vždy nastaveno na fixní hodnotu. Pokud nastavíte maxIntensityPct: 80, ale limit uživatele je 50, skutečné maximum bude 50 %.

Příklad:

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`

Povolí nebo zakáže režim šoku berserk na zařízení nositele.

Parametr	Typ	Rozsah	Výchozí	Popis
`enabled`	boolean	—	—	Povolit (`true`) nebo zakázat (`false`) režim berserk
`message`	řetězec	—	—	Volitelná zpráva zobrazená uživateli

Příklad:

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

Příkazy zařízení závisí na aktivním zámku, dostupnosti zařízení a zásadách příkazů.

Výběr zařízení

Nemusíte zadávat ID zařízení ani typ zařízení. Každý uživatel může mít aktivní pouze jedno zařízení v danou chvíli – server ho automaticky vyhledá.

V odpovědi je vrácen kód deviceType, abyste věděli, které zařízení příkaz přijalo.

Odpovědi

Úspěch (200)

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

Pole	Popis
`ok`	`true` při přijetí příkazu
`command`	Příkaz, který byl proveden
`result.success`	`true`, pokud zařízení potvrdilo příkaz
`result.message`	Stavová zpráva čitelná člověkem
`result.deviceType`	Typ zařízení nositele (např. `lockink-aa-a1012`, `cellmate-pro-3`)
`active.shock`	Zda je na zařízení uživatele aktuálně aktivní výboj
`active.vibration`	Zda je na zařízení nositele aktuálně aktivní vibrace

Poznámka: shock.start a vibration.start čekají až 25 sekund na potvrzení příjmu zařízením. Příkazy na zastavení (shock.stop, vibration.stop, all.stop) se vrátí okamžitě.

Selhání

Všechna selhání vrací HTTP 4xx/5xx s tělem JSON:

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

Scénář	HTTP	`error`	`message`
Zámek nenalezen nebo žádný aktivní zámek	404	`lock_not_found`	`No active lock found`
Zámek již není aktivní	409	`lock_ended`	`The lock is no longer active`
Chybějící relace nositele	400	`no_wearer`	`Missing wearer session`
Chybějící nebo neplatný `durationSeconds`	400	`invalid_params`	`durationSeconds is required for server-initiated shocks`
Náhodný/berserkový režim na nepodporovaném zařízení	400	`unsupported_device`	`Random mode only supported on Lockink AA-A1012`
Uživatel neudělil souhlas s výbojem	403	`not_authorized`	`User not eligible for shock commands (consent or device check failed)`
Nebylo spárováno žádné zařízení odolné proti nárazům/vibracím	404	`no_device`	`No shock-capable device found for user`
Zařízení je offline (žádné socketové připojení)	404	`device_offline`	`No active device socket found for user`
Zařízení se nepotvrdilo včas (25 s)	504	`device_timeout`	`Device verification timeout`
Nerozpoznaná nebo neošetřená porucha	400	`command_failed`	`command_failed`

Pokud je k dispozici, je v odpovědi zahrnut deviceType.

Vysvětlení běžných scénářů selhání

caution

Zařízení musí být připojeno přes mobilní aplikaci

Vibrace a funkce Shock vyžadují, aby měl uživatel spárované podporované zařízení Bluetooth a aby v telefonu aktivně běžela mobilní aplikace Chastify. Aplikace udržuje připojení v reálném čase k socketu, které doručuje příkazy do zařízení. Pokud je aplikace zavřená nebo telefon nemá internet, příkazy selžou.

no_device — Uživatel nespároval zařízení schopné odeslat výboj (např. CellMate Pro 3, Cagink Metal, Lockink AA-A1012) v aplikaci Chastify. Zařízení musí být spárována, aktivní a plně nakonfigurována, než je API může cílit.

device_offline — Zařízení uživatele je spárované, ale Nativní služba Shock není v aplikaci Android povolena nebo neběží. Toto je nejčastější chyba – uživatel musí mít v nastavení aplikace Android povolenou Nativní službu Shock, aby byly příkazy spolehlivě doručovány.

device_timeout — Příkaz byl odeslán do mobilní aplikace, ale aplikace do 25 sekund nepotvrdila, že jej zařízení Bluetooth přijalo. To obvykle znamená, že Bluetooth uživatele je vypnutý, zařízení je mimo dosah nebo je zařízení vypnuté. Zařízení Lockink přejdou do režimu spánku po pouhých 3 minutách nečinnosti, pokud není povolena funkce keep-alive – a i tehdy mohou optimalizace baterie od výrobce v telefonu omezit Bluetooth na pozadí a zabránit spolehlivému fungování funkce keep-alive.

not_authorized — Uživatel v nastavení zařízení výslovně neudělil souhlas s výboji. Jedná se o bezpečnostní požadavek – i v případě spárovaného zařízení se musí uživatel přihlásit k povolení dálkových příkazů k výbojům/vibracím.

unsupported_device — Režimy Random a Berserk jsou k dispozici pouze na Lockink AA-A1012 (Beesting). Jiná zařízení, jako například CellMate Pro 3 nebo Cagink Metal, tyto režimy nepodporují.

Časté chyby

401 missing_token: odeslat Authorization: Bearer YOUR_DEV_TOKEN.
401 invalid_token: token je chybný nebo byl nesprávně zkopírován.
401 revoked_token: klíč DEV byl zrušen.
403 insufficient_scope: klíč nemá požadovaný rozsah.
409 no_active_lock_session: uživatel momentálně nemá aktivní zámek.
409 lock_ended: vyřešený zámek již není aktivní.

info

Pochopení kódu device_timeout (504)

Chyba device_timeout znamená, že server odeslal příkaz k výboji do aplikace Android uživatele, ale aplikace nepotvrdila doručení do zařízení Bluetooth do 25 sekund. Toto je nejzásadnější chyba – na straně Android se děje toto:

Server → Aplikace: Příkaz se přes Socket.IO přenáší do nativní služby Shock spuštěné na telefonu uživatele.
Aplikace → Zařízení: Aplikace se připojí k zařízení přes Bluetooth Low Energy (BLE) a odešle příkaz k šoku. U zařízení QIUI to zahrnuje nejprve načtení tokenu z API výrobce zařízení a následné zapsání příkazu BLE. U zařízení Lockink se příkaz BLE odešle přímo.
Aplikace → Server: Aplikace odešle potvrzení zpět na server.

25sekundový časový limit začíná v kroku 1. K časovému limitu v kroku 2 může dojít z následujících důvodů:

Bluetooth je vypnutý nebo je zařízení mimo dosah telefonu nositele.
Klec je v režimu spánku. Zařízení Lockink přejdou do hlubokého spánku po pouhých 3 minutách nečinnosti BLE. Funkce keep-alive tomu může zabránit, ale optimalizace baterie od OEM (Samsung, Xiaomi, Huawei atd.) mohou ukončit připojení Bluetooth na pozadí, čímž se funkce keep-alive stane nespolehlivou.
Připojení BLE selhalo. Aplikace se znovu pokusí o připojení BLE, ale pokud zařízení nereaguje, dojde k vypršení časového limitu.
Bezpečnostní blokování. Aplikace má vestavěný bezpečnostní systém, který blokuje šoky, pokud je detekován pohyb uživatele (např. řízení, jízda na kole) na základě rozpoznání aktivity a rychlosti GPS. Pokud je uživatel v pohybu, šok je tiše zablokován a hlášen jako selhání.
Načtení tokenu QIUI se nezdařilo. U zařízení CellMate Pro 3 a Cagink musí aplikace před odesláním příkazu BLE načíst token příkazu z cloudového API QIUI. Pokud telefon uživatele nemá připojení k internetu nebo je API QIUI pomalé/nedostupné, může tento krok zabrat většinu 25sekundového okna.

Praktický vzor

Většina externích programů se řídí tímto postupem:

Zavolejte GET /api/apps/v1/session.
Přečtěte si lockData.
Rozhodněte, co by se mělo stát.
Zavolejte /api/apps/v1/action nebo jeden z jednodušších koncových bodů zámku.
Volitelně zapište vlastní protokol s parametrem /api/apps/v1/logs/custom.

Například skript může zkontrolovat timeRemainingSeconds, přidat čas selhání pravidla a poté zapsat vlastní protokol s vysvětlením, co se stalo.

Vytvořte token DEV​

První volání: Zkontrolujte aktuální zámek​

Pomocníci pro uzamčení dat​

Koncové body akcí hlavního zámku​

Přidat nebo odebrat čas​

Zmrazit a rozmrazit​

Koncový bod obecné akce​

Názvy podporovaných akcí​

Užitečné příklady akcí​

Vlastní protokol zámků​

Příkazy zařízení​

Tělo požadavku​

Podporované příkazy a jejich parametry​

shock.start​

shock.stop​

vibration.start​

vibration.stop​

all.stop​

shock.random.set​

shock.berserk.set​

Výběr zařízení​

Odpovědi​

Úspěch (200)​

Selhání​

Vysvětlení běžných scénářů selhání​

Časté chyby​

Praktický vzor​

Vytvořte token DEV

První volání: Zkontrolujte aktuální zámek

Pomocníci pro uzamčení dat

Koncové body akcí hlavního zámku

Přidat nebo odebrat čas

Zmrazit a rozmrazit

Koncový bod obecné akce

Názvy podporovaných akcí

Užitečné příklady akcí

Vlastní protokol zámků

Příkazy zařízení

Tělo požadavku

Podporované příkazy a jejich parametry

`shock.start`

`shock.stop`

`vibration.start`

`vibration.stop`

`all.stop`

`shock.random.set`

`shock.berserk.set`

Výběr zařízení

Odpovědi

Úspěch (200)

Selhání

Vysvětlení běžných scénářů selhání

Časté chyby

Praktický vzor