API Access

API Access adalah halaman administrator untuk membuat token public API read-only bagi sistem eksternal.

Gunakan fitur ini saat sistem tepercaya lain perlu membaca data KartuStok seperti metadata perusahaan, item, warehouse, kategori barang, atau report stok. Contoh umum: dashboard BI, sinkronisasi ke data warehouse, middleware integrasi, atau alat monitoring internal.

Fungsi API Access

API Access dibuat untuk integrasi baca data.

Fitur ini cocok jika sistem eksternal perlu:

• membaca metadata perusahaan
• membaca master item
• membaca master warehouse
• membaca master kategori barang
• membaca data report stock summary atau stock detail

Fitur ini bukan untuk:

• membuat atau mengubah transaksi
• mengubah master data
• mengelola user, role, print template, atau email template

Jika tim hanya perlu pertukaran spreadsheet sesekali, import/export biasanya lebih sederhana daripada integrasi API.

Lokasi Menu dan Akses

Buka Manage -> Integrations -> API Access.

Aksi	Permission
Melihat token API	apiAccessView
Generate token	apiAccessCreate
Revoke token	apiAccessRevoke

Daftar Token

Daftar menampilkan:

Kolom	Arti
Name	Label integrasi, misalnya BI Dashboard atau ERP Sync.
Prefix	Bagian awal token untuk membantu identifikasi token di kemudian hari.
Scopes	Scope read yang diberikan ke token.
Status	Active atau Inactive.
Last Used	Waktu terakhir token dipakai, jika tersedia.
Expires	Tanggal expiry opsional.
Revoke	Aksi untuk menonaktifkan token.

Membuat API Access

Field	Arti
Name	Label integrasi, wajib diisi.
Expires At	Tanggal expiry opsional. Jika kosong, token tidak punya expiry date yang dikonfigurasi.
Scopes	Minimal satu scope harus dipilih.
Allowed IPs	IP allowlist opsional. Isi satu IP per baris atau pisahkan dengan koma. CIDR tidak didukung.

Scope yang tersedia:

Scope	Akses Data
meta.read	Metadata perusahaan dan health check
item.read	Daftar item dan detail item
category.read	Daftar kategori barang
locator.read	Daftar warehouse
stock.read	Report stock summary dan stock detail

Setelah memilih Generate Token, KartuStok menampilkan token lengkap satu kali di card Copy Token Now.

Penting: Token lengkap hanya ditampilkan satu kali. Jika tidak langsung disalin dan disimpan, buat token baru.

Cara Integrator Memakainya

Halaman ini juga menampilkan contoh penggunaan berdasarkan domain company yang sedang aktif:

• Public API base URL
• format bearer authorization header
• contoh request ke /public/v1/items

Public API selalu memakai domain frontend company, bukan domain member.kartustok.com.

Contoh:

https://company-anda.kartustok.com/public/v1

Handoff dari Admin ke Integrator

Gunakan alur ini saat administrator menyiapkan akses untuk developer atau vendor integrasi:

1. Buat token dengan nama integrasi yang jelas.
2. Pilih hanya scope yang memang dibutuhkan integrasi itu.
3. Isi Expires At jika akses tidak boleh permanen.
4. Isi Allowed IPs jika integrasi berjalan dari IP server yang stabil.
5. Copy token segera dan simpan di sistem tujuan.
6. Minta integrator mengetes health dulu, lalu meta/company, sebelum membaca item atau stok.

Buat satu token untuk satu integrasi. Jangan memakai token yang sama untuk beberapa sistem yang tidak berkaitan.

Referensi Teknis untuk Integrator

Gunakan file teknis berikut jika tim integrasi membutuhkan detail sampai level endpoint:

• Public API Integrator Guide
• OpenAPI Specification
• Postman Collection

Dokumen teknis itu menjelaskan:

• path endpoint
• query parameter
• kebutuhan scope
• public ID yang opaque
• contoh request dan response
• catatan kompatibilitas istilah warehouse (/locators, locator_id)
• transaction type report stok, termasuk ItemAssembly dan ItemDisassembly

Masalah Umum

Masalah	Perbaikan
Token hilang setelah dibuat	Ini normal. Token lengkap hanya tampil sekali. Buat token baru jika belum disimpan.
Sistem eksternal mendapat Unauthorized	Cek nilai bearer token, status token, expiry date, dan pastikan request memakai domain company.
Sistem eksternal mendapat Forbidden	Cek pilihan scope dan Allowed IPs.
Developer memakai member.kartustok.com	Public API harus memakai domain frontend company, misalnya https://your-subdomain.kartustok.com/public/v1.
Integrasi tidak boleh dipakai lagi	Revoke token dari daftar.

Praktik Keamanan

1. Buat satu token untuk satu integrasi.
2. Berikan scope sekecil mungkin sesuai kebutuhan.
3. Gunakan Allowed IPs jika integrasi berjalan dari infrastruktur yang stabil.
4. Revoke token yang tidak dipakai lagi.
5. Rotasi token saat vendor, server, atau kepemilikan kredensial berubah.
6. Simpan token di secret manager atau konfigurasi server-side, bukan di kode browser.