Integrasi API & Katalog
Hubungkan website atau katalog kustom ke Arzen menggunakan API key untuk inventori read-only, rekening, cek ongkir, dan upsert pelanggan di port 7090.
Konsep integrasi katalog kustom
Arzen menyediakan Platform API untuk menghubungkan website kustom, toko online headless, atau katalog publik ke data operasional bisnis Anda.
Dengan pendekatan ini, tampilan katalog, keranjang belanja, dan pengalaman pengguna dapat Anda kustomisasi sepenuhnya pada website Anda sendiri. Setiap kali pengunjung membuka halaman produk, website langsung meminta data ketersediaan terkini ke endpoint resmi api.arzen.id pada port 7090.
Seluruh alur pemrosesan pesanan, verifikasi transfer, faktur invoice, dan surat jalan pengiriman tetap diproses secara terpusat dan aman di dalam aplikasi Arzen.
Membuat API Key dan mengatur domain
Buka Settings → Email & integrasi → API platform sebagai pemilik atau administrator workspace.
Pada kolom Domain yang diizinkan, masukkan domain website kustom Anda (misalnya tokosaya.com atau https://shop.example.com), satu domain per baris.
Pada bagian Buat kunci API, isi Nama integrasi dan tentukan masa berlaku kunci (1 hingga 365 hari, default 90 hari).
Pilih izin yang dibutuhkan website Anda. Untuk katalog kustom, pilih Inventori / Stok · Baca, Rekening Pembayaran · Baca, Cek Ongkir · Hitung Tarif, dan Kontak · Buat & Ubah (Upsert).
Pilih Buat kunci, lalu segera salin token yang ditampilkan. Kunci API hanya ditampilkan sekali dan tidak dapat dilihat kembali.
Simpan kunci API pada server atau backend website Anda jika memungkinkan. Arzen hanya menyimpan hash SHA-256 dari token dan menerapkan rate limit 120 permintaan per menit per kunci.
Izin Read-Only untuk katalog dan keamanan
Demi keamanan data bisnis, katalog publik dibatasi secara ketat hanya untuk akses BACA (Read-Only) pada modul inventori dan rekening:
1. Inventori & Produk: Membaca nama, SKU, varian, harga jual, dan stok fisik yang tersedia secara real-time. Informasi internal seperti harga pokok produksi (HPP/COGS) dan catatan rahasia otomatis disaring dan tidak dikirimkan ke publik.
2. Rekening Pembayaran: Mengambil nomor rekening resmi toko (Bank, Nomor Rekening, dan Atas Nama) agar pelanggan pada website kustom mengetahui tujuan transfer pembayaran secara akurat.
3. Cek Ongkir: Menghitung tarif dan pilihan kurir ekspedisi (JNE, SiCepat, J&T, dll.) berdasarkan lokasi pengiriman dan bobot barang belanjaan pelanggan tanpa mengubah data apapun di sistem.
inventory:read — Menampilkan daftar produk dan ketersediaan stok fisik per varian dan gudang.
payment_accounts:read — Menampilkan rekening bank resmi workspace untuk pembayaran pesanan.
shipping_rates:read — Menghitung ongkir dan estimasi hari pengiriman untuk keranjang belanja.
Upsert pelanggan untuk checkout website
Saat pembeli melakukan pemesanan di website kustom, website mengirimkan data identitas pembeli ke endpoint Upsert Kontak Arzen.
Sistem secara cerdas memeriksa apakah pelanggan sudah terdaftar berdasarkan nomor telepon WhatsApp atau email. Jika nomor HP atau email sudah ada, data pelanggan otomatis diperbarui (status HTTP 200). Jika belum ada, kontak baru otomatis dibuat (status HTTP 201).
Dengan demikian, data master pelanggan tetap rapi dan terpusat di Arzen tanpa duplikasi.
contacts:create & contacts:update — Izin untuk membuat dan memperbarui kontak pelanggan.
Pencocokan otomatis: Mendukung format nomor HP Indonesia (+62 dan 08) serta validasi email.
Endpoint dan gateway port 7090
Kirimkan header Authorization: Bearer <API_KEY> pada setiap permintaan HTTP ke subdomain resmi api.arzen.id (mendengarkan di port 7090:openapi-port).
Katalog & Stok: GET /api/v1/workspaces/:workspaceId/inventory?limit=25&search=Kaos. Mengembalikan ketersediaan stok, status inStock, harga dasar, dan varian.
Rekening Pembayaran: GET /api/v1/workspaces/:workspaceId/payment-accounts. Mengembalikan bankName, accountNumber, accountHolder, dan petunjuk transfer.
Cek Ongkir: POST /api/v1/workspaces/:workspaceId/shipping/rates dengan body JSON berisi origin, destination, daftar kurir, serta item paket.
Upsert Pelanggan: POST /api/v1/workspaces/:workspaceId/contacts/upsert dengan body JSON berisi nama, telepon, email, dan alamat pengiriman.
Dokumentasi interaktif OpenAPI 3.1 lengkap tersedia langsung di /api/v1/docs dan spesifikasi mesin di /api/v1/openapi.json.