Heartbeat & masa tenggang offline

Model sinkronisasi lisensi bersifat pull: produk memanggil POST /v1/validate secara berkala untuk menyegarkan token dan mengetahui perubahan status (langganan diperpanjang, ditangguhkan, dicabut, entitlement berubah). Ini sumber kebenaran dan wajib diimplementasikan.

Berlanggan juga bisa push webhook keluar — license.issued / license.renewed / license.suspended — bila seller mengatur URL webhook pada produk. Anggap itu sebagai petunjuk berlatensi rendah agar kamu bisa bereaksi lebih cepat; ini tidak menggantikan POST /v1/validate.

Irama yang disarankan

Kondisi	Frekuensi validate
Normal	Sekali per hari, atau saat aplikasi start.
Mendekati token_expires_at	Percepat menjadi tiap beberapa jam.
Setelah gagal jaringan	Exponential backoff: 5m → 15m → 1j → …
status = rate_limited	Backoff lebih panjang; jangan retry ketat.

Selalu ganti token lokal dengan token dari respons terbaru.

Menangani produk offline

grace_days di respons menyatakan berapa hari produk boleh tetap berfungsi tanpa berhasil menghubungi server setelah token_expires_at lewat.

Logika yang disarankan di sisi produk:

token_exp    = token_expires_at dari respons terakhir
grace_days   = grace_days dari respons terakhir

if sekarang <= token_exp:
    JALAN NORMAL
elif sekarang <= token_exp + grace_days:
    JALAN NORMAL + tampilkan "perlu online untuk verifikasi lisensi"
else:
    BATASI sampai validate berhasil lagi

Simpan token, token_expires_at, grace_days, dan entitlement (beserta tanda tangannya) secara lokal & terenkripsi supaya keputusan di atas bisa diambil tanpa jaringan.

Perubahan status yang perlu ditangani

Dari respons	Arti	Aksi
active → grace	Langganan telat bayar tetapi masih dalam tenggang.	Tetap jalan; peringatan halus + ajak pengguna cek akun.
grace → active	Sudah dibayar/diperpanjang.	Hapus peringatan.
→ suspended / expired	Akses dicabut sementara/berakhir.	Kunci fitur berbayar.
→ revoked	Dicabut permanen.	Kunci; minta aktivasi ulang bila pengguna yakin ini keliru.
entitlements berubah	Plan di-upgrade/downgrade.	Terapkan batasan/fitur baru pada siklus berikutnya.

Jaringan gagal ≠ lisensi tidak valid

Bedakan dengan tegas:

• HTTP error / timeout → jangan ubah status; pakai state tepercaya terakhir dan hormati grace_days.
• HTTP 200 dengan status non-aktif → status resmi berubah; terapkan.

Deaktivasi saat uninstall

Panggil POST /v1/deactivate saat pengguna meng-uninstall atau memindahkan instalasi, agar seat langsung bebas dan pengguna tidak perlu melepasnya manual dari dashboard.