Zewnętrzne API i programy

Użyj tej strony, jeśli chcesz, aby prosty program zewnętrzny, skrypt, serwer lokalny lub usługa zaplecza sterowała bieżącą blokadą Chastify.

Najprostszym sposobem jest utworzenie tokenu DEV dla całego użytkownika, a następnie wysłanie go jako tokenu okaziciela do punktów końcowych /api/apps/v1/*.

Kod /api/apps/v1/* jest przeznaczony tylko dla Twoich własnych sesji aktywnej blokady. Jeśli tworzysz rozszerzenie publiczne używane przez innych użytkowników Chastify, użyj klucza API dla programisty o zasięgu aplikacji z kodem /api/extensions/sessions/:sessionId/* i przekaż ramkę iframe mainToken w kodzie x-chastify-main-token.

Utwórz token DEV

Otwórz Chastify.
Przejdź do Developer API.
Znajdź User-wide DEV API keys.
Utwórz klucz.
Skopiuj token natychmiast. Jest on wyświetlany tylko raz.

Użyj tego w prośbach tego typu:

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

Tokeny DEV:

nie wymaga tworzenia rozszerzenia
nie wygasają automatycznie
praca dla bieżącej aktywnej blokady i przyszłych sesji aktywnej blokady
użyj swojej roli na aktywnej blokadzie, jako noszący lub posiadacz klucza
można odwołać ze strony API dla programistów

Traktuj token DEV jak hasło. Każdy, kto ma token, może wywoływać API dla programistów jako Ty.

Pierwsze wezwanie: Sprawdź obecną blokadę

Zacznij od:

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

Przykład:

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

Zwraca bieżący kontekst blokady, rolę, zakresy, pozostały czas i kod lockData.

Zablokuj pomocników danych

GET /api/apps/v1/session zawiera lockData, który został zaprojektowany tak, aby był łatwy do odczytania przez programy i silniki reguł.

Typowe wartości logiczne:

frozen
unlockable
trusted
taskAssigned: true, gdy aktywna blokada ma otwarty TaskRun

Typowe liczby:

timeLockedSeconds
timeRemainingSeconds
maxTimeRemainingSeconds
taskPoints

Popularne ciągi znaków:

lockTitle
pola profilu użytkownika
pola profilu posiadacza klucza

Uwaga dotycząca prywatności:

wearerLastSeenTimestamp i keyholderLastSeenTimestamp są zmieniane na null, gdy użytkownik ma wyłączony status online.

Główne punkty końcowe działania blokady

Tego typu punkty końcowe są najczęściej używane przez programy zewnętrzne do modyfikowania blokad.

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

Wszystkie żądania wykorzystują:

Authorization: Bearer YOUR_DEV_TOKEN
Content-Type: application/json

Dodaj lub usuń czas

Użyj prostego punktu końcowego czasu, jeśli chcesz zmienić tylko pozostały czas.

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

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

Zamrozić i rozmrozić

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

Odmrozić:

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

Ogólny punkt końcowy akcji

Używać:

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

Kształt ciała:

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

Przykład:

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

Obsługiwane nazwy akcji

name obsługuje:

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

Ograniczenia działania:

Akcje zadań wymagają włączenia modułu Zadania na zamku.
hygienic_unlock.start wymaga włączenia opcji Otwieranie higieniczne i braku aktywnej sesji higienicznej.
Polecenia urządzenia wymagają podłączonego, obsługiwanego urządzenia i uprawnień.

Przydatne przykłady działań

Usuń 15 minut:

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

Zamrozić na 5 minut:

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

Przełącz zamrożenie:

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

Przypisz zadanie:

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

Tworzy to kod TaskRun dla aktywnej blokady. Jeśli inne uruchomienie zadania jest już otwarte, bieżąca implementacja anuluje stare uruchomienie i tworzy nowe.

Uruchom licznik aktywnego zadania:

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

Zakończ aktywne zadanie:

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

Tym samym zakończono ostatni otwarty kod TaskRun dla aktywnej blokady.

Rozpocznij higieniczne odblokowanie:

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

Zakończyć aktywny pręgierz:

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

Niestandardowy dziennik blokad

Użyj tej opcji, gdy Twój program wykonał jakąś czynność i chcesz, aby była ona widoczna w historii blokad.

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

Przykład:

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

Pola ciała:

title: wymagane
description: opcjonalny
role: extension, wearer lub keyholder
icon: opcjonalny
color: opcjonalny kolor szesnastkowy, na przykład #ffcc00

Polecenia urządzenia

Polecenia urządzenia umożliwiają wywoływanie wstrząsów i wibracji na podłączonym urządzeniu użytkownika.

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

Działa z tokenem DEV — nie wymaga identyfikatora sesji. Serwer automatycznie rozpoznaje blokadę i użytkownika na podstawie tokena.

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

Treść żądania

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

command (string, wymagany) — polecenie urządzenia do wykonania.
params (obiekt, opcjonalny) — parametry specyficzne dla polecenia (patrz poniżej).

Obsługiwane polecenia i ich parametry

`shock.start`

Rozpoczyna impuls elektryczny w urządzeniu użytkownika.

Parametr	Typ	Zakres	Domyślny	Opis
`intensityPct`	liczba	1–100	50	Shock intensywność w procentach
`durationSeconds`	liczba	1–300	60	Shock czas trwania w sekundach
`message`	ciąg	—	—	Opcjonalny komunikat wyświetlany użytkownikowi

notatka

Maksymalne napięcie skonfigurowane dla użytkownika jest zawsze egzekwowane jako limit, niezależnie od tego, co wysyłasz. W przypadku urządzeń Lockink jest to limit napięcia dla każdego urządzenia. W przypadku urządzeń QIUI jest to ustawienie shockVolt (skala 1–4). Jeśli wyślesz intensityPct: 80, ale limit dla użytkownika wynosi 50%, urządzenie dostarczy tylko 50%.

Przykład:

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`

Zatrzymuje wszystkie aktywne wstrząsy w urządzeniu użytkownika. Nie wymaga parametrów.

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`

Uruchamia wibracje na urządzeniu użytkownika.

Parametr	Typ	Zakres	Domyślny	Opis
`intensityPct`	liczba	1–100	50	Intensywność wibracji wyrażona w procentach
`durationSeconds`	liczba	1–300	30	Czas trwania wibracji w sekundach
`frequencyPct`	liczba	1–100	50	Częstotliwość wibracji wyrażona w procentach
`message`	ciąg	—	—	Opcjonalny komunikat wyświetlany użytkownikowi

Przykład:

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`

Zatrzymuje wszystkie aktywne wibracje. Nie wymaga parametrów.

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`

Zatrzymuje wszelką aktywność urządzenia (wstrząsy, wibracje itp.). Nie wymaga parametrów.

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`

Włącza lub wyłącza tryb losowego wstrząsu w urządzeniu użytkownika.

Parametr	Typ	Zakres	Domyślny	Opis
`enabled`	wartość logiczna	—	—	Włącz (`true`) lub wyłącz (`false`) tryb losowy
`minIntensityPct`	liczba	1–100	20	Minimalny procent intensywności wstrząsu
`maxIntensityPct`	liczba	1–100	80	Maksymalna intensywność wstrząsu w procentach
`message`	ciąg	—	—	Opcjonalny komunikat wyświetlany użytkownikowi

notatka

Maksymalne napięcie skonfigurowane dla użytkownika to zawsze limit. Jeśli ustawisz maxIntensityPct: 80, ale limit dla użytkownika wynosi 50, rzeczywiste maksimum wyniesie 50%.

Przykład:

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`

Włącza lub wyłącza tryb szoku berserk w urządzeniu użytkownika.

Parametr	Typ	Zakres	Domyślny	Opis
`enabled`	wartość logiczna	—	—	Włącz (`true`) lub wyłącz (`false`) tryb berserk
`message`	ciąg	—	—	Opcjonalny komunikat wyświetlany użytkownikowi

Przykład:

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

Polecenia urządzenia zależą od aktywnej blokady, dostępności urządzenia i zasad dotyczących poleceń.

Wybór urządzenia

Nie musisz określać identyfikatora ani typu urządzenia. Każdy użytkownik może mieć tylko jedno aktywne urządzenie na raz — serwer automatycznie je wykryje.

W odpowiedzi zwracany jest kod deviceType, dzięki czemu wiadomo, które urządzenie otrzymało polecenie.

Odpowiedzi

Sukces (200)

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

Pole	Opis
`ok`	`true` po zaakceptowaniu polecenia
`command`	Polecenie, które zostało wykonane
`result.success`	`true` jeśli urządzenie potwierdziło polecenie
`result.message`	Komunikat o stanie czytelny dla człowieka
`result.deviceType`	Typ urządzenia użytkownika (np. `lockink-aa-a1012`, `cellmate-pro-3`)
`active.shock`	Czy na urządzeniu użytkownika aktualnie aktywny jest impuls elektryczny
`active.vibration`	Czy w urządzeniu użytkownika aktualnie aktywna jest wibracja

Uwaga: shock.start i vibration.start czekają do 25 sekund na potwierdzenie odbioru przez urządzenie. Polecenia stop (shock.stop, vibration.stop, all.stop) zwracają sygnał natychmiast.

Awaria

Wszystkie błędy zwracają HTTP 4xx/5xx z treścią JSON:

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

Scenariusz	HTTP	`error`	`message`
Nie znaleziono blokady lub nie ma aktywnej blokady	404	`lock_not_found`	`No active lock found`
Blokada nie jest już aktywna	409	`lock_ended`	`The lock is no longer active`
Brak sesji użytkownika	400	`no_wearer`	`Missing wearer session`
Brakujący lub nieprawidłowy kod `durationSeconds`	400	`invalid_params`	`durationSeconds is required for server-initiated shocks`
Tryb losowy/szału na nieobsługiwanym urządzeniu	400	`unsupported_device`	`Random mode only supported on Lockink AA-A1012`
Użytkownik nie wyraził zgody na porażenie prądem	403	`not_authorized`	`User not eligible for shock commands (consent or device check failed)`
Nie sparowano żadnego urządzenia zdolnego do generowania wstrząsów/wibracji	404	`no_device`	`No shock-capable device found for user`
Urządzenie jest offline (brak połączenia z gniazdem)	404	`device_offline`	`No active device socket found for user`
Urządzenie nie zostało potwierdzone w czasie (25 s)	504	`device_timeout`	`Device verification timeout`
Nierozpoznana lub nieobsługiwana awaria	400	`command_failed`	`command_failed`

Jeśli dostępny, w odpowiedzi uwzględniany jest kod deviceType.

Wyjaśnienie typowych scenariuszy awarii

uwaga

Urządzenie musi być połączone za pomocą aplikacji mobilnej

Shock i wibracje wymagają sparowania urządzenia z obsługą Bluetooth i aktywnej aplikacji mobilnej Chastify na telefonie. Aplikacja utrzymuje połączenie z gniazdem w czasie rzeczywistym, które przekazuje polecenia do urządzenia. Jeśli aplikacja jest zamknięta lub telefon nie ma dostępu do internetu, polecenia nie zostaną zrealizowane.

no_device — Użytkownik nie sparował urządzenia z funkcją defibrylacji (np. CellMate Pro 3, Cagink Metal, Lockink AA-A1012) w aplikacji Chastify. Urządzenia muszą być sparowane, aktywne i w pełni skonfigurowane, zanim API będzie mogło je przejąć.

device_offline — Urządzenie użytkownika jest sparowane, ale usługa Natywna usługa Shock nie jest włączona lub nie działa w aplikacji Android. Jest to najczęstszy błąd — użytkownik musi mieć włączoną usługę Natywna usługa Shock w ustawieniach aplikacji Android, aby polecenia były dostarczane niezawodnie.

device_timeout — Polecenie zostało wysłane do aplikacji mobilnej, ale aplikacja nie potwierdziła jego odebrania przez urządzenie Bluetooth w ciągu 25 sekund. Zazwyczaj oznacza to, że Bluetooth użytkownika jest wyłączony, urządzenie jest poza zasięgiem lub jest wyłączone. Urządzenia Lockink przechodzą w stan uśpienia po zaledwie 3 minutach bezczynności, chyba że funkcja podtrzymywania aktywności jest włączona — a nawet wtedy optymalizacja baterii OEM w telefonie może ograniczać działanie Bluetooth w tle i uniemożliwiać niezawodne działanie funkcji podtrzymywania aktywności.

not_authorized — Użytkownik nie wyraził wyraźnej zgody na porażenie prądem w ustawieniach urządzenia. Jest to wymóg bezpieczeństwa — nawet w przypadku sparowanego urządzenia użytkownik musi wyrazić zgodę na zdalne polecenia porażenia prądem/wibracji.

unsupported_device — Tryby losowy i berserk są dostępne tylko w modelu Lockink AA-A1012 (Beesting). Inne urządzenia, takie jak CellMate Pro 3 lub Cagink Metal, nie obsługują tych trybów.

Typowe błędy

401 missing_token: wyślij Authorization: Bearer YOUR_DEV_TOKEN.
401 invalid_token: token jest błędny lub został nieprawidłowo skopiowany.
401 revoked_token: klucz DEV został unieważniony.
403 insufficient_scope: klucz nie ma wymaganego zakresu.
409 no_active_lock_session: użytkownik nie ma obecnie aktywnej blokady.
409 lock_ended: rozwiązana blokada nie jest już aktywna.

informacja

Zrozumienie device_timeout (504)

Błąd device_timeout oznacza, że serwer wysłał polecenie defibrylacji do aplikacji Android użytkownika, ale aplikacja nie potwierdziła dostarczenia go do urządzenia Bluetooth w ciągu 25 sekund. To najbardziej niuansowy błąd — oto, co dzieje się po stronie Android:

Serwer → Aplikacja: Polecenie jest przesyłane przez Socket.IO do natywnej usługi Shock uruchomionej na telefonie użytkownika.
Aplikacja → Urządzenie: Aplikacja łączy się z urządzeniem za pomocą technologii Bluetooth Low Energy (BLE) i wysyła polecenie wyładowania elektrostatycznego. W przypadku urządzeń QIUI wiąże się to z pobraniem tokena z API producenta urządzenia, a następnie wysłaniem polecenia BLE. W przypadku urządzeń Lockink polecenie BLE jest wysyłane bezpośrednio.
Aplikacja → Serwer: Aplikacja wysyła potwierdzenie do serwera.

25-sekundowy limit czasu zaczyna się od kroku 1. Limit czasu w kroku 2 może wystąpić z następujących powodów:

Bluetooth jest wyłączony lub urządzenie znajduje się poza zasięgiem telefonu użytkownika.
Klatka jest uśpiona. Urządzenia Lockink przechodzą w stan głębokiego uśpienia po zaledwie 3 minutach braku aktywności BLE. Funkcja podtrzymywania aktywności (keep-alive) może temu zapobiec, ale optymalizacje baterii OEM (Samsung, Xiaomi, Huawei itp.) mogą przerywać połączenia Bluetooth w tle, przez co funkcja podtrzymywania aktywności (keep-alive) staje się niestabilna.
Połączenie BLE nie powiodło się. Aplikacja próbuje ponownie nawiązać połączenie BLE, ale jeśli urządzenie nie odpowiada, następuje przekroczenie limitu czasu.
Blokada bezpieczeństwa. Aplikacja posiada wbudowany system bezpieczeństwa, który blokuje wstrząsy, jeśli użytkownik wykryje ruch (np. jadąc samochodem, na rowerze) na podstawie rozpoznania aktywności i prędkości GPS. Jeśli użytkownik się porusza, wstrząs jest dyskretnie blokowany i zgłaszany jako nieudany.
Pobieranie tokenu QIUI nie powiodło się. W przypadku urządzeń CellMate Pro 3 i Cagink aplikacja musi pobrać token polecenia z interfejsu API w chmurze urządzenia QIUI przed wysłaniem polecenia BLE. Jeśli telefon użytkownika nie ma dostępu do internetu lub interfejs API urządzenia QIUI jest powolny/niedostępny, ten krok może zająć większość 25-sekundowego okna.

Praktyczny wzór

Większość programów zewnętrznych działa według następującego schematu:

Zadzwoń pod numer GET /api/apps/v1/session.
Przeczytaj lockData.
Zdecyduj, co powinno się wydarzyć.
Wywołaj /api/apps/v1/action lub jeden z prostszych punktów końcowych blokady.
Opcjonalnie zapisz niestandardowy dziennik za pomocą /api/apps/v1/logs/custom.

Na przykład skrypt może sprawdzić kod timeRemainingSeconds, dodać czas, w którym reguła nie zostanie spełniona, a następnie zapisać niestandardowy dziennik wyjaśniający, co się stało.

Utwórz token DEV​

Pierwsze wezwanie: Sprawdź obecną blokadę​

Zablokuj pomocników danych​

Główne punkty końcowe działania blokady​

Dodaj lub usuń czas​

Zamrozić i rozmrozić​

Ogólny punkt końcowy akcji​

Obsługiwane nazwy akcji​

Przydatne przykłady działań​

Niestandardowy dziennik blokad​

Polecenia urządzenia​

Treść żądania​

Obsługiwane polecenia i ich parametry​

shock.start​

shock.stop​

vibration.start​

vibration.stop​

all.stop​

shock.random.set​

shock.berserk.set​

Wybór urządzenia​

Odpowiedzi​

Sukces (200)​

Awaria​

Wyjaśnienie typowych scenariuszy awarii​

Typowe błędy​

Praktyczny wzór​

Utwórz token DEV

Pierwsze wezwanie: Sprawdź obecną blokadę

Zablokuj pomocników danych

Główne punkty końcowe działania blokady

Dodaj lub usuń czas

Zamrozić i rozmrozić

Ogólny punkt końcowy akcji

Obsługiwane nazwy akcji

Przydatne przykłady działań

Niestandardowy dziennik blokad

Polecenia urządzenia

Treść żądania

Obsługiwane polecenia i ich parametry

`shock.start`

`shock.stop`

`vibration.start`

`vibration.stop`

`all.stop`

`shock.random.set`

`shock.berserk.set`

Wybór urządzenia

Odpowiedzi

Sukces (200)

Awaria

Wyjaśnienie typowych scenariuszy awarii

Typowe błędy

Praktyczny wzór