# WordPress Woo API Contract v1

Kontrak awal untuk integrasi plugin WooCommerce ke BayarQR.

## Auth

- Header `X-Api-Key: <user_api_key_bayarqr>`
- Alternatif: `Authorization: Bearer <token_user>`

## 1) Create/Reuse Checkout Session

`POST /api/v1/wordpress/woo/session`

### Request body

```json
{
  "environment": "LIVE",
  "checkoutMode": "OFFSITE_REDIRECT",
  "externalOrderId": "woo-123-wc_order_key",
  "title": "Order #123",
  "amount": 150000,
  "customerName": "Budi",
  "customerEmail": "budi@mail.com",
  "successUrl": "https://site-merchant.com/order-received/123",
  "expiresInHours": 24
}
```

### Idempotency

- Header opsional: `X-Idempotency-Key`
- Jika tidak dikirim, fallback ke `externalOrderId`.
- Session akan direuse jika external order yang sama sudah pernah dibuat.

### Response (sukses)

```json
{
  "success": true,
  "data": {
    "sessionKey": "LIVE:cm...",
    "paymentLinkId": "cm...",
    "paymentLinkSlug": "a1b2c3d4e5f6",
    "checkoutMode": "OFFSITE_REDIRECT",
    "checkoutUrl": "/p/a1b2c3d4e5f6",
    "initiateUrl": "/api/v1/p/a1b2c3d4e5f6/initiate",
    "publicReadUrl": "/api/v1/p/a1b2c3d4e5f6",
    "environment": "LIVE",
    "idempotency": { "reused": false }
  }
}
```

## 2) Status Lookup

`GET /api/v1/wordpress/woo/status?externalOrderId=...`

atau

`GET /api/v1/wordpress/woo/status?referenceId=...`

### Response (sukses)

```json
{
  "success": true,
  "data": {
    "integrationSource": "WORDPRESS_WOO",
    "paymentLink": { "id": "cm...", "slug": "abc", "status": "ACTIVE" },
    "transaction": { "referenceId": "REF-123", "status": "PENDING" }
  }
}
```

## 3) Verify Signature Helper

`POST /api/v1/wordpress/woo/verify-signature`

```json
{
  "signature": "hex_signature",
  "payload": { "event": "payment.success", "referenceId": "REF-123" }
}
```

Digunakan untuk validasi HMAC SHA256 dengan `apiSecret` user.

## 4) Health Diagnostics

`GET /api/v1/wordpress/woo/health`

Response berisi counter operasional:

- `activeWooLinks`
- `paidWooLinks`
- `pendingTransactions`

## 4b) Ops Summary (Human-readable)

`GET /api/v1/wordpress/woo/ops-summary`

Menggabungkan health + funnel 24 jam + go-live state untuk panel operasional ringkas plugin.

## 4c) Auto Recover

`POST /api/v1/wordpress/woo/auto-recover`

Body minimal:

```json
{
  "environment": "LIVE",
  "externalOrderId": "woo-123"
}
```

atau:

```json
{
  "environment": "LIVE",
  "referenceId": "REF-123"
}
```

atau (disarankan untuk auto-recovery cepat dari panel ops):

```json
{
  "environment": "LIVE",
  "paymentLinkId": "cm_abc123"
}
```

Endpoint ini akan mengecek sinyal recovery (mis. status `PENDING/VERIFYING/EXPIRED/FAILED`) lalu menjalankan resync otomatis jika perlu.

## 5) Track Event

`POST /api/v1/wordpress/woo/track-event`

```json
{
  "environment": "LIVE",
  "eventType": "checkout_redirect_issued",
  "externalOrderId": "woo-123-wc_order_key",
  "paymentLinkId": "cm...",
  "referenceId": null,
  "meta": { "mode": "offsite_redirect" }
}
```

Event type yang diterima:

- `session_created`
- `session_reused`
- `checkout_redirect_issued`
- `checkout_opened`
- `onsite_qr_rendered`
- `manual_resync_triggered`
- `auto_resync_triggered`

## 6) Funnel Metrics

`GET /api/v1/wordpress/woo/funnel?environment=LIVE&hours=24`

Response mengembalikan funnel:

- `sessionCreated`
- `sessionReused`
- `checkoutIssued`
- `checkoutOpened`
- `paid`
- `webhookSent`

## 7) Manual Resync

`POST /api/v1/wordpress/woo/resync`

```json
{
  "externalOrderId": "woo-123-wc_order_key",
  "referenceId": "REF-123"
}
```

Tujuan:

- Rekonsiliasi status payment link dan transaksi.
- Auto-mark payment link menjadi `PAID` jika transaksi `SUCCESS`.

## 8) Go Live State (Cross-Device)

### Ambil state go-live terbaru

`GET /api/v1/wordpress/woo/go-live-state?environment=LIVE`

Response mengembalikan:

- `state.status` (`idle` | `active` | `revoked`)
- `state.blockersCount`
- `state.blockedStreak`
- `state.activatedAt`, `state.revokedAt`, `state.revokedReason`
- `incidents[]` (riwayat ACTIVE/REVOKE terbaru)

### Sinkronisasi blocker dari wizard/checklist

`POST /api/v1/wordpress/woo/go-live/sync?environment=LIVE`

```json
{
  "source": "wordpress_pack",
  "blockers": [
    {
      "title": "Webhook delivery rendah",
      "detail": "Rasio webhook sent terhadap paid masih di bawah 80%.",
      "action": "webhook"
    }
  ]
}
```

Catatan:

- Endpoint ini mengelola `blockedStreak` di server.
- Jika mode `active` dan blocker berulang mencapai ambang grace, server akan `auto-revoke`.
- Server juga menyuntikkan guard internal (contoh: SLA queue webhook backlog) walaupun client tidak mengirim blocker itu.

### Aktivasi mode live campaign

`POST /api/v1/wordpress/woo/go-live/activate?environment=LIVE`

Catatan:

- Aktivasi ditolak (`409`) jika `blockersCount > 0`.
- Setelah auto-revoke, aktivasi bisa terkena cooldown (`429` + `waitSeconds`).
- Aktivasi/revoke bisa memicu alert multi-channel (`webhookUrl`, Telegram, SMTP email) best-effort.

## 9) Admin Monitoring (Ops)

`GET /api/v1/admin/wordpress/woo/go-live/incidents?page=1&limit=50&environment=LIVE`

Response:

- daftar incident `ACTIVE/REVOKE` lintas merchant
- summary state (`activeStates`, `revokedStates`, `blockedStates`)
- pagination standar admin