> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kawan.digital/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrasi API

> Hubungkan sistem eksternal ke toko: buat order lewat REST API dan terima event lewat webhook.

Public API tersedia di paket **Growth** dan **Scale**. Kelola kunci dan webhook di [Dashboard → Pengaturan → Developer API](https://kawan.digital/dashboard/settings/developers). Referensi lengkap (coba request langsung) ada di [API Reference](/api).

## 1. Buat API Key

1. Buka Developer API di dashboard.
2. Generate key. Secret lengkap hanya ditampilkan **sekali**.
3. Kirim di setiap request: `Authorization: Bearer ktd_live_…`

Key terikat ke satu toko. Key yang di-revoke mengembalikan `401 UNAUTHORIZED`.

## 2. Base URL

```bash theme={null}
# Produksi
https://api.kawan.digital/v1
```

## 3. List produk, lalu buat order

```bash theme={null}
export API_KEY="ktd_live_..."
export API="https://api.kawan.digital/v1"

curl -sS "$API/products" \
  -H "Authorization: Bearer $API_KEY"

curl -sS "$API/payment-methods" \
  -H "Authorization: Bearer $API_KEY"

curl -sS -X POST "$API/orders" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "buyer": {
      "name": "Budi",
      "email": "budi@example.com",
      "phone": "081234567890"
    },
    "items": [{ "type": "product", "product_id": "PRODUCT_UUID" }],
    "payment_method": "duitku:qris",
    "success_url": "https://yoursite.com/thanks"
  }'
```

Response `201` berisi `data.order`, `data.payment`, dan `data.redirect`.

* `payment_url` — link pembayaran Duitku. Untuk UI sendiri pakai JSON `payment`, atau `checkout_url` untuk halaman bayar Kawan.
* Transfer bank penjual — rekening dan nominal ada di `payment.seller_bank`.
* Setelah lunas, pembeli diarahkan ke `success_url` (jika dikirim) plus query `?order=…`. Return dari gateway bisa masih pending — sumber kebenaran adalah webhook `order.paid`.

Request yang sama (buyer + keranjang) saat order masih pending mengembalikan HTTP 200 dengan `duplicate_pending: true`.

## 4. Webhook

Daftarkan URL HTTPS di dashboard, pilih event (misalnya `order.paid`), dan simpan signing secret. Dokumentasi lengkap — daftar event, payload, HMAC, retry — ada di [Webhooks](/webhooks).

## 5. Limit & error

* 60 request / menit per API key
* 10 create-order / menit per key
* Limit terlampaui: `429 RATE_LIMITED` + header `Retry-After`

Lihat skema, contoh, dan tombol Try it di [API Reference](/api). Event order: [Webhooks](/webhooks).