Integrasi: API, webhook, keamanan

Melengkapi panduan penjual. Fokus ke panggilan program, tanda tangan, dan kode error.

Dokumentasi ini untuk siapa?

Non-teknis	Panduan penjual
Developer / integrator	Halaman ini (bagian berikut)
WordPress (Elementor / Woo)	Ringkasan WordPress + tabel di bawah

Dasar

Base API	`https://<host>/api/v1` (lokal: `http://localhost:3001/api/v1`)
Format	Kebanyakan `Content-Type: application/json`
Kunci	API key (header) dan apiSecret (verifikasi webhook)—atur lewat Pengaturan / Webhook di aplikasi.

API key memanggil API sebagai pemilik; apiSecret memverifikasi bahwa POST webhook asli dari BayarQR (HMAC). Simpan apiSecret seperti password. Jangan menaruh kunci di query string publik (log/cache).

Autentikasi

X-Api-Key: <api_key> — umum untuk server & plugin.
Authorization: Bearer <token> — sesi / JWT, sesuai rute.

Respon 401: periksa kunci, pencabutan, atau environment. Hindari membanjiri request.

Payment link (dasbor) vs memanggil API

Cara	Cocok bila	Catatan
Hanya atur di dasbor, bagikan URL	Mayoritas penjual	Tidak wajib API
API (link/transaksi)	Back-office, toko, bot	Amankan API key
Kombinasi	Link umum + order khusus lewat API	Satukan environment (Live/Sandbox) di semua sisi

referenceId wajib unik per alur agar transaksi idempoten.

Webhook (server Anda menerima event)

URL disetel di profil / pengaturan BayarQR, bukan header tiap panggilan API acak.
POST ke URL Anda, body teks JSON utuh.
Validasi: header X-BayarQR-Signature = HMAC-SHA256 hex dari body string persis, kunci = apiSecret. Contoh Node: crypto.createHmac('sha256', apiSecret).update(bodyString, 'utf8').digest('hex')
Balas 2xx dengan cepat; proses berat ke antrean. Anggap event bisa duplikat (retry). Produksi: HTTPS ke endpoint Anda.

Plugin WordPress “Digital Commerce” dapat menerima webhook lewat REST di WordPress, sementara URL di profil BayarQR bisa ke endpoint berbeda—ikuti rilis plugin Anda.

Uji: setelah login, alur uji memanggil POST /api/v1/webhooks/test ke URL yang tersimpan.

Kode respons HTTP (ringkas)

Kode	Arti	Tindak
200 / 201	OK	Cek `success` & `data` JSON
400	Input salah	Baca `message` / `code`
401	Auth gagal	Periksa kunci / token
402 (jika ada)	Kredit / langganan	Perpanjang / top up (Billing)
404	Tidak ada	ID, slug, environment
429	Terbatasi	Perlambat, backoff
5xx	Server sementara	Retry terbatas

Kredit, paket, langganan (integrator)

Transaksi sukses memakai credit per kebijakan UI. Masa grace lalu lapsed dapat memblokir transaksi baru (mis. 402). Tampilkan peringatan di produk sendiri bila hampir habis.

Kaitan WordPress

Digital Commerce: API key, environment, shortcode, widget Elementor. Wizard kesiapan: GET /api/v1/wordpress/woo/onboarding-readiness (auth pemilik akun).
Woo: POST /wordpress/woo/session, GET /wordpress/woo/status, GET /wordpress/woo/health, dsb. Detail: lihat rujukan teknis di bawah (opsional).

Endpoint & lingkungan

Parameter environment dengan nilai LIVE / SANDBOX mencegur data tercampur. Rute lengkap: sumber rute api.js di backend. Contoh sering: GET /auth/me, POST /webhooks/test, endpoint Woo di atas (prefix /api/v1).

Batas beban, keamanan, data

Rate limit / 429 — kurangi frekuensi polling. Jangan menerbitkan log berisi kunci. PII mengikuti kebijakan privasi situs produksi.

Bantuan

Untuk tiket: sertakan waktu, environment, kode HTTP, dan idempotency bila dipakai. Sumber baca: jika isi sini beda dengan response runtime, runtime yang benar.

Referensi sumber repositori (teknis)

File Markdown penuh untuk disalin / CI tersedia di INTEGRASI_DEVELOPER_DAN_API dan WORDPRESS_WOO_API_CONTRACT_V1—bukan tujuan bacaan utama.