Documentación de la API

Envía notificaciones a los empleados desde otros sistemas — scripts, cron de otros servidores, n8n, webhooks, bots de WhatsApp.

Obtén una clave API

Propietario: ve a Gestionar → 🔑 API Key, ponle un nombre, pulsa Crear clave.

La clave tiene la forma jss_ + 64 caracteres y solo se muestra una vez. El servidor solo guarda su huella, así que si la pierdes nadie puede volver a mostrártela — ni siquiera nosotros. Revoca la antigua, crea una nueva.

Guárdala en una variable de entorno o un archivo de configuración fuera del docroot. Nunca en código que se suba a git.

2 · Envía la clave

Cualquiera de estas dos cabeceras — elige la que sea más fácil para tu herramienta:

Authorization: Bearer jss_xxxxxxxx...

X-API-Key: jss_xxxxxxxx...

La clave determina la empresa. Ningún endpoint tiene un parámetro de tenant — si lo tuviera, una clave filtrada bastaría para enviar a todas las empresas de esta plataforma.

Aquí no hay protección CSRF, y eso es correcto. CSRF protege contra peticiones disparadas desde el navegador de otra persona aprovechando sus cookies. Las peticiones basadas en clave no llevan las cookies de nadie — no hay nada que aprovechar.

Qué puede hacer esta clave

Solo envía notificaciones a los empleados de la empresa propietaria, además de leer la lista de nombres + ids de empleados (para que tengas una forma de obtener user_id sin adivinar).

No puede leer el sueldo, la asistencia, el correo, la cuenta bancaria ni las notificaciones de nadie; no puede cambiar nada; no puede tocar otras empresas. Deliberadamente tan limitado — las credenciales que viven en otro servidor se filtrarán tarde o temprano, y cuánto daño hagan depende de cuán poco puedan hacer.

3 · Comprueba que la clave funciona

GET/api/v1/notif.php?aksi=ping

curl "https://staff.jidanshoppu.com/api/v1/notif.php?aksi=ping" \
  -H "Authorization: Bearer jss_xxx"

{ "ok": true, "key": "n8n produksi", "perusahaan": "Perusahaan Kamu" }

4 · Obtén la lista de empleados

GET/api/v1/notif.php?aksi=karyawan — para obtener user_id.

curl "https://staff.jidanshoppu.com/api/v1/notif.php?aksi=karyawan" \
  -H "Authorization: Bearer jss_xxx"

{
  "ok": true,
  "karyawan": [
    { "user_id": 3, "nama": "Sela",   "peran": "staff" },
    { "user_id": 5, "nama": "Syauqi", "peran": "staff" }
  ]
}

Solo id, nombre y rol. Sin correo/tarifa/cuenta bancaria — esta clave es para enviar notificaciones, no para leer datos de las personas.

5 · Envía una notificación

POST/api/v1/notif.php — acepta JSON o datos de formulario.

Campo	Obligatorio	Descripción
`judul`	sí	máx. 120 caracteres
`isi`	sí	máx. 255 caracteres
`user_id`	no	id del empleado. 0 u omitido = todos los empleados activos
`jenis`	no	`info` (por defecto), `kasbon` (adelanto), `gaji` (sueldo), `bonus`, `timer`, `absen` (asistencia). Solo determina el icono; los valores desconocidos caen en `info`
`url`	no	debe ser una ruta interna que empiece con `/`

A todos los empleados

curl -X POST https://staff.jidanshoppu.com/api/v1/notif.php \
  -H "Authorization: Bearer jss_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "judul": "Besok libur",
    "isi": "Tanggal 17 libur, timer tidak perlu dinyalakan."
  }'

{ "ok": true, "terkirim": 5 }

A una persona, con un enlace

curl -X POST https://staff.jidanshoppu.com/api/v1/notif.php \
  -H "X-API-Key: jss_xxx" \
  -d "user_id=3" \
  -d "judul=Cek transaksi kamu" \
  -d "isi=Ada penyesuaian baru bulan ini." \
  -d "jenis=gaji" \
  -d "url=/staff/transaksi.php"

url debe ser una ruta interna. https://… y //evil.com se rechazan con 400.

Motivo: una notificación con apariencia oficial que puede apuntar a cualquier lugar es la herramienta de phishing perfecta — los empleados hacen clic sin sospechar precisamente porque el portal es quien la entrega. Una clave filtrada basta para difundir "Haz clic para ver tu sueldo" hacia una página de login falsa.

//evil.com también se rechaza, aunque empiece con una barra: los navegadores lo leen como una dirección a otro host.

Qué pasa después de enviar

Los empleados con el portal abierto oyen un sonido y ven una ventana emergente en ≤20 segundos. Los que no lo tienen abierto serán recibidos la próxima vez que inicien sesión. Todo llega a su página de Notificaciones, y cada envío por API queda registrado en el registro de auditoría con el nombre de la clave.

Límite de tasa

60 peticiones por minuto por clave. Cada respuesta lleva:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57

Al superar el límite → 429 + Retry-After: 60.

Códigos de estado

Código	Significado
`200`	Correcto
`400`	Parámetro incorrecto, cuerpo JSON dañado, o `url` no es una ruta interna
`401`	Clave no enviada, incorrecta, o ya revocada
`404`	`user_id` no es empleado de esta empresa
`405`	Método incorrecto
`429`	Límite de tasa superado

Si falla

Síntoma	Suele deberse a
`401` aunque la clave es correcta	Algunos servidores eliminan la cabecera `Authorization` antes de que llegue a PHP. Prueba con `X-API-Key` — una cabecera normal que el servidor nunca toca. Si eso funciona pero Bearer no, avísanos.
`401` de repente, aunque antes funcionaba	El propietario revocó la clave. Revisa la página de API Key.
`400` "url debe ser una ruta interna"	Enviaste `https://…`. Usa `/staff/transaksi.php`.
`200` pero `"terkirim": 0`	El empleado no está activo, o la empresa aún no tiene empleados activos.

Limitaciones honestas

Esta API solo tiene notificaciones. No hay endpoint de asistencia, nómina ni adelantos. Cada adición significa que una clave filtrada se vuelve más peligrosa, así que cada una merece repensarse — no añadirse porque "ya que estamos".
No hay ámbitos (scopes) por clave. Todas las claves pueden hacer lo mismo. Mientras lo único que se pueda hacer sea enviar notificaciones, un scope solo añadiría una columna sin ninguna garantía real.
El límite de tasa es por clave, no por IP. Una clave filtrada sigue limitada a 60/minuto — pero 60 notificaciones por minuto a todos los empleados sigue siendo disruptivo. La verdadera defensa es revocar la clave, así que revisa la columna "último uso" y su IP en la página de API Key.

¿Necesitas que los empleados inicien sesión en tu app con su cuenta de JS Staff (no solo recibir notificaciones)? Eso es SSO — la guía de instalación está aquí.