Lewati ke konten utama

13. Integrasi & Response Webhook Event Flink POS

Selain mendukung operasional offline-first yang tangguh di tingkat gerai fisik, Flink POS dilengkapi dengan fitur Real-Time Webhook Engine. Fitur ini memungkinkan setiap aktivitas kasir—terutama penyelesaian transaksi pembayaran (payment completed)—secara otomatis memicu pengiriman data terstruktur ke URL webhook yang Anda tentukan (seperti platform otomasi n8n, backend ERP, sistem akuntansi, CRM loyalty, maupun gateway notifikasi WhatsApp).

Dokumentasi ini menyajikan format data resmi dari body payload webhook Flink POS beserta penjelasan terperinci mengenai setiap variabel data untuk mempermudah proses integrasi dan pengolahan data di sisi penerima (receiver).


1. Arsitektur & Pemicu Event Webhook​

Ketika kasir menyelesaikan proses pembayaran di kasir tablet:

  1. Data transaksi disimpan seketika di SQLite lokal.
  2. Mesin webhook Flink POS menyusun paket event (event payload) berbasis JSON.
  3. Event dikirimkan melalui protokol HTTP/HTTPS POST ke endpoint webhook yang terdaftar dengan Content-Type: application/json.
  4. Sistem penerima (misalnya workflow n8n atau API server Anda) menerima payload dan dapat langsung memproses otomasi bisnis secara real-time.
Idempotensi & Keandalan

Setiap event webhook menyertakan atribut unik event_id berbasis UUID v4. Gunakan nilai ini sebagai kunci idempotensi (idempotency key) di sistem penerima Anda untuk mencegah pemrosesan ganda jika terjadi pengiriman ulang (retry) akibat kendala jaringan.


2. Struktur Lengkap JSON Body Webhook​

Berikut adalah contoh utuh data body yang dikirimkan oleh Flink POS saat event transaksi pembayaran kasir berhasil diselesaikan:

{
"schema_version": 1,
"event_id": "5d788c35-9ca6-443b-afc7-2d037f6cda40",
"event_type": "payment",
"action": "created",
"triggered_at": "2026-10-17T13:20:14.817773",
"source": {
"app": "pos_app_new",
"platform": "android",
"base_url": "http://cekproducts.flinkaja.com/",
"device_id": "POS-091f82fb-a5f0-4c98-8ed4-82f1667871ff",
"location": "1068",
"company_name": "Xie Cikgu Manag",
"company_address": "Jl Parkit 7, Kajen, Wonogiri",
"company_phone": "62874837373",
"user_id": 2,
"user_name": "IT Flink",
"user_email": "cekproducts.it@gmail.com",
"role": "owner"
},
"meta": {
"request_method": "POST",
"request_body": {
"id_pos": "f9930a24-11de-4776-a500-0683908b680e",
"invoiceid": "f9930a24-11de-4776-a500-0683908b680e",
"amount": "17000",
"paymentmode": "10",
"paymentmethod": "EDC",
"date": "2026-10-17",
"daterecorded": "2026-10-17T13:20:14.712019",
"transactionid": "",
"note": "",
"sale_agent": "2"
},
"awarded_points": 1
},
"payment": {
"local_id": 670,
"id_pos": "f9930a24-11de-4776-a500-0683908b680e",
"invoice_id": "f9930a24-11de-4776-a500-0683908b680e",
"amount": 17000,
"payment_mode_id": "10",
"payment_mode_name": "EDC",
"payment_method": "EDC",
"date": "2026-10-17",
"recorded_at": "2026-10-17T13:20:14.712019",
"note": "",
"transaction_id": "",
"is_synced": false
},
"order": {
"local_id": 178,
"remote_id": null,
"id_pos": "f9930a24-11de-4776-a500-0683908b680e",
"remote_number": "",
"queue_number": 6,
"status_id": 2,
"status_label": "paid",
"flags": {
"is_void": false,
"is_paid": true,
"has_refund_items": false,
"is_fully_refunded": false
},
"timestamps": {
"created_at": "2026-10-17T13:20:12.531933",
"paid_at": "2026-10-17T13:20:14.712019"
},
"order_type": "Dine In",
"order_note": "",
"label": "Walk-in Customer",
"cashier": {
"id": 2,
"name": "IT Flink",
"email": "cekproducts.it@gmail.com",
"phone": "",
"role": "Owner"
},
"member": {
"id": 1,
"id_pos": "",
"name": "walk in",
"phone": "",
"address": "",
"email": "",
"points": 587,
"datecreated": "2026-04-13 13:36:18"
},
"shift": {
"id_shift": null,
"shift_name": "Shift 1",
"user_id": "IT Flink",
"start_time": "2026-10-17T09:30:14.284436",
"end_time": "",
"status": 0
},
"totals": {
"item_count": 1,
"subtotal": 17000,
"discount": 0,
"grand_total": 17000,
"received_total": 17000,
"manual_discount_value": 0,
"discount_type": "fixed",
"refund_total": 0,
"awarded_points": 1
},
"items": [
{
"local_id": 341,
"product_id": 856,
"product_name": "Butter Parmesan _Sayap-Nasi",
"description": "Butter Parmesan | Sayap-Nasi",
"qty": 1,
"price": 17000,
"subtotal": 17000,
"note": "",
"order_type": "Dine In",
"order_types_json": "[{\"dinein\":\"17000.00\"},{\"gofood\":\"17000.00\"},{\"shopeefood\":\"17000.00\"},{\"grabfood\":\"17000.00\"},{\"tiktok\":\"17000.00\"},{\"takeaway\":\"17000.00\"}]",
"remote_item_id": null,
"discount_total": 0,
"discount_type": "percent",
"is_refund": false
}
],
"payments": [
{
"local_id": 670,
"id_pos": "f9930a24-11de-4776-a500-0683908b680e",
"invoice_id": "f9930a24-11de-4776-a500-0683908b680e",
"amount": 17000,
"payment_mode_id": "10",
"payment_mode_name": "EDC",
"payment_method": "EDC",
"date": "2026-10-17",
"recorded_at": "2026-10-17T13:20:14.712019",
"note": "",
"transaction_id": "",
"is_synced": false
}
]
}
}

3. Penjelasan Rinci Parameter & Struktur Data​

Untuk mempermudah integrasi, payload di atas dibagi menjadi beberapa komponen utama:

A. Root Envelope (Identitas Event)​

Bagian terluar dari objek body yang memuat metadata penting event:

FieldTipe DataDeskripsi & Penjelasan
schema_versionIntegerVersi skema struktur payload (contoh: 1). Membantu integrasi sistem jika di kemudian hari terdapat penambahan format.
event_idString (UUID)ID unik untuk setiap kejadian/pengiriman webhook. Wajib dijadikan acuan idempotency untuk mencegah transaksi diproses berulang.
event_typeStringKategori entitas pemicu. Contoh: payment (transaksi pembayaran lunas).
actionStringOperasi yang dilakukan. Nilai created mengindikasikan pembayaran baru saja berhasil dibuat dan dibukukan.
triggered_atString (ISO 8601)Waktu presisi saat webhook ditembakkan oleh tablet kasir (contoh: 2026-10-17T13:20:14.817773).

B. Objek source (Identitas Outlet & Perangkat Kasir)​

Menjelaskan asal-usul transaksi secara transparan, termasuk nama cabang fisik, ID perangkat, dan kasir yang bertugas:

FieldTipe DataDeskripsi & Contoh
appStringNama aplikasi POS (contoh: pos_app_new).
platformStringSistem operasi tablet kasir (contoh: android).
base_urlStringDomain server cloud Flink yang terhubung ke lisensi gerai ini.
device_idStringPengenal unik perangkat (device fingerprint), contoh: POS-091f82fb-....
locationStringID cabang toko / outlet fisik tempat transaksi berlangsung (contoh: 1068).
company_nameStringNama gerai / perusahaan pemilik cabang (contoh: Xie Cikgu Manag).
company_addressStringAlamat fisik gerai operasional.
company_phoneStringNomor kontak resmi toko.
user_idIntegerID akun pengguna staf kasir yang memproses pesanan.
user_nameStringNama staf kasir yang sedang bertugas saat checkout (contoh: IT Flink).
user_emailStringAlamat surel staf kasir.
roleStringHak wewenang pengguna (contoh: owner, supervisor, cashier).

C. Objek meta (Parameter Input & Poin Reward)​

Menyimpan payload masukan awal saat transaksi dipicu serta perhitungan poin loyalitas:

  • request_method: Metode HTTP pemrosesan transaksi internal (POST).
  • request_body: Data formulir mentah saat pembayaran divalidasi ke sistem kasir (mencakup id_pos, invoiceid, nominal, metode pembayaran, tanggal rekam, dan ID kasir).
  • awarded_points: Jumlah poin loyalitas baru yang berhak didapatkan member dari transaksi ini (pada contoh: 1 poin).

D. Objek payment (Rincian Transaksi Pembayaran)​

Menyajikan rincian keuangan dari proses pelunasan:

FieldTipe DataKeterangan
local_idIntegerID urutan baris pembayaran pada SQLite lokal tablet.
id_posString (UUID)UUID unik transaksi pembayaran kasir.
invoice_idString (UUID)Nomor nota/invoice digital yang terhubung dengan pesanan ini.
amountNumberNilai uang yang dibayarkan (contoh: 17000).
payment_mode_idStringID mode metode pembayaran di master data (contoh: 10).
payment_mode_nameStringNama mode pembayaran yang dipilih (contoh: EDC, Cash, QRIS).
payment_methodStringKlasifikasi metode pembayaran.
dateString (YYYY-MM-DD)Tanggal transaksi (contoh: 2026-10-17).
recorded_atString (ISO 8601)Stempel waktu lengkap pembayaran dicatat di database lokal.
transaction_idStringNomor referensi/otorisasi eksternal (misal nomor batch EDC / approval code QRIS).
is_syncedBooleanMenandai apakah data pembayaran sudah terunggah ke database cloud pusat saat webhook dipicu (true/false).

E. Objek order (Detail Lengkap Pesanan)​

Berisi seluruh data pesanan, nomor antrean, status, pelanggan/member, kasir, shift kasir, daftar item produk, dan rekap finansial:

1. Header & Antrean Pesanan​

  • local_id: ID unik pesanan pada SQLite lokal perangkat.
  • id_pos: UUID referensi unik transaksi.
  • queue_number: Nomor urut antrean pesanan pelanggan (contoh: nomor 6), ideal untuk dihubungkan ke layar panggil nomor pesanan (Customer Display System).
  • status_id & status_label: Status pembayaran akhir (2 / paid).
  • order_type: Saluran pesanan (misalnya Dine In, Take Away, GoFood, GrabFood).
  • label: Label pelanggan (contoh: Walk-in Customer).

2. Status & Boolean Flags (flags)​

Menyediakan status cepat kondisi pesanan:

  • is_void: Bernilai true jika pesanan dibatalkan/dihapus (void).
  • is_paid: Bernilai true jika pesanan sudah berstatus lunas.
  • has_refund_items: Menandakan apakah ada salah satu item yang dikembalikan/refund.
  • is_fully_refunded: Menandakan apakah transaksi sudah direfund secara keseluruhan.

3. Waktu Transaksi (timestamps)​

  • created_at: Waktu pesanan pertama kali dibuka di kasir.
  • paid_at: Waktu penyelesaian pembayaran berhasil divalidasi.

4. Kasir & Pelanggan Loyalitas (cashier & member)​

  • cashier: Objek data staf pelayan (ID, nama, email, telepon, dan role).
  • member: Data member pelanggan:
    • id: ID profil member (ID 1 dialokasikan untuk pelanggan umum/walk-in).
    • name: Nama pelanggan.
    • points: Total saldo akumulasi poin member saat ini setelah ditambah transaksi berjalan (contoh: 587).
    • datecreated: Tanggal pendaftaran member pertama kali.

5. Sesi Shift Kasir (shift)​

  • shift_name: Nama sesi shift operasional kasir (contoh: Shift 1).
  • user_id: Kasir penanggung jawab shift.
  • start_time: Waktu pembukaan shift kasir (Open Shift).
  • status: Status sesi shift kasir (0 = aktif/berjalan).

6. Rekapitulasi Finansial (totals)​

  • item_count: Jumlah kuantitas produk yang dibeli.
  • subtotal: Total kotor sebelum potongan diskon.
  • discount: Nilai total potongan diskon yang diaplikasikan.
  • grand_total: Nilai akhir tagihan bersih yang wajib dibayar pelanggan.
  • received_total: Total nominal pembayaran yang diterima kasir.
  • refund_total: Nilai uang yang dikembalikan jika ada refund.
  • awarded_points: Poin loyalitas yang dihadiahkan dari nota ini.

7. Rincian Item Produk (items[])​

Setiap elemen di dalam array items merepresentasikan satu produk/menu yang dibeli:

  • product_id: ID produk katalog master.
  • product_name: Nama produk (contoh: Butter Parmesan _Sayap-Nasi).
  • description: Keterangan varian produk.
  • qty: Jumlah porsi/barang yang dibeli.
  • price: Harga satuan yang berlaku pada transaksi ini.
  • subtotal: Perhitungan perkalian qty * price.
  • order_types_json: String JSON yang memetakan daftar harga jual produk tersebut untuk setiap channel penjualan (dinein, gofood, shopeefood, grabfood, tiktok, takeaway).
  • is_refund: Menandakan status apakah item bersangkutan mengalami refund.

8. Array Pembayaran (payments[])​

Mendukung transaksi dengan pembayaran terpisah (split payment). Jika satu pesanan dilunasi dengan kombinasi Tunai + EDC/QRIS, seluruh detail masing-masing metode pembayaran akan terdaftar di dalam array ini.


4. Contoh Skenario Integrasi Bisnis​

Dengan memanfaatkan payload webhook Flink POS di atas, tim pengembang dapat membangun beragam solusi otomasi:

graph LR
POS["Flink POS (Tablet Kasir)"] -->|"Webhook POST (JSON)"| N8N["Workflow Engine (n8n / Backend API)"]
N8N -->|"Kirim Struk Digital"| WA["WhatsApp API Pelanggan"]
N8N -->|"Update Saldo Poin"| CRM["Sistem Loyalty / CRM"]
N8N -->|"Sinkron Omzet Kas"| ACC["Software Akuntansi (Jurnal / Accurate)"]
N8N -->|"Pengurangan Stok Bahan"| ERP["Warehouse / Gudang Pusat"]
  1. Pengiriman Struk Digital Otomatis ke WhatsApp Pelanggan: Mengambil data kontak pelanggan (order.member.phone) dan rincian belanja (order.items), lalu mengirimkan pesan WhatsApp otomatis berisi rincian nota digital dan ucapan terima kasih.
  2. Pembaruan Poin & Notifikasi Loyalitas Real-Time: Memanfaatkan order.totals.awarded_points dan order.member.points untuk memberi tahu member secara instan: "Selamat! Anda mendapatkan 1 poin baru. Saldo poin Anda kini 587 poin."
  3. Pencatatan Buku Kas & Jurnal Finansial Otomatis: Mengirimkan order.totals.grand_total dan payment.payment_mode_name ke aplikasi akuntansi untuk otomatis membukukan penerimaan kas atau piutang EDC perbankan tanpa rekonsiliasi manual.
  4. Pengurangan Stok Bahan Baku Restoran (Inventory Depletion): Berdasarkan order.items[].product_id dan qty, sistem gudang/kitchen dapat langsung memotong persediaan bahan baku (misal: porsi sayap ayam, beras, dan saus parmesan) secara seketika.

5. Ringkasan & Navigasi​

Dengan adanya integrasi Webhook Event ini, Flink POS tidak hanya berfungsi sebagai aplikasi kasir toko yang andal secara offline, namun juga menjadi titik pusat data operasional (central operational hub) yang siap berkolaborasi secara dinamis dengan seluruh ekosistem digital bisnis Anda.

Untuk meninjau modul sebelumnya atau kembali ke awal: