Referensi REST API
Referensi REST API ini memuat seluruh spesifikasi integrasi yang mendukung platform DagangBot AI. Dokumentasi ini merinci 105 operasi unik yang dikelompokkan ke dalam 21 tag layanan, mulai dari manajemen autentikasi, manipulasi knowledge base, hingga sinkronisasi data billing dan analitik. Setiap endpoint telah distandardisasi mengikuti pola arsitektur REST, menerima dan merespons dalam format JSON murni.
Stable1. Ikhtisar & Nilai Bisnis
- Penyatuan Sistem (Unified API): Memungkinkan integrasi menyeluruh (end-to-end) sistem ERP, CRM, atau dashboard internal perusahaan Anda secara langsung dengan instans core DagangBot tanpa memerlukan middleware konversi tambahan.
- Isolasi Keamanan Ketat: Menggunakan pemisahan tipe key secara eksplisit antara konektivitas inter-server (
dgb_all_) dan kredensial pengguna (Bearer Auth), memastikan rotasi kunci dapat dilakukan tanpa mematikan sesi peramban pengguna. - Prediktabilitas Skema Data: Memiliki arsitektur Error Envelope terpusat yang selalu memastikan balasan kesalahan tertata seragam. Integrator tidak perlu melakukan pengecekan ganda bentuk error di tingkat catch aplikasi klien.
- Kontrol Limitasi (Rate-Limiting): Dilengkapi sistem throttle deterministik yang mencegah lonjakan beban trafik berlebih dari level tenant. Rate limit dikelola secara ketat melalui sistem keamanan platform, dengan batas global default 600 permintaan/menit (dapat diubah via variabel lingkungan
RATE_LIMIT_PER_MINUTE), batas autentikasi 20 permintaan/menit (AUTH_RATE_LIMIT_PER_MINUTE), dan operasi sensitif 10 permintaan/menit (SENSITIVE_RATE_LIMIT_PER_MINUTE). Jika terlampaui, server akan membalas HTTP 429 dengan kode errorRATE_LIMIT_EXCEEDEDdan menyertakan headerRetry-After.
Referensi ini mencerminkan struktur internal per spesifikasi OpenAPI (v3) nyata di server.
2. Alur Visual & Antarmuka
Karena API beroperasi di belakang layar tanpa antarmuka grafis spesifik, konfigurasi otorisasi kunci harus dilakukan pada Dashboard Admin Tenant sebelum mulai mengirim request.


3. Panduan Langkah-demi-Langkah
Berikut ini panduan integrasi standar dari inisialisasi hingga manipulasi endpoint spesifik menggunakan perintah curl konvensional.
- 1
Langkah 1: Persiapkan URL dan Kredensial
Tentukan lingkungan target server Anda (pengembangan berlokasi di
localhost:8080/api/v1sementara basis produksi merujuk padahttps://dagangbot.web.id/api/v1). Dapatkan API Key Anda melalui menu integrasi dan simpan dalam variabel environment lokal. - 2
Langkah 2: Uji Konektivitas Sistem (Liveness)
Lakukan verifikasi kelancaran jalur lalu-lintas jaringan Anda terhadap server kami. Pengujian probe di bawah tidak mensyaratkan autentikasi.
bashcurl -X GET "https://dagangbot.web.id/api/v1/health" \ -H "Accept: application/json" - 3
Langkah 3: Eksekusi Query ke Sistem Terproteksi
Setelah terhubung, kirimkan perintah mutasi (misalnya: membuat produk baru). Sisipkan kunci atau token JWT pada parameter
AuthorizationatauX-API-Keydi header.bashcurl -X POST "https://dagangbot.web.id/api/v1/all-in-one/products" \ -H "X-API-Key: dgb_all_abc123" \ -H "Content-Type: application/json" \ -d '{ "name": "Layanan Premium Integrasi", "price": 500000, "description": "Deskripsi layanan panjang lebar." }' - 4
Langkah 4: Validasi Format Kesalahan
Selalu rancang interseptor (interceptor) jaringan pada pustaka fetch HTTP Anda yang mengantisipasi skema 4xx atau 5xx untuk diselaraskan ke fungsi UI atau notifikasi pelaporan eror internal.
4. Parameter & Spesifikasi Teknis
Semua komunikasi data harus menyertakan tipe konten application/json (kecuali tipe formulir unggahan multipart).
4.1. Skema Autentikasi & Otorisasi
DagangBot menggunakan pemisahan yang tegas antara token Personal/User dan Machine-to-Machine (M2M) Key untuk memitigasi penyalahgunaan kredensial. Setiap endpoint mensyaratkan salah satu dari pendekatan ini:
- Bearer Token (JWT): Digunakan oleh aplikasi dasbor atau peramban pengguna. Dikirim pada
Authorization: Bearer <token>. Masa berlaku (Time-to-Live) lebih singkat dan terkait dengan sesi pengguna individu serta izin (RBAC scopes). - API Key (M2M): Spesifik untuk klaster
/api/v1/all-in-one/*. Dikirim pada headerX-API-KeyatauAuthorizationdengan awalandgb_all_. Bersifat statis, tidak terikat ke satu pengguna, dan digunakan secara eksklusif untuk integrasi server antar peladen (misal: penarikan katalog otomatis dari ERP).
4.2. Konvensi Paginasi
Endpoint berdata besar mendukung dua jenis paginasi yang tidak dapat dicampur:
-
Paginasi Berbasis Halaman (Offset-based): Digunakan pada API daftar standar (seperti
/customersatau/products). Memanfaatkan parameter URLpage(default1) danper_page(default tergantung endpoint, maksimum100). Balasan akan mengembalikan bungkusanmetadengan format:json"meta": { "page": 1, "per_page": 20, "total": 512, "total_pages": 26 } -
Paginasi Kursor (Cursor-based / Monotonic): Dirancang khusus untuk sinkronisasi sekstensif dan berkecepatan tinggi, seperti modul antrean pesan atau pengunduhan log antrean internal (
event/outbox). Klien memberikancursor(berupasequenceID, atau-1/0untuk dari awal) beserta limitlimit. Klien lalu menelusuri balasanCursor(atauCursorRef) untuk pemanggilan selanjutnya. Pendekatan cursor sangat resisten terhadap insiden penambahan data acak (phantom reads) saat paginasi berjalan.
4.3. Tabel A. Header Fundamental Jaringan
4.4. Tabel Parameter URL Global (Query Params)
4.5. Struktur Bungkusan (Envelope)
Sukses Envelope (SuccessResponse)
Setiap keberhasilan membalas dalam bentuk standar yang selalu memiliki field data, serta field opsional meta untuk parameter paginasi.
{
"data": [
{ "id": "123", "name": "Budi" }
],
"meta": {
"page": 1,
"per_page": 20,
"total": 1,
"total_pages": 1
}
}Bungkusan Error Berstandar (ErrorResponse)
Platform kami menggunakan ErrorResponse deterministik. Semua 4xx dan 5xx mematuhi JSON berikut ini (pesan internal pangkalan data / SQLSTATE leak tidak akan disajikan, ditangani oleh fungsi sanitizeMessage).
Daftar Katalog Endpoint Aktif
Terdapat 105 titik akses API yang tercatat aktif beroperasi, tersebar melintasi klaster sub-sistem utama.
All-in-One API
/all-in-one/accountApiKeyAuthBaca detail akun merchant
Identitas, langganan, saldo token, statistik. Scope `account:read`.
Respons
/all-in-one/mediaApiKeyAuthDaftar media library tenant
Daftar aset (foto produk, media katalog WA, lampiran bukti bayar). Read-only. Scope `media:read`. Query `module`, `file_type`, `page`, `per_page` (maks 100).
Parameter
Respons
/all-in-one/otp/sendApiKeyAuthKirim OTP
Scope `otp:send`.
Body (wajib)
Respons
/all-in-one/otp/verifyApiKeyAuthVerifikasi OTP
Scope `otp:send`.
Body (wajib)
Respons
/all-in-one/rag/queryApiKeyAuthQuery RAG (jawaban dari knowledge base)
Pencarian vektor + sintesis jawaban AI atas knowledge base merchant. Scope `rag:read`. Bila provider embedding tidak tersedia, otomatis beralih ke pencarian kata kunci (field `used_fallback` = true).
Body (wajib)
Respons
/all-in-one/notify/sendApiKeyAuthKirim notifikasi multi-kanal
Scope `notify:send`.
Body (wajib)
Respons
/all-in-one/messages/sendApiKeyAuthKirim pesan WhatsApp ke satu nomor
Scope `messages:send`.
Body (wajib)
Respons
/all-in-one/webhookApiKeyAuthTerima event webhook masuk (dua arah)
Menyimpan event ke inbox tenant. Scope `webhook:receive`.
Body (opsional)
Respons
/all-in-one/wa/instancesApiKeyAuthDaftar instance WhatsApp
Menampilkan nomor WhatsApp milik tenant beserta status koneksinya (id, instance_name, phone_number, connection_status, connection_type, service_role, dsb). Scope `wa:manage`.
Respons
/all-in-one/wa/instancesApiKeyAuthTambah nomor WhatsApp baru
Membuat sesi WhatsApp baru di gateway lalu menyimpannya. Scope `wa:manage`. Rate-limited (SensitiveLimit). Untuk tenant dengan scope cabang, `branch_id` wajib diisi.
Body (wajib)
Respons
/all-in-one/wa/instances/{id}/qrApiKeyAuthAmbil kode QR untuk scan
Mengembalikan QR live (data URL base64) untuk memindai nomor. Bila perangkat sudah tersambung, balasan berisi connected=true tanpa QR. Scope `wa:manage`.
Parameter
Respons
/all-in-one/wa/instances/{id}/restartApiKeyAuthRestart koneksi sesi WhatsApp
Scope `wa:manage`. Rate-limited (SensitiveLimit).
Parameter
Respons
/all-in-one/wa/instances/{id}ApiKeyAuthHapus instance WhatsApp
Memutus dan menghapus instance. Scope `wa:manage`. Rate-limited (SensitiveLimit).
Parameter
Respons
/all-in-one/billing/balanceApiKeyAuthLihat saldo token
Scope `billing:read`.
Respons
/all-in-one/billing/transactionsApiKeyAuthRiwayat transaksi token
Scope `billing:read`.
Respons
/all-in-one/billing/invoicesApiKeyAuthDaftar invoice
Scope `billing:read`.
Respons
/all-in-one/billing/topupApiKeyAuthTopup saldo (membuat invoice pembayaran)
Membuat invoice top-up saldo token lewat payment gateway. Saldo bertambah setelah pembayaran terkonfirmasi (webhook gateway). Scope `billing:create`. Wajib header `Idempotency-Key`.
Parameter
Body (wajib)
Respons
/all-in-one/productsApiKeyAuthDaftar produk
Scope `products:read`.
Respons
/all-in-one/productsApiKeyAuthBuat produk
Scope `products:create`.
Respons
/all-in-one/products/{id}ApiKeyAuthUbah produk
Scope `products:update`.
Parameter
Respons
/all-in-one/products/{id}ApiKeyAuthHapus produk
Scope `products:delete`.
Parameter
Respons
/all-in-one/ordersApiKeyAuthDaftar pesanan
Scope `orders:read`.
Respons
/all-in-one/ordersApiKeyAuthBuat pesanan
Scope `orders:create`.
Respons
/all-in-one/orders/{id}ApiKeyAuthDetail pesanan
Scope `orders:read`.
Parameter
Respons
/all-in-one/orders/{id}/statusApiKeyAuthUbah status pesanan
Scope `orders:update`.
Parameter
Respons
/all-in-one/customersApiKeyAuthDaftar pelanggan
Scope `customers:read`.
Respons
/all-in-one/customers/{id}ApiKeyAuthDetail pelanggan
Scope `customers:read`.
Parameter
Respons
/all-in-one/customers/{id}ApiKeyAuthUbah pelanggan
Scope `customers:update`.
Parameter
Respons
/all-in-one/vouchersApiKeyAuthDaftar voucher
Scope `vouchers:read`.
Respons
/all-in-one/vouchersApiKeyAuthBuat voucher
Scope `vouchers:create`.
Respons
/all-in-one/vouchers/validateApiKeyAuthValidasi voucher
Scope `vouchers:read`.
Respons
/all-in-one/vouchers/{id}ApiKeyAuthDetail voucher
Scope `vouchers:read`.
Parameter
Respons
/all-in-one/vouchers/{id}ApiKeyAuthUbah voucher
Scope `vouchers:update`.
Parameter
Respons
/all-in-one/vouchers/{id}ApiKeyAuthHapus voucher
Scope `vouchers:delete`.
Parameter
Respons
/all-in-one/servicesApiKeyAuthDaftar layanan (service catalog)
Scope `services:read`.
Respons
/all-in-one/servicesApiKeyAuthBuat layanan
Scope `services:create`.
Respons
/all-in-one/services/{id}ApiKeyAuthUbah layanan
Scope `services:update`.
Parameter
Respons
/all-in-one/services/{id}ApiKeyAuthHapus layanan
Scope `services:delete`.
Parameter
Respons
/all-in-one/bookingsApiKeyAuthDaftar booking
Scope `bookings:read`.
Respons
/all-in-one/bookings/{id}ApiKeyAuthDetail booking
Scope `bookings:read`.
Parameter
Respons
/all-in-one/bookings/{id}/statusApiKeyAuthUbah status booking
Scope `bookings:update`.
Parameter
Respons
/all-in-one/bookings/{id}/cancelApiKeyAuthBatalkan booking
Scope `bookings:update`.
Parameter
Respons
/all-in-one/conversationsApiKeyAuthDaftar percakapan (inbox)
Scope `conversations:read`.
Respons
/all-in-one/conversations/{id}ApiKeyAuthDetail percakapan
Scope `conversations:read`.
Parameter
Respons
/all-in-one/conversations/{id}/messagesApiKeyAuthPesan dalam percakapan
Scope `conversations:read`.
Parameter
Respons
/all-in-one/conversations/{id}/replyApiKeyAuthBalas percakapan
Scope `conversations:create` atau `conversations:update`.
Parameter
Body (wajib)
Respons
/all-in-one/article-gen/generateApiKeyAuthBuat antrian generate artikel AI
Scope `article_gen`. Menerima project_id atau daftar keywords langsung untuk generate artikel SEO otomatis.
Body (wajib)
Respons
/all-in-one/article-gen/batches/{id}ApiKeyAuthStatus dan progres antrian batch artikel
Scope `article_gen`.
Parameter
Respons
/all-in-one/article-gen/batches/{id}/articlesApiKeyAuthDaftar artikel dalam batch
Scope `article_gen`.
Parameter
Respons
/all-in-one/article-gen/articles/{id}ApiKeyAuthDetail artikel hasil generate
Scope `article_gen`.
Parameter
Respons
/all-in-one/article-gen/estimateApiKeyAuthEstimasi biaya dan kuota artikel
Scope `article_gen`.
Body (wajib)
Respons
Analytics
/analytics/overviewBearerAuthAnalytics KPI and conversion overview
Parameter
Respons
Anti-Fraud
/fraud/flagsBearerAuthList fraud flags
Respons
/fraud/flags/{id}/resolveBearerAuthResolve fraud flag
Parameter
Body (opsional)
Respons
Auth
/auth/registerPublikRegister merchant and trigger OTP
Body (wajib)
Respons
/auth/verify-otpPublikVerify registration OTP and issue JWT
Body (wajib)
Respons
/auth/loginPublikLogin with email and password
Body (wajib)
Respons
/auth/refreshPublikRefresh JWT access token
Body (wajib)
Respons
/auth/logoutBearerAuthRevoke current session JWT token
Respons
/auth/meBearerAuthInspect user and merchant profile
Respons
/auth/api-key/rotateBearerAuthRotate tenant API Key (Owner only)
Respons
Billing
/billing/balanceBearerAuthGet token balance and consumption breakdown
Respons
/billing/topupBearerAuthCreate token topup invoice
Respons
/billing/invoicesBearerAuthList billing invoices
Respons
/billing/transactionsBearerAuthList token ledger transactions
Respons
Bookings
/bookingsBearerAuthList bookings
Respons
/bookingsBearerAuthCreate booking
Respons
/bookings/availabilityBearerAuthGet booking availability slots for a date
Parameter
Respons
Broadcast
/broadcast/campaignsBearerAuthList broadcast campaigns
Respons
/broadcast/campaignsBearerAuthCreate broadcast campaign
Respons
/broadcast/campaigns/{id}/startBearerAuthStart throttled broadcast delivery
Parameter
Respons
Customers
/customersBearerAuthList customers with pagination and filtering
Parameter
Respons
/customers/{id}BearerAuthGet customer detail profile including conversations, orders, and pipeline history
Parameter
Respons
/customers/exportBearerAuthExport customers to CSV
Parameter
Respons
Health
/healthPublikLiveness Probe
Respons
/health/readyPublikReadiness Probe
Respons
Knowledge Base
/kb/documentsBearerAuthList KB documents
Respons
/kb/uploadBearerAuthUpload KB document with 512-byte MIME sniffing
Body (opsional)
Respons
/kb/searchBearerAuthVector similarity search
Respons
Legal & PDP
/legal/documents/{type}PublikPublic legal documents (ToS, Privacy Policy, DPA)
Parameter
Respons
/consentBearerAuthRecord user or customer consent
Respons
/data-deletion-requestsBearerAuthSubmit PDP data deletion / anonymization request
Respons
Media
/mediaBearerAuthList media library assets
Respons
/mediaBearerAuthUpload and auto-optimize media with MIME sniffing
Body (opsional)
Respons
Notifications
/notify/sendBearerAuthApiKeyAuthDispatch multi-channel notification
Respons
OTP
/otp/sendApiKeyAuthSend OTP via WhatsApp or SMS fallback
Body (wajib)
Respons
/otp/verifyApiKeyAuthVerify OTP code
Body (wajib)
Respons
Orders
/ordersBearerAuthList tenant orders
Respons
/ordersBearerAuthCreate new order
Respons
/orders/{id}BearerAuthGet order by ID
Parameter
Respons
/orders/{id}/statusBearerAuthUpdate order status
Parameter
Respons
Pipeline
/pipelineBearerAuthRetrieve pipeline Kanban board with stages and contacts
Parameter
Respons
/pipeline/stagesBearerAuthCreate new pipeline stage
Body (wajib)
Respons
/pipeline/stages/generate-criteriaBearerAuthGenerate AI classification criteria for a pipeline stage
Body (wajib)
Respons
/pipeline/stages/{id}BearerAuthUpdate pipeline stage
Parameter
Body (opsional)
Respons
/pipeline/stages/{id}BearerAuthDelete pipeline stage and migrate contacts to default stage
Parameter
Respons
/pipeline/contacts/{id}/stageBearerAuthMove customer pipeline stage (Kanban drag) with manual cooldown pin
Parameter
Body (wajib)
Respons
/pipeline/contacts/{id}/unpinBearerAuthClear active manual pin on customer pipeline stage
Parameter
Respons
Products
/productsBearerAuthList catalog products
Respons
/productsBearerAuthCreate catalog product
Respons
/products/{id}BearerAuthGet product by ID
Parameter
Respons
/products/{id}BearerAuthUpdate product
Parameter
Respons
/products/{id}BearerAuthDelete product
Parameter
Respons
RBAC & Permissions
/rbac/permissionsBearerAuthList role permissions
Respons
/rbac/permissionsBearerAuthBatch update role permissions (Owner only)
Respons
/rbac/permissions/meBearerAuthGet caller permissions
Respons
System Configs
/system/configsBearerAuthGet system configs by category
Respons
/system/configsBearerAuthBatch update dynamic system configs
Respons
WebSocket
/ws/ticketBearerAuthObtain short-lived single-use ticket for WebSocket handshake
Respons
Webhooks
/webhook/payment/midtransPublikMidtrans payment notification webhook
Respons
/webhook/wa/incomingPublikEvolution WhatsApp incoming message webhook
Respons
5. Relasi & Integrasi
Semua API yang dideskripsikan di atas terintegrasi secara mendalam dengan subsistem All-in-One API yang mana menyatukan seluruh interaksi mutasi dengan satu prefix akses kontrol kredensial (dgb_all_). Anda dapat menguji sebagian besar lalu-lintas tanpa menulis program dengan memanfaatkan API Playground.
