# API Plan — Wavora / WAGW SaaS

## Tenant Auth

```http
Authorization: Bearer <tenant_api_key>
```

API keys are scoped to tenant and permissions.

## MVP Endpoints

### Send Message (Async Default)

Semua endpoint kirim pesan default **async/background**:
- Respon cepat: `202 Accepted` + `job_id/message_id`.
- Worker memproses job → kirim ke GOWA → update status `sent/failed`.

Mode sync opsional:
- Header: `X-Send-Mode: sync` (hanya untuk admin/dev fallback).
- Respon: `200 OK` dengan hasil langsung (atau error).

**Branding Footer untuk Free Plan:**
- Semua outgoing text/caption otomatis di-append footer branding.
- Footer diambil dari field `branding_footer` di `m_plan` yang aktif untuk device.
- Payload asli disimpan di `original_payload_json`; payload + footer di `payload_json`.

### Devices

```http
GET    /api/v1/devices
POST   /api/v1/devices
GET    /api/v1/devices/{id}
POST   /api/v1/devices/{id}/login-qr
POST   /api/v1/devices/{id}/login-code
POST   /api/v1/devices/{id}/reconnect
POST   /api/v1/devices/{id}/logout
DELETE /api/v1/devices/{id}
```

### Messages

```http
POST /api/v1/messages/text
POST /api/v1/messages/image
POST /api/v1/messages/file
POST /api/v1/messages/video
POST /api/v1/messages/audio
GET  /api/v1/messages/{id}
GET  /api/v1/messages/jobs/{job_id}
GET  /api/v1/message-logs
```

#### Send Message Response (Async)

Default: `202 Accepted`

```json
{
  "success": true,
  "job_id": "uuid-job-id",
  "message_id": "uuid-job-id",
  "status": "pending",
  "message": "Message queued for delivery"
}
```

#### Sync Mode Response

Jika `X-Send-Mode: sync` (admin/dev only):

```json
{
  "success": true,
  "message_id": "gowa-msg-id",
  "status": "sent",
  "sent_at": "2026-05-17T12:00:00Z"
}
```

### Webhooks

```http
GET  /api/v1/webhooks
POST /api/v1/webhooks
POST /api/v1/webhooks/test
```

## GOWA Mapping

Wavora wraps selected GOWA endpoints:

- `/devices`
- `/devices/{device_id}`
- `/devices/{device_id}/login`
- `/devices/{device_id}/login/code`
- `/devices/{device_id}/status`
- `/send/message`
- `/send/image`
- `/send/audio`
- `/send/file`
- `/send/sticker`
- `/send/video`
- `/send/contact`
- `/send/link`
- `/send/location`
- `/send/poll`
- `/message/{message_id}/revoke`
- `/message/{message_id}/reaction`
- `/message/{message_id}/read`
- `/chats`
- `/chat/{chat_jid}/messages`
- `/user/check`

## Billing & Payments API

### Tenant Billing

```http
GET  /api/v1/billing/plan
GET  /api/v1/billing/invoices
GET  /api/v1/billing/invoices/{id}
POST /api/v1/billing/invoices/{id}/pay/doku
POST /api/v1/billing/invoices/{id}/pay/qris-manual
POST /api/v1/billing/invoices/{id}/pay/bank-transfer
POST /api/v1/billing/payments/{id}/proof
```

### Platform Admin Billing

```http
GET  /admin/billing/plans
POST /admin/billing/plans
POST /admin/billing/plans/{id}
GET  /admin/billing/invoices
GET  /admin/billing/payments/pending-verification
POST /admin/billing/payments/{id}/approve
POST /admin/billing/payments/{id}/reject
POST /admin/tenants/{id}/billing-settings
```

### DOKU Callback

```http
POST /webhook/payment/doku
```

Rules:

- Validate DOKU signature.
- Idempotent by external reference.
- Update `t_billing_payment` and `t_billing_invoice` atomically.
- Never trust callback amount without matching invoice amount.

### Manual Payment Proof

Manual methods:

- `qris_manual`
- `bank_transfer_manual`

Required proof fields:

- payment id
- uploaded image/pdf proof
- payer name optional
- paid amount
- paid at
- note optional

Admin must approve/reject before invoice becomes paid.