Ringkasan Activation API¶

API ini dipakai oleh produk on-premise (aplikasi yang diinstal pengguna) untuk mengaktifkan dan memvalidasi lisensi berbasis token. Endpoint internal (top-up, checkout, dashboard) tidak termasuk di sini.

Base URL & format¶

https://berlanggan.web.id/v1

Semua request & response JSON.
Semua endpoint aktivasi memakai POST dan selalu balas HTTP 200 — hasil ada di field status pada body (konvensi activation API).
Uang: Rupiah bulat; timestamp ISO-8601 UTC.

Dokumentasi interaktif (OpenAPI) tersedia di /v1/docs.

Autentikasi¶

Kredensial utama adalah kunci lisensi itu sendiri (license_key), model "license-key-as-credential" ala Keygen/Cryptlex.

Seller/produk dapat mengaktifkan secret produk tambahan. Bila aktif, sertakan header:

X-Berlanggan-Secret: <secret produk>

Jika secret tidak dikonfigurasi untuk produk tersebut, header boleh dihilangkan. Hubungi penerbit produk untuk mengetahui apakah secret diwajibkan.

Field respons (endpoint aktivasi)¶

Field	Arti
`status`	`active`, `grace`, `invalid`, `expired`, `revoked`, `suspended`, `seat_full`, `rate_limited`.
`token`	Token aktivasi bertanda tangan. Simpan; kirim lagi saat `validate`.
`expires_at` / `token_expires_at`	Kapan token perlu di-refresh (lewat `validate`).
`license_expires_at`	Kapan lisensi/langganan berakhir (`null` untuk lisensi abadi).
`grace_days`	Berapa hari produk boleh tetap jalan offline setelah token kedaluwarsa.
`entitlements`	Objek `kunci → nilai` untuk feature gating lokal, mis. `{"MAX_AGENTS": 10}`.
`entitlement`	Amplop entitlement kanonik yang ditandatangani.
`entitlement_signature`	Tanda tangan Ed25519 base64 atas `entitlement`.

status yang bisa dipakai produk sebagai "boleh jalan" adalah active dan grace. Selain itu, produk harus membatasi/menonaktifkan diri sesuai kebijakannya.

Status yang dapat dikembalikan¶

`status`	Makna	Tindakan produk
`active`	Lisensi valid.	Jalan normal.
`grace`	Valid tetapi dalam masa tenggang (mis. langganan telat bayar).	Jalan normal; peringatan halus.
`expired`	Periode lisensi berakhir.	Kunci fitur berbayar.
`suspended`	Ditangguhkan sementara (mis. tunggakan).	Kunci; minta pengguna cek akun.
`revoked`	Dicabut permanen.	Kunci.
`seat_full`	Semua seat terpakai.	Minta pengguna melepas perangkat lain.
`invalid`	Kunci/token salah atau rusak.	Minta aktivasi ulang.
`rate_limited`	Terlalu sering memanggil.	Backoff, coba lagi nanti.

Endpoint¶

Endpoint	Fungsi
`POST /v1/activate`	Daftarkan perangkat, terbitkan token.
`POST /v1/validate`	Heartbeat — validasi & refresh token.
`POST /v1/deactivate`	Lepaskan seat perangkat.
`POST /v1/operation-authorize`	Grant jangka pendek untuk operasi premium tertentu.
`GET /v1/catalog/products/{slug}/plans`	Daftar plan publik sebuah produk.

Rinci di Aktivasi, validasi & deaktivasi.

Webhook keluar¶

Berlanggan juga bisa push peristiwa license.issued / license.renewed / license.suspended ke endpoint produk (ditandatangani dengan X-Berlanggan-Signature). Lihat Webhook keluar.