Pengesahan

FreeMaint menerima dua mekanisme pengesahan: JWT (dikeluarkan oleh /auth/login, digunakan oleh aplikasi web dan mudah alih kami) dan kunci API (dicipta di /company-settings/api, digunakan oleh integrasi anda sendiri).

JWT (sesi pengguna)

1. POST /auth/login — Badan: {email, password}. Memulangkan {access_token, refresh_token}.
2. Hantar pengepala Authorization — Pada setiap permintaan: Authorization: Bearer <access_token>.
3. Segarkan semula apabila luput — POST /auth/refresh dengan refresh_token untuk mendapatkan access_token baharu. Token akses bertahan 2 jam.

Kunci API (integrasi pelayan)

1. Buka /company-settings/api atau /profile/api-keys — Pentadbir mencipta kunci di Tetapan Syarikat > API, mulai pelan Business ke atas. Orang yang peranannya mempunyai kebenaran “Mencipta kunci API peribadi” mencipta kunci mereka sendiri di Profil > Keselamatan > Kunci API. Peranan dengan kebenaran "Mengurus integrasi" (contohnya templat Pentadbir integrasi) boleh mencipta, membatalkan dan memadam kunci syarikat tanpa menjadi pentadbir; hanya pentadbir boleh menyerahkan kunci kepada orang lain.
2. Klik 'Kunci Baharu' — Secara pilihan, tetapkan tarikh luput dan tahap capaian (Baca sahaja secara lalai). Kunci mentah dipaparkan SEKALI SAHAJA — salinnya dengan segera.
3. Gunakannya — Hantar Authorization: Bearer fmk_<rawKey> pada setiap permintaan. Format: bermula dengan fmk_ diikuti 32 aksara heksadesimal.

Nota keselamatan

• Kunci API disimpan sebagai hash SHA-256 — setelah anda menutup dialog paparan, nilai mentah tidak boleh dipulihkan
• Membatalkan kunci akan menyahaktifkannya serta-merta; baris tersebut dikekalkan untuk audit
• Setiap kunci milik satu syarikat sahaja dan hanya mencapai data syarikat itu — rekod syarikat lain dianggap tidak dijumpai
• Kunci boleh mempunyai expiresAt pilihan untuk integrasi jangka pendek
• Tahap capaian, iaitu had siling di atas kebenaran pemilik: READ (lalai — pertanyaan sahaja), READ_STOCK (pertanyaan + adjustStock — sesuai untuk kiosk penggunaan sahaja), FULL (setiap operasi yang dibenarkan oleh peranan pemilik)
• Setiap kunci bertindak sebagai pemiliknya: setiap panggilan membawa kebenaran dan keterlihatan data pemiliknya, dan apa yang ditulisnya ditandatangani dengan nama pemiliknya. Jika pemilik dinyahaktifkan, kunci ditolak (401, kod API_KEY_OWNER_INACTIVE) sehingga pentadbir menyerahkannya kepada orang lain di Tetapan Syarikat > API — nilai kunci tidak berubah.

Menguji integrasi

Tiada persekitaran sandbox yang berasingan: kunci API sentiasa mencapai data sebenar syarikat pemiliknya. Ada dua cara untuk menguji dengan selamat. (1) Gunakan syarikat kedua sebagai syarikat ujian — pengasingan antara syarikat ialah mekanisme yang sama yang memisahkan setiap pelanggan, jadi apa sahaja yang anda lakukan di sana tidak boleh mencapai data pengeluaran anda. Kunci API memerlukan pelan Business, jadi syarikat itu juga mesti berada pada Business: syarikat percuma tidak boleh mencipta kunci. (2) Untuk kerja baca sahaja, cipta kunci dengan tahap akses READ: ia boleh menjalankan setiap pertanyaan dan tiada mutasi, jadi ia langsung tidak boleh mengubah apa-apa. Apabila anda bersedia untuk menulis, kunci READ_STOCK hanya membenarkan adjustStock.