Untuk pengurus koperasi, vendor POS, dan teknisi yang memasang kasir di toko koperasi.
Status: rancangan API v1. Di prototipe v2.0 alurnya disimulasikan di Toko & Minimarket → Integrasi POS. Tombol "Simulasikan struk dari POS" membukukan struk contoh persis seperti yang akan dilakukan server. Belum ada server yang menerima permintaan. Alamat
api.ariba.examplehanya contoh.
Berkas pendamping (unduh di bawah):
ARIBA-POS.postman_collection.json: semua permintaan beserta skrip uji.ARIBA-POS.postman_environment.json: variabel (alamat, kode toko, client id/secret).
0. Mode Kasir bawaan ARIBA (tanpa POS pihak ketiga)
Toko yang belum punya mesin kasir dapat memakai Mode Kasir di ARIBA (menu Mode Kasir, atau tombol di Toko & Minimarket). Tidak perlu API key: penjualan langsung masuk buku besar, stok, dan dasar SHU.
| Fitur | Cara kerja di prototipe |
|---|---|
| Peran Kasir toko | Hanya layar kasir; tidak melihat keuangan koperasi |
| Shift | Buka dengan modal laci; satu shift per petugas dan per mesin kasir |
| Pindai barcode | Pemindai USB/Bluetooth bekerja sebagai keyboard di kolom pencarian, lalu Enter |
| Kartu anggota | QR/barcode berisi nomor anggota; belanja dicatat untuk SHU |
| Bayar | Tunai dengan kembalian; QRIS/transfer simulasi (ditandai manual) |
| Struk | 58 mm (32 kolom) atau 80 mm (48 kolom) lewat dialog cetak browser; kirim lewat WhatsApp |
| Ditahan | Beberapa keranjang disimpan sementara di perangkat |
| Retur | Sebagian, maksimal jumlah yang dibeli, 7 hari (lewat itu perlu pengurus); jurnal Dr Penjualan / Cr Kas dan Dr Persediaan / Cr HPP |
| Tutup shift | Hitung uang per pecahan; selisih kurang → 5-3300, lebih → 4-9100; laporan akhir shift |
| Stok opname | Pengurus; selisih × harga pokok → 5-3200 (kurang) atau 4-9100 (lebih) |
| Offline | Simulasi: transaksi antre di perangkat, dikirim saat online; clientRef mencegah pembukuan ganda |
Untuk produksi: aplikasi dipasang sebagai PWA di tablet, antrean offline disimpan di IndexedDB, dan server menolak clientRef ganda (lihat supabase/migrations/0009_mode_kasir.sql). Printer thermal dipasang sebagai printer biasa di perangkat; cetak langsung ESC/POS lewat Bluetooth belum diaktifkan.
1. Gambaran
┌────────────┐ 1. token (client credentials) ┌──────────────┐
│ POS toko │ ────────────────────────────────▶ │ ARIBA API │
│ (kasir di │ 2. tarik katalog & harga │ │
│ lokasi) │ ◀──────────────────────────────── │ Toko & │
│ │ 3. cek nomor anggota │ Minimarket │
│ │ ────────────────────────────────▶ │ │ │
│ │ 4. kirim struk / rekap harian │ ▼ │
│ │ ────────────────────────────────▶ │ Buku besar + │
└────────────┘ │ dasar SHU │
└──────────────┘
Yang terjadi di ARIBA ketika struk diterima:
| Langkah | Jurnal |
|---|---|
| Penjualan | Dr Kas (1-1100) / Cr Penjualan Toko (4-4100) |
| Harga pokok | Dr HPP (5-2100) / Cr Persediaan (1-1900), dengan biaya rata-rata bergerak |
| Stok | Berkurang sesuai jumlah barang |
| Anggota | Bila struk membawa member_no, total belanja masuk dasar jasa transaksi saat pembagian SHU |
Pembatalan struk membuat jurnal balik (reversal). Jurnal asli tidak pernah diubah atau dihapus.
Prinsip
- ARIBA adalah sumber harga dan stok. POS menarik katalog; harga di struk harus sama dengan harga ARIBA saat itu (selisih ditolak
PRICE_MISMATCH, kecuali koperasi mengaktifkan "harga POS dipercaya"). - Idempoten.
receipt_noadalah kunci unik per toko. Struk yang dikirim ulang (mis. karena sinyal putus) tidak dibukukan dua kali. - Data minimal. POS hanya menerima nomor dan nama anggota yang disamarkan. Tidak ada NIK, saldo, atau skor kredit.
- Rahasia tetap di server.
client_secretdisimpan di perangkat kasir yang terkunci atau di server vendor POS, tidak di aplikasi web publik.
2. Persiapan di ARIBA (pengurus koperasi)
- Koperasi → Ubah profil → Unit usaha: centang Toko / minimarket. Menu Toko & Minimarket muncul.
- Toko & Minimarket → Produk & stok: lengkapi SKU dan barcode setiap produk. SKU harus sama dengan kode barang di POS.
- Integrasi → Tambah mitra: pilih jenis Mesin kasir (POS) toko/minimarket. Scope bawaan:
pos:produk: membaca katalog dan hargapos:penjualan: mengirim dan membatalkan strukanggota:baca: mengecek nomor anggota- Salin client id dan client secret (secret hanya tampil sekali) lalu serahkan ke teknisi POS lewat jalur aman, tidak lewat grup chat.
- Catat kode toko (contoh demo:
KMY-TOKO-01).
3. Autentikasi
POST /oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&client_id=…&client_secret=…&scope=pos:produk pos:penjualan anggota:baca
Respons:
{ "access_token": "eyJ…", "token_type": "Bearer", "expires_in": 900, "scope": "pos:produk pos:penjualan anggota:baca" }
Kirim Authorization: Bearer <access_token> di setiap permintaan. Minta token baru sebelum 15 menit habis.
4. Endpoint
Alamat dasar: https://api.ariba.example/v1.
4.1 Katalog produk
GET /stores/{store_code}/products?updated_since=2026-11-01T00:00:00+07:00
{
"store_code": "KMY-TOKO-01",
"items": [
{ "sku": "BRS-5", "barcode": "2075…", "name": "Beras premium 5 kg", "unit": "karung", "price": 78000, "stock": 44, "active": true, "updated_at": "2026-11-01T08:00:00+07:00" }
],
"next_cursor": null
}
Tarik penuh saat POS menyala, lalu tarik perubahan tiap 15 menit dengan updated_since. Harga dalam rupiah bulat, tanpa desimal.
4.2 Cek anggota
GET /members?member_no=KMY-250004
{ "member_no": "KMY-250004", "name": "Ah*** Ha***", "status": "AKTIF" }
Kasir memindai kartu anggota (QR/barcode berisi nomor anggota) atau mengetik nomornya. Hanya anggota berstatus AKTIF yang dihitung untuk SHU. Bila tidak ditemukan, struk tetap bisa dikirim tanpa member_no sebagai penjualan umum.
4.3 Kirim satu struk
POST /stores/{store_code}/sales
Idempotency-Key: AM-20261106-0101
Content-Type: application/json
{
"receipt_no": "AM-20261106-0101",
"occurred_at": "2026-11-06T14:05:00+07:00",
"cashier": "Kasir 1",
"member_no": "KMY-250004",
"payment": "TUNAI",
"items": [
{ "sku": "BRS-5", "qty": 1, "unit_price": 78000 },
{ "sku": "KPI-10", "qty": 2, "unit_price": 14000 }
],
"total": 106000
}
| Kolom | Wajib | Keterangan |
|---|---|---|
receipt_no |
ya | Nomor struk dari POS, unik per toko. Sama dengan Idempotency-Key. |
occurred_at |
ya | Waktu transaksi di kasir (ISO 8601 dengan zona waktu). |
cashier |
ya | Nama atau kode kasir. |
member_no |
tidak | Nomor anggota. Kosongkan untuk pembeli umum. |
payment |
ya | TUNAI, QRIS, atau TRANSFER. |
items[].sku / qty / unit_price |
ya | Kuantitas bilangan bulat > 0; harga rupiah bulat. |
total |
ya | Harus sama dengan Σ qty × unit_price. |
Respons 201 Created:
{ "sale_id": "JUAL-KMY-20261106-0003", "receipt_no": "AM-20261106-0101", "status": "DIBUKUKAN", "journal_id": "JRN-…", "member_counted_for_shu": true }
Kirim ulang dengan receipt_no sama → 200 OK dengan isi respons pertama dan header Idempotent-Replay: true.
4.4 Cek status struk
GET /stores/{store_code}/sales/{receipt_no}
Status: DIBUKUKAN, DIBATALKAN, atau 404 bila belum pernah diterima. Pakai ini saat POS ragu apakah struk sudah terkirim.
4.5 Batalkan struk
POST /stores/{store_code}/sales/{receipt_no}/void
{ "reason": "Salah input barang", "voided_at": "2026-11-06T14:20:00+07:00", "cashier": "Kasir 1" }
ARIBA membuat jurnal balik dan mengembalikan stok. Struk yang sudah dibatalkan tidak bisa dibatalkan lagi (409 ALREADY_VOIDED). Retur sebagian dilakukan dengan membatalkan struk lalu mengirim struk baru.
4.6 Rekap akhir hari (mode luring)
Untuk toko dengan internet tidak stabil, POS boleh menyimpan struk lalu mengirimnya sekaligus:
POST /stores/{store_code}/sales:batch
{ "business_date": "2026-11-06", "sales": [ { …struk 1… }, { …struk 2… } ] }
Respons memuat hasil per struk:
{ "accepted": 41, "replayed": 2, "rejected": 1, "results": [ { "receipt_no": "AM-20261106-0102", "status": "DITOLAK", "error": "SKU_NOT_FOUND" } ] }
Maksimal 500 struk per permintaan. Struk yang ditolak diperbaiki lalu dikirim ulang satu per satu. Toko tanpa POS sama sekali bisa memakai rekap harian manual di aplikasi (kanal REKAP).
5. Kode galat
| HTTP | Kode | Arti | Tindakan POS |
|---|---|---|---|
| 400 | VALIDATION |
Kolom wajib kosong/format salah | Perbaiki data |
| 401 | TOKEN_EXPIRED |
Token habis | Minta token baru, ulangi |
| 403 | SCOPE_MISSING |
Kunci tak punya scope | Minta pengurus menambah scope |
| 404 | SKU_NOT_FOUND |
SKU tidak ada di katalog toko | Sinkron katalog, cek SKU |
| 404 | MEMBER_NOT_FOUND |
Nomor anggota tak dikenal | Kirim tanpa member_no |
| 409 | ALREADY_VOIDED |
Struk sudah dibatalkan | Tidak perlu diulang |
| 422 | TOTAL_MISMATCH |
Total ≠ jumlah baris | Hitung ulang |
| 422 | PRICE_MISMATCH |
Harga beda dengan ARIBA | Sinkron katalog |
| 422 | STOCK_INSUFFICIENT |
Stok ARIBA kurang | Catat penerimaan barang di ARIBA dulu |
| 422 | RULE_BLOCKED |
Ditolak Konstitusi Ekonomi | Hubungi pengurus |
| 429 | RATE_LIMITED |
Terlalu sering | Tunggu sesuai Retry-After |
| 5xx | — | Gangguan server | Simpan struk, kirim ulang (aman karena idempoten) |
Bentuk badan galat:
{ "error": { "code": "SKU_NOT_FOUND", "message": "SKU TIDAK-ADA tidak terdaftar di toko KMY-TOKO-01", "field": "items[0].sku" } }
6. Uji dengan Postman (langkah demi langkah)
- Pasang Postman (aplikasi desktop atau web).
- Import → seret kedua berkas
ARIBA-POS.postman_collection.jsondanARIBA-POS.postman_environment.json. - Pojok kanan atas → pilih environment ARIBA POS (demo).
- Buka environment, isi
client_iddanclient_secret(kolom secret tersembunyi). Sesuaikanbase_url,token_url, danstore_codebila server sungguhan sudah tersedia. - Jalankan 0. Autentikasi → Minta token. Skrip uji menyimpan
access_tokenke environment secara otomatis. - Jalankan 1. Katalog produk. Pastikan SKU di POS sama dengan daftar ini.
- Jalankan 2. Anggota → Cek nomor anggota.
- Jalankan 3. Penjualan → Kirim satu struk (harus
201), lalu Kirim ulang struk yang sama (harus200denganIdempotent-Replay: true, tidak dibukukan dua kali). - Cek status struk →
DIBUKUKAN. Batalkan struk → statusDIBATALKAN. - Jalankan folder 4. Contoh galat untuk memastikan POS menangani 404/422 dengan benar.
- Untuk uji menyeluruh: klik kanan koleksi → Run collection. Semua tes harus hijau.
Selama server belum tersedia, gunakan simulasi di aplikasi: Toko & Minimarket → Integrasi POS → Simulasikan struk dari POS, lalu periksa tab Penjualan (kanal "POS") dan Universal Ledger (sumber "Penjualan toko").
7. Checklist pemasangan di toko
- ☐ SKU dan barcode di POS sama dengan ARIBA
- ☐ Jam perangkat kasir sinkron (NTP), zona waktu WIB/WITA/WIT benar
- ☐ Client secret tersimpan di perangkat terkunci atau server vendor
- ☐ Pemindai kartu anggota terpasang; kasir tahu cara memasukkan nomor anggota
- ☐ Mode luring diuji: cabut internet, buat 3 transaksi, sambungkan, pastikan rekap terkirim sekali saja
- ☐ Uji pembatalan struk
- ☐ Stok awal di ARIBA dicatat lewat Terima barang sebelum toko buka
8. Keamanan & kepatuhan
- Kunci POS bisa dicabut kapan saja dari halaman Integrasi; semua panggilan tercatat di Audit Trail.
- ARIBA tidak menyimpan data kartu pembayaran. Pembayaran QRIS/transfer diproses penyedia pembayaran berizin; ARIBA hanya mencatat metodenya.
- Penjualan ke non-anggota tetap dibukukan, tetapi tidak menjadi dasar SHU anggota. Kewajiban pajak (mis. PPN bila koperasi PKP) mengikuti konsultan pajak koperasi; ARIBA belum menghitung pajak.
Lihat sendiri dengan data contoh.
Demo berjalan di peramban, tanpa mendaftar. Semua pembayaran disimulasikan.