kalcerPOSPanduan
Pengaturan

External API

Add-on untuk menghubungkan aplikasi lain, misalnya asisten AI atau spreadsheet, agar bisa membaca laporan, mengelola produk dan stok, serta membuat open bill.

Add-on

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.

HalAturan
Alamat dasarhttps://<slug>.kalcerpos.com/api/external, contoh https://namatoko.kalcerpos.com/api/external
AutentikasiHeader Authorization: Bearer <API_KEY> di setiap panggilan. Kunci berbentuk <tenantId>.<rahasia>. Kunci itulah yang menentukan toko, bukan alamatnya
FormatKirim dan terima JSON. Untuk POST dan PATCH wajib header Content-Type: application/json
TanggalYYYY-MM-DD, tanggal kalender toko (zona waktu toko, biasanya Asia/Jakarta)
UangRupiah sebagai angka bulat tanpa titik atau koma, contoh 22000
IdId produk adalah teks acak dari GET /products, peka huruf besar dan kecil. Jangan menebak id dari nama
StokAngka 999 atau lebih berarti stok tanpa batas
GalatJawaban gagal berbentuk {"error":"..."} dengan kode HTTP 4xx atau 5xx
MetodePathFungsi
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/productsSemua produk: id, SKU, nama, kategori, harga, stok, batas stok
POST/productsMenambah satu produk
PATCH/products/<id>Mengubah stok, harga atau batas stok satu produk
POST/ordersMembuat open bill (belum dibayar) dan mengirim pesanan ke dapur atau bar

Alur kerja yang disarankan:

  1. Untuk laporan, isi from dan to. 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.
  2. Sebelum membuat order atau mengubah produk, panggil GET /products dan cocokkan nama yang diminta pengguna dengan id. Kalau ada beberapa yang mirip, tanyakan dulu ke pengguna.
  3. Cek stock di daftar produk sebelum membuat order. Kalau jawaban 409, sampaikan sisa stok (available) ke pengguna, jangan mengulang otomatis.
  4. POST /orders dan POST /products tidak idempoten. Mengulang panggilan yang sama membuat order atau produk kedua. Ulangi hanya kalau jawaban sebelumnya jelas gagal (4xx, 5xx atau tidak tersambung sebelum terkirim).
  5. Untuk menambah stok, baca stok sekarang, jumlahkan, lalu kirim totalnya lewat PATCH. stock di PATCH menimpa, bukan menambah.
  6. Jangan menjanjikan hal di luar API: menerima pembayaran, menghapus, membaca satu order atau data pelanggan memang tidak tersedia.

Membuat kunci API

  1. Buka Admin → Settings, cari kotak External API access.
  2. Ketuk Generate API key.
  3. Ketuk Show untuk melihat kuncinya, atau Copy untuk menyalin.
  4. 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

BisaTidak bisa
Membaca ringkasan penjualan, penjualan per item, per metode bayar, dan per jamMembaca detail satu order, daftar order, atau data pelanggan
Melihat daftar produk dengan harga dan stokMenghapus produk atau order
Menambah produk baruMengatur modifier, diskon grosir, resep, paket atau foto
Mengubah stok, harga dan batas stok menipisMengubah nama, kategori, SKU, stasiun, HPP atau status aktif produk yang sudah ada
Membuat open billMenerima 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 range berisi from dan to yang 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}

IsianArti
ordersJumlah order lunas
grossSalesHarga item (termasuk modifier) dikali jumlah, sebelum diskon voucher
refundsTotal refund atas order di rentang itu
netSalesTotal yang ditagih ke pelanggan (setelah diskon, termasuk kode unik QRIS) dikurangi refund
cogsHPP item yang terjual
grossProfitnetSales 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.
  • stock 999 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 dan 0 untuk 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"

IsianJenisKeterangan
nameteksWajib, tidak boleh kosong
priceangkaWajib, 0 atau lebih
skuteksOpsional, bawaan kosong
categoryteksOpsional, bawaan Uncategorised
stationtekskitchen atau bar. Nilai lain atau kosong menjadi bar
cogsangkaHPP per porsi, bawaan 0
stockangkaBawaan 999 (tanpa batas)
stockThresholdangkaBatas stok menipis, bawaan 0
descteksDeskripsi, bawaan kosong
activetrue atau falseBawaan 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}

IsianJenisKeterangan
itemsdaftarWajib, minimal satu baris
items[].productIdteksWajib, id dari GET /products
items[].qtyangkaWajib, lebih dari 0
items[].notesteksOpsional, catatan untuk dapur, maksimal 200 karakter
tableteks atau angkaOpsional, bawaan T. "5" dan 5 sama-sama diterima, maksimal 40 karakter
customerteksOpsional, 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

KodeIsi errorArtinya
200Berhasil (GET dan PATCH)
201Berhasil membuat produk atau order
400name is requiredname kosong atau bukan teks
400price is required and must be a non-negative numberprice kosong, bukan angka, atau negatif
400invalid stock, invalid price, invalid stockThresholdNilai PATCH bukan angka atau negatif
400no valid fields to updatePATCH tanpa stock, price atau stockThreshold
400items must be a non-empty arrayitems kosong atau bukan daftar
400each item needs a productId and a positive qtyBaris tanpa productId atau qty tidak lebih dari 0
400(halaman HTML)Isi kiriman bukan JSON yang sah
401unauthorizedKunci kosong, salah, sudah diganti, atau toko ditangguhkan
403External API add-on is not active for this storeAdd-on External API belum aktif
403kode trial_lockedMasa coba gratis toko habis. Laporan dan daftar produk tetap bisa dibaca, perubahan ditolak sampai paket dibayar
404product not found atau product not found: <id>Id produk tidak ada
404combo 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
409insufficient stock: <nama> atau insufficient ingredient stock: <nama>Stok tidak cukup. Jawaban juga membawa available dan needed
500internal errorGalat di server, disertai detail. Coba lagi nanti
503external API not configuredServer 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.