Bisadagang BisnisBisadagang BisnisDocs
HargaMasukDaftar gratis
Mulai
  • Pengenalan
  • Quick start
Dasar
  • Autentikasi & signature
  • Format respons & kode error
Referensi API
  • GETCek saldo
  • GETDaftar harga & produk
  • Transaksi
  • Komplain
  • Webhook
Panduan
  • Sandbox
  • Panduan vibe coder
Butuh bantuan?

Tim teknis kami siap membantu integrasi lewat WhatsApp.

Chat tim teknis
Syarat dan ketentuanKebijakan privasi
Mulai
  • Pengenalan
  • Quick start
Dasar
  • Autentikasi & signature
  • Format respons & kode error
Referensi API
  • GETCek saldo
  • GETDaftar harga & produk
  • Transaksi
  • Komplain
  • Webhook
Panduan
  • Sandbox
  • Panduan vibe coder
Panduan

Panduan vibe coder

Membangun dengan asisten AI seperti Claude Code, Cursor, atau ChatGPT? Salin prompt di halaman ini; isinya sudah memuat semua yang perlu diketahui asisten untuk endpoint yang tersedia.

Persiapan#

  1. Buat API key sandbox di dashboard (lihat Quick start).
  2. Isi BISADAGANG_API_KEY dan BISADAGANG_API_SECRET di file .env project Anda, dan pastikan .env ada di .gitignore.
  3. Buka project di asisten AI Anda.

Prompt siap salin#

Tempel prompt ini apa adanya. Key dan secret tidak perlu ditulis di prompt.

Prompt
Bantu saya mengintegrasikan API H2H Bisadagang Bisnis ke project ini.

Aturan:
- Base URL: https://api.bisadagang.com (semua endpoint di bawah /h2h/v1, hanya HTTPS, respons JSON).
- Ambil API key dan secret dari environment variable BISADAGANG_API_KEY dan BISADAGANG_API_SECRET. Jangan pernah menulis key atau secret di kode, log, atau commit.
- Mulai dengan key sandbox (berawalan bdk_test_). Key production (bdk_live_) baru dipakai setelah semuanya jalan.

Autentikasi, kirim di setiap request:
- X-Bisadagang-Key: API key.
- X-Bisadagang-Timestamp: waktu Unix dalam detik (bukan milidetik), maksimal selisih 300 detik dari server.
- X-Bisadagang-Nonce: string acak baru per request, 16–64 karakter A-Z a-z 0-9 _ - (mis. 32 karakter hex).
- X-Bisadagang-Signature: hex huruf kecil dari HMAC-SHA256(secret, canonical).
- canonical = METHOD + "\n" + PATH_DENGAN_QUERY + "\n" + TIMESTAMP + "\n" + NONCE + "\n" + hex(sha256(body mentah)).
  Body kosong untuk GET (sha256 dari string kosong). Path ditulis persis seperti dikirim, termasuk query string.
- Uji fungsi sign() dengan contoh ini: secret "rahasia-contoh", GET /h2h/v1/products?category=Pulsa, timestamp 1763337600, nonce 0123456789abcdef0123456789abcdef, body kosong. Hasilnya harus 1c70ec830551bf90d017616759d563f395be4fbf5528f0beeb01ac5fad71cae6.

Format respons:
- Sukses: { "success": true, "data": …, "request_id": "…" }
- Gagal: { "success": false, "error": { "code", "message", "details" }, "request_id": "…" }
- Buat logika berdasarkan error.code, bukan message. Simpan request_id di log.
- 429 RATE_LIMITED: tunggu sesuai header Retry-After lalu coba lagi.

Endpoint yang tersedia:
- GET /h2h/v1/balance → data: { balance, currency: "IDR", environment: "production" | "sandbox" }
- GET /h2h/v1/products?category=&status=normal|gangguan&semua=true → data: { updated_at, total, products: [{ code, product_name, category, brand, type, product_type, is_open_amount, status, price, fee, admin_fee, commission, success_rate, speed_seconds, active }] }

Endpoint transaksi sudah aktif untuk key sandbox dan production. Di sandbox, hasil ditentukan oleh 4 digit terakhir nomor tujuan (0001 sukses, 0002 gagal, 0003 pending lalu sukses, 0004 pending lalu gagal, 0005 pending terus, 0006 tidak ditemukan); lihat https://bisnis.bisadagang.com/docs/sandbox. Detailnya ada di https://bisnis.bisadagang.com/docs/api/transaksi. 
Webhook (https://bisnis.bisadagang.com/docs/api/webhook):
- Mitra mengisi URL HTTPS per environment (sandbox dan production, masing-masing punya secret) di dashboard, menu Webhook. Secret berawalan whsec_, simpan di environment variable BISADAGANG_WEBHOOK_SECRET, bukan di kode.
- Bisadagang mengirim POST JSON { event_id, event, environment, created_at, data }. Event: transaction.updated (selalu aktif), complaint.updated, product.auto_disabled, product.auto_enabled, product.created, price.changed, balance.low. Untuk transaction.updated, data berisi transaction_id, ref_id, product_code, customer_no, price, status, sn, message; cocokkan lewat ref_id.
- data per event: complaint.updated { complaint_id, transaction_id, ref_id, status, result, message|null }; product.auto_disabled { product_code, product_name, category, success_rate, threshold, transactions, min_transactions, disabled_at } (hanya production); product.auto_enabled { product_code, product_name, category, success_rate, threshold, enabled_at } (hanya production); product.created { total, products[{ code, product_name, category, brand, type, product_type, is_open_amount, status, price, fee, admin_fee, commission, active }] }; price.changed { total, products[{ code, product_name, product_type, changes: { price|fee|admin_fee|commission: { old, new } } }] }; balance.low { balance, threshold, currency } (hanya production). Abaikan field yang tidak dikenal.
- Header: X-Bisadagang-Event, X-Bisadagang-Delivery (sama dengan event_id), X-Bisadagang-Timestamp (detik Unix), X-Bisadagang-Signature.
- Verifikasi sebelum memproses, pakai body mentah (bukan hasil parse JSON): signature = hex huruf kecil HMAC-SHA256(secret_webhook_lengkap, TIMESTAMP + "." + BODY_MENTAH). Header bisa berisi dua signature dipisah koma saat rotasi secret; terima jika salah satunya cocok. Bandingkan constant-time dan tolak (401) jika timestamp selisih lebih dari 300 detik. Contoh uji: secret "whsec_contoh_rahasia_jangan_dipakai", timestamp 1763522142, body contoh di halaman webhook, hasilnya 16587d07452dff66f95860bd51f9cc322d41cbe5b31e89ad9c9fea3f58277ef2.
- Balas 2xx secepatnya (maks. 10 detik), simpan event lalu proses di belakang (antrean atau worker). Selain 2xx atau timeout dianggap gagal dan dikirim ulang sampai 8 percobaan dalam sekitar 24 jam (jeda ±1, 6, 21 menit, 1j21m, 3j21m, 9j21m, 24 jam sejak event).
- Idempotensi: simpan event_id dengan aturan unik; jika sudah ada, balas 200 dan lewati. Urutan tiba tidak dijamin, jangan menurunkan transaksi yang sudah final. Cek status tetap ada sebagai cadangan.
- Event pending dikirim paling banyak sekali per rentang pending, lalu status akhir. Tombol Kirim tes mengirim event webhook.test (tidak masuk log); balas 2xx. Dashboard punya tombol Kirim tes, log pengiriman 30 hari, dan Kirim ulang.

API komplain (https://bisnis.bisadagang.com/docs/api/komplain), signature sama dengan endpoint lain:
- POST /h2h/v1/complaints { ref_id ATAU transaction_id (salah satu), reason: pending_too_long | success_not_received | invalid_sn | other, note? (maks. 1000; other wajib min. 10) } → data: objek komplain { complaint_id, transaction_id, ref_id, product_code, product_name, customer_no, price, reason, status: open | processing | resolved, result: success | failed | null, source, environment, created_at, messages: [{ from: partner | team | system, text, created_at }] }
- GET /h2h/v1/complaints/{complaint_id}; GET /h2h/v1/complaints?status=&ref_id=&transaction_id=&limit=&cursor= → data: { complaints, next_cursor }; POST /h2h/v1/complaints/{complaint_id}/messages { text } (1–1000, hanya saat open/processing).
- Aturan: pending bisa dikomplain langsung (reason pending_too_long atau other); sukses hanya jika belum masuk (success_not_received, invalid_sn, other); gagal ditolak (COMPLAINT_NOT_ALLOWED, saldo sudah kembali); batas H+7 sejak transaksi dibuat (COMPLAINT_WINDOW_CLOSED, details.deadline); satu komplain aktif per transaksi (COMPLAINT_EXISTS, details.complaint_id). Balasan ke komplain resolved: COMPLAINT_CLOSED.
- Perubahan status dan balasan tim dikirim lewat webhook complaint.updated.

Tugas pertama: buat modul klien kecil dengan fungsi sign(), getBalance(), dan getProducts(), lalu uji dengan key sandbox. Setelah itu buat handler webhook yang memverifikasi signature.
Dokumentasi lengkap: https://bisnis.bisadagang.com/docs

Cek hasilnya#

  • Minta asisten menjalankan tes fungsi sign() dengan contoh uji. Hasilnya harus sama dengan signature di Contoh uji.
  • Jalankan cek saldo dengan key sandbox. Respons yang benar berisi "environment": "sandbox".
  • Jika muncul error, salin error.code dan message ke asisten, lalu cocokkan dengan daftar kode error.

Jaga keamanan#

  • Jangan menempel API secret ke chat AI. Cukup sebut nama environment variable-nya.
  • Periksa kode sebelum commit: tidak boleh ada key, secret, atau token yang tertulis.
  • Panggil API Bisadagang dari server Anda, bukan dari browser atau aplikasi mobile, supaya secret tidak ikut terkirim ke pengguna.
Prompt ini diperbarui setiap ada endpoint baru. Salin ulang versi terbaru dari halaman ini saat ada endpoint baru.
Sebelumnya
Sandbox
Butuh bantuan?
Tanya soal integrasi teknis lewat WhatsApp.
Chat di WhatsApp
Di halaman ini
  • Persiapan
  • Prompt siap salin
  • Cek hasilnya
  • Jaga keamanan