Manual integrasi mesin kasir (POS) minimarket koperasi

Sambungkan kasir di toko koperasi ke ARIBA: katalog dan harga ditarik dari ARIBA, setiap struk dibukukan sekali, dan belanja anggota otomatis menjadi dasar SHU.

Unduh koleksi Postman Unduh environment

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.example hanya contoh.

Berkas pendamping (unduh di bawah):


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

  1. 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").
  2. Idempoten. receipt_no adalah kunci unik per toko. Struk yang dikirim ulang (mis. karena sinyal putus) tidak dibukukan dua kali.
  3. Data minimal. POS hanya menerima nomor dan nama anggota yang disamarkan. Tidak ada NIK, saldo, atau skor kredit.
  4. Rahasia tetap di server. client_secret disimpan di perangkat kasir yang terkunci atau di server vendor POS, tidak di aplikasi web publik.

2. Persiapan di ARIBA (pengurus koperasi)

  1. Koperasi → Ubah profil → Unit usaha: centang Toko / minimarket. Menu Toko & Minimarket muncul.
  2. Toko & Minimarket → Produk & stok: lengkapi SKU dan barcode setiap produk. SKU harus sama dengan kode barang di POS.
  3. Integrasi → Tambah mitra: pilih jenis Mesin kasir (POS) toko/minimarket. Scope bawaan:
  4. pos:produk: membaca katalog dan harga
  5. pos:penjualan: mengirim dan membatalkan struk
  6. anggota:baca: mengecek nomor anggota
  7. Salin client id dan client secret (secret hanya tampil sekali) lalu serahkan ke teknisi POS lewat jalur aman, tidak lewat grup chat.
  8. 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)

  1. Pasang Postman (aplikasi desktop atau web).
  2. Import → seret kedua berkas ARIBA-POS.postman_collection.json dan ARIBA-POS.postman_environment.json.
  3. Pojok kanan atas → pilih environment ARIBA POS (demo).
  4. Buka environment, isi client_id dan client_secret (kolom secret tersembunyi). Sesuaikan base_url, token_url, dan store_code bila server sungguhan sudah tersedia.
  5. Jalankan 0. Autentikasi → Minta token. Skrip uji menyimpan access_token ke environment secara otomatis.
  6. Jalankan 1. Katalog produk. Pastikan SKU di POS sama dengan daftar ini.
  7. Jalankan 2. Anggota → Cek nomor anggota.
  8. Jalankan 3. Penjualan → Kirim satu struk (harus 201), lalu Kirim ulang struk yang sama (harus 200 dengan Idempotent-Replay: true, tidak dibukukan dua kali).
  9. Cek status struk → DIBUKUKAN. Batalkan struk → status DIBATALKAN.
  10. Jalankan folder 4. Contoh galat untuk memastikan POS menangani 404/422 dengan benar.
  11. 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.

Coba demo aplikasi