API: membaca buku ini dari sistem lain
Cara sebuah program menarik data perusahaan Anda — token, alamatnya, bentuk jawabannya, dan apa arti setiap penolakan.
±7 menit baca
Sebuah program lain — kasir di toko, marketplace, lembar kerja yang menarik angka setiap pagi — bisa membaca buku perusahaan ini tanpa seorang pun menyalin data dengan tangan. Jalannya API: alamat web yang mengembalikan data sebagai JSON, bukan sebagai halaman. Untuk masuk, API memakai TOKEN yang Anda terbitkan sendiri di layar Token API — bukan nama pengguna dan kata sandi.
API juga menyediakan jalur migrasi: mengisi atau memperbarui master pelanggan, pemasok, barang, dan bagan akun. Master tidak membawa nominal; plafon kredit diisi di aplikasi. Saldo awal lewat API belum tersedia dan akan menyusul dengan nominal sebagai string desimal. Bentuk masukan lengkap tersedia dalam spesifikasi mesin di bawah.
Mencatat Kas dan Bank lewat API
POST /api/v1/cash-movements memerlukan izin cash.write dan scope cash-movements:write bila token memakai scope. Kirim Idempotency-Key (1–128 karakter) dan direction (in atau out), bankAccountId (ID master rekening bank, bukan akun COA), counterAccountId, date (YYYY-MM-DD), currency, amount, rate, description. amount dan rate wajib string desimal positif, bukan angka JSON; IDR wajib rate 1. Contoh CNY: amount 0.03 dan rate 100.5 menghasilkan baseAmount IDR 3.02 dengan ROUND_HALF_UP. Tidak membuat akun atau mengubah pemetaan.
Respons 201 memuat id, direction, bankAccountId, counterAccountId, date, currency, amount, rate, baseAmount dan description. Gerakan kas dan jurnal seimbang tersimpan bersama; kegagalan membatalkan keduanya. Rekening dan akun lawan wajib aktif di buku PT token; mata uang rekening harus cocok dan akun rekening bertipe cash_bank. Periode tutup: 409 period_closed sebelum penulisan. Masukan salah: 422 invalid_fields, invalid_bank_account atau invalid_counter_account. Kunci hilang: 422 idempotency_key_required; kunci dipakai ulang dengan body atau endpoint berbeda: 422 idempotency_conflict. Kunci dan byte body sama mengulang respons tersimpan tanpa posting kedua. Maksimum body 16 KiB (413 too_large); autentikasi/izin/laju memakai 401/403/429; kegagalan internal 500 migration_failed. Skema lengkap ada di OpenAPI.
Token BERPERAN, jadi izinnya bukan izin baru
Token diterbitkan sebagai salah satu peran di perusahaan ini. Izin efektif peran menjadi batas tertingginya, termasuk ketika modul dimatikan atau izin peran ditimpa. Scope opsional hanya mempersempit akses itu. Langganan hanya-baca, pembekuan pemindahan buku, dan buku contoh juga menolak tulisan mesin.
- Terbitkan token untuk peran yang PALING SEDIKIT cukup. Sebuah penarik faktur tidak perlu peran yang juga boleh melihat gaji.
- Satu token per sistem yang menyambung, bukan satu untuk semuanya — kalau salah satu bocor, yang dicabut hanya yang itu.
- Token diperlihatkan sekali saat diterbitkan; yang tersimpan hanya sidik jarinya. Yang hilang tidak bisa dilihat lagi, hanya dicabut lalu diterbitkan ulang.
- Token baru wajib memiliki expiresAt, maksimum 90 hari; token lama mendapat batas yang lebih akhir antara 90 hari sejak diterbitkan dan 30 hari sejak migration. Penerbit menerima pengingat dalam aplikasi H-14 dan H-3. Respons data untuk token sah menyertakan Sai-Token-Expires-At (ISO 8601). Pencabutan berlaku pada permintaan berikutnya. Rotasi menerbitkan token baru dan mencabut yang lama dalam satu transaksi.
Perusahaannya ditentukan token, bukan alamat
Alamat API tidak memuat nama tenant maupun nama perusahaan. Sebuah token diterbitkan DI DALAM satu perusahaan dan selamanya membaca buku perusahaan itu saja. Konsekuensinya: kalau Anda memegang tiga perusahaan, Anda memerlukan tiga token, dan sebuah program yang menarik ketiganya menyimpan ketiganya. Itu disengaja — alamat yang bisa menyebut perusahaan lain adalah satu salah ketik antara buku yang benar dan buku tetangganya.
Satu permintaan, dari awal sampai jawabannya
Token dikirim di header Authorization dengan skema Bearer. Tidak ada bentuk lain: tidak lewat parameter kueri (ia tercatat di log server dan riwayat peramban), tidak lewat cookie.
curl -H "Authorization: Bearer sai_12_xxxxxxxxxxxxxxxxxxxxxxxx" \
"https://buku.contoh.co.id/api/v1/customers?limit=50&offset=0"Jawaban daftar GET berbentuk sama: sebuah larik `data`, dan sebuah `meta` yang memberi tahu ada berapa seluruhnya dan apakah masih ada halaman berikutnya.
{
"data": [
{ "id": 7, "name": "PT Contoh Sejahtera", "isActive": true, "updatedAt": "2026-08-21T09:14:02.000Z" }
],
"meta": { "total": 128, "limit": 50, "offset": 0, "hasMore": true }
}- Ambil `meta.hasMore` apa adanya; jangan menghitung sendiri dari `total` dan `limit`. Yang menghitung sendiri berhenti satu halaman terlalu awal, diam-diam, dan kehilangan baris terakhir setiap kali.
- Nilai kueri yang salah ditolak, bukan diperbaiki: `?limit=abc` menjawab 400, bukan diam-diam kembali ke bawaan. Parameter yang salah ketik tetapi tetap dijawab “berhasil” menghasilkan program yang tampak bekerja sambil menarik halaman yang salah selama berbulan-bulan.
- `limit` di atas batas juga ditolak, bukan dipotong — penarik yang meminta 10.000 lalu menerima 200 tanpa diberi tahu akan menyimpulkan datanya memang cuma 200.
- Tidak ada bentuk “kembalikan semuanya”. Daftar yang muat hari ini adalah daftar yang tidak muat setelah pelanggan keseratus.
Menulis dengan aman saat mengulang permintaan
Setiap POST Bearer wajib membawa Idempotency-Key sepanjang 1–128 karakter. Gunakan kunci dan body yang persis sama saat mengulang: selama tujuh hari jawaban tersimpan dikembalikan tanpa menjalankan mutasi lagi. Kunci sama dengan body atau endpoint berbeda ditolak 422. Koreksi masukan memakai kunci baru. Batch master paling banyak 1000 baris dan mengembalikan hasil per baris; hanya kolom yang dikirim berubah, sementara deactivateMissing menonaktifkan yang tidak tercakup batch tanpa menghapus riwayat.
Endpoint yang ada hari ini
Endpoint yang tersedia
| Alamat | Isinya | Izin yang dituntut |
|---|---|---|
| POST /api/v1/cash-movements | Catat penerimaan atau pengeluaran Kas dan Bank | cash.write |
| POST /api/v1/customers:upsert | Upsert pelanggan | customer.write |
| POST /api/v1/suppliers:upsert | Upsert pemasok | supplier.write |
| POST /api/v1/items:upsert | Upsert barang | inventory.write |
| POST /api/v1/accounts:upsert | Upsert bagan akun | account.manage |
| POST /api/v1/opening-balances | Posting saldo awal | setup.manage |
| POST /api/v1/opening-balances:reopen | Buka ulang saldo awal | setup.manage |
| POST /api/v1/documents:upload | Unggah dokumen kontrak | document.write |
| GET /api/v1/customers | Daftar pelanggan | customer.read |
| GET /api/v1/suppliers | Daftar pemasok | supplier.read |
| GET /api/v1/items | Daftar barang | inventory.read |
| GET /api/v1/accounts | Bagan akun | account.read |
| GET /api/v1/invoices | Daftar faktur penjualan | invoice.read |
Menarik hanya yang berubah
Setiap baris membawa `updatedAt`, dan setiap daftar menerima `?updatedSince=` berisi waktu ISO-8601. Simpan `updatedAt` tertinggi yang pernah Anda terima, lalu kirimkan kembali pada penarikan berikutnya: yang datang hanya yang berubah sejak itu. Itulah selisih antara satu permintaan kecil per jam dan seluruh daftar per jam — dan pada buku yang sudah besar, selisih antara integrasi yang tetap cepat dan integrasi yang lama-lama ditinggalkan orang.
curl -H "Authorization: Bearer $SAI_TOKEN" \
"https://buku.contoh.co.id/api/v1/invoices?updatedSince=2026-08-21T09:14:02Z&limit=200"Urutannya `updatedAt` menaik dengan `id` sebagai pemutus seri. Itu yang membuat penarikan bertahap tidak pernah melewatkan atau menggandakan baris ketika dua dokumen berubah pada detik yang sama.
Kalau jawabannya bukan 200
- 400 — permintaannya yang salah: parameter yang bukan angka, tanggal yang tidak terbaca, `limit` di luar batas. Pesannya menyebut parameter mana.
- 401 — kredensialnya bermasalah: tidak ada, salah, sudah dicabut, atau kedaluwarsa. Semuanya dijawab sama persis, dan itu disengaja. Jawaban yang membedakan ketiganya akan menjadikan endpoint ini alat untuk menebak token yang masih hidup.
- 403 — tokennya sah, tetapi perannya tidak berhak. Jawabannya menyebut izin yang kurang, supaya yang perlu diminta adalah token berperan lain, bukan tebakan peran satu per satu.
- 409 — keadaan buku menolak perubahan, misalnya periode tutup atau dokumen sudah dilunasi. Data bisnis tidak berubah. 422 — masukan tidak sah atau kunci idempotensi bertabrakan; perbaikan masukan memakai kunci baru.
- 429 — terlalu banyak permintaan. Batasnya dihitung per TOKEN, bukan per alamat IP: dua sistem dengan tokennya masing-masing tidak saling menghabiskan jatah, dan satu program yang mengamuk tidak mematikan yang lain.
- Ulangi permintaan yang gagal karena 429 atau galat jaringan dengan jeda yang membesar, bukan seketika. Penarik yang mengulang tanpa jeda adalah penarik yang menghabiskan jatahnya sendiri lalu menyalahkan servernya.
Spesifikasi mesin, untuk yang membangkitkan kode
Seluruh bentuk di atas juga tersedia sebagai dokumen OpenAPI 3.1 di alamat `/api/v1/openapi.json` — setiap endpoint, setiap kolom, setiap tipe, beserta izin yang dituntutnya. Ia bisa dibuka pembangkit klien (kode penarik yang ditulis mesin), penguji API, atau alat dokumentasi apa pun yang membaca OpenAPI.
Yang tidak akan Anda temukan di sini: janji waktu tanggap, jaminan ketersediaan, dan versi kedua. `v1` di alamatnya adalah janji yang sudah dibuat — bentuk jawaban yang sudah terbit tidak diubah diam-diam; kolom baru boleh muncul, kolom yang ada tidak dicabut tanpa alamat versi baru.
Menerbitkan dan mencabut token
- Buka Bantuan & Pengaturan → Token API.
- Isi Nama (mis. nama sistem yang memakainya) dan pilih Berperan sebagai.
- Tekan Terbitkan dan SALIN tokennya saat itu juga — ia hanya ditampilkan sekali.
- Untuk menghentikan akses, tekan Cabut pada baris token; penolakan berlaku seketika.
