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

Syarat

Membuat Kunci

  1. Buat dulu role khusus untuk integrasi ini di Daftar Role User, dengan menu, divisi, gudang, dan hak tabel sesempit mungkin. Jangan memakai role administrator.
  2. Buka menu Pengaturan / User & Hak Akses / Kunci API, lalu klik Kunci baru.
  3. Isi Nama kunci sebagai penanda (misalnya n8n gudang), pilih Role, lalu pilih Cakupan: Baca saja atau Baca dan tulis.
  4. Opsional: isi Berlaku sampai agar kunci kedaluwarsa sendiri, dan IP yang diizinkan (IP atau CIDR, dipisah koma) bila server Anda punya IP tetap.
  5. Klik Buat kunci, lalu salin kuncinya. Kunci hanya ditampilkan sekali; yang tersimpan di Acosys hanya sidik jarinya.
  6. 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.
Simpan kunci seperti kata sandi. Bila bocor, klik Cabut pada kunci itu; aplikasi yang memakainya langsung berhenti. Lalu buat kunci baru.

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

PermintaanFungsi
GET /v1/meIdentitas kunci, role, cakupan, sisa kuota gratis, dan tarif.
GET /v1/formsDaftar form yang boleh dipakai kunci ini, termasuk bisa ditulis atau tidak.
GET /v1/forms/{form}/schemaKolom 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/toolsDaftar 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.

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"}'

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.

Jenis permintaanToken bawaan per permintaan (di atas kuota)
/me, /forms, schema, /tools, openapi0 (gratis)
Membaca satu dokumen1
Membaca daftar2
Membuat atau mengubah (POST, PATCH)5
Menjalankan laporan siap pakai (POST /v1/tools/{name})20 (pencarian kode filter 2, jumlah siswa aktif 1)

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.

HTTPKodeArti
400IDEMPOTENCY_KEY_REQUIRED, INVALID_JSONHeader atau badan permintaan tidak lengkap.
401API_KEY_REQUIRED, INVALID_API_KEY, IP_NOT_ALLOWED, ROLE_NOT_FOUNDKunci tidak dikirim, salah, dicabut, kedaluwarsa, dipakai dari IP lain, atau role-nya sudah dihapus.
402INSUFFICIENT_TOKENKuota gratis bulan ini habis dan saldo token kosong.
403SCOPE_REQUIRED, ROLE_FORBIDDEN, FORM_WRITE_NOT_AVAILABLECakupan kunci atau hak role tidak mengizinkan, atau form berupa tampilan yang tidak bisa ditulis.
403DEMO_TENANT, API_NOT_AVAILABLEDipanggil di akun demo, atau di instalasi yang bukan layanan cloud.
404FORM_NOT_FOUND, NOT_FOUND, TOOL_NOT_FOUNDForm, data, atau laporan siap pakai tidak ada, atau tidak terlihat oleh role kunci.
409IDEMPOTENCY_MISMATCH, IDEMPOTENCY_IN_PROGRESSIdempotency-Key bentrok dengan permintaan lain.
421WRONG_HOSTKunci dipakai di luar subdomain tenantnya.
422VALIDATION_FAILED, CREDIT_LIMIT_EXCEEDED, SAVE_REJECTED, NUMBERING_NOT_CONFIGUREDData ditolak; fields dan message menunjuk kolom atau baris yang salah.
422TOOL_REJECTEDArgumen laporan ditolak; message menyebut argumen yang salah dan yang tersedia.
429RATE_LIMITEDTerlalu cepat; tunggu sesuai header Retry-After.
500TOOL_FAILEDLaporan gagal dijalankan di server.

Keamanan

Masalah Umum

Lokasi Menu