Selamat datang di dokumentasi bosOnline API. API ini dirancang untuk mendukung kebutuhan aplikasi bosOnline, yaitu platform manajemen toko online yang mencakup modul autentikasi, manajemen toko, katalog produk, pengelolaan pesanan, dan form builder. Dengan bosOnline API, Anda dapat mengintegrasikan, mengotomatisasi, dan memperluas sistem bosOnline pada berbagai front-end (web, mobile, atau integrasi pihak ketiga).API ini bersifat RESTful, memungkinkan Anda untuk memanfaatkan endpoint yang jelas dan terstruktur berdasarkan entitas utama dalam bosOnline. Berikut ringkasan modul dan entitas yang menjadi dasar rancangan API:
Modul dan Entitas Utama#
1.
Users: Menyimpan data pengguna (email, nama, telepon, verifikasi KTP, status aktif).
Refresh Tokens: Menyimpan token sesi, IP address, user agent, informasi perangkat, dan status aktif.
Login Attempts: Melacak upaya login (login via email/username, IP address, user agent, pesan kesalahan).
Roles: Mendefinisikan peran pengguna (contoh: admin, manager, agent).
2.
Manajemen Toko (Store Management)Stores: Menyimpan data toko (nama, pemilik, tanggal pembuatan/pebaruan, status onboarding, sub-domain, nomor telepon toko).
Staff: Menyimpan relasi staf ke user dan toko (user ID, store ID, peran, tanggal pembuatan/pebaruan).
Modules: Menyimpan modul yang dapat diakses staf (nama modul, kode, izin CRUD, staf pemegang izin).
3.
Katalog Produk (Product Catalog)Categories: Menyimpan kategori produk (nama, status).
Products: Menyimpan produk utama (nama, deskripsi, relasi ke toko, kategori, SKU, dimensi, harga max/min, HPP, stok, URL path, status publish).
Product Variants: Menyimpan varian produk (nama varian, SKU, berat, dimensi, harga, HPP, stok, minimum QTY grosir, status).
Product Images: Menyimpan gambar produk (URL, nama file, lokasi file).
Attributes & Attribute Items: Menyimpan atribut khusus produk (contoh: kemasan, ukuran) dan pilihan item atribut (100gr, 200gr, dll.).
4.
Manajemen Pesanan (Order Management)Customers: Menyimpan data pelanggan (email, nama, telepon, alamat lengkap, kota, provinsi).
Orders: Menyimpan data pesanan (relasi ke pelanggan, toko, total amount, status, catatan, AWB, status pelacakan, upaya follow-up).
Order Items: Menyimpan detail item pada pesanan (relasi ke produk, varian, quantity, harga satuan, snapshot nama produk & SKU varian, form structure, voucher jika ada).
Payments: Menyimpan data pembayaran (relasi ke pesanan, jumlah, status, metode pembayaran—manual/COD/e-payment, tanggal pembayaran, kode invoice).
Vouchers: Menyimpan data voucher diskon (kode, tipe—persentase atau nominal, nilai, minimal pembelian, tanggal mulai/akhir, batas penggunaan, status, relasi ke toko).
5.
Form Builder & Success PagesForms: Menyimpan data formulir dinamis (nama, status, relasi ke toko & produk, struktur JSON form builder, jumlah tampilan halaman, jumlah leads, conversion rate, file template).
Success Pages: Menyimpan konfigurasi halaman sukses setelah submit form (relasi ke form, URL header image, headline, tagline, warna latar, teks & warna tombol, aksi post-submit, tautan media sosial, video, metode pembayaran).
Ads Trackings: Menyimpan pengaturan pelacakan iklan pada success page (trigger all events, hanya submit event, daftar pixel configs).
Ringkasan Fitur API#
1.
Autentikasi & AutentikasiRegistrasi (membuat akun baru dengan verifikasi KTP jika diperlukan).
Login (menghasilkan access token & refresh token).
Refresh Token (memperbarui access token menggunakan refresh token yang masih aktif).
Logout (menonaktifkan session & refresh token).
Verifikasi Peran (role-based access control untuk endpoint tertentu: hanya admin/manager/agent yang memiliki izin sesuai perannya).
2.
Buat & Perbarui Toko (POST /api/stores, PUT /api/stores/{id}).
Dapatkan Daftar Toko (pemilik & staf) (GET /api/stores, GET /api/stores/{id}).
Tambah/Hapus Staf (POST /api/stores/{id}/staff, DELETE /api/stores/{store_id}/staff/{staff_id}).
Atur Modul & Izin Staf (POST /api/staff/{id}/modules, PUT /api/staff/{id}/modules/{module_id}).
3.
Kategori: Buat, Edit, Hapus, dan Dapatkan (/api/categories).
Produk Utama: CRUD Produk (/api/stores/{store_id}/products).
Varian: CRUD Varian Produk (/api/products/{product_id}/variants).
Gambar: Upload, Hapus, dan Dapatkan Gambar Produk (/api/products/{product_id}/images).
Atribut & Item Atribut: CRUD Atribut (/api/products/{product_id}/attributes, /api/attributes/{attribute_id}/items).
4.
Pelanggan: Daftar & Edit Data Pelanggan (/api/customers).
Pesanan: Buat Pesanan Baru (POST /api/orders), Dapatkan Daftar Pesanan Toko, Edit Status Pesanan (PUT /api/orders/{id}), Dapatkan Detail Pesanan (GET /api/orders/{id}).
Order Items: Termasuk snapshot informasi produk/varian, struktur form jika pesanan kustom.
Pembayaran: Tambah & Validasi Pembayaran (POST /api/orders/{order_id}/payments, GET /api/orders/{order_id}/payments).
Voucher: Buat, Aktifkan/Nonaktifkan, dan Terapkan pada Pesanan (/api/stores/{store_id}/vouchers).
5.
Form Builder & Success PagesFormulir: Buat Form Dinamis (POST /api/stores/{store_id}/forms), Update, Hapus, dan Lihat Struktur Form (GET /api/forms/{id}).
Success Pages: Buat & Konfigurasikan Halaman Setelah Submit (/api/forms/{form_id}/success-pages).
Ads Tracking: Konfigurasi Pixel, Event Submit, atau All Events untuk Success Page (/api/success-pages/{id}/ads-trackings).
Alur Umum Penggunaan#
1.
Pengembang melakukan panggilan ke endpoint /api/auth/login untuk mendapatkan access token (JWT) beserta refresh token.
Access token harus disertakan pada header Authorization: Bearer <token> untuk mengakses endpoint terproteksi.
Saat access token kadaluarsa, lakukan refresh melalui /api/auth/refresh.
2.
Setelah login sebagai pemilik, panggil /api/stores untuk membuat toko baru.
Pemilik dapat menambahkan staf dan menetapkan peran, yang menentukan modul apa saja yang dapat diakses staf tersebut.
Staf mengakses resource sesuai modul yang diizinkan (misalnya, hanya staf dengan modul “product” yang dapat mengelola produk).
3.
Pengelolaan Katalog ProdukBuat kategori untuk mengelompokkan produk.
Buat produk utama pada toko tertentu, lalu tambahkan varian (jika diperlukan), unggah gambar, serta atur atribut seperti ukuran, kemasan, atau pilihan khusus lainnya.
Produk dapat di-publish atau di-unpublish berdasarkan status dan ketersediaan stok.
4.
Pelanggan (akan otomatis disimpan saat checkout) membuat pesanan yang mencakup satu atau beberapa item.
Pada saat pembuatan pesanan, snapshot nama produk dan SKU varian disimpan agar histori tetap akurat meski data produk berubah di kemudian hari.
Pembayaran dapat diproses secara manual, COD, atau melalui e-payment. Setelah pembayaran berhasil, status pesanan diperbarui.
Staf dapat memantau status pelacakan (AWB) dan melakukan follow-up sesuai kebutuhan.
5.
Formulir & Lead GenerationPemilik toko dapat membuat formulir kustom—misalnya untuk pre-order, survey kepuasan, atau promosi khusus—menggunakan struktur JSON.
Setelah formulir di-submit, pengguna diarahkan ke success page yang telah dikonfigurasi, lengkap dengan opsi redirect ke halaman lain atau membuka kontak customer service.
Melalui Ads Tracking, pemilik dapat memantau konversi dengan menambahkan pixel (Facebook, Google Analytics, dll.) pada success page.
Tujuan Dokumentasi#
1.
Panduan Cepat
Memperlihatkan endpoint-endpoint utama beserta metode HTTP, URI, parameter wajib/opsional, dan contoh request/response.
2.
Referensi Lengkap
Menjelaskan struktur request & response JSON, error codes, dan status HTTP yang mungkin dikembalikan oleh API.
3.
Best Practices
Memberikan rekomendasi keamanan (misalnya rate limiting, validasi input), cara mengelola token JWT dan refresh token, serta tips mengoptimalkan performa (misalnya caching Redis, pagination daftar hasil).
4.
Use Case
Menjelaskan alur-end-to-end: contoh integrasi sederhana untuk pembuatan toko, pengelolaan produk, pemrosesan pesanan hingga analitik formulir—sebagai panduan bagi tim front-end maupun developer integrasi pihak ketiga.
Dengan memahami struktur modul dan entitas di atas serta tujuan penggunaan API, diharapkan Anda dapat membangun, mengelola, dan memelihara aplikasi bosOnline secara efisien dan terstruktur. Dokumentasi ini akan menguraikan setiap endpoint secara detail dan memberikan contoh-contoh praktis untuk mempermudah integrasi. Selamat mengeksplorasi bosOnline API! Modified at 2025-05-31 13:57:30
