# Integrasi developer: API, webhook, dan WordPress

Dokumen ini melengkapi [PANDUAN_PENJUAL_CEPAT.md](PANDUAN_PENJUAL_CEPAT.md) (untuk pengguna **tanpa** kode). Di sini fokus **API, keamanan, dan automasi**.

## 0. Dokumen ini untuk siapa?

| Peran | Mulai dari |
|-------|------------|
| Penjual non-teknis | [PANDUAN_PENJUAL_CEPAT.md](PANDUAN_PENJUAL_CEPAT.md) |
| Developer / integrator | Lanjut bagian 1–9 di file ini |
| WordPress (Elementor / Woo) | Bagian 4 + file `WORDPRESS_*` di folder `docs/` |

## 1. Dasar

| Item | Nilai |
|------|--------|
| Base URL API | `https://<host-anda>/api/v1` (contoh lokal: `http://localhost:3001/api/v1`) |
| Format request ke server BayarQR | JSON umumnya: `Content-Type: application/json` |
| Di mana mengatur kunci | Aplikasi web: **Pengaturan**, **Webhook**, atau halaman yang menampilkan **API key** / kredensial integrasi (menu dapat diperbarui antar versi UI) |

Satu akun memiliki setidaknya:

- **API key** — untuk memanggil API sebagai pemilik akun (header `X-Api-Key`).
- **apiSecret** — dipakai untuk **memverifikasi** bahwa POST webhook ke server Anda benar-benar dari BayarQR (HMAC). Simpan seperti password; jangan menaruh di repo publik.

**Jangan** mengirim API key di query string URL publik (bisa tercatat di log server & cache).

## 2. Autentikasi

Mendukung salah satu (tergantung rute; lihat `401` bila ditolak):

- **Header** `X-Api-Key: <api_key_user>` — paling umum untuk skrip & plugin server-to-server.
- **Header** `Authorization: Bearer <access_token_user>` — sesi login / JWT, untuk alur browser atau klien yang sudah login.

Jika menerima **401 Unauthorized**: cek sisa kunci, kunci dicabut, atau environment salah. Jangan mengulang ratusan kali; itu tidak membuka akses.

## 3. Memilih: Payment link (dashboard) vs API transaksi

| Cara | Cocok bila | Catatan |
|------|------------|---------|
| **Hanya** buat/atur link di **dasbor** web, bagikan URL | Banyak penjual, tanpa kode | Tidak wajib memanggil API. |
| **API** (buat/ubah link, buat transaksi) | Sistem back-office, integrasi toko, bot | Wajib amankan API key. |
| **Keduanya** | Mis. link utama dari dashboard, order khusus dari API | Disiplinkan **environment** (Live/Sandbox) di semua sisi. |

Jangan menganggap `referenceId` bebas: biasanya wajib unik per transaksi di sisi BayarQR agar idempoten.

## 4. Webhook (server **Anda** menerima event dari BayarQR)

1. **URL webhook** disetel di **profil / pengaturan** akun BayarQR, bukan sebagai header wajar pada *setiap* panggilan API.
2. **Metode HTTP:** `POST` ke URL Anda; body umumnya **string JSON** (lihat contoh uji lewat rute `POST /api/v1/webhooks/test` setelah login).
3. **Verifikasi keaslian (sangat disarankan):** header **`X-BayarQR-Signature`**: HMAC-SHA256 **hex** dari **string body request persis** (byte sama dengan yang dibaca), kunci = **apiSecret** Anda. Contoh Node.js:
   - `crypto.createHmac('sha256', apiSecret).update(bodyString, 'utf8').digest('hex')`
4. **Praktik produksi**
   - Balas `2xx` **secepat mungkin**; proses berat (email, gudang) sebaiknya antre di background.  
   - Anggap event bisa **duplikat** (retry) — gunakan `referenceId` / id transaksi idempoten.  
   - Terima hanya **HTTPS** di depan.  
5. Bila perlu, bandingkan IP sumber (jika Anda memfilter) dengan dokumentasi jaringan BayarQR (jika tersedia di kontrak khusus; jangan andalkan satu-satunya garis pertahanan).

*Catatan arsitektur plugin WordPress “Digital Commerce”: sebagian alur menerima webhook **di WordPress (REST)**, sementara URL di profil BayarQR bisa memakai endpoint lain. Ikuti [WORDPRESS_DIGITAL_COMMERCE_PLUGIN_SPEC_V1.md](WORDPRESS_DIGITAL_COMMERCE_PLUGIN_SPEC_V1.md) agar sesuai rilis plugin Anda.*

## 5. Kode respons HTTP yang sering muncul

| Kode | Arti (ringkas) | Tindak awal |
|------|----------------|-------------|
| `200` / `201` | Permintaan diterima | Cek isi `success` + `data` (format JSON) |
| `400` | Body/query tidak valid | Baca `message` / `code` di response |
| `401` | Autentikasi gagal | Periksa API key / token |
| `402` (jika muncul) | Pembayaran / kredit / langganan menahan operasi | Cek `code` (mis. credit habis, langganan lewat) — **Perpanjang paket** atau **top up** via Billing |
| `404` | Sumber daya tidak ditemukan | ID/slug/lingkungan salah |
| `429` | Terlalu banyak request | Sebentar, backoff, jangan run loop ketat di produksi |
| `5xx` | Gangguan server sementara | Coba ulang terbatas; cek status layanan |

*Daftar kode resmi per endpoint dapat berkembang; bila ragu, baca sumber rute `src/routes/api.js` di repositori backend.*

## 6. Kredit, paket, dan langganan (integrator wajib sadar)

- Operasional “sukses” transaksi memakai **credit** (kebijakan rinci di UI dan halaman harga).  
- **Perpanjangan** paket: jika lewat waktu, akun dapat masuk **grace** lalu **lapsed**; setelah lapsed, API dapat **menolak transaksi / link baru** (mis. kode 402) sampai perpanjangan.  
- **Bukan** tanggung jawab BayarQR untuk menebak kebutuhan credit pelanggan Anda; embed **peringatan** di produk jika hampir habis.  

## 7. Kaitan dengan integrasi WordPress

### 7.1 Plugin Digital Commerce (produk digital, Elementor/shortcode)

- Plugin memanggil **BayarQR** dengan **API key**; inbound webhook ke path WordPress; selaras environment (`LIVE` / `SANDBOX`) di plugin dan di BayarQR.  
- **Baca:** [WORDPRESS_DIGITAL_COMMERCE_PLUGIN_SPEC_V1.md](WORDPRESS_DIGITAL_COMMERCE_PLUGIN_SPEC_V1.md), [WORDPRESS_USER_PATHS_ELEMENTOR_WOOCOMMERCE.md](WORDPRESS_USER_PATHS_ELEMENTOR_WOOCOMMERCE.md), [WORDPRESS_ELEMENTOR_PLAYBOOK.md](WORDPRESS_ELEMENTOR_PLAYBOOK.md).  
- **Shortcode** = kontrak UI: `bayarqr_digital_checkout`, `bayarqr_digital_access`, `bayarqr_digital_library`. Widget Elementor memanggil logika shortcode yang sama.  
- **Cek kesiapan (wizard)**: lewat app BayarQR `GET /api/v1/wordpress/woo/onboarding-readiness?...` (juga dipakai skenario Woo; peta langkah: API, webhook, slug, transaksi, akses).  

### 7.2 WooCommerce gateway

- [WORDPRESS_WOO_API_CONTRACT_V1.md](WORDPRESS_WOO_API_CONTRACT_V1.md) — session, status, health, resync, verify-signature, onboarding-readiness, funnel, go-live.  
- Sering dipanggil: `POST /wordpress/woo/session`, `GET /wordpress/woo/status`, `GET /wordpress/woo/health`.  

### 7.3 Baseline & QA

- [WORDPRESS_SELLER_PROGRAM_BASELINE.md](WORDPRESS_SELLER_PROGRAM_BASELINE.md)  
- Rilis & regression: [WORDPRESS_DIGITAL_COMMERCE_RELEASE_CHECKLIST.md](WORDPRESS_DIGITAL_COMMERCE_RELEASE_CHECKLIST.md), [WORDPRESS_QA_PROGRAM_SUITE.md](WORDPRESS_QA_PROGRAM_SUITE.md)  

## 8. Endpoint & lingkungan

- Rute penuh: **sumber kebenaran** = `src/routes/api.js` (backend).  
- **Query atau body** `environment` dengan nilai `LIVE` / `SANDBOX` (besar kecil normalnya dinormalisasi) agar data tidak tercampur.  
- Contoh rute sering muncul (prefix `/api/v1`):
  - `GET /auth/me` — profil + ringkasan langganan (berguna untuk cek sebelum transaksi)  
  - `POST /webhooks/test` — uji ke URL yang disimpan  
  - Woo: lihat tabel di kontrak di atas.  

## 9. Batas beban, keamanan, dan data

- **Rate limiting** dan perlindungan abuse dapat diterapkan di edge atau aplikasi. Jika dapat `429` atau pesan batas, kurangi **frekuensi** polling status (gunakan backoff).  
- **Jangan** mengekspor **log harian** yang memuat kunci, utuh, ke publik.  
- Tanggung jawab PII (email pembeli, dsb.) mengikuti [Kebijakan privasi] situs produksi.  

## 10. Bantuan & versi

- Perubahan API publik hendaknya tercatat rilis.  
- Dukungan operasional: **saluran resmi** (email/tiket) sesuai kebijakan di situs produksi — sediakan **waktu, environment, kode HTTP,** dan **idempotency key** bila dipakai.  

---

*Jika isi rujukan di dokumen ini bertentangan dengan sumber rute atau response runtime, rute/response **runtime** yang berlaku.*  
*Untuk istilah sehari-hari tanpa jargoni API, baca [PANDUAN_PENJUAL_CEPAT.md](PANDUAN_PENJUAL_CEPAT.md).*