External API membuka akses terbatas ke data toko untuk aplikasi lain. Contohnya asisten AI yang menjawab "berapa omzet kemarin?" lewat chat, atau sistem gudang yang memperbarui stok produk. Aplikasi itu memakai satu kunci rahasia yang kamu buat di Admin.
Untuk AI agent / LLM: berikan link https://docs.kalcerpos.com/docs/external-api.md ke asisten AI kamu (ChatGPT, Claude, n8n, dan sejenisnya). Isinya manual lengkap dalam Markdown polos yang mudah dibaca AI. Untuk tool calling, pakai spesifikasi OpenAPI 3.1. Sertakan juga alamat toko (https://namatoko.kalcerpos.com/api/external) dan kunci API dari Settings, tapi simpan kuncinya di pengaturan rahasia agent, jangan ditempel di chat publik.
Paket: External API adalah add-on seharga Rp 50.000 per bulan per toko, bisa ditambahkan ke paket apa pun. Add-on ini diaktifkan oleh admin kalcerPOS, jadi hubungi tim kalcerPOS untuk menyalakannya. Tanpa add-on, kotak External API access di Settings terkunci dan setiap panggilan ditolak dengan kode 403.
Untuk AI agent
Bagian ini ringkasan padat untuk asisten AI atau program yang memanggil API. Salinan Markdown polos ada di external-api.md dan spesifikasi OpenAPI 3.1 di external-api.openapi.json. Keduanya bisa diambil langsung tanpa login.
| Hal | Aturan |
|---|---|
| Alamat dasar | https://<slug>.kalcerpos.com/api/external, contoh https://namatoko.kalcerpos.com/api/external |
| Autentikasi | Header Authorization: Bearer <API_KEY> di setiap panggilan. Kunci berbentuk <tenantId>.<rahasia>. Kunci itulah yang menentukan toko, bukan alamatnya |
| Format | Kirim dan terima JSON. Untuk POST dan PATCH wajib header Content-Type: application/json |
| Tanggal | YYYY-MM-DD, tanggal kalender toko (zona waktu toko, biasanya Asia/Jakarta) |
| Uang | Rupiah sebagai angka bulat tanpa titik atau koma, contoh 22000 |
| Id | Id produk adalah teks acak dari GET /products, peka huruf besar dan kecil. Jangan menebak id dari nama |
| Stok | Angka 999 atau lebih berarti stok tanpa batas |
| Galat | Jawaban gagal berbentuk {"error":"..."} dengan kode HTTP 4xx atau 5xx |
| Metode | Path | Fungsi |
|---|---|---|
| GET | /reports/summary?from=&to= | Jumlah order, penjualan kotor, refund, penjualan bersih, HPP, laba kotor |
| GET | /reports/by-item?from=&to= | Jumlah terjual dan omzet per nama produk |
| GET | /reports/by-payment?from=&to= | Total per metode pembayaran |
| GET | /reports/by-hour?from=&to= | Jumlah order dan omzet per jam 0 sampai 23 |
| GET | /products | Semua produk: id, SKU, nama, kategori, harga, stok, batas stok |
| POST | /products | Menambah satu produk |
| PATCH | /products/<id> | Mengubah stok, harga atau batas stok satu produk |
| POST | /orders | Membuat open bill (belum dibayar) dan mengirim pesanan ke dapur atau bar |
Alur kerja yang disarankan:
- Untuk laporan, isi
fromdanto. Kalau dikosongkan, server memakai tanggal hari ini menurut zona waktu toko. Untuk "kemarin" atau rentang lain, hitung tanggalnya dalam zona waktu toko (WIB untuk kebanyakan toko), jangan UTC. - Sebelum membuat order atau mengubah produk, panggil
GET /productsdan cocokkan nama yang diminta pengguna denganid. Kalau ada beberapa yang mirip, tanyakan dulu ke pengguna. - Cek
stockdi daftar produk sebelum membuat order. Kalau jawaban 409, sampaikan sisa stok (available) ke pengguna, jangan mengulang otomatis. POST /ordersdanPOST /productstidak idempoten. Mengulang panggilan yang sama membuat order atau produk kedua. Ulangi hanya kalau jawaban sebelumnya jelas gagal (4xx, 5xx atau tidak tersambung sebelum terkirim).- Untuk menambah stok, baca stok sekarang, jumlahkan, lalu kirim totalnya lewat PATCH.
stockdi PATCH menimpa, bukan menambah. - Jangan menjanjikan hal di luar API: menerima pembayaran, menghapus, membaca satu order atau data pelanggan memang tidak tersedia.
Membuat kunci API
- Buka Admin → Settings, cari kotak External API access.
- Ketuk Generate API key.
- Ketuk Show untuk melihat kuncinya, atau Copy untuk menyalin.
- Tempel kunci itu di aplikasi yang mau kamu hubungkan.
Di bawah kunci tertulis kapan kunci terakhir dibuat. Kunci berbentuk dua bagian yang dipisah titik: id toko lalu 64 karakter acak. Salin utuh, termasuk bagian sebelum titik.
Penting: perlakukan kunci ini seperti kata sandi. Siapa pun yang memegangnya bisa membaca laporan penjualan, menambah produk, mengubah harga dan stok, serta membuat open bill. Jangan kirim lewat grup chat atau taruh di halaman publik.
Mengganti kunci
Ketuk Regenerate key lalu setujui konfirmasinya. Kunci lama langsung tidak berlaku di mana pun. Tempel kunci baru di setiap aplikasi yang masih memakainya.
Yang bisa dan tidak bisa dilakukan
| Bisa | Tidak bisa |
|---|---|
| Membaca ringkasan penjualan, penjualan per item, per metode bayar, dan per jam | Membaca detail satu order, daftar order, atau data pelanggan |
| Melihat daftar produk dengan harga dan stok | Menghapus produk atau order |
| Menambah produk baru | Mengatur modifier, diskon grosir, resep, paket atau foto |
| Mengubah stok, harga dan batas stok menipis | Mengubah nama, kategori, SKU, stasiun, HPP atau status aktif produk yang sudah ada |
| Membuat open bill | Menerima pembayaran, menandai order lunas, memakai voucher, atau mengubah order |
Cara memanggil API
Semua alamat diawali alamat toko kamu, contoh https://namatoko.kalcerpos.com/api/external/. Setiap panggilan wajib membawa header Authorization: Bearer <API_KEY>, dengan <API_KEY> diganti kunci dari Settings. Data dikirim dan diterima dalam format JSON.
API ini dipanggil dari server atau aplikasi, bukan dari halaman web di browser lain (tidak ada izin CORS). Contoh di bawah memakai curl. Baris "Jawaban" menunjukkan isi JSON yang dikembalikan, dengan angka contoh.
Laporan
Keempat laporan menerima from dan to berformat YYYY-MM-DD. Keduanya termasuk: from=2026-11-01&to=2026-11-07 berarti 1 sampai 7 November penuh. Tanggal yang dipakai adalah tanggal order menurut zona waktu toko, sama seperti laporan di Admin.
Penting: from atau to yang kosong diisi tanggal hari ini menurut zona waktu toko. Tanggal yang formatnya salah, tidak ada (misalnya 2026-02-30), atau from setelah to ditolak dengan kode 400. Tetap periksa range di jawaban.
Aturan yang berlaku untuk semua laporan:
- Hanya order yang sudah dibayar yang dihitung. Open bill yang belum dibayar, termasuk yang dibuat lewat API, baru masuk laporan setelah kasir menerima pembayarannya.
- Refund dihitung pada tanggal order aslinya, bukan tanggal refund dilakukan.
- Setiap jawaban membawa
rangeberisifromdantoyang benar-benar dipakai.
Ringkasan penjualan
curl -H "Authorization: Bearer <API_KEY>" "https://namatoko.kalcerpos.com/api/external/reports/summary?from=2026-11-01&to=2026-11-07"
Jawaban: {"range":{"from":"2026-11-01","to":"2026-11-07"},"orders":182,"grossSales":5460000,"refunds":45000,"netSales":5398000,"cogs":1910000,"grossProfit":3488000}
| Isian | Arti |
|---|---|
orders | Jumlah order lunas |
grossSales | Harga item (termasuk modifier) dikali jumlah, sebelum diskon voucher |
refunds | Total refund atas order di rentang itu |
netSales | Total yang ditagih ke pelanggan (setelah diskon, termasuk kode unik QRIS) dikurangi refund |
cogs | HPP item yang terjual |
grossProfit | netSales dikurangi cogs |
Penjualan per item
curl -H "Authorization: Bearer <API_KEY>" "https://namatoko.kalcerpos.com/api/external/reports/by-item?from=2026-11-01&to=2026-11-07"
Jawaban: {"range":{"from":"2026-11-01","to":"2026-11-07"},"items":[{"name":"Es Kopi Susu","qty":64,"revenue":1408000},{"name":"Roti Bakar","qty":31,"revenue":558000}]}
Dikelompokkan per nama produk dan diurutkan dari qty terbanyak. revenue adalah omzet kotor (harga termasuk modifier dikali jumlah), belum dikurangi diskon atau refund.
Penjualan per metode bayar
curl -H "Authorization: Bearer <API_KEY>" "https://namatoko.kalcerpos.com/api/external/reports/by-payment?from=2026-11-01&to=2026-11-07"
Jawaban: {"range":{"from":"2026-11-01","to":"2026-11-07"},"byMethod":{"cash":2150000,"qris":3020000,"card":228000}}
byMethod memakai kode metode dalam huruf kecil: cash, qris dan card (EDC). Metode tambahan dari Metode pembayaran punya kode yang diawali m_. Order lama tanpa metode tercatat sebagai other. Angkanya belum dikurangi refund. Metode yang tidak dipakai di rentang itu tidak muncul.
Penjualan per jam
curl -H "Authorization: Bearer <API_KEY>" "https://namatoko.kalcerpos.com/api/external/reports/by-hour?from=2026-11-01&to=2026-11-07"
Jawaban: {"range":{"from":"2026-11-01","to":"2026-11-07"},"timezone":"Asia/Jakarta","byHour":[{"hour":0,"orders":0,"revenue":0},{"hour":1,"orders":0,"revenue":0},...,{"hour":12,"orders":31,"revenue":948000},...,{"hour":23,"orders":0,"revenue":0}]}
byHour selalu berisi 24 baris, jam 0 sampai 23 menurut zona waktu toko (timezone). Semua hari dalam rentang dijumlahkan per jam, jadi hasilnya menjawab "jam berapa paling ramai", bukan rincian per hari. Untuk satu hari tertentu, isi from dan to dengan tanggal yang sama. revenue adalah total order, belum dikurangi refund.
Produk dan stok
Melihat daftar produk
curl -H "Authorization: Bearer <API_KEY>" "https://namatoko.kalcerpos.com/api/external/products"
Jawaban: {"products":[{"id":"7fQ2kLm9XbR1sT4uVw8y","sku":"KP-01","name":"Es Kopi Susu","category":"Kopi","price":22000,"stock":40,"stockThreshold":5},{"id":"a1B2c3D4e5F6g7H8i9J0","sku":"","name":"Paket Hemat","category":"Paket","price":30000,"stock":999,"stockThreshold":0}]}
- Semua produk dikembalikan sekaligus, tanpa halaman, termasuk produk yang dinonaktifkan dari kasir. Status aktif tidak ikut di daftar.
stock999 berarti tanpa batas. Produk dengan resep atau paket selalu 999, karena stoknya ada di bahan baku atau produk penyusunnya.- Isian yang kosong menjadi
""untuk teks dan0untuk angka.
Pakai id produk untuk mengubah produk atau membuat order.
Menambah produk
curl -X POST -H "Authorization: Bearer <API_KEY>" -H "Content-Type: application/json" -d '{"name":"Es Kopi Susu","price":22000,"category":"Kopi","stock":50}' "https://namatoko.kalcerpos.com/api/external/products"
| Isian | Jenis | Keterangan |
|---|---|---|
name | teks | Wajib, tidak boleh kosong |
price | angka | Wajib, 0 atau lebih |
sku | teks | Opsional, bawaan kosong |
category | teks | Opsional, bawaan Uncategorised |
station | teks | kitchen atau bar. Nilai lain atau kosong menjadi bar |
cogs | angka | HPP per porsi, bawaan 0 |
stock | angka | Bawaan 999 (tanpa batas) |
stockThreshold | angka | Batas stok menipis, bawaan 0 |
desc | teks | Deskripsi, bawaan kosong |
active | true atau false | Bawaan true. false menyembunyikan dari kasir |
Angka opsional yang bukan angka atau negatif tidak ditolak, tapi diganti nilai bawaannya. Isian lain diabaikan. Produk baru tidak punya modifier, diskon grosir, resep atau foto. Atur itu di Produk.
Jawaban (201): {"ok":true,"id":"Zx81LmQp0aB2cD3eF4gH","product":{"id":"Zx81LmQp0aB2cD3eF4gH","name":"Es Kopi Susu","sku":"","category":"Kopi","station":"bar","price":22000,"cogs":0,"stock":50,"stockThreshold":0,"bulkQty":0,"bulkType":"percent","bulkValue":0,"swatch":"#a98558","desc":"","active":true,"modifiers":[],"recipe":[]}}
Nama tidak dicek ganda. Mengirim produk yang sama dua kali membuat dua produk.
Mengubah stok atau harga
curl -X PATCH -H "Authorization: Bearer <API_KEY>" -H "Content-Type: application/json" -d '{"stock":40,"price":23000}' "https://namatoko.kalcerpos.com/api/external/products/7fQ2kLm9XbR1sT4uVw8y"
Jawaban: {"ok":true,"id":"7fQ2kLm9XbR1sT4uVw8y","updated":{"stock":40,"price":23000}}
Hanya stock, price dan stockThreshold yang bisa diubah, masing-masing angka 0 atau lebih. Kirim minimal satu. Isian lain dan nilai null diabaikan. updated berisi isian yang benar-benar disimpan.
Catatan: stock di sini menimpa angka stok, bukan menambah. Perubahan stok tercatat di laporan Pergerakan stok sebagai penyesuaian (alasan adjustment, catatan "External API"), dan jawabannya menyertakan stockBefore. PATCH tidak mengirim notifikasi stok menipis. Untuk mencatat barang masuk dengan harga beli, pakai Penerimaan barang di Admin.
Membuat open bill
curl -X POST -H "Authorization: Bearer <API_KEY>" -H "Content-Type: application/json" -d '{"table":"5","customer":"Rina","items":[{"productId":"7fQ2kLm9XbR1sT4uVw8y","qty":2,"notes":"less sugar"}]}' "https://namatoko.kalcerpos.com/api/external/orders"
Jawaban (201): {"ok":true,"id":"Hk3PqR8sT1uV2wX4yZ5a","shortId":"K7MPX","total":44000,"items":1}
| Isian | Jenis | Keterangan |
|---|---|---|
items | daftar | Wajib, minimal satu baris |
items[].productId | teks | Wajib, id dari GET /products |
items[].qty | angka | Wajib, lebih dari 0 |
items[].notes | teks | Opsional, catatan untuk dapur, maksimal 200 karakter |
table | teks atau angka | Opsional, bawaan T. "5" dan 5 sama-sama diterima, maksimal 40 karakter |
customer | teks | Opsional, bawaan Walk-in |
Di jawaban, id adalah id order, shortId kode 5 huruf yang tercetak di tiket dan tampil di kasir, total jumlah tagihan, dan items jumlah baris.
Yang terjadi saat order dibuat:
- Harga diambil dari daftar produk saat itu. Harga dari pemanggil tidak dipakai, dan diskon grosir tidak berlaku.
- Stok dicek dulu untuk semua baris sekaligus. Kalau kurang, order ditolak dengan kode 409 dan tidak ada yang tersimpan.
- Kalau cukup, stok langsung dipotong, termasuk bahan baku untuk produk dengan resep dan produk penyusun untuk paket. Setiap potongan tercatat di laporan Pergerakan stok.
- Order masuk sebagai open bill yang belum dibayar, tercatat pada tanggal hari ini menurut zona waktu toko. Pesanan muncul di daftar Bills kasir dan di layar dapur. Kasir menyelesaikan pembayarannya seperti open bill biasa.
- Tiket dapur, bar dan pelayan dicetak. Paket yang isinya dari dapur dan bar dicetak ke kedua stasiun.
- Order dari API tercatat dengan kasir
external-api, jadi mudah dikenali di laporan.
Modifier, diskon grosir, voucher, deposit dan pembayaran tidak bisa dikirim lewat API. Produk yang dinonaktifkan dari kasir (Active tidak dicentang) ditolak dengan kode 409 dan code: "inactive". Pengecekan stok, order dan potongan stok disimpan dalam satu transaksi, jadi dua order bersamaan tidak bisa sama-sama mengambil stok terakhir.
Kode jawaban
| Kode | Isi error | Artinya |
|---|---|---|
| 200 | Berhasil (GET dan PATCH) | |
| 201 | Berhasil membuat produk atau order | |
| 400 | name is required | name kosong atau bukan teks |
| 400 | price is required and must be a non-negative number | price kosong, bukan angka, atau negatif |
| 400 | invalid stock, invalid price, invalid stockThreshold | Nilai PATCH bukan angka atau negatif |
| 400 | no valid fields to update | PATCH tanpa stock, price atau stockThreshold |
| 400 | items must be a non-empty array | items kosong atau bukan daftar |
| 400 | each item needs a productId and a positive qty | Baris tanpa productId atau qty tidak lebih dari 0 |
| 400 | (halaman HTML) | Isi kiriman bukan JSON yang sah |
| 401 | unauthorized | Kunci kosong, salah, sudah diganti, atau toko ditangguhkan |
| 403 | External API add-on is not active for this store | Add-on External API belum aktif |
| 403 | kode trial_locked | Masa coba gratis toko habis. Laporan dan daftar produk tetap bisa dibaca, perubahan ditolak sampai paket dibayar |
| 404 | product not found atau product not found: <id> | Id produk tidak ada |
| 404 | combo component product not found: <id>, ingredient not found: <id> | Produk paket atau resep merujuk produk atau bahan baku yang sudah dihapus |
| 404 | (bukan JSON) | Alamat tidak dikenal |
| 409 | insufficient stock: <nama> atau insufficient ingredient stock: <nama> | Stok tidak cukup. Jawaban juga membawa available dan needed |
| 500 | internal error | Galat di server, disertai detail. Coba lagi nanti |
| 503 | external API not configured | Server belum siap. Coba lagi nanti |
Contoh jawaban 409: {"error":"insufficient stock: Es Kopi Susu","available":1,"needed":2}
Contoh jawaban 403 masa coba habis: {"ok":false,"error":"Masa coba toko ini sudah habis. Data kamu aman, tapi toko hanya bisa dilihat sampai paket dibayar.","code":"trial_locked"}
Tanya jawab
Bisakah membuat beberapa kunci untuk aplikasi berbeda?
Belum. Satu toko punya satu kunci External API. Semua aplikasi yang terhubung memakai kunci yang sama, dan semuanya harus diperbarui saat kunci diganti.
Apakah kunci External API sama dengan kunci QRIS listener?
Tidak. Kunci untuk QRIS otomatis ada di kotak QRIS listener key dan hanya berlaku untuk aplikasi pembaca notifikasi.
Apakah tiket dapur tercetak untuk order dari API?
Ya. Order langsung tampil di layar dapur, dan tiket dapur, bar dan pelayan dicetak lewat tablet yang terhubung ke printer stasiun itu (aplikasi Android kalcerPOS, terbuka dan sudah login). Tiket menunggu di antrean. Kalau tablet printernya baru dibuka lebih dari 10 menit kemudian, tiket itu tidak tercetak, tapi order tetap tersimpan dan tampil di layar dapur. Lihat Tiket printer.
Apakah order dari API langsung masuk laporan?
Belum. Order dari API adalah open bill yang belum dibayar. Order itu masuk laporan setelah kasir menerima pembayarannya.
Berapa biaya External API?
Rp 50.000 per bulan per toko, di luar harga paket. Hubungi tim kalcerPOS untuk mengaktifkannya.