Kunci API
Kunci API membuka data Acosys Anda untuk aplikasi, skrip, atau agent AI buatan sendiri, misalnya n8n, Make, Python, atau Claude/ChatGPT dengan function calling. Satu API yang sama berlaku untuk semua form Acosys, ditambah laporan siap pakai yang sama dengan Asisten AI, dan hak akses setiap kunci sama persis dengan role yang Anda pilih saat membuatnya.
API hanya tersedia di layanan cloud Acosys (<tenant>.acosys.co.id), tidak di instalasi sendiri (self-hosted) dan tidak di akun demo.
Kapan Dipakai
- Pesanan dari WhatsApp, marketplace, atau formulir web ingin langsung menjadi Faktur Penjualan atau Order Penjualan tanpa diketik ulang.
- Agent AI perlu membaca stok, harga, piutang, atau riwayat transaksi untuk menjawab pelanggan atau menyusun laporan.
- Data master (pelanggan, produk, pemasok) perlu disinkronkan dengan sistem lain secara terjadwal.
- Dasbor sendiri, laporan terjadwal, atau agent AI butuh angka penjualan, piutang, hutang, stok, arus kas, atau laba rugi yang dihitung sama dengan layar laporan Acosys.
Syarat
- Langganan berbayar Anda berlaku minimal 6 bulan ke depan (bawaan) pada saat kunci dibuat. Syarat ini hanya diperiksa saat membuat kunci; kunci yang sudah ada tetap jalan selama langganan aktif.
- Role Anda memegang menu Kunci API atau Daftar User.
- Akun demo (
demo*.acosys.co.id) tidak bisa membuat maupun memakai kunci API, karena akun demo dipakai bersama oleh siapa saja.
Membuat Kunci
- Buat dulu role khusus untuk integrasi ini di Daftar Role User, dengan menu, divisi, gudang, dan hak tabel sesempit mungkin. Jangan memakai role administrator.
- Buka menu Pengaturan / User & Hak Akses / Kunci API, lalu klik Kunci baru.
- Isi Nama kunci sebagai penanda (misalnya
n8n gudang), pilih Role, lalu pilih Cakupan: Baca saja atau Baca dan tulis. - Opsional: isi Berlaku sampai agar kunci kedaluwarsa sendiri, dan IP yang diizinkan (IP atau CIDR, dipisah koma) bila server Anda punya IP tetap.
- Klik Buat kunci, lalu salin kuncinya. Kunci hanya ditampilkan sekali; yang tersimpan di Acosys hanya sidik jarinya.
- Setelah Anda menekan Sudah saya simpan, Panduan Developer API langsung terbuka, lengkap dengan alamat API tenant Anda. Panduan ini bisa dibuka lagi kapan saja lewat tombol Dokumentasi API.
Alamat dan Autentikasi
Setiap tenant punya alamat API sendiri. Kunci berbentuk acsk_<tenant>_<40 karakter> dan hanya berlaku di subdomain tenantnya.
https://<tenant>.acosys.co.id/api/v1/
Authorization: Bearer acsk_<tenant>_xxxxxxxx
curl https://<tenant>.acosys.co.id/api/v1/me -H "Authorization: Bearer $ACOSYS_API_KEY"
Spesifikasi OpenAPI lengkap tersedia tanpa kunci di https://<tenant>.acosys.co.id/api/v1/openapi, dan bisa diimpor langsung ke Postman, n8n, atau dipakai sebagai daftar tool agent AI.
Yang Bisa Dilakukan
| Permintaan | Fungsi |
|---|---|
GET /v1/me | Identitas kunci, role, cakupan, sisa kuota gratis, dan tarif. |
GET /v1/forms | Daftar form yang boleh dipakai kunci ini, termasuk bisa ditulis atau tidak. |
GET /v1/forms/{form}/schema | Kolom satu form: jenis, wajib, panjang, pilihan, rincian, dan kolom yang dihitung. |
GET /v1/forms/{form} | Daftar data dengan pencarian (q), filter sama-dengan (filter[kolom]), urutan, dan halaman berikutnya lewat cursor; maksimal 200 baris per halaman. |
GET /v1/forms/{form}/{id} | Satu dokumen beserta rinciannya. Nomor dokumen bergaris miring (misalnya I/SL-000123) boleh dikirim apa adanya. |
POST /v1/forms/{form} | Membuat data atau dokumen beserta rinciannya. Wajib membawa header Idempotency-Key. |
PATCH /v1/forms/{form}/{id} | Mengubah kolom tertentu pada data yang sudah ada. |
GET /v1/tools | Daftar laporan siap pakai yang boleh dipakai kunci ini, beserta skema argumennya. |
POST /v1/tools/{name} | Menjalankan satu laporan siap pakai (hanya membaca). Lihat Laporan Siap Pakai. |
- Semua form yang bisa diakses role kunci bisa dibaca, dibuat, dan diubah lewat API. Batasnya sama dengan layar: menu role, hak tabel role, divisi dan gudang role, serta cakupan kunci. Data langganan pusat tidak bisa diakses.
- API menyimpan lewat jalur yang sama dengan layar: aturan form, kunci periode tutup buku, persetujuan, dan cek stok tetap berlaku. Nomor dokumen dibuat otomatis dari format nomor divisi bila tidak dikirim.
- Kolom yang tidak dikirim diisi nilai bawaan form, sama seperti membuka form baru di layar. Kolom sandi boleh dikirim (disimpan ter-hash) tetapi tidak pernah keluar saat dibaca.
- Angka yang di layar dihitung browser (bruto, netto, total) dikirim sendiri oleh aplikasi Anda, kecuali untuk Faktur Penjualan.
- Setiap dokumen yang dibuat atau diubah lewat API tercatat dengan pembuat
api:<nomor kunci>, jadi mudah dibedakan dari input manual.
Faktur Penjualan Dihitung Server
Untuk Faktur Penjualan cukup kirim pelanggan, produk, dan jumlah. Harga, diskon, pajak, HPP, termin, dan total dihitung server dengan aturan yang sama dengan layar: harga nego pelanggan, level harga, harga grosir, diskon satuan dan aturan diskon, serta pajak produk. Limit kredit dan stok (bila role memeriksa stok) ikut diperiksa, lalu faktur langsung diposting ke jurnal, stok, dan piutang, atau menunggu persetujuan bila perusahaan mewajibkannya.
curl -X POST https://<tenant>.acosys.co.id/api/v1/forms/sales \
-H "Authorization: Bearer $ACOSYS_API_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: pesanan-wa-8841" \
-d '{"customerid":"C002","salesdetail":[{"productid":"KOPI-250","salesqty":10}]}'
Pembayaran di faktur, uang muka, nomor seri, dan sewa belum didukung jalur hitung server ini.
Laporan Siap Pakai
Laporan yang dipakai Asisten AI juga tersedia lewat API: ringkasan penjualan, piutang, hutang, persediaan, arus kas, laba rugi, produk terlaris, ikhtisar kinerja, perbandingan dua periode, dan pemeriksaan penjualan bulanan. Total dan ringkasan dihitung server dari seluruh baris laporan dengan definisi yang sama dengan layar laporan, jadi aplikasi atau agent AI Anda tidak perlu menjumlahkan sendiri.
curl https://<tenant>.acosys.co.id/api/v1/tools -H "Authorization: Bearer $ACOSYS_API_KEY"
curl -X POST https://<tenant>.acosys.co.id/api/v1/tools/sales_summary \
-H "Authorization: Bearer $ACOSYS_API_KEY" -H "Content-Type: application/json" \
-d '{"period":"last_month","currtrans":"IDR"}'
- Laporan yang muncul mengikuti role kunci: menu laporan yang dimiliki role dan modul yang termasuk paket Anda. Role kunci tidak perlu izin Asisten AI.
- Batas divisi, gudang, dan grup role ditegakkan server dan menimpa argumen yang dikirim. Bagian
filterdi jawaban menunjukkan filter yang benar-benar dipakai. - Tanggal diisi dengan
period(misalnyathis_month,last_month,this_year,last_30_days) ataudate_fromdandate_to. Kode divisi, salesman, atau mata uang bisa dicari denganlookup_filter_options. summaryselalu utuh. Rinciandatapaling banyak 40 baris;truncated: trueberarti masih ada baris lain. Untuk mengambil semua dokumen, pakaiGET /v1/forms/{form}yang berhalaman.- Laporan hanya membaca: kueri SQL bebas dan fungsi pengubah data Asisten AI tidak dibuka lewat API.
Pengiriman Ulang yang Aman
Setiap POST wajib membawa Idempotency-Key yang unik per dokumen, misalnya UUID. Bila jaringan putus dan permintaan diulang dengan kunci yang sama, Anda menerima jawaban pertama (header Idempotent-Replay: true), bukan dokumen kedua. Kunci yang sama dengan isi berbeda ditolak 409.
Batas dan Biaya
API tidak memerlukan langganan tambahan. Pemakaiannya dihitung per permintaan. Angka di bagian ini adalah bawaan; angka yang berlaku untuk tenant Anda tampil di dialog Dokumentasi API pada menu Kunci API dan di GET /v1/me.
- Kuota gratis bawaan 1.000 permintaan berhasil per bulan per tenant.
- Di atas kuota, pemakaian memotong saldo token Acosys, saldo yang sama dengan Asisten AI.
- Permintaan yang gagal tidak dihitung dan tidak ditagih.
- Tagihan dihitung sekali sehari, sesudah tengah malam, untuk pemakaian hari sebelumnya.
| Jenis permintaan | Token bawaan per permintaan (di atas kuota) |
|---|---|
/me, /forms, schema, /tools, openapi | 0 (gratis) |
| Membaca satu dokumen | 1 |
| Membaca daftar | 2 |
Membuat atau mengubah (POST, PATCH) | 5 |
Menjalankan laporan siap pakai (POST /v1/tools/{name}) | 20 (pencarian kode filter 2, jumlah siswa aktif 1) |
- Bila kuota gratis bulan ini habis dan saldo token kosong, API menjawab
402 INSUFFICIENT_TOKENsampai saldo diisi atau bulan berganti. - Batas laju bawaan: 60 permintaan per menit dan 5.000 per hari per kunci. Melewatinya dijawab
429dengan headerRetry-After. - Sisa kuota, batas laju, dan tarif yang berlaku selalu bisa dilihat di
GET /v1/me.
Galat yang Sering Muncul
Semua galat berbentuk sama: {"error":{"code":"...","message":"...","fields":[...]}}. Untuk agent AI: baca fields[].field dan message, perbaiki permintaan, lalu kirim ulang dengan Idempotency-Key baru.
| HTTP | Kode | Arti |
|---|---|---|
| 400 | IDEMPOTENCY_KEY_REQUIRED, INVALID_JSON | Header atau badan permintaan tidak lengkap. |
| 401 | API_KEY_REQUIRED, INVALID_API_KEY, IP_NOT_ALLOWED, ROLE_NOT_FOUND | Kunci tidak dikirim, salah, dicabut, kedaluwarsa, dipakai dari IP lain, atau role-nya sudah dihapus. |
| 402 | INSUFFICIENT_TOKEN | Kuota gratis bulan ini habis dan saldo token kosong. |
| 403 | SCOPE_REQUIRED, ROLE_FORBIDDEN, FORM_WRITE_NOT_AVAILABLE | Cakupan kunci atau hak role tidak mengizinkan, atau form berupa tampilan yang tidak bisa ditulis. |
| 403 | DEMO_TENANT, API_NOT_AVAILABLE | Dipanggil di akun demo, atau di instalasi yang bukan layanan cloud. |
| 404 | FORM_NOT_FOUND, NOT_FOUND, TOOL_NOT_FOUND | Form, data, atau laporan siap pakai tidak ada, atau tidak terlihat oleh role kunci. |
| 409 | IDEMPOTENCY_MISMATCH, IDEMPOTENCY_IN_PROGRESS | Idempotency-Key bentrok dengan permintaan lain. |
| 421 | WRONG_HOST | Kunci dipakai di luar subdomain tenantnya. |
| 422 | VALIDATION_FAILED, CREDIT_LIMIT_EXCEEDED, SAVE_REJECTED, NUMBERING_NOT_CONFIGURED | Data ditolak; fields dan message menunjuk kolom atau baris yang salah. |
| 422 | TOOL_REJECTED | Argumen laporan ditolak; message menyebut argumen yang salah dan yang tersedia. |
| 429 | RATE_LIMITED | Terlalu cepat; tunggu sesuai header Retry-After. |
| 500 | TOOL_FAILED | Laporan gagal dijalankan di server. |
Keamanan
- Satu role khusus untuk setiap integrasi, dengan menu dan hak sesempit mungkin. Mengubah role langsung mengubah hak semua kunci yang memakainya; menghapus role mematikan kuncinya.
- Pilih Baca saja bila integrasi tidak perlu menulis.
- Isi IP yang diizinkan dan Berlaku sampai bila memungkinkan.
- Kolom Terakhir dipakai di daftar kunci membantu menemukan kunci yang tidak dipakai lagi; cabut kunci seperti itu.
Masalah Umum
- Menu Kunci API tidak tampil: menu ini hanya ada di layanan cloud Acosys, tidak di akun demo, dan role Anda harus memegang menu Kunci API atau Daftar User.
- Gagal membuat kunci karena langganan: perpanjang langganan sampai tanggal yang disebut pesan galatnya (bawaan 6 bulan ke depan) lewat menu Upgrade / Perpanjang Tenant, lalu coba lagi.
- Jawaban
421 WRONG_HOST: panggil API di alamat tenant Anda sendiri,https://<tenant>.acosys.co.id/api/v1/, bukan alamat lain. - Data tidak muncul padahal ada di layar: kunci mengikuti divisi, gudang, dan grup role-nya; data di luar cakupan role tidak terlihat.
- Laporan tidak ada di
GET /v1/tools: tambahkan menu laporannya ke role kunci (misalnya Laporan Laba Rugi), dan pastikan modulnya termasuk paket Anda (Laba Rugi dan Arus Kas butuh modul akuntansi, Piutang butuh modul transaksi kredit).
Lokasi Menu
- Pengaturan / User & Hak Akses / Kunci API
/apikeys