Scopes yang dibutuhkan
write:contacts
write:sales
write:payments
write:inventory
read:reports
Alur Integrasi
- Terima webhook dari platform marketplace (Tokopedia, Shopee, dll.) setiap kali ada pesanan baru masuk ke toko Anda.
- Cek atau buat kontak pembeli berdasarkan nama dan nomor HP via
GET /api/v2/contacts?search=.... Jika belum ada, buat dengan POST /api/v2/contacts.
- Buat sales invoice untuk setiap order menggunakan
POST /api/v2/sales_invoices. Sertakan produk, qty, harga, dan ongkos kirim sebagai line item.
- Catat pembayaran saat status order di marketplace berubah menjadi "lunas" atau "selesai" via
POST /api/v2/receivable_payments.
- Kurangi stok produk yang terjual menggunakan
POST /api/v2/inventory_adjustments dengan quantity negatif.
- Monitor profitabilitas per channel/periode via
GET /api/v2/reports/profit_loss dan GET /api/v2/dashboards/revenue.
Contoh: Proses Order Masuk dari Marketplace
// Dipanggil saat webhook order baru diterima dari marketplace
async function processMarketplaceOrder(order) {
// Langkah 1 — cari atau buat kontak pembeli
let contactId;
const search = await fetch(
`https://app.zahironline.com/api/v2/contacts?search=${encodeURIComponent(order.buyer_phone)}`,
{ headers: { 'Authorization': 'Bearer zat_access_token_here' } }
);
const { data: contacts } = await search.json();
if (contacts.length > 0) {
contactId = contacts[0].id;
} else {
const newContact = await fetch('https://app.zahironline.com/api/v2/contacts', {
method: 'POST',
headers: { 'Authorization': 'Bearer zat_access_token_here', 'Content-Type': 'application/json' },
body: JSON.stringify({ name: order.buyer_name, phone: order.buyer_phone }),
});
contactId = ((await newContact.json()).data).id;
}
// Langkah 2 — buat invoice penjualan
const invRes = await fetch('https://app.zahironline.com/api/v2/sales_invoices', {
method: 'POST',
headers: { 'Authorization': 'Bearer zat_access_token_here', 'Content-Type': 'application/json' },
body: JSON.stringify({
contact_id: contactId,
transaction_date: order.created_at,
description: `Order #${order.order_id} — ${order.channel}`,
items: order.items.map(item => ({
product_id: item.zahir_product_id,
quantity: item.qty,
price: item.price,
})),
tags: [order.channel, 'marketplace'], // tag per channel
}),
});
const { data: invoice } = await invRes.json();
console.log(`Invoice #${invoice.invoice_number} dibuat untuk order ${order.order_id}`);
}
Webhook Events Terkait
sales_invoice.created
payment.received
inventory.adjusted
Gunakan tags pada setiap invoice untuk memfilter laporan per channel. Contoh: GET /api/v2/reports/profit_loss?tag=shopee untuk melihat profitabilitas khusus channel Shopee.
Scopes yang dibutuhkan
read:products
read:master_data
write:inventory
write:sales
Alur Integrasi
- WMS sebagai sumber kebenaran stok fisik. Setiap pergerakan barang di gudang (masuk, keluar, transfer) dikirimkan ke Zahir via
POST /api/v2/inventory_adjustments.
- Transfer stok antar gudang (misal: dari gudang pusat ke gudang cabang) dicatat di Zahir via
POST /api/v2/inventory_transfers.
- Zahir sebagai sumber stok untuk marketplace. Setelah stok diperbarui di Zahir, baca stok terkini via
GET /api/v2/products/{id} lalu push update ke API masing-masing marketplace.
- Catat pengiriman (delivery) saat WMS mengkonfirmasi barang sudah keluar gudang via
POST /api/v2/sales_deliveries, lengkap dengan nomor resi.
- Webhook
inventory.adjusted dari Zahir dapat digunakan untuk memicu pipeline push stok ke marketplace secara otomatis tanpa polling.
Contoh: Sinkronisasi Stok dari WMS ke Zahir & Marketplace
// Dipanggil oleh WMS setiap kali ada pergerakan stok keluar
async function syncStockFromWMS({ productId, warehouseId, qty, reason }) {
// Langkah 1 — catat penyesuaian stok di Zahir
await fetch('https://app.zahironline.com/api/v2/inventory_adjustments', {
method: 'POST',
headers: { 'Authorization': 'Bearer zat_access_token_here', 'Content-Type': 'application/json' },
body: JSON.stringify({
product_id: productId,
warehouse_id: warehouseId,
quantity: qty, // negatif untuk keluar, positif untuk masuk
description: reason, // "Fulfillment order #TKP-20260411-xxx"
}),
});
// Langkah 2 — baca stok terbaru dari Zahir
const res = await fetch(
`https://app.zahironline.com/api/v2/products/${productId}`,
{ headers: { 'Authorization': 'Bearer zat_access_token_here' } }
);
const { data: product } = await res.json();
const newStock = product.stock_quantity;
// Langkah 3 — push stok terbaru ke setiap marketplace
await Promise.all([
updateTokopediaStock(product.sku, newStock),
updateShopeeStock(product.sku, newStock),
updateLazadaStock(product.sku, newStock),
]);
console.log(`Stok ${product.name} diperbarui: ${newStock} unit`);
}
Webhook Events Terkait
inventory.adjusted
sales_invoice.created
inventory.transferred
Subscribe ke event inventory.adjusted di Zahir untuk membangun pipeline push stok ke marketplace secara event-driven — tidak perlu polling berkala.
Scopes yang dibutuhkan
read:products
write:sales
write:payments
write:inventory
read:reports
read:dashboards
Alur Integrasi
- Sinkronisasi katalog produk dan harga dari Zahir ke POS saat aplikasi kasir dibuka via
GET /api/v2/products. Tampilkan harga dan stok terkini di layar kasir.
- Setiap transaksi penjualan di kasir → buat sales invoice di Zahir via
POST /api/v2/sales_invoices dengan semua item yang dibeli.
- Catat pembayaran tunai via
POST /api/v2/cash_ins. Untuk pembayaran non-tunai (kartu/QRIS/transfer), gunakan POST /api/v2/receivable_payments.
- Kurangi stok produk yang terjual via
POST /api/v2/inventory_adjustments dengan quantity negatif sesuai jumlah item terjual.
- Rekonsiliasi akhir hari: tarik ringkasan penjualan via
GET /api/v2/dashboards/revenue dan laporan arus kas via GET /api/v2/reports/cash_flow untuk tutup buku kasir.
- Multi-outlet: transfer stok dari gudang pusat ke outlet via
POST /api/v2/inventory_transfers saat stok outlet menipis.
Contoh: Proses Transaksi Kasir
// Dipanggil saat kasir menekan tombol "Bayar" di POS
async function processPOSTransaction({ items, paymentMethod, cashierId }) {
const headers = { 'Authorization': 'Bearer zat_access_token_here', 'Content-Type': 'application/json' };
// Langkah 1 — buat invoice penjualan
const invRes = await fetch('https://app.zahironline.com/api/v2/sales_invoices', {
method: 'POST', headers,
body: JSON.stringify({
transaction_date: new Date().toISOString().split('T')[0],
description: `POS — Kasir ${cashierId} — ${new Date().toLocaleTimeString('id-ID')}`,
items: items.map(i => ({ product_id: i.id, quantity: i.qty, price: i.price })),
tags: ['pos', `kasir-${cashierId}`],
}),
});
const { data: invoice } = await invRes.json();
// Langkah 2 — catat pembayaran (tunai atau non-tunai)
const paymentEndpoint = paymentMethod === 'cash'
? '/api/v2/cash_ins'
: '/api/v2/receivable_payments';
await fetch(`https://app.zahironline.com${paymentEndpoint}`, {
method: 'POST', headers,
body: JSON.stringify({
sales_invoice_id: invoice.id,
amount: invoice.total,
payment_method: paymentMethod, // 'cash' | 'card' | 'qris'
transaction_date: invoice.transaction_date,
}),
});
// Langkah 3 — kurangi stok semua item yang terjual
for (const item of items) {
await fetch('https://app.zahironline.com/api/v2/inventory_adjustments', {
method: 'POST', headers,
body: JSON.stringify({
product_id: item.id, quantity: -item.qty,
description: `POS terjual — Invoice #${invoice.invoice_number}`,
}),
});
}
console.log(`Transaksi selesai: Invoice #${invoice.invoice_number}, Total Rp ${invoice.total.toLocaleString('id-ID')}`);
}
Webhook Events Terkait
sales_invoice.created
payment.received
inventory.adjusted
Gunakan tags: ['pos', 'kasir-01'] pada setiap invoice untuk filter laporan per kasir atau per outlet. Rekonsiliasi harian bisa dijadwalkan otomatis tiap pukul 23:59 via cron job.
Scopes yang dibutuhkan
write:contacts
write:purchases
write:inventory
write:sales
write:payments
read:reports
Alur Integrasi
- Daftarkan supplier bahan baku sebagai kontak via
POST /api/v2/contacts. Tandai dengan kategori "supplier" untuk memudahkan filter laporan.
- Buat Purchase Order bahan baku ke supplier via
POST /api/v2/purchases_orders saat sistem produksi membutuhkan material.
- Catat faktur pembelian saat bahan baku diterima di gudang via
POST /api/v2/purchases_invoices. Ini menambah stok bahan baku secara otomatis.
- Konsumsi bahan baku dalam produksi — kurangi stok bahan baku via
POST /api/v2/inventory_adjustments (qty negatif) bersamaan dengan tambah stok produk jadi (qty positif) ke gudang finished goods.
- Buat invoice penjualan produk jadi ke pembeli via
POST /api/v2/sales_invoices.
- Analisis biaya produksi vs revenue via
GET /api/v2/reports/profit_loss untuk menghitung margin per batch produksi menggunakan filter project_id.
Contoh: Pencatatan Batch Produksi
// Catat satu siklus produksi: konsumsi BM → tambah produk jadi
async function recordProductionBatch({ batchId, rawMaterials, finishedGoods }) {
const headers = {
'Authorization': 'Bearer zat_access_token_here',
'Content-Type': 'application/json',
};
// Langkah 1 — kurangi stok bahan baku (qty negatif)
for (const rm of rawMaterials) {
await fetch('https://app.zahironline.com/api/v2/inventory_adjustments', {
method: 'POST', headers,
body: JSON.stringify({
product_id: rm.product_id,
warehouse_id: rm.warehouse_id, // gudang bahan baku
quantity: -rm.qty_used, // negatif = keluar dari gudang BM
description: `Konsumsi produksi batch #${batchId}`,
}),
});
}
// Langkah 2 — tambah stok produk jadi (qty positif)
for (const fg of finishedGoods) {
await fetch('https://app.zahironline.com/api/v2/inventory_adjustments', {
method: 'POST', headers,
body: JSON.stringify({
product_id: fg.product_id,
warehouse_id: fg.warehouse_id, // gudang finished goods
quantity: fg.qty_produced, // positif = masuk gudang FG
description: `Hasil produksi batch #${batchId}`,
}),
});
}
console.log(`Batch #${batchId}: ${rawMaterials.length} BM dikonsumsi, ${finishedGoods.length} FG diproduksi.`);
}
Webhook Events Terkait
purchases_invoice.created
inventory.adjusted
sales_invoice.created
payment.received
Gunakan project_id pada setiap transaksi untuk mengelompokkan biaya dan pendapatan per batch/proyek produksi, lalu analisis dengan GET /api/v2/reports/profit_loss?project_id={id}.
Scopes yang dibutuhkan
write:contacts
write:products
write:sales
write:payments
write:inventory
read:reports
Alur Integrasi
- Daftarkan pasien baru sebagai kontak saat pendaftaran di EMR. Sinkronkan nama, nomor rekam medis, dan data kontak ke Zahir via
POST /api/v2/contacts.
- Pastikan layanan dan obat terdaftar sebagai produk. Buat produk untuk tiap jenis layanan (konsultasi, tindakan, rawat inap) dan obat-obatan via
POST /api/v2/products.
- Buat tagihan pasien saat pasien selesai berobat. Sertakan semua line item (layanan + obat yang digunakan) dalam satu invoice via
POST /api/v2/sales_invoices.
- Catat pembayaran pasien (tunai, kartu, BPJS) via
POST /api/v2/receivable_payments.
- Kurangi stok obat setelah diresepkan menggunakan
POST /api/v2/inventory_adjustments dengan nilai quantity negatif.
- Monitor stok kritis secara berkala:
GET /api/v2/products?filter[stock_quantity][$lte]=10 untuk memperoleh daftar obat yang hampir habis.
Contoh: Buat Tagihan Pasien & Kurangi Stok Obat
// Langkah 1 — buat invoice layanan pasien
const invoiceRes = await fetch('https://app.zahironline.com/api/v2/sales_invoices', {
method: 'POST',
headers: { 'Authorization': 'Bearer zat_access_token_here', 'Content-Type': 'application/json' },
body: JSON.stringify({
contact_id: 88, // ID pasien Dewi Rahayu
transaction_date: '2026-04-11',
due_date: '2026-04-11',
description: 'Kunjungan Poli Umum — No. RM: 00145',
items: [
{ product_id: 20, quantity: 1, price: 150000 }, // Konsultasi dokter
{ product_id: 45, quantity: 10, price: 3500 }, // Amoxicillin 500mg (10 tab)
],
}),
});
const { data: invoice } = await invoiceRes.json();
// Langkah 2 — kurangi stok Amoxicillin setelah diresepkan
await fetch('https://app.zahironline.com/api/v2/inventory_adjustments', {
method: 'POST',
headers: { 'Authorization': 'Bearer zat_access_token_here', 'Content-Type': 'application/json' },
body: JSON.stringify({
product_id: 45,
warehouse_id: 1, // Gudang farmasi
quantity: -10, // Negatif = pengurangan stok
description: `Resep pasien — Invoice #${invoice.invoice_number}`,
}),
});
console.log('Tagihan & penyesuaian stok selesai.');
Webhook Events Terkait
sales_invoice.created
payment.received
inventory.adjusted
Gunakan event inventory.adjusted untuk memicu alert ke tim farmasi ketika stok obat tertentu turun di bawah ambang batas minimum yang Anda tentukan.
Scopes yang dibutuhkan
write:contacts
write:sales
write:payments
read:reports
Alur Integrasi
- Daftarkan siswa atau wali murid sebagai kontak. Simpan data nama, email, dan nomor HP untuk keperluan notifikasi tagihan.
- Buat tagihan SPP bulanan untuk setiap siswa aktif menggunakan
POST /api/v2/sales_invoices. Sertakan due_date dan item tagihan sesuai kelas.
- Catat pembayaran masuk ketika wali murid membayar melalui transfer bank atau tunai menggunakan
POST /api/v2/receivable_payments.
- Catat penerimaan donasi tunai langsung (non-tagihan) dari donatur yayasan menggunakan
POST /api/v2/cash_ins.
- Tarik laporan arus kas setiap akhir bulan untuk pelaporan ke pengurus yayasan via
GET /api/v2/reports/cash_flow.
Contoh: Buat Tagihan SPP
// POST /api/v2/sales_invoices — buat tagihan SPP bulanan
const response = await fetch('https://app.zahironline.com/api/v2/sales_invoices', {
method: 'POST',
headers: {
'Authorization': 'Bearer zat_access_token_here',
'Content-Type': 'application/json',
},
body: JSON.stringify({
contact_id: 12, // ID wali murid Budi Santoso
transaction_date: '2026-04-01',
due_date: '2026-04-10',
description: 'SPP April 2026 — Kelas 7A',
items: [{
product_id: 5, // Produk "SPP Bulanan"
quantity: 1,
price: 750000,
}],
}),
});
const { data } = await response.json();
console.log(`Invoice dibuat: #${data.invoice_number}`);
Webhook Events Terkait
sales_invoice.created
payment.received
cash_in.created
Gunakan event payment.received untuk memicu notifikasi WhatsApp/email ke wali murid secara otomatis saat pembayaran berhasil dikonfirmasi.
Scopes yang dibutuhkan
write:contacts
write:payments
read:accounts
read:reports
Alur Integrasi
- Daftarkan donatur dan mustahik sebagai kontak terpisah. Gunakan field
tags untuk membedakan kategori (donatur vs mustahik).
- Catat penerimaan zakat atau infaq dari setiap donatur menggunakan
POST /api/v2/cash_ins. Arahkan ke akun Chart of Accounts yang sesuai (Dana Zakat, Dana Infaq, Dana Sedekah).
- Verifikasi saldo per pos dana secara real-time dengan menarik buku besar akun via
GET /api/v2/reports/general_ledger?account_id={id}.
- Catat penyaluran ke mustahik menggunakan
POST /api/v2/purchases_invoices (jika terstruktur per program) atau POST /api/v2/cash_outs untuk distribusi tunai langsung.
- Cetak laporan neraca dana per periode untuk keperluan audit dan pelaporan BAZNAS via
GET /api/v2/reports/balance_sheet.
Contoh: Catat Penerimaan Zakat Maal
// POST /api/v2/cash_ins — catat penerimaan zakat maal dari donatur
const response = await fetch('https://app.zahironline.com/api/v2/cash_ins', {
method: 'POST',
headers: {
'Authorization': 'Bearer zat_access_token_here',
'Content-Type': 'application/json',
},
body: JSON.stringify({
contact_id: 34, // ID donatur Ahmad Fauzi
account_id: 210, // Akun: Dana Zakat Maal
bank_account_id: 3, // Rekening bank LAZ
transaction_date: '2026-04-10',
amount: 2500000,
description: 'Zakat Maal — Ahmad Fauzi — Transfer BCA',
tags: ['zakat-maal', 'ramadan-1447'],
}),
});
const { data } = await response.json();
console.log(`Penerimaan dicatat: #${data.reference_number}, Rp ${data.amount.toLocaleString('id-ID')}`);
Webhook Events Terkait
cash_in.created
cash_out.created
Gunakan event cash_in.created untuk memicu pengiriman bukti donasi digital (PDF/WhatsApp) kepada donatur secara otomatis segera setelah pencatatan berhasil.