API y programas externos

Utilice esta página cuando desee que un programa externo sencillo, un script, un servidor local o un servicio de backend controle su bloqueo Chastify actual.

La forma más sencilla es crear un token DEV para todo el usuario y luego enviarlo como un token de portador a los puntos finales /api/apps/v1/*.

/api/apps/v1/* es solo para tus propias sesiones de bloqueo activas. Si estás creando una extensión pública utilizada por otros usuarios de Chastify, usa una clave API de desarrollador con ámbito de aplicación con /api/extensions/sessions/:sessionId/* y pasa el iframe mainToken en x-chastify-main-token.

Crear un token DEV

Abra Chastify.
Ve a Developer API.
Encuentra User-wide DEV API keys.
Crea una clave.
Copia el token inmediatamente. Solo se muestra una vez.

Úselo en solicitudes como esta:

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

Tokens DEV:

no requieren la creación de una extensión
no caducan automáticamente
Funciona para su bloqueo activo actual y futuras sesiones de bloqueo activo.
Utilice su rol en la cerradura activa, ya sea usuario o poseedor de la llave.
Se puede revocar desde la página de la API para desarrolladores.

Trata el token DEV como una contraseña. Cualquiera que tenga el token puede llamar a la API para desarrolladores haciéndose pasar por ti.

Primera llamada: Compruebe el bloqueo actual.

Comience con:

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

Ejemplo:

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

Esto devuelve el contexto de bloqueo actual, el rol, los ámbitos, el tiempo restante y el código lockData.

Ayudantes de bloqueo de datos

GET /api/apps/v1/session incluye lockData, que está diseñado para que los programas y los motores de reglas lo lean fácilmente.

Valores booleanos comunes:

frozen
unlockable
trusted
taskAssigned: true cuando el candado activo está abierto TaskRun

Números comunes:

timeLockedSeconds
timeRemainingSeconds
maxTimeRemainingSeconds
taskPoints

Cadenas comunes:

lockTitle
campos del perfil del usuario
campos del perfil del titular de la llave

Aviso de privacidad:

wearerLastSeenTimestamp y keyholderLastSeenTimestamp son null cuando ese usuario ha desactivado el estado en línea.

Puntos finales de acción de bloqueo principal

Estos puntos finales son los que utilizan la mayoría de los programas externos para modificar un bloqueo.

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

Todas las solicitudes utilizan:

Authorization: Bearer YOUR_DEV_TOKEN
Content-Type: application/json

Agregar o quitar tiempo

Utilice el punto final de tiempo simple cuando solo desee cambiar el tiempo restante.

Añadir 10 minutos:

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

Eliminar 5 minutos:

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

Congelar y descongelar

Congelar durante 30 minutos:

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

Descongelar:

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

Punto final de acción general

Usar:

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

Forma del cuerpo:

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

Ejemplo:

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

Nombres de acciones compatibles

name admite:

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

Restricciones de acción:

Las acciones de tarea requieren que el módulo Tareas esté habilitado en el bloqueo.
hygienic_unlock.start requiere que la Apertura Higiénica esté habilitada y que no haya ninguna sesión de higiene activa.
Los comandos del dispositivo requieren un dispositivo conectado compatible y los permisos necesarios.

Ejemplos de acciones útiles

Retirar 15 minutos:

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

Congelar durante 5 minutos:

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

Alternar congelación:

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

Asignar una tarea:

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

Esto crea un TaskRun para el bloqueo activo. Si ya hay otra tarea en ejecución abierta, la implementación actual cancela la ejecución anterior y crea una nueva.

Iniciar el temporizador de la tarea activa:

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

Completa la tarea activa:

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

Esto completa el último código TaskRun abierto para la cerradura activa.

Inicie un desbloqueo higiénico:

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

Fin de la picota activa:

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

Registro de cerraduras personalizadas

Utilice esta opción cuando su programa haya realizado alguna acción y desee que sea visible en el historial de bloqueos.

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

Ejemplo:

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

Campos corporales:

title: requerido
description: opcional
role: extension, wearer o keyholder
icon: opcional
color: color hexadecimal opcional, por ejemplo #ffcc00

Comandos del dispositivo

Los comandos del dispositivo permiten activar descargas eléctricas y vibraciones en el dispositivo conectado del usuario.

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

Funciona con tu token DEV; no se necesita ID de sesión. El servidor resuelve automáticamente el bloqueo y el usuario a partir de tu 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}}'

Cuerpo de la solicitud

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

command (cadena, obligatorio): el comando del dispositivo que se va a ejecutar.
params (objeto, opcional): parámetros específicos del comando (ver más abajo).

Comandos compatibles y sus parámetros

`shock.start`

Inicia una descarga eléctrica en el dispositivo del usuario.

Parámetro	Tipo	Rango	Predeterminado	Descripción
`intensityPct`	número	1–100	50	Shock intensidad como porcentaje
`durationSeconds`	número	1–300	60	Shock duración en segundos
`message`	cadena	—	—	Mensaje opcional que se muestra al usuario

nota

El voltaje máximo configurado para el usuario siempre se aplica como un límite estricto, independientemente de lo que se envíe. Para los dispositivos Lockink, este es el límite de voltaje por dispositivo. Para los dispositivos QIUI, este es el ajuste shockVolt (escala de 1 a 4). Si se envía intensityPct: 80 pero el límite del usuario es del 50 %, el dispositivo solo suministrará el 50 %.

Ejemplo:

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`

Desactiva todas las descargas eléctricas activas en el dispositivo del usuario. No requiere parámetros.

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`

Inicia una vibración en el dispositivo del usuario.

Parámetro	Tipo	Rango	Predeterminado	Descripción
`intensityPct`	número	1–100	50	Intensidad de vibración como porcentaje
`durationSeconds`	número	1–300	30	Duración de la vibración en segundos
`frequencyPct`	número	1–100	50	Frecuencia de vibración como porcentaje
`message`	cadena	—	—	Mensaje opcional que se muestra al usuario

Ejemplo:

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`

Detiene todas las vibraciones activas. No requiere parámetros.

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`

Detiene toda la actividad del dispositivo (golpes, vibraciones, etc.). No requiere parámetros.

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`

Activa o desactiva el modo de descarga aleatoria en el dispositivo del usuario.

Parámetro	Tipo	Rango	Predeterminado	Descripción
`enabled`	booleano	—	—	Habilitar (`true`) o deshabilitar (`false`) el modo aleatorio
`minIntensityPct`	número	1–100	20	Porcentaje mínimo de intensidad de choque
`maxIntensityPct`	número	1–100	80	Porcentaje de intensidad máxima de choque
`message`	cadena	—	—	Mensaje opcional que se muestra al usuario

nota

El voltaje máximo configurado para el usuario siempre es el límite máximo. Si se configura maxIntensityPct: 80, pero el límite del usuario es 50, el máximo real será del 50 %.

Ejemplo:

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`

Activa o desactiva el modo de choque extremo en el dispositivo del usuario.

Parámetro	Tipo	Rango	Predeterminado	Descripción
`enabled`	booleano	—	—	Habilitar (`true`) o deshabilitar (`false`) el modo berserk
`message`	cadena	—	—	Mensaje opcional que se muestra al usuario

Ejemplo:

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

Los comandos del dispositivo dependen del bloqueo activo, la disponibilidad del dispositivo y la política de comandos.

Selección de dispositivos

No es necesario especificar un ID de dispositivo ni un tipo de dispositivo. Cada usuario solo puede tener un dispositivo activo a la vez; el servidor lo identifica automáticamente.

El código deviceType se devuelve en la respuesta para que sepas qué dispositivo recibió el comando.

Respuestas

Éxito (200)

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

Campo	Descripción
`ok`	`true` cuando se aceptó el comando
`command`	El comando que se ejecutó
`result.success`	`true` si el dispositivo confirmó el comando
`result.message`	Mensaje de estado legible para humanos
`result.deviceType`	Tipo de dispositivo del usuario (por ejemplo, `lockink-aa-a1012`, `cellmate-pro-3`)
`active.shock`	Si hay una descarga activa en el dispositivo del usuario
`active.vibration`	Indica si la vibración está activa en el dispositivo del usuario

Nota: Los comandos shock.start y vibration.start esperan hasta 25 segundos para que el dispositivo confirme la recepción. Los comandos de parada (shock.stop, vibration.stop, all.stop) regresan inmediatamente.

Falla

Todos los fallos devuelven HTTP 4xx/5xx con un cuerpo JSON:

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

Escenario	HTTP	`error`	`message`
No se encontró ningún candado o no hay ningún candado activo	404	`lock_not_found`	`No active lock found`
El bloqueo ya no está activo	409	`lock_ended`	`The lock is no longer active`
Sesión de usuario faltante	400	`no_wearer`	`Missing wearer session`
Falta o no es válido `durationSeconds`	400	`invalid_params`	`durationSeconds is required for server-initiated shocks`
Modo aleatorio/berserker en dispositivo no compatible	400	`unsupported_device`	`Random mode only supported on Lockink AA-A1012`
El usuario no ha otorgado su consentimiento para recibir descargas eléctricas	403	`not_authorized`	`User not eligible for shock commands (consent or device check failed)`
No se ha emparejado ningún dispositivo compatible con golpes/vibraciones	404	`no_device`	`No shock-capable device found for user`
El dispositivo está desconectado (sin conexión de socket)	404	`device_offline`	`No active device socket found for user`
El dispositivo no confirmó a tiempo (25 s)	504	`device_timeout`	`Device verification timeout`
Fallo no reconocido o no controlado	400	`command_failed`	`command_failed`

Cuando está disponible, deviceType se incluye en la respuesta.

Explicación de los escenarios de fallos más comunes.

precaución

El dispositivo debe estar conectado a través de la aplicación móvil.

El funcionamiento de los auriculares Shock y sus vibraciones requiere que el usuario tenga un dispositivo Bluetooth compatible emparejado y la aplicación móvil Chastify en ejecución en su teléfono. La aplicación mantiene la conexión en tiempo real que envía los comandos al dispositivo. Si la aplicación está cerrada o el teléfono no tiene conexión a internet, los comandos fallarán.

no_device — El usuario no ha emparejado un dispositivo con capacidad de respuesta a impactos (por ejemplo, CellMate Pro 3, Cagink Metal, Lockink AA-A1012) en la aplicación Chastify. Los dispositivos deben estar emparejados, activos y completamente configurados para que la API pueda detectarlos.

device_offline — El dispositivo del usuario está emparejado, pero el Servicio nativo Shock no está habilitado o no se está ejecutando en la aplicación Android. Este es el fallo más común: el usuario debe tener habilitado el Servicio nativo Shock en la configuración de la aplicación Android para que los comandos se entreguen correctamente.

device_timeout — El comando se envió a la aplicación móvil, pero esta no confirmó que el dispositivo Bluetooth lo recibiera en 25 segundos. Esto suele significar que el Bluetooth del usuario está desactivado, que el dispositivo está fuera de alcance o que está apagado. Los dispositivos Lockink entran en modo de suspensión tras solo 3 minutos de inactividad, a menos que la función de mantenimiento de conexión esté activada; incluso en ese caso, las optimizaciones de batería del fabricante del teléfono pueden restringir el Bluetooth en segundo plano e impedir que la función de mantenimiento de conexión funcione correctamente.

not_authorized — El usuario no ha otorgado su consentimiento explícito para recibir descargas eléctricas en la configuración de su dispositivo. Este es un requisito de seguridad: incluso con un dispositivo emparejado, el usuario debe autorizar el uso de comandos remotos de descarga/vibración.

unsupported_device — Los modos aleatorio y berserk solo están disponibles en el Lockink AA-A1012 (Beesting). Otros dispositivos como CellMate Pro 3 o Cagink Metal no son compatibles con estos modos.

Errores comunes

401 missing_token: enviar Authorization: Bearer YOUR_DEV_TOKEN.
401 invalid_token: el token es incorrecto o se copió incorrectamente.
401 revoked_token: la clave DEV ha sido revocada.
403 insufficient_scope: la clave no tiene el alcance requerido.
409 no_active_lock_session: el usuario no tiene actualmente un bloqueo activo.
409 lock_ended: el bloqueo resuelto ya no está activo.

info

Comprendiendo el código ZXQ0ZXQ (504)

El error device_timeout significa que el servidor envió el comando de descarga a la aplicación Android del usuario, pero la aplicación no confirmó la entrega al dispositivo Bluetooth en 25 segundos. Este es el error más complejo; esto es lo que sucede en el lado del Android:

Servidor → Aplicación: El comando viaja a través de Socket.IO al servicio nativo Shock que se ejecuta en el teléfono del usuario.
Aplicación → Dispositivo: La aplicación se conecta al dispositivo mediante Bluetooth de baja energía (BLE) y envía el comando de descarga. Para los dispositivos QIUI, esto implica obtener primero un token de la API del fabricante y luego escribir el comando BLE. Para los dispositivos Lockink, el comando BLE se envía directamente.
Aplicación → Servidor: La aplicación envía una confirmación al servidor.

El tiempo de espera de 25 segundos comienza en el paso 1. Un tiempo de espera en el paso 2 puede ocurrir porque:

Bluetooth está desactivado o el dispositivo está fuera del alcance del teléfono del usuario.
La jaula está en modo de suspensión. Los dispositivos Lockink entran en modo de suspensión profunda tras solo 3 minutos de inactividad de BLE. La función de mantenimiento de conexión puede evitarlo, pero las optimizaciones de batería del fabricante (Samsung, Xiaomi, Huawei, etc.) pueden interrumpir las conexiones Bluetooth en segundo plano, lo que hace que el mantenimiento de conexión no sea fiable.
Error de conexión BLE. La aplicación vuelve a intentar la conexión BLE, pero si el dispositivo no responde, se agota el tiempo de espera.
Bloqueo de seguridad. La aplicación cuenta con un sistema de seguridad integrado que bloquea las descargas eléctricas si se detecta que el usuario se está moviendo (por ejemplo, conduciendo o en bicicleta), basándose en el reconocimiento de actividad y la velocidad GPS. Si el usuario está en movimiento, la descarga se bloquea silenciosamente y se informa como fallida.
Error al obtener el token QIUI. Para los dispositivos CellMate Pro 3 y Cagink, la aplicación debe obtener un token de comando de la API en la nube de QIUI antes de enviar el comando BLE. Si el teléfono del usuario no tiene conexión a internet o la API de QIUI es lenta o inaccesible, este paso puede consumir la mayor parte de los 25 segundos disponibles.

Patrón práctico

La mayoría de los programas externos siguen este flujo:

Llama al código ZXQ0ZXQ.
Lee lockData.
Decide qué debe suceder.
Llame a /api/apps/v1/action o a uno de los puntos finales de bloqueo más sencillos.
Opcionalmente, escriba un registro personalizado con /api/apps/v1/logs/custom.

Por ejemplo, un script puede comprobar timeRemainingSeconds, añadir tiempo cuando falla una regla y, a continuación, escribir un registro personalizado que explique lo sucedido.

Crear un token DEV​

Primera llamada: Compruebe el bloqueo actual.​

Ayudantes de bloqueo de datos​

Puntos finales de acción de bloqueo principal​

Agregar o quitar tiempo​

Congelar y descongelar​

Punto final de acción general​

Nombres de acciones compatibles​

Ejemplos de acciones útiles​

Registro de cerraduras personalizadas​

Comandos del dispositivo​

Cuerpo de la solicitud​

Comandos compatibles y sus parámetros​

shock.start​

shock.stop​

vibration.start​

vibration.stop​

all.stop​

shock.random.set​

shock.berserk.set​

Selección de dispositivos​

Respuestas​

Éxito (200)​

Falla​

Explicación de los escenarios de fallos más comunes.​

Errores comunes​

Patrón práctico​

Crear un token DEV

Primera llamada: Compruebe el bloqueo actual.

Ayudantes de bloqueo de datos

Puntos finales de acción de bloqueo principal

Agregar o quitar tiempo

Congelar y descongelar

Punto final de acción general

Nombres de acciones compatibles

Ejemplos de acciones útiles

Registro de cerraduras personalizadas

Comandos del dispositivo

Cuerpo de la solicitud

Comandos compatibles y sus parámetros

`shock.start`

`shock.stop`

`vibration.start`

`vibration.stop`

`all.stop`

`shock.random.set`

`shock.berserk.set`

Selección de dispositivos

Respuestas

Éxito (200)

Falla

Explicación de los escenarios de fallos más comunes.

Errores comunes

Patrón práctico