Documentação da API

Envie notificações aos funcionários de outros sistemas — scripts, cron de outros servidores, n8n, webhooks, bots do WhatsApp.

Obtenha uma chave de API

Proprietário: vá em Gerenciar → 🔑 Chave de API, dê um nome, clique em Criar chave.

A chave tem o formato jss_ + 64 caracteres e é mostrada apenas uma vez. O servidor guarda só a sua impressão digital, então se você a perder ninguém pode mostrá-la de novo — nem nós. Revogue a antiga, crie uma nova.

Guarde em uma variável de ambiente ou arquivo de configuração fora do docroot. Nunca em código versionado no git.

2 · Envie a chave

Um dos dois cabeçalhos abaixo — escolha o mais fácil para sua ferramenta:

Authorization: Bearer jss_xxxxxxxx...

X-API-Key: jss_xxxxxxxx...

A chave determina a empresa. Nenhum endpoint tem um parâmetro de tenant — se tivesse, uma chave vazada bastaria para enviar a todas as empresas nesta plataforma.

Não há proteção CSRF aqui, e isso está correto. CSRF protege contra requisições disparadas pelo navegador de outra pessoa aproveitando seus cookies. Requisições baseadas em chave não carregam cookie de ninguém — não há nada a aproveitar.

O que essa chave pode fazer

Só envia notificações aos funcionários da empresa proprietária, além de ler a lista de nomes + ids dos funcionários (para você ter como obter o user_id sem adivinhar).

Não pode ler o salário, presença, e-mail, conta bancária ou notificações de ninguém; não pode alterar nada; não pode tocar em outras empresas. Deliberadamente tão restrito — credenciais que vivem em outro servidor vazarão mais cedo ou mais tarde, e o quão pouco dano isso causa depende de quão pouco elas conseguem fazer.

3 · Verifique se a chave está ativa

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 · Obtenha a lista de funcionários

GET/api/v1/notif.php?aksi=karyawan — para obter o 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" }
  ]
}

Apenas id, nome e cargo. Sem e-mail/taxa/conta bancária — esta chave é para enviar notificações, não para ler dados das pessoas.

5 · Envie uma notificação

POST/api/v1/notif.php — aceita JSON ou dados de formulário.

Campo	Obrigatório	Descrição
`judul`	sim	máx. 120 caracteres
`isi`	sim	máx. 255 caracteres
`user_id`	não	id do funcionário. 0 ou omitido = todos os funcionários ativos
`jenis`	não	`info` (padrão), `kasbon` (adiantamento), `gaji` (salário), `bonus`, `timer`, `absen` (presença). Só determina o ícone; valores desconhecidos caem em `info`
`url`	não	deve ser um caminho interno que comece com `/`

Para todos os funcionários

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 }

Para uma pessoa, com um link

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 precisa ser um caminho interno. https://… e //evil.com são rejeitados com 400.

Motivo: uma notificação de aparência oficial que pode apontar para qualquer lugar é a ferramenta de phishing perfeita — os funcionários clicam sem desconfiar justamente porque foi o portal que a entregou. Uma chave vazada basta para transmitir "Clique para ver seu salário" para uma página de login falsa.

//evil.com também é rejeitado, mesmo começando com barra: os navegadores o leem como um endereço para outro host.

O que acontece após o envio

Funcionários com o portal aberto ouvem um som e veem um pop-up em ≤20 segundos. Os que não estão com ele aberto serão recebidos na próxima vez que entrarem. Tudo cai na página de Notificações deles, e cada envio pela API fica registrado no log de auditoria com o nome da chave.

Limite de taxa

60 requisições por minuto por chave. Cada resposta traz:

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

Ao exceder o limite → 429 + Retry-After: 60.

Códigos de status

Código	Significado
`200`	Sucesso
`400`	Parâmetro errado, corpo JSON quebrado, ou `url` não é um caminho interno
`401`	Chave não enviada, errada, ou já revogada
`404`	`user_id` não é funcionário desta empresa
`405`	Método errado
`429`	Limite de taxa excedido

Se falhar

Sintoma	Geralmente causado por
`401` mesmo com a chave correta	Alguns servidores removem o cabeçalho `Authorization` antes que chegue ao PHP. Tente `X-API-Key` — um cabeçalho comum que o servidor nunca toca. Se isso funcionar mas Bearer não, avise-nos.
`401` do nada, mesmo funcionando antes	O proprietário revogou a chave. Verifique na página de Chave de API.
`400` "url precisa ser um caminho interno"	Você enviou `https://…`. Use `/staff/transaksi.php`.
`200` mas `"terkirim": 0`	O funcionário não está ativo, ou a empresa ainda não tem funcionários ativos.

Limitações honestas

Esta API só tem notificações. Não há endpoint de presença, folha de pagamento ou adiantamento. Cada adição significa que uma chave vazada fica mais perigosa, então cada uma merece ser repensada — não adicionada só porque "já que estamos nisso".
Sem escopos por chave. Todas as chaves podem fazer a mesma coisa. Enquanto a única capacidade for enviar notificações, um escopo seria só uma coluna extra sem nenhuma garantia real.
O limite de taxa é por chave, não por IP. Uma chave vazada ainda fica limitada a 60/minuto — mas 60 notificações por minuto para todos os funcionários ainda é perturbador. A defesa de verdade é revogar a chave, então confira a coluna "último uso" e o IP na página de Chave de API.

Precisa que os funcionários façam login no seu app com a conta JS Staff (não só receber notificações)? Isso é SSO — o guia de configuração está aqui.