{"openapi":"3.1.0","info":{"title":"WartaHub API","version":"0.1.0","summary":"Gateway WhatsApp multi-tenant dengan proteksi anti-banned","description":"Gateway WhatsApp multi-tenant untuk notifikasi transaksional (tagihan, konfirmasi pembayaran, pemberitahuan layanan).\n\n## Autentikasi\n\nSemua endpoint `/v1/*` memakai **API key tenant**: `Authorization: Bearer wh_live_xxxxxxxx…`. Key diterbitkan operator dan hanya ditampilkan sekali.\n`401 INVALID_API_KEY` (key salah/dicabut) sengaja dibedakan dari `403 TENANT_SUSPENDED` (tenant ditangguhkan).\nSemua data **terisolasi per tenant**: data milik tenant lain selalu `404`, bukan `403`.\n\n## Cara kerja pengiriman\n\n`POST /v1/messages` menjawab `201` begitu pesan **diterima** ke antrean — bukan saat terkirim. Antrean bekerja **per device** dengan jeda acak,\njam kirim WIB, dan batas harian (proteksi anti-banned); nomor pengirim yang bermasalah dijeda otomatis dan pesan **tidak hilang** (dikembalikan ke antrean).\nStatus pesan: `scheduled` → `queued` → `sending` → `sent` | `failed` (atau `cancelled`). Pantau lewat `GET /v1/messages/{id}` atau webhook.\n\n## Idempotency\n\nSertakan `idempotency_key` (body) atau header `Idempotency-Key`. Mengirim ulang key yang sama mengembalikan `200` dengan pesan yang sama — aman untuk retry setelah timeout.\n\n## Kuota & batas\n\n- **Kuota pesan bulanan** menurut paket (starter 3.000, bisnis 15.000, pro 50.000; bulan WIB). Habis → `402 QUOTA_EXCEEDED` dengan `details.resets_at`. Cek `GET /v1/usage`.\n- **Rate limit**: 120 request/menit per API key → `429 RATE_LIMITED` (`Retry-After`).\n- Unggahan: maks. 15 MB per file; lampiran inline (`base64`/`url`) maks. 5 MB.\n\n## Format error\n\n```json\n{ \"error\": { \"code\": \"VALIDATION_ERROR\", \"message\": \"Nomor tujuan tidak valid. …\", \"details\": null } }\n```\n\n`code` stabil untuk diproses mesin; `message` berbahasa Indonesia untuk manusia. Pengecualian: `/fonnte/send` meniru Fonnte (selalu HTTP 200, `status:false`).\n\n## Webhook (event keluar)\n\nSetel URL lewat `PUT /v1/webhook`. WartaHub mengirim `POST` JSON `{event, timestamp, data}` dengan header `X-WartaHub-Signature: sha256=<hex>`.\nVerifikasi dengan HMAC-SHA256 atas **body mentah**:\n\n```js\nconst crypto = require('crypto');\nfunction valid(rawBody, header, secret) {\n  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');\n  return header.length === expected.length && crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));\n}\n```\n\nDaftar event dan bentuk payload ada di bagian **Webhooks** di bawah."},"servers":[{"url":"https://wartahub.my.id"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Pesan","description":"Kirim, jadwalkan, pantau, dan batalkan pesan WhatsApp."},{"name":"Media","description":"Unggah dokumen/gambar (hingga 15 MB) untuk dilampirkan ke pesan."},{"name":"Perangkat","description":"Kelola nomor pengirim: tautkan (QR / kode), jeda, dan atur laju kirim anti-banned."},{"name":"Magic Link","description":"Endpoint publik untuk halaman penautan nomor klien (tanpa API key; token sesi sebagai kredensial)."},{"name":"Webhook","description":"Konfigurasi webhook tenant dan event yang dikirim WartaHub."},{"name":"Template","description":"Template pesan dengan variabel `{{…}}`."},{"name":"Kontak","description":"Buku kontak, tag, dan impor massal."},{"name":"Auto-Reply","description":"Balasan otomatis berdasarkan kata kunci untuk chat masuk."},{"name":"Tenant","description":"Informasi tenant, pemakaian, dan kuota."},{"name":"Kompatibel Fonnte","description":"Pengganti langsung `api.fonnte.com/send` untuk migrasi tanpa mengubah kode klien."},{"name":"Sistem","description":"Status layanan."}],"paths":{"/health":{"get":{"tags":["Sistem"],"operationId":"healthCheck","summary":"Status layanan","security":[],"responses":{"200":{"description":"Layanan berjalan.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"ok"},"service":{"type":"string","const":"wartahub"}},"required":["status","service"]},"example":{"status":"ok","service":"wartahub"}}}}}}},"/v1/me":{"get":{"tags":["Tenant"],"operationId":"getMe","summary":"Periksa API key","description":"Cara tercepat memastikan API key bekerja dan melihat tenant + jumlah device-nya.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"API key valid.","content":{"application/json":{"schema":{"type":"object","properties":{"tenant":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"plan":{"enum":["starter","bisnis","pro"]}},"required":["slug","name","plan"]},"devices":{"type":"integer","description":"Jumlah device."}},"required":["tenant","devices"]},"example":{"tenant":{"slug":"fiberaccess","name":"FiberAccess","plan":"bisnis"},"devices":1}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TenantSuspended"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/usage":{"get":{"tags":["Tenant"],"operationId":"getUsage","summary":"Pemakaian & kuota","description":"Kuota bulanan paket (bulan WIB), statistik hari ini, pemakaian per device, dan riwayat 7 hari.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Ringkasan pemakaian.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TenantSuspended"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/messages":{"post":{"tags":["Pesan"],"operationId":"sendMessage","summary":"Kirim pesan (tunggal, broadcast, atau terjadwal)","description":"Pesan masuk **antrean** dan dikirim satu per satu per device dengan jeda acak, jam kirim WIB, dan batas harian (proteksi anti-banned) — `201` berarti diterima, bukan sudah terkirim. Pantau lewat `GET /v1/messages/{id}` atau webhook.\n\n- **Idempotent**: kirim `idempotency_key` (atau header `Idempotency-Key`); pengiriman ulang mengembalikan `200` dengan pesan yang sama.\n- **Broadcast**: `to` berupa array/daftar (maks. 100) → semua dibuat atau tidak sama sekali; respons `201` memuat `messages[]`.\n- **Kuota**: melebihi kuota paket bulan ini → `402 QUOTA_EXCEEDED`.\n- **Lampiran**: `document.base64` / `document.url` (maks. 5 MB) atau `document.media_id` dari `POST /v1/media/upload` (maks. 15 MB).","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Alternatif field `idempotency_key` (maks. 100 karakter).","schema":{"type":"string","maxLength":100}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageRequest"},"example":{"to":"081234567890","message":"Tagihan internet Oktober Rp150.000 jatuh tempo 10 Nov.","priority":"normal","idempotency_key":"invoice-123-reminder","scheduled_at":"2026-11-08T09:00:00+07:00"}}}},"responses":{"200":{"description":"`idempotency_key` sudah pernah dipakai: pesan lama dikembalikan, tidak ada pesan baru.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageSingleResponse"}}}},"201":{"description":"Pesan dibuat dan masuk antrean (atau berstatus `scheduled`).","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/SendMessageSingleResponse"},{"$ref":"#/components/schemas/SendMessageBroadcastResponse"}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/QuotaExceeded"},"403":{"$ref":"#/components/responses/TenantSuspended"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"x-codeSamples":[{"lang":"Shell","label":"cURL","source":"curl -X POST https://wartahub.example/v1/messages \\\n  -H \"Authorization: Bearer wh_live_xxx\" -H \"Content-Type: application/json\" \\\n  -d '{\"to\":\"081234567890\",\"message\":\"Halo!\",\"idempotency_key\":\"invoice-123\"}'"}]},"get":{"tags":["Pesan"],"operationId":"listMessages","summary":"Daftar pesan terbaru","security":[{"bearerAuth":[]}],"parameters":[{"name":"status","in":"query","required":false,"description":"Filter status.","schema":{"enum":["scheduled","queued","sending","sent","failed","cancelled"]}},{"name":"limit","in":"query","required":false,"description":"Jumlah maksimum (1–100).","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"device","in":"query","required":false,"description":"Filter ID device pengirim (`t-...`).","schema":{"type":"string","maxLength":60}},{"name":"search","in":"query","required":false,"description":"Cari nomor tujuan (08xx / 628xx), isi pesan, atau ID pesan.","schema":{"type":"string","maxLength":100}},{"name":"sort","in":"query","required":false,"description":"Kolom urut.","schema":{"enum":["time","to","device","status"]}},{"name":"dir","in":"query","required":false,"description":"Arah urut.","schema":{"enum":["asc","desc"]}},{"name":"page","in":"query","required":false,"description":"Halaman (mulai 1); mengaktifkan metadata `pagination`.","schema":{"type":"integer","minimum":1}},{"name":"offset","in":"query","required":false,"description":"Offset baris (alternatif `page`).","schema":{"type":"integer","minimum":0}},{"name":"with_total","in":"query","required":false,"description":"Sertakan `pagination` meski tanpa `page`.","schema":{"enum":["1","true","0","false"]}}],"responses":{"200":{"description":"Pesan terbaru lebih dulu (disertai `pagination` bila param pagination dipakai).","content":{"application/json":{"schema":{"type":"object","properties":{"messages":{"type":"array","items":{"$ref":"#/components/schemas/Message"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["messages"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TenantSuspended"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/messages/scheduled":{"get":{"tags":["Pesan"],"operationId":"listScheduledMessages","summary":"Daftar pesan terjadwal","description":"Pesan berstatus `scheduled` (belum masuk antrean), jadwal terdekat lebih dulu.","security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"description":"Jumlah maksimum (1–100).","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"device","in":"query","required":false,"description":"Filter ID device pengirim (`t-...`).","schema":{"type":"string","maxLength":60}},{"name":"search","in":"query","required":false,"description":"Cari nomor tujuan (08xx / 628xx), isi pesan, atau ID pesan.","schema":{"type":"string","maxLength":100}},{"name":"sort","in":"query","required":false,"description":"Kolom urut.","schema":{"enum":["time","to","device","status"]}},{"name":"dir","in":"query","required":false,"description":"Arah urut.","schema":{"enum":["asc","desc"]}},{"name":"page","in":"query","required":false,"description":"Halaman (mulai 1); mengaktifkan metadata `pagination`.","schema":{"type":"integer","minimum":1}},{"name":"offset","in":"query","required":false,"description":"Offset baris (alternatif `page`).","schema":{"type":"integer","minimum":0}},{"name":"with_total","in":"query","required":false,"description":"Sertakan `pagination` meski tanpa `page`.","schema":{"enum":["1","true","0","false"]}}],"responses":{"200":{"description":"Pesan terjadwal (disertai `pagination` bila param pagination dipakai).","content":{"application/json":{"schema":{"type":"object","properties":{"messages":{"type":"array","items":{"$ref":"#/components/schemas/Message"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["messages"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TenantSuspended"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/messages/{id}":{"get":{"tags":["Pesan"],"operationId":"getMessage","summary":"Status satu pesan","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"ID pesan.","schema":{"type":"string","pattern":"^\\d{1,19}$","example":"42"}}],"responses":{"200":{"description":"Detail pesan.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"$ref":"#/components/schemas/Message"}},"required":["message"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TenantSuspended"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/messages/{id}/cancel":{"post":{"tags":["Pesan"],"operationId":"cancelMessage","summary":"Batalkan pesan","description":"Hanya pesan `queued` atau `scheduled`. Membatalkan mengembalikan kuota bulan ini.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"ID pesan.","schema":{"type":"string","pattern":"^\\d{1,19}$","example":"42"}}],"responses":{"200":{"description":"Pesan dibatalkan.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"$ref":"#/components/schemas/Message"}},"required":["message"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TenantSuspended"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Pesan sudah diproses (`sending`/`sent`/`failed`/`cancelled`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/media/upload":{"post":{"tags":["Media"],"operationId":"uploadMedia","summary":"Unggah dokumen/gambar","description":"Unggah PDF/JPG/PNG (maks. **15 MB**) lalu kirim `document.media_id` di `POST /v1/messages`. Jenis file dicek dari **isi**, dan ekstensi nama file harus cocok dengan isinya. File disimpan 24 jam; total unggahan aktif per tenant dibatasi (default 200 MB).","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","description":"Berkas PDF/JPG/PNG.","format":"binary"}},"required":["file"]}}}},"responses":{"201":{"description":"Tersimpan.","content":{"application/json":{"schema":{"type":"object","properties":{"media":{"$ref":"#/components/schemas/Media"}},"required":["media"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TenantSuspended"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"x-codeSamples":[{"lang":"Shell","label":"cURL","source":"curl -X POST https://wartahub.example/v1/media/upload \\\n  -H \"Authorization: Bearer wh_live_xxx\" -F \"file=@INV-123.pdf\""}]}},"/v1/media/{mediaId}":{"delete":{"tags":["Media"],"operationId":"deleteMedia","summary":"Hapus unggahan","description":"Membebaskan kuota penyimpanan lebih awal. Pesan yang sudah dibuat dengan media ini tidak terpengaruh (isinya sudah disalin).","security":[{"bearerAuth":[]}],"parameters":[{"name":"mediaId","in":"path","required":true,"description":"ID media (32 karakter hex).","schema":{"type":"string","pattern":"^[a-f0-9]{32}$"}}],"responses":{"200":{"description":"Berhasil.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"]},"example":{"ok":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TenantSuspended"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/media/{mediaId}/{filename}":{"get":{"tags":["Media"],"operationId":"getMedia","summary":"Unduh unggahan","description":"Membutuhkan API key tenant pemilik (bukan URL publik). `filename` harus sama dengan nama file tersimpan.","security":[{"bearerAuth":[]}],"parameters":[{"name":"mediaId","in":"path","required":true,"description":"ID media.","schema":{"type":"string","pattern":"^[a-f0-9]{32}$"}},{"name":"filename","in":"path","required":true,"description":"Nama file (URL-encoded).","schema":{"type":"string"}}],"responses":{"200":{"description":"Isi file.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}},"image/jpeg":{"schema":{"type":"string","format":"binary"}},"image/png":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TenantSuspended"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/devices":{"get":{"tags":["Perangkat"],"operationId":"listDevices","summary":"Daftar device (nomor pengirim)","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Device milik tenant.","content":{"application/json":{"schema":{"type":"object","properties":{"devices":{"type":"array","items":{"$ref":"#/components/schemas/Device"}}},"required":["devices"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TenantSuspended"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["Perangkat"],"operationId":"createDevice","summary":"Tambah device WA baru (sesuai batas paket)","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","description":"Label perangkat, mis. \"WA Billing\".","minLength":1,"maxLength":60}},"required":["label"]}}}},"responses":{"201":{"description":"Device berhasil ditambahkan.","content":{"application/json":{"schema":{"type":"object","properties":{"device":{"$ref":"#/components/schemas/Device"}},"required":["device"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"Batas jumlah nomor WA pada paket sudah tercapai.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"$ref":"#/components/responses/TenantSuspended"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/apikeys":{"get":{"tags":["Tenant"],"operationId":"listApiKeys","summary":"Daftar API key tenant (tanpa hash/rahasia)","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Daftar API key.","content":{"application/json":{"schema":{"type":"object","properties":{"api_keys":{"type":"array","items":{"$ref":"#/components/schemas/ApiKeyMeta"}}},"required":["api_keys"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TenantSuspended"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["Tenant"],"operationId":"issueApiKey","summary":"Terbitkan API key baru (key mentah tampil sekali)","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","description":"Label key, mis. \"Server NetBill\".","minLength":1,"maxLength":60}},"required":["label"]}}}},"responses":{"201":{"description":"API key diterbitkan.","content":{"application/json":{"schema":{"type":"object","properties":{"api_key":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"prefix":{"type":"string"},"key":{"type":"string"},"created_at":{"type":"string","format":"date-time"}},"required":["id","label","prefix","key","created_at"]}},"required":["api_key"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TenantSuspended"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/apikeys/{id}":{"delete":{"tags":["Tenant"],"operationId":"revokeApiKey","summary":"Cabut API key milik tenant","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"ID API key.","schema":{"type":"string","pattern":"^\\d{1,19}$","example":"42"}}],"responses":{"200":{"description":"API key dicabut.","content":{"application/json":{"schema":{"type":"object","properties":{"revoked":{"type":"boolean"},"id":{"type":"string"}},"required":["revoked","id"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TenantSuspended"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/billing/status":{"get":{"tags":["Tenant"],"operationId":"getBillingStatus","summary":"Status langganan, masa aktif, batas device, dan riwayat order","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Status langganan tenant.","content":{"application/json":{"schema":{"type":"object","properties":{"tenant":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"plan":{"type":"string"},"status":{"type":"string"},"owner_phone":{"type":["string","null"]},"contact_email":{"type":["string","null"]},"paid_until":{"type":["string","null"]},"grace_ends_at":{"type":["string","null"]},"is_expired":{"type":"boolean"}},"required":["slug","name","plan","status","owner_phone","contact_email","paid_until","grace_ends_at","is_expired"]},"device_count":{"type":"integer"},"device_limit":{"type":"integer"},"quota":{"type":"object","properties":{"plan":{"type":"string"},"limit":{"type":"integer"},"used":{"type":"integer"},"remaining":{"type":"integer"},"resets_at":{"type":"string"},"overridden":{"type":"boolean"}},"required":["plan","limit","used","remaining","resets_at","overridden"]},"catalog":{"type":"object","properties":{"plans":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"price_idr":{"type":"integer"},"quota_monthly":{"type":"integer"},"device_limit":{"type":"integer"},"cycle_days":{"type":"integer"}},"required":["id","name","price_idr","quota_monthly","device_limit","cycle_days"]}},"providers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"is_live":{"type":"boolean"},"is_sandbox":{"type":"boolean"},"channels":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"group":{"type":"string"}},"required":["code","name","group"]}}},"required":["id","label","is_live","is_sandbox","channels"]}},"sandbox_enabled":{"type":"boolean"}},"required":["plans","providers","sandbox_enabled"]},"recent_orders":{"type":"array","items":{"$ref":"#/components/schemas/BillingOrder"}}},"required":["tenant","device_count","device_limit","quota","catalog","recent_orders"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TenantSuspended"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/billing/checkout":{"post":{"tags":["Tenant"],"operationId":"createBillingCheckout","summary":"Buat tagihan perpanjangan atau upgrade paket","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"plan":{"enum":["starter","bisnis","pro"]},"provider":{"enum":["sandbox","midtrans","tripay"]},"channel":{"type":"string"}},"required":["provider"]}}}},"responses":{"201":{"description":"Tagihan dibuat.","content":{"application/json":{"schema":{"type":"object","properties":{"order":{"$ref":"#/components/schemas/BillingOrder"}},"required":["order"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TenantSuspended"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/devices/{id}":{"get":{"tags":["Perangkat"],"operationId":"getDevice","summary":"Status device (termasuk status langsung dari gateway)","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"ID device, mis. `t-fiberaccess-1` (lihat `GET /v1/devices`).","schema":{"type":"string"}}],"responses":{"200":{"description":"Device + status langsung.","content":{"application/json":{"schema":{"type":"object","properties":{"device":{"$ref":"#/components/schemas/Device"},"live":{"$ref":"#/components/schemas/DeviceLive"}},"required":["device","live"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TenantSuspended"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/BadGateway"}}}},"/v1/devices/{id}/qr":{"post":{"tags":["Perangkat"],"operationId":"startDeviceQr","summary":"Minta QR untuk menautkan nomor","description":"Scan dengan WhatsApp di HP (Perangkat tertaut). QR kedaluwarsa dalam `expires_in_sec`. Ditolak `409` bila nomor sudah login. Setelah login, pantau lewat `GET /v1/devices/{id}`.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"ID device, mis. `t-fiberaccess-1` (lihat `GET /v1/devices`).","schema":{"type":"string"}}],"responses":{"200":{"description":"QR siap dipindai.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QrLogin"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TenantSuspended"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/BadGateway"}}}},"/v1/devices/{id}/pair-code":{"post":{"tags":["Perangkat"],"operationId":"startDevicePairCode","summary":"Minta kode pairing (tanpa QR)","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"ID device, mis. `t-fiberaccess-1` (lihat `GET /v1/devices`).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"phone":{"type":"string","description":"Nomor WhatsApp yang akan ditautkan.","example":"081234567890"}},"required":["phone"]}}}},"responses":{"200":{"description":"Kode untuk dimasukkan di WhatsApp.","content":{"application/json":{"schema":{"type":"object","properties":{"pair_code":{"type":"string","example":"ABCD-1234"}},"required":["pair_code"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TenantSuspended"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/BadGateway"}}}},"/v1/devices/{id}/logout":{"post":{"tags":["Perangkat"],"operationId":"logoutDevice","summary":"Putuskan nomor dari device","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"ID device, mis. `t-fiberaccess-1` (lihat `GET /v1/devices`).","schema":{"type":"string"}}],"responses":{"200":{"description":"Device setelah logout (`state: logged_out`).","content":{"application/json":{"schema":{"type":"object","properties":{"device":{"$ref":"#/components/schemas/Device"}},"required":["device"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TenantSuspended"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/BadGateway"}}}},"/v1/devices/{id}/pause":{"post":{"tags":["Perangkat"],"operationId":"pauseDevice","summary":"Jeda antrean device","description":"Pesan tetap diterima dan tertahan di antrean sampai device dilanjutkan.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"ID device, mis. `t-fiberaccess-1` (lihat `GET /v1/devices`).","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"Alasan (opsional).","maxLength":500}}}}}},"responses":{"200":{"description":"Device dijeda (`paused_code: manual`).","content":{"application/json":{"schema":{"type":"object","properties":{"device":{"$ref":"#/components/schemas/Device"}},"required":["device"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TenantSuspended"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/devices/{id}/resume":{"post":{"tags":["Perangkat"],"operationId":"resumeDevice","summary":"Lanjutkan antrean device","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"ID device, mis. `t-fiberaccess-1` (lihat `GET /v1/devices`).","schema":{"type":"string"}}],"responses":{"200":{"description":"Device berjalan lagi.","content":{"application/json":{"schema":{"type":"object","properties":{"device":{"$ref":"#/components/schemas/Device"}},"required":["device"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TenantSuspended"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/devices/{id}/config":{"patch":{"tags":["Perangkat"],"operationId":"updateDeviceConfig","summary":"Atur laju kirim device","description":"Jeda acak, jam kirim WIB, dan batas harian. Semua field opsional.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"ID device, mis. `t-fiberaccess-1` (lihat `GET /v1/devices`).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":60},"daily_limit":{"type":"integer","description":"Pesan per hari WIB.","minimum":1,"maximum":50000},"min_delay_sec":{"type":"integer","minimum":1,"maximum":300},"max_delay_sec":{"type":"integer","description":"Harus ≥ `min_delay_sec`.","minimum":1,"maximum":300},"window_start":{"type":"integer","description":"Jam mulai kirim (WIB).","minimum":0,"maximum":23},"window_end":{"type":"integer","description":"Jam akhir kirim (WIB), harus > `window_start`.","minimum":1,"maximum":24}}},"example":{"daily_limit":300,"min_delay_sec":15,"max_delay_sec":45,"window_start":8,"window_end":20}}}},"responses":{"200":{"description":"Konfigurasi baru.","content":{"application/json":{"schema":{"type":"object","properties":{"device":{"$ref":"#/components/schemas/Device"}},"required":["device"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TenantSuspended"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/devices/{id}/pairing-session":{"post":{"tags":["Perangkat"],"operationId":"createDevicePairingSession","summary":"Buat Magic Link penautan nomor untuk klien","description":"Klien menautkan nomornya lewat halaman `url` **tanpa** memegang API key. Berlaku 15–120 menit.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"ID device, mis. `t-fiberaccess-1` (lihat `GET /v1/devices`).","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"expires_in_min":{"type":"integer","description":"Masa berlaku menit.","minimum":1,"maximum":120}}}}}},"responses":{"200":{"description":"Sesi dibuat.","content":{"application/json":{"schema":{"type":"object","properties":{"session":{"$ref":"#/components/schemas/PairingSession"}},"required":["session"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TenantSuspended"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/pairing-sessions/{token}":{"get":{"tags":["Magic Link"],"operationId":"getPairingSession","summary":"Status sesi Magic Link","description":"Dipakai halaman tamu `/pair/{token}`. **Tanpa API key**: token sesi adalah kredensialnya.","security":[],"parameters":[{"name":"token","in":"path","required":true,"description":"Token sesi.","schema":{"type":"string"}}],"responses":{"200":{"description":"Sesi aktif.","content":{"application/json":{"schema":{"type":"object","properties":{"session":{"type":"object","properties":{"token":{"type":"string"},"tenant_name":{"type":"string"},"device_id":{"type":"string"},"device_label":{"type":"string"},"expires_at":{"type":"string","format":"date-time"},"remaining_sec":{"type":"integer"}},"required":["token","tenant_name","device_id","device_label","expires_at","remaining_sec"]},"device":{"$ref":"#/components/schemas/Device"},"live":{"$ref":"#/components/schemas/DeviceLive"}},"required":["session","device","live"]}}}},"404":{"$ref":"#/components/responses/NotFound"},"502":{"$ref":"#/components/responses/BadGateway"}}}},"/v1/pairing-sessions/{token}/qr":{"post":{"tags":["Magic Link"],"operationId":"startPairingSessionQr","summary":"Minta QR lewat sesi Magic Link","security":[],"parameters":[{"name":"token","in":"path","required":true,"description":"Token sesi.","schema":{"type":"string"}}],"responses":{"200":{"description":"QR siap dipindai.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QrLogin"}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"502":{"$ref":"#/components/responses/BadGateway"}}}},"/v1/pairing-sessions/{token}/pair-code":{"post":{"tags":["Magic Link"],"operationId":"startPairingSessionPairCode","summary":"Minta kode pairing lewat sesi Magic Link","security":[],"parameters":[{"name":"token","in":"path","required":true,"description":"Token sesi.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"phone":{"type":"string","example":"081234567890"}},"required":["phone"]}}}},"responses":{"200":{"description":"Kode pairing.","content":{"application/json":{"schema":{"type":"object","properties":{"pair_code":{"type":"string"}},"required":["pair_code"]}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/ValidationError"},"502":{"$ref":"#/components/responses/BadGateway"}}}},"/v1/webhook":{"get":{"tags":["Webhook"],"operationId":"getWebhookConfig","summary":"Konfigurasi webhook + 10 log pengiriman terakhir","description":"Event yang dikirim WartaHub ke URL Anda dijelaskan di bagian **Webhooks** (tanda tangan HMAC, bentuk payload).","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Konfigurasi.","content":{"application/json":{"schema":{"type":"object","properties":{"webhook":{"$ref":"#/components/schemas/WebhookConfig"},"recent_logs":{"type":"array","items":{"$ref":"#/components/schemas/WebhookLog"}}},"required":["webhook","recent_logs"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TenantSuspended"},"429":{"$ref":"#/components/responses/RateLimited"}}},"put":{"tags":["Webhook"],"operationId":"updateWebhookConfig","summary":"Simpan konfigurasi webhook","description":"Secret HMAC dibuat otomatis saat URL pertama kali disimpan; nilainya hanya muncul di respons ini (atau lewat `GET /v1/webhook/secret`).","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":["string","null"],"format":"uri","description":"URL http(s) penerima, harus beralamat **publik** (alamat internal/privat seperti 127.0.0.1, 10.x, 192.168.x ditolak `422`; redirect tidak diikuti). `null` menonaktifkan."},"events":{"type":"array","items":{"type":"string"},"description":"Filter event; kosong = semua."},"rotate_secret":{"type":"boolean","description":"`true` membuat secret baru."}}},"example":{"url":"https://sistem-anda.example/wartahub","events":["message.sent","message.failed","message.inbound"]}}}},"responses":{"200":{"description":"Tersimpan.","content":{"application/json":{"schema":{"type":"object","properties":{"webhook":{"$ref":"#/components/schemas/WebhookConfig"},"secret":{"type":"string","description":"Hanya ada bila secret baru dibuat."}},"required":["webhook"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TenantSuspended"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/webhook/secret":{"get":{"tags":["Webhook"],"operationId":"getWebhookSecret","summary":"Ambil secret HMAC","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Secret saat ini.","content":{"application/json":{"schema":{"type":"object","properties":{"secret":{"type":["string","null"]}},"required":["secret"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TenantSuspended"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/webhook/test":{"post":{"tags":["Webhook"],"operationId":"testWebhook","summary":"Kirim event uji (`ping`) ke URL webhook","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Hasil pengiriman uji.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"status_code":{"type":["integer","null"]},"duration_ms":{"type":["integer","null"]},"error":{"type":["string","null"]}},"required":["ok"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TenantSuspended"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/templates":{"get":{"tags":["Template"],"operationId":"listTemplates","summary":"Daftar template pesan","security":[{"bearerAuth":[]}],"parameters":[{"name":"category","in":"query","required":false,"description":"Filter kategori.","schema":{"type":"string"}}],"responses":{"200":{"description":"Template.","content":{"application/json":{"schema":{"type":"object","properties":{"templates":{"type":"array","items":{"$ref":"#/components/schemas/Template"}}},"required":["templates"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TenantSuspended"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["Template"],"operationId":"createTemplate","summary":"Buat template","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":100},"body":{"type":"string","description":"Dengan `{{variabel}}`."},"category":{"type":"string","maxLength":50}},"required":["name","body"]},"example":{"name":"Tagihan Bulanan","body":"Halo {{nama}}, tagihan {{bulan}} Rp{{nominal}} jatuh tempo {{jatuh_tempo}}.","category":"billing"}}}},"responses":{"201":{"description":"Dibuat.","content":{"application/json":{"schema":{"type":"object","properties":{"template":{"$ref":"#/components/schemas/Template"}},"required":["template"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TenantSuspended"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/templates/{id}":{"get":{"tags":["Template"],"operationId":"getTemplate","summary":"Detail template","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"ID template.","schema":{"type":"string","pattern":"^\\d{1,19}$","example":"42"}}],"responses":{"200":{"description":"Template.","content":{"application/json":{"schema":{"type":"object","properties":{"template":{"$ref":"#/components/schemas/Template"}},"required":["template"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TenantSuspended"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"put":{"tags":["Template"],"operationId":"updateTemplate","summary":"Ubah template","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"ID template.","schema":{"type":"string","pattern":"^\\d{1,19}$","example":"42"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":100},"body":{"type":"string"},"category":{"type":"string","maxLength":50}}}}}},"responses":{"200":{"description":"Diubah.","content":{"application/json":{"schema":{"type":"object","properties":{"template":{"$ref":"#/components/schemas/Template"}},"required":["template"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TenantSuspended"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}},"delete":{"tags":["Template"],"operationId":"deleteTemplate","summary":"Hapus template","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"ID template.","schema":{"type":"string","pattern":"^\\d{1,19}$","example":"42"}}],"responses":{"200":{"description":"Berhasil.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"]},"example":{"ok":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TenantSuspended"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/templates/{id}/render":{"post":{"tags":["Template"],"operationId":"renderTemplate","summary":"Pratinjau template dengan variabel","description":"Variabel yang tidak diberikan dibiarkan apa adanya (`{{nama}}`).","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"ID template.","schema":{"type":"string","pattern":"^\\d{1,19}$","example":"42"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"variables":{"type":"object","additionalProperties":true}},"required":["variables"]},"example":{"variables":{"nama":"Budi","bulan":"Oktober"}}}}},"responses":{"200":{"description":"Hasil render.","content":{"application/json":{"schema":{"type":"object","properties":{"rendered":{"type":"string"}},"required":["rendered"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TenantSuspended"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/contacts":{"get":{"tags":["Kontak"],"operationId":"listContacts","summary":"Daftar kontak","security":[{"bearerAuth":[]}],"parameters":[{"name":"tag","in":"query","required":false,"description":"Filter tag.","schema":{"type":"string"}},{"name":"search","in":"query","required":false,"description":"Cari pada nama atau nomor.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Jumlah maksimum (maks. 200).","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"Kontak.","content":{"application/json":{"schema":{"type":"object","properties":{"contacts":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}}},"required":["contacts"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TenantSuspended"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["Kontak"],"operationId":"upsertContact","summary":"Tambah atau perbarui kontak (berdasarkan nomor)","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactInput"},"example":{"phone":"081234567890","name":"Budi","tags":["pelanggan","rt-03"]}}}},"responses":{"201":{"description":"Tersimpan.","content":{"application/json":{"schema":{"type":"object","properties":{"contact":{"$ref":"#/components/schemas/Contact"}},"required":["contact"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TenantSuspended"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/contacts/import":{"post":{"tags":["Kontak"],"operationId":"importContacts","summary":"Impor kontak massal","description":"Isi `contacts` (maks. 1.000) dan/atau `csv` (baris `nomor,nama,tag…`, baris header dilewati). Baris yang tidak valid dilaporkan di `errors` (maks. 5 contoh).","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contacts":{"type":"array","items":{"$ref":"#/components/schemas/ContactInput"},"minItems":1,"maxItems":1000},"csv":{"type":"string","description":"Teks CSV: `nomor,nama,tag1,tag2`."}}},"example":{"csv":"081234567890,Budi,pelanggan\n081234567891,Sari,pelanggan,vip"}}}},"responses":{"200":{"description":"Ringkasan impor.","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer"},"imported":{"type":"integer"},"invalid":{"type":"integer"},"errors":{"type":"array","items":{"type":"string"}}},"required":["total","imported","invalid","errors"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TenantSuspended"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/contacts/tags":{"get":{"tags":["Kontak"],"operationId":"listContactTags","summary":"Daftar tag beserta jumlah kontak","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Tag.","content":{"application/json":{"schema":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"tag":{"type":"string"},"count":{"type":"integer"}},"required":["tag","count"]}}},"required":["tags"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TenantSuspended"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/contacts/tags/{tag}/phones":{"get":{"tags":["Kontak"],"operationId":"listContactPhonesByTag","summary":"Nomor semua kontak dengan tag tertentu","description":"Berguna untuk broadcast: kirim hasilnya sebagai `to` di `POST /v1/messages` (maks. 100 per request).","security":[{"bearerAuth":[]}],"parameters":[{"name":"tag","in":"path","required":true,"description":"Nama tag.","schema":{"type":"string"}}],"responses":{"200":{"description":"Nomor.","content":{"application/json":{"schema":{"type":"object","properties":{"tag":{"type":"string"},"count":{"type":"integer"},"phones":{"type":"array","items":{"type":"string"}}},"required":["tag","count","phones"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TenantSuspended"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/contacts/{id}":{"delete":{"tags":["Kontak"],"operationId":"deleteContact","summary":"Hapus kontak","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"ID kontak.","schema":{"type":"string","pattern":"^\\d{1,19}$","example":"42"}}],"responses":{"200":{"description":"Berhasil.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"]},"example":{"ok":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TenantSuspended"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/auto-responder":{"get":{"tags":["Auto-Reply"],"operationId":"listAutoReplyRules","summary":"Daftar aturan balasan otomatis","description":"`inbound_ready: false` berarti webhook pesan masuk dari gateway belum dikonfigurasi operator: aturan bisa disimpan dan diuji, tetapi belum membalas chat sungguhan.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Aturan, prioritas tertinggi dulu.","content":{"application/json":{"schema":{"type":"object","properties":{"inbound_ready":{"type":"boolean"},"rules":{"type":"array","items":{"$ref":"#/components/schemas/AutoReplyRule"}}},"required":["inbound_ready","rules"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TenantSuspended"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["Auto-Reply"],"operationId":"createAutoReplyRule","summary":"Tambah aturan balasan otomatis","description":"Chat **pribadi** yang cocok dibalas lewat antrean prioritas tinggi (tetap mengikuti jeda & jam kirim device). Maks. 1 balasan per aturan per pengirim per menit. Grup dan pesan dari nomor sendiri tidak dibalas. Maks. 100 aturan per tenant.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutoReplyRuleInput"},"example":{"keyword":"TAGIHAN","match_type":"starts_with","reply_message":"Tagihan Anda bisa dicek di https://contoh.id","priority":5}}}},"responses":{"201":{"description":"Dibuat.","content":{"application/json":{"schema":{"type":"object","properties":{"rule":{"$ref":"#/components/schemas/AutoReplyRule"}},"required":["rule"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TenantSuspended"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/auto-responder/test":{"post":{"tags":["Auto-Reply"],"operationId":"testAutoReply","summary":"Simulator: aturan mana yang akan membalas","description":"Tidak mengirim apa pun.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","description":"Contoh pesan dari pelanggan.","maxLength":4096}},"required":["text"]},"example":{"text":"tagihan bulan ini berapa?"}}}},"responses":{"200":{"description":"Hasil pencocokan.","content":{"application/json":{"schema":{"type":"object","properties":{"matched":{"type":"boolean"},"rule":{"oneOf":[{"$ref":"#/components/schemas/AutoReplyRule"},{"type":"null"}]},"reply":{"type":["string","null"]}},"required":["matched","rule","reply"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TenantSuspended"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/auto-responder/{id}":{"put":{"tags":["Auto-Reply"],"operationId":"updateAutoReplyRule","summary":"Ubah aturan","description":"Semua field opsional (ubah sebagian).","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"ID aturan.","schema":{"type":"string","pattern":"^\\d{1,19}$","example":"42"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"keyword":{"type":"string","maxLength":100,"example":"TAGIHAN"},"match_type":{"enum":["exact","starts_with","contains"],"default":"exact","description":"Tanpa membedakan huruf besar/kecil dan spasi berlebih. Regex tidak didukung."},"reply_message":{"type":"string","description":"Maks. 4.096 karakter; 1.024 bila ada lampiran.","maxLength":4096},"reply_attachment_url":{"type":["string","null"],"description":"URL https (PDF/JPG/PNG), maks. 500 karakter.","maxLength":500},"is_active":{"type":"boolean","default":true},"priority":{"type":"integer","minimum":-1000,"maximum":1000,"default":0}}},"example":{"is_active":false}}}},"responses":{"200":{"description":"Diubah.","content":{"application/json":{"schema":{"type":"object","properties":{"rule":{"$ref":"#/components/schemas/AutoReplyRule"}},"required":["rule"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TenantSuspended"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}},"delete":{"tags":["Auto-Reply"],"operationId":"deleteAutoReplyRule","summary":"Hapus aturan","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"ID aturan.","schema":{"type":"string","pattern":"^\\d{1,19}$","example":"42"}}],"responses":{"200":{"description":"Berhasil.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"]},"example":{"ok":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/TenantSuspended"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/fonnte/send":{"post":{"tags":["Kompatibel Fonnte"],"operationId":"sendFonnte","summary":"Kirim pesan (format Fonnte)","description":"Pengganti langsung `POST https://api.fonnte.com/send`: ganti URL ke `/fonnte/send` dan token ke API key WartaHub. Seperti Fonnte, **selalu HTTP 200**; periksa `status` di body. Terima `application/json`, `application/x-www-form-urlencoded`, atau `multipart/form-data` (dengan `file`).\n\nKata **\"target invalid\"** pada `reason` dipertahankan untuk nomor tujuan salah, supaya klien (mis. NetBill) tidak menganggapnya gangguan pengirim. Kuota habis → `status:false`, `reason` diawali \"Kuota pesan paket…\".","security":[{"fonnteToken":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"target":{"type":"string","description":"Satu atau banyak nomor dipisah koma (maks. 100). Format `08xx`, `+62 8xx`, `628xx`.","example":"081234567890,081234567891"},"message":{"type":"string","description":"Teks pesan (caption bila ada lampiran)."},"countryCode":{"type":"string","description":"Awalan negara untuk nomor tanpa kode.","default":"62"},"schedule":{"type":"integer","description":"Waktu kirim **unix detik** (bukan milidetik), maks. 1 tahun ke depan."},"url":{"type":"string","description":"URL https lampiran (PDF/JPG/PNG, maks. 5 MB).","format":"uri"},"filename":{"type":"string","description":"Nama file lampiran."},"file":{"type":"string","description":"Lampiran biner (hanya `multipart/form-data`, maks. 5 MB).","format":"binary"}},"required":["target"],"description":"Parameter Fonnte `delay`, `typing`, `preview`, `connectOnly`, `sequence`, `duration` diabaikan (laju diatur antrean WartaHub). Parameter `location`, `choices`, `pollname`, `select`, `data`, `inboxid`, `followup` ditolak dengan `status:false`."},"example":{"target":"081234567890","message":"Halo dari WartaHub"}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"target":{"type":"string","description":"Satu atau banyak nomor dipisah koma (maks. 100). Format `08xx`, `+62 8xx`, `628xx`.","example":"081234567890,081234567891"},"message":{"type":"string","description":"Teks pesan (caption bila ada lampiran)."},"countryCode":{"type":"string","description":"Awalan negara untuk nomor tanpa kode.","default":"62"},"schedule":{"type":"integer","description":"Waktu kirim **unix detik** (bukan milidetik), maks. 1 tahun ke depan."},"url":{"type":"string","description":"URL https lampiran (PDF/JPG/PNG, maks. 5 MB).","format":"uri"},"filename":{"type":"string","description":"Nama file lampiran."},"file":{"type":"string","description":"Lampiran biner (hanya `multipart/form-data`, maks. 5 MB).","format":"binary"}},"required":["target"],"description":"Parameter Fonnte `delay`, `typing`, `preview`, `connectOnly`, `sequence`, `duration` diabaikan (laju diatur antrean WartaHub). Parameter `location`, `choices`, `pollname`, `select`, `data`, `inboxid`, `followup` ditolak dengan `status:false`."}},"multipart/form-data":{"schema":{"type":"object","properties":{"target":{"type":"string","description":"Satu atau banyak nomor dipisah koma (maks. 100). Format `08xx`, `+62 8xx`, `628xx`.","example":"081234567890,081234567891"},"message":{"type":"string","description":"Teks pesan (caption bila ada lampiran)."},"countryCode":{"type":"string","description":"Awalan negara untuk nomor tanpa kode.","default":"62"},"schedule":{"type":"integer","description":"Waktu kirim **unix detik** (bukan milidetik), maks. 1 tahun ke depan."},"url":{"type":"string","description":"URL https lampiran (PDF/JPG/PNG, maks. 5 MB).","format":"uri"},"filename":{"type":"string","description":"Nama file lampiran."},"file":{"type":"string","description":"Lampiran biner (hanya `multipart/form-data`, maks. 5 MB).","format":"binary"}},"required":["target"],"description":"Parameter Fonnte `delay`, `typing`, `preview`, `connectOnly`, `sequence`, `duration` diabaikan (laju diatur antrean WartaHub). Parameter `location`, `choices`, `pollname`, `select`, `data`, `inboxid`, `followup` ditolak dengan `status:false`."}}}},"responses":{"200":{"description":"Sukses (`status:true`) atau gagal (`status:false`) — HTTP tetap 200.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/FonnteSuccess"},{"$ref":"#/components/schemas/FonnteFailure"}]}}}},"429":{"description":"Rate limit (`status:false`).","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer"},"status":{"type":"boolean","const":false},"reason":{"type":"string","example":"rate limit exceeded"}},"required":["status","reason"]}}}}},"x-codeSamples":[{"lang":"Shell","label":"cURL","source":"curl -X POST https://wartahub.example/fonnte/send \\\n  -H \"Authorization: wh_live_xxx\" \\\n  -d \"target=081234567890\" -d \"message=Halo\""}]}}},"webhooks":{"message.sent":{"post":{"tags":["Webhook"],"summary":"Pesan diterima gateway WhatsApp","description":"`sent` berarti diterima gateway; konfirmasi sampai ke HP lewat `message.delivered`.\n\nBalas HTTP **2xx** dalam 10 detik. Header: `X-WartaHub-Event`, `X-WartaHub-Delivery` (ID unik), dan `X-WartaHub-Signature: sha256=<hex>` = HMAC-SHA256 dari **body mentah** dengan secret webhook Anda. Verifikasi tanda tangan sebelum memproses.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string","const":"message.sent"},"timestamp":{"type":"string","description":"Waktu pengiriman.","format":"date-time"},"data":{"type":"object","properties":{"message_id":{"type":"string","description":"ID pesan WartaHub."},"recipient":{"type":"string"},"device":{"type":"string"},"status":{"enum":["sent","failed"]},"provider_message_id":{"type":["string","null"],"description":"ID pesan di WhatsApp."},"error":{"type":["string","null"]},"failure_kind":{"oneOf":[{"enum":["recipient","sender","other"]},{"type":"null"}]},"timestamp":{"type":"string","format":"date-time"}},"required":["message_id","recipient","device","status","provider_message_id","error","failure_kind","timestamp"]}},"required":["event","timestamp","data"]}}}},"responses":{"2XX":{"description":"Diterima."}},"operationId":"onMessageSent"}},"message.failed":{"post":{"tags":["Webhook"],"summary":"Pesan gagal","description":"`failure_kind: recipient` = nomor tujuan tidak terdaftar/bermasalah.\n\nBalas HTTP **2xx** dalam 10 detik. Header: `X-WartaHub-Event`, `X-WartaHub-Delivery` (ID unik), dan `X-WartaHub-Signature: sha256=<hex>` = HMAC-SHA256 dari **body mentah** dengan secret webhook Anda. Verifikasi tanda tangan sebelum memproses.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string","const":"message.failed"},"timestamp":{"type":"string","description":"Waktu pengiriman.","format":"date-time"},"data":{"type":"object","properties":{"message_id":{"type":"string","description":"ID pesan WartaHub."},"recipient":{"type":"string"},"device":{"type":"string"},"status":{"enum":["sent","failed"]},"provider_message_id":{"type":["string","null"],"description":"ID pesan di WhatsApp."},"error":{"type":["string","null"]},"failure_kind":{"oneOf":[{"enum":["recipient","sender","other"]},{"type":"null"}]},"timestamp":{"type":"string","format":"date-time"}},"required":["message_id","recipient","device","status","provider_message_id","error","failure_kind","timestamp"]}},"required":["event","timestamp","data"]}}}},"responses":{"2XX":{"description":"Diterima."}},"operationId":"onMessageFailed"}},"message.delivered":{"post":{"tags":["Webhook"],"summary":"Pesan sampai ke perangkat penerima","description":"Dari status terima WhatsApp (centang dua).\n\nBalas HTTP **2xx** dalam 10 detik. Header: `X-WartaHub-Event`, `X-WartaHub-Delivery` (ID unik), dan `X-WartaHub-Signature: sha256=<hex>` = HMAC-SHA256 dari **body mentah** dengan secret webhook Anda. Verifikasi tanda tangan sebelum memproses.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string","const":"message.delivered"},"timestamp":{"type":"string","description":"Waktu pengiriman.","format":"date-time"},"data":{"type":"object","properties":{"device":{"type":"string"},"provider_message_ids":{"type":"array","items":{"type":"string"},"description":"ID di WhatsApp; cocok dengan `provider_message_id` pada pesan."},"message_ids":{"type":"array","items":{"type":"string"},"description":"ID pesan WartaHub yang cocok (kosong bila bukan pesan yang dikirim lewat WartaHub)."},"to":{"type":["string","null"],"description":"Nomor penerima yang membuka/menerima pesan."},"chat_id":{"type":["string","null"]},"timestamp":{"type":["string","null"]}},"required":["device","provider_message_ids"]}},"required":["event","timestamp","data"]}}}},"responses":{"2XX":{"description":"Diterima."}},"operationId":"onMessageDelivered"}},"message.read":{"post":{"tags":["Webhook"],"summary":"Pesan dibaca penerima","description":"Hanya bila penerima mengaktifkan tanda baca.\n\nBalas HTTP **2xx** dalam 10 detik. Header: `X-WartaHub-Event`, `X-WartaHub-Delivery` (ID unik), dan `X-WartaHub-Signature: sha256=<hex>` = HMAC-SHA256 dari **body mentah** dengan secret webhook Anda. Verifikasi tanda tangan sebelum memproses.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string","const":"message.read"},"timestamp":{"type":"string","description":"Waktu pengiriman.","format":"date-time"},"data":{"type":"object","properties":{"device":{"type":"string"},"provider_message_ids":{"type":"array","items":{"type":"string"},"description":"ID di WhatsApp; cocok dengan `provider_message_id` pada pesan."},"message_ids":{"type":"array","items":{"type":"string"},"description":"ID pesan WartaHub yang cocok (kosong bila bukan pesan yang dikirim lewat WartaHub)."},"to":{"type":["string","null"],"description":"Nomor penerima yang membuka/menerima pesan."},"chat_id":{"type":["string","null"]},"timestamp":{"type":["string","null"]}},"required":["device","provider_message_ids"]}},"required":["event","timestamp","data"]}}}},"responses":{"2XX":{"description":"Diterima."}},"operationId":"onMessageRead"}},"message.inbound":{"post":{"tags":["Webhook"],"summary":"Pesan masuk dari pelanggan","description":"Chat yang diterima nomor tenant (juga memicu auto-reply bila ada aturan yang cocok).\n\nBalas HTTP **2xx** dalam 10 detik. Header: `X-WartaHub-Event`, `X-WartaHub-Delivery` (ID unik), dan `X-WartaHub-Signature: sha256=<hex>` = HMAC-SHA256 dari **body mentah** dengan secret webhook Anda. Verifikasi tanda tangan sebelum memproses.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string","const":"message.inbound"},"timestamp":{"type":"string","description":"Waktu pengiriman.","format":"date-time"},"data":{"type":"object","properties":{"device":{"type":"string"},"message_id":{"type":["string","null"]},"from":{"type":["string","null"],"description":"Nomor pengirim (62xxx); null bila bukan akun pribadi."},"from_jid":{"type":["string","null"]},"chat_id":{"type":["string","null"]},"is_group":{"type":"boolean"},"sender_name":{"type":["string","null"]},"text":{"type":"string","description":"Teks pesan (kosong untuk media tanpa teks)."},"timestamp":{"type":["string","null"],"description":"Waktu pesan menurut WhatsApp."}},"required":["device","from","is_group","text"]}},"required":["event","timestamp","data"]}}}},"responses":{"2XX":{"description":"Diterima."}},"operationId":"onMessageInbound"}},"ping":{"post":{"tags":["Webhook"],"summary":"Uji koneksi","description":"Dikirim oleh `POST /v1/webhook/test`.\n\nBalas HTTP **2xx** dalam 10 detik. Header: `X-WartaHub-Event`, `X-WartaHub-Delivery` (ID unik), dan `X-WartaHub-Signature: sha256=<hex>` = HMAC-SHA256 dari **body mentah** dengan secret webhook Anda. Verifikasi tanda tangan sebelum memproses.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string","const":"ping"},"timestamp":{"type":"string","description":"Waktu pengiriman.","format":"date-time"},"data":{"type":"object","properties":{"message":{"type":"string"},"sentAt":{"type":"string","format":"date-time"}},"required":["message","sentAt"]}},"required":["event","timestamp","data"]}}}},"responses":{"2XX":{"description":"Diterima."}},"operationId":"onPing"}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"wh_live_…","description":"API key tenant: `Authorization: Bearer wh_live_xxxxxxxx…`. Diterbitkan operator (`apikey:issue`), ditampilkan sekali."},"fonnteToken":{"type":"apiKey","in":"header","name":"Authorization","description":"Khusus `/fonnte/send`: API key WartaHub sebagai token, boleh TANPA awalan `Bearer` (seperti klien Fonnte)."}},"responses":{"Unauthorized":{"description":"API key tidak ada, salah, atau sudah dicabut (`INVALID_API_KEY`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"INVALID_API_KEY","message":"API key tidak valid atau sudah dicabut."}}}}},"TenantSuspended":{"description":"Tenant ditangguhkan operator (`TENANT_SUSPENDED`). Dibedakan dari 401 supaya klien tidak mengira API key-nya salah.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"TENANT_SUSPENDED","message":"Layanan tenant ini sedang ditangguhkan. Hubungi operator WartaHub."}}}}},"NotFound":{"description":"Data tidak ada **atau milik tenant lain** (sengaja tidak dibedakan).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"NOT_FOUND","message":"Pesan tidak ditemukan."}}}}},"ValidationError":{"description":"Input tidak valid (`VALIDATION_ERROR`). `details` berisi daftar isu bila berasal dari validasi skema.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"VALIDATION_ERROR","message":"Nomor tujuan tidak valid. Contoh: 081234567890 atau 6281234567890."}}}}},"Conflict":{"description":"Konflik keadaan (`CONFLICT`), mis. nomor sudah login saat meminta QR.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"CONFLICT","message":"Nomor sudah login."}}}}},"QuotaExceeded":{"description":"Kuota pesan bulanan paket tidak cukup (`QUOTA_EXCEEDED`). Kuota direset tanggal 1 pukul 00.00 WIB; operator dapat menaikkannya. **Jangan di-retry otomatis** sebelum `details.resets_at`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"QUOTA_EXCEEDED","message":"Kuota pesan paket starter bulan ini tidak cukup. Terpakai 3.000 dari 3.000 pesan. Kuota direset 1 Desember; hubungi operator WartaHub untuk menaikkan paket.","details":{"plan":"starter","limit":3000,"used":3000,"remaining":0,"requested":1,"resets_at":"2026-11-30T17:00:00.000Z"}}}}}},"PayloadTooLarge":{"description":"Body/file terlalu besar (`PAYLOAD_TOO_LARGE`) atau penyimpanan unggahan tenant penuh (`MEDIA_QUOTA_EXCEEDED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"PAYLOAD_TOO_LARGE","message":"Ukuran file maksimal 15 MB."}}}}},"RateLimited":{"description":"Terlalu banyak request (`RATE_LIMITED`; default 120/menit per API key). Header `Retry-After` memuat detik tunggu.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"RATE_LIMITED","message":"Terlalu banyak request. Coba lagi sebentar lagi."}}}}},"BadGateway":{"description":"Gateway WhatsApp (GOWA) gagal atau menolak (`WA_GATEWAY_ERROR`). Sengaja 502, bukan 401/403.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"WA_GATEWAY_ERROR","message":"Tidak bisa menghubungi GOWA: fetch failed"}}}}}},"schemas":{"PaginationMeta":{"type":"object","properties":{"page":{"type":"integer","description":"Nomor halaman saat ini (mulai dari 1).","minimum":1},"limit":{"type":"integer","description":"Jumlah maksimum item per halaman (1–100).","minimum":1,"maximum":100},"total":{"type":"integer","description":"Total item yang cocok dengan filter di database.","minimum":0},"total_pages":{"type":"integer","description":"Jumlah seluruh halaman.","minimum":1},"has_next":{"type":"boolean","description":"`true` bila masih ada halaman berikutnya."},"has_prev":{"type":"boolean","description":"`true` bila ada halaman sebelumnya."}},"required":["page","limit","total","total_pages","has_next","has_prev"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Kode mesin yang stabil, mis. `VALIDATION_ERROR`.","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Pesan manusiawi (Bahasa Indonesia)."},"details":{"description":"Opsional; bentuknya tergantung `code`."}},"required":["code","message"]}},"required":["error"]},"Message":{"type":"object","properties":{"id":{"type":"string","description":"ID pesan (string angka).","example":"42"},"status":{"enum":["scheduled","queued","sending","sent","failed","cancelled"],"description":"`scheduled` → `queued` → `sending` → `sent` | `failed`; `cancelled` bila dibatalkan. `sent` = diterima gateway WhatsApp; penerimaan nyata hanya terlihat di HP penerima (pantau lewat webhook `message.delivered`/`message.read`)."},"to":{"type":"string","description":"Nomor tujuan ternormalisasi (62xxx).","example":"6281234567890"},"device":{"type":"string","description":"ID device pengirim.","example":"t-fiberaccess-1"},"priority":{"enum":["normal","high"]},"message":{"type":"string","description":"Isi pesan (caption bila ada lampiran)."},"attachment":{"oneOf":[{"type":"object","properties":{"filename":{"type":"string","example":"INV-123.pdf"},"mime_type":{"enum":["application/pdf","image/jpeg","image/png"]},"size_bytes":{"type":"integer"}},"required":["filename","mime_type","size_bytes"]},{"type":"null"}]},"idempotency_key":{"type":["string","null"]},"source":{"enum":["api","fonnte","auto_reply"]},"failure_kind":{"oneOf":[{"enum":["recipient","sender","other"]},{"type":"null"}],"description":"`recipient` = nomor tujuan bermasalah (device tidak dijeda); `other` = kegagalan lain."},"detail":{"type":["string","null"],"description":"Alasan gagal / catatan."},"provider_message_id":{"type":["string","null"],"description":"ID pesan di WhatsApp; dipakai webhook `message.delivered`/`message.read`."},"scheduled_at":{"type":["string","null"],"description":"Waktu jadwal kirim (paling cepat dikirim), bila dijadwalkan.","format":"date-time"},"send_after":{"type":["string","null"],"description":"Alias lama `scheduled_at`.","format":"date-time","deprecated":true},"processed_at":{"type":["string","null"],"description":"Waktu selesai diproses (terkirim/gagal).","format":"date-time"},"delivered_at":{"type":["string","null"],"description":"Waktu pesan sampai di HP penerima (status terima WhatsApp). Terisi setelah gateway menerima konfirmasi; bisa tetap null bila penerima offline.","format":"date-time"},"read_at":{"type":["string","null"],"description":"Waktu dibaca penerima. Hanya terisi bila penerima mengaktifkan tanda baca; dibaca ⇒ `delivered_at` juga terisi.","format":"date-time"},"created_at":{"type":"string","format":"date-time"}},"required":["id","status","to","device","priority","message","attachment","idempotency_key","source","failure_kind","detail","provider_message_id","scheduled_at","send_after","processed_at","delivered_at","read_at","created_at"]},"SendMessageRequest":{"type":"object","properties":{"to":{"description":"Satu nomor, atau banyak nomor (array maks. 100, atau string dipisah koma/baris baru/titik koma) untuk broadcast. Format `08xx`, `+62 8xx`, atau `628xx`.","oneOf":[{"type":"string","example":"081234567890"},{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":100}]},"message":{"type":"string","description":"Teks maks. 4.096 karakter; 1.024 bila ada lampiran (batas caption WhatsApp). Boleh kosong bila ada lampiran.","default":""},"device":{"type":"string","description":"ID device. Default: device pertama tenant.","maxLength":60},"priority":{"enum":["normal","high"],"default":"normal","description":"`high` didahulukan di antrean (mis. konfirmasi lunas/isolir)."},"idempotency_key":{"type":"string","description":"Disarankan. Request ulang dengan key sama → 200 dengan pesan yang sama, tidak ada pesan ganda, tidak memakan kuota. Bisa juga lewat header `Idempotency-Key`.","maxLength":100},"scheduled_at":{"type":"string","description":"ISO 8601 **dengan zona waktu** (mis. `2026-11-10T09:00:00+07:00`). Di masa depan → status `scheduled` (maks. 1 tahun); di masa lalu → langsung `queued`. Jadwal = paling cepat dikirim: pesan tetap mengikuti jeda, jam kirim, dan batas harian device.","format":"date-time"},"send_after":{"type":"string","description":"Alias lama `scheduled_at`.","format":"date-time","deprecated":true},"document":{"type":"object","description":"Lampiran PDF/JPG/PNG (jenis dicek dari isi file). Isi **tepat salah satu**: `base64`, `url`, atau `media_id`.","properties":{"filename":{"type":"string","maxLength":150,"example":"INV-123.pdf"},"base64":{"type":"string","description":"Isi file base64 (boleh berawalan `data:…;base64,`). Maks. 5 MB."},"url":{"type":"string","description":"URL **https** publik (bukan alamat internal/IP privat). Maks. 5 MB.","format":"uri"},"media_id":{"type":"string","description":"ID dari `POST /v1/media/upload` milik tenant yang sama. Maks. 15 MB."}},"oneOf":[{"required":["base64"]},{"required":["url"]},{"required":["media_id"]}]}},"required":["to"]},"SendMessageSingleResponse":{"type":"object","properties":{"message":{"$ref":"#/components/schemas/Message"},"created":{"type":"boolean","description":"`false` bila `idempotency_key` sudah pernah dipakai (pesan lama dikembalikan apa adanya)."}},"required":["message","created"]},"SendMessageBroadcastResponse":{"type":"object","properties":{"created":{"type":"boolean","const":true},"queued":{"type":"boolean","description":"`false` bila dijadwalkan."},"scheduled":{"type":"boolean"},"total":{"type":"integer"},"message":{"$ref":"#/components/schemas/Message"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/Message"}}},"required":["created","queued","scheduled","total","message","messages"]},"Media":{"type":"object","properties":{"id":{"type":"string","description":"32 karakter hex acak.","pattern":"^[a-f0-9]{32}$"},"filename":{"type":"string"},"mime_type":{"enum":["application/pdf","image/jpeg","image/png"]},"size_bytes":{"type":"integer"},"url":{"type":"string","description":"Path relatif untuk `GET` (wajib API key yang sama; bukan URL publik)."},"expires_at":{"type":"string","description":"Dihapus otomatis setelah waktu ini (default 24 jam).","format":"date-time"}},"required":["id","filename","mime_type","size_bytes","url","expires_at"]},"Device":{"type":"object","properties":{"id":{"type":"string","description":"ID device GOWA.","example":"t-fiberaccess-1"},"label":{"type":"string"},"state":{"enum":["connected","disconnected","logged_out","unknown"],"description":"Status nomor menurut monitor (diperiksa tiap 60 detik)."},"phone":{"type":["string","null"]},"paused":{"type":"boolean","description":"Antrean device dijeda (manual atau otomatis)."},"paused_code":{"oneOf":[{"enum":["sender_offline","sender_restricted","failures","manual"]},{"type":"null"}],"description":"Hanya `sender_offline` yang dilanjutkan otomatis."},"paused_reason":{"type":["string","null"]},"daily_limit":{"type":"integer","description":"Batas pesan diproses per hari WIB."},"delay_sec":{"type":"object","properties":{"min":{"type":"integer"},"max":{"type":"integer"}},"required":["min","max"],"description":"Rentang jeda acak antar pesan (detik)."},"send_window_wib":{"type":"string","example":"08:00–20:00"},"window_start":{"type":"integer","minimum":0,"maximum":23},"window_end":{"type":"integer","minimum":1,"maximum":24},"state_changed_at":{"type":["string","null"],"format":"date-time"},"last_checked_at":{"type":["string","null"],"format":"date-time"}},"required":["id","label","state","phone","paused","paused_code","paused_reason","daily_limit","delay_sec","send_window_wib","window_start","window_end","state_changed_at","last_checked_at"]},"DeviceLive":{"type":"object","properties":{"registered":{"type":"boolean"},"logged_in":{"type":"boolean"},"connected":{"type":"boolean"},"phone":{"type":["string","null"]}},"required":["registered","logged_in","connected","phone"],"description":"Status langsung dari gateway WhatsApp."},"QrLogin":{"type":"object","properties":{"qr_image":{"type":"string","description":"Data URI PNG.","example":"data:image/png;base64,iVBOR…"},"expires_in_sec":{"type":"integer"}},"required":["qr_image","expires_in_sec"]},"PairingSession":{"type":"object","properties":{"token":{"type":"string"},"device_id":{"type":"string"},"device_label":{"type":"string"},"tenant_name":{"type":"string"},"expires_at":{"type":"string","format":"date-time"},"url":{"type":"string","description":"Path halaman tamu, mis. `/pair/<token>` (gabungkan dengan domain WartaHub)."}},"required":["token","device_id","device_label","tenant_name","expires_at","url"]},"ApiKeyMeta":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"prefix":{"type":"string"},"last_used_at":{"type":["string","null"],"format":"date-time"},"revoked_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}},"required":["id","label","prefix","last_used_at","revoked_at","created_at"]},"BillingOrder":{"type":"object","properties":{"token":{"type":"string"},"kind":{"enum":["register","renewal","upgrade"]},"slug":{"type":"string"},"name":{"type":"string"},"plan":{"enum":["starter","bisnis","pro"]},"amount_idr":{"type":"integer"},"provider":{"enum":["sandbox","midtrans","tripay"]},"channel":{"type":["string","null"]},"external_id":{"type":"string"},"provider_ref":{"type":["string","null"]},"payment_url":{"type":["string","null"]},"pay_code":{"type":["string","null"]},"qr_string":{"type":["string","null"]},"qr_image":{"type":["string","null"],"description":"Data URI SVG gambar QRIS siap tampil bila qr_string tersedia."},"status":{"enum":["pending","paid","expired","failed"]},"can_enter_console":{"type":"boolean"},"paid_at":{"type":["string","null"],"format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"}},"required":["token","kind","slug","name","plan","amount_idr","provider","channel","external_id","provider_ref","payment_url","pay_code","qr_string","qr_image","status","can_enter_console","paid_at","expires_at","created_at"]},"Contact":{"type":"object","properties":{"id":{"type":"string"},"phone":{"type":"string","description":"Ternormalisasi (62xxx)."},"name":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"custom_fields":{"type":["object","null"],"additionalProperties":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","phone","name","tags","custom_fields","created_at","updated_at"]},"ContactInput":{"type":"object","properties":{"phone":{"type":"string","example":"081234567890"},"name":{"type":"string","maxLength":120},"tags":{"description":"Satu tag, daftar dipisah koma, atau array.","oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"custom_fields":{"type":"object","additionalProperties":true}},"required":["phone","name"]},"Template":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"body":{"type":"string","description":"Gunakan `{{nama_variabel}}` untuk personalisasi."},"category":{"type":"string"},"variables":{"type":"array","items":{"type":"string"},"description":"Variabel `{{…}}` yang terdeteksi otomatis."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","name","body","category","variables","created_at","updated_at"]},"AutoReplyRule":{"type":"object","properties":{"id":{"type":"string"},"keyword":{"type":"string"},"match_type":{"enum":["exact","starts_with","contains"]},"reply_message":{"type":"string"},"reply_attachment_url":{"type":["string","null"],"description":"URL https lampiran balasan."},"is_active":{"type":"boolean"},"priority":{"type":"integer","description":"Lebih besar = dicek lebih dulu.","minimum":-1000,"maximum":1000},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","keyword","match_type","reply_message","reply_attachment_url","is_active","priority","created_at","updated_at"]},"AutoReplyRuleInput":{"type":"object","properties":{"keyword":{"type":"string","maxLength":100,"example":"TAGIHAN"},"match_type":{"enum":["exact","starts_with","contains"],"default":"exact","description":"Tanpa membedakan huruf besar/kecil dan spasi berlebih. Regex tidak didukung."},"reply_message":{"type":"string","description":"Maks. 4.096 karakter; 1.024 bila ada lampiran.","maxLength":4096},"reply_attachment_url":{"type":["string","null"],"description":"URL https (PDF/JPG/PNG), maks. 500 karakter.","maxLength":500},"is_active":{"type":"boolean","default":true},"priority":{"type":"integer","minimum":-1000,"maximum":1000,"default":0}},"required":["keyword","reply_message"]},"WebhookConfig":{"type":"object","properties":{"url":{"type":["string","null"]},"has_secret":{"type":"boolean"},"secret_preview":{"type":["string","null"]},"events":{"type":"array","items":{"type":"string"},"description":"Daftar event yang dikirim; kosong = semua."}},"required":["url","has_secret","secret_preview","events"]},"WebhookLog":{"type":"object","properties":{"id":{"type":"string"},"event":{"type":"string"},"url":{"type":"string"},"status_code":{"type":["integer","null"]},"duration_ms":{"type":["integer","null"]},"error":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}},"required":["id","event","url","status_code","duration_ms","error","created_at"]},"Usage":{"type":"object","properties":{"plan":{"type":"object","properties":{"name":{"enum":["starter","bisnis","pro"]},"quota_monthly":{"type":"integer","description":"Kuota pesan bulan ini (kuota paket, atau penimpaan operator)."},"used_monthly":{"type":"integer","description":"Pesan yang **dibuat** bulan ini selain yang dibatalkan — dasar penegakan kuota."},"sent_monthly":{"type":"integer","description":"Pesan terkirim bulan ini."},"usage_pct":{"type":"integer","minimum":0,"maximum":100},"remaining_monthly":{"type":"integer"},"resets_at":{"type":"string","description":"Awal bulan WIB berikutnya.","format":"date-time"},"quota_overridden":{"type":"boolean","description":"`true` bila kuota ditimpa operator."}},"required":["name","quota_monthly","used_monthly","sent_monthly","usage_pct","remaining_monthly","resets_at","quota_overridden"]},"today":{"type":"object","properties":{"sent":{"type":"integer"},"failed":{"type":"integer"},"queued":{"type":"integer"},"delivery_rate_pct":{"type":"integer"}},"required":["sent","failed","queued","delivery_rate_pct"],"description":"Hari WIB berjalan."},"devices":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"gowa_id":{"type":"string"},"label":{"type":"string"},"state":{"type":"string"},"daily_limit":{"type":"integer"},"processed_today":{"type":"integer"},"remaining_today":{"type":"integer"},"usage_pct":{"type":"integer"}},"required":["id","gowa_id","label","state","daily_limit","processed_today","remaining_today","usage_pct"]}},"daily_history":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","example":"05 Nov"},"sent":{"type":"integer"},"failed":{"type":"integer"}},"required":["date","sent","failed"]},"description":"7 hari terakhir."}},"required":["plan","today","devices","daily_history"]},"FonnteSuccess":{"type":"object","properties":{"status":{"type":"boolean","const":true},"detail":{"type":"string","example":"success! message in queue"},"id":{"type":"array","items":{"type":"string"},"description":"ID pesan WartaHub, satu per target."},"process":{"type":"string","example":"pending"},"requestid":{"type":"integer"},"target":{"type":"array","items":{"type":"string"},"description":"Nomor ternormalisasi."}},"required":["status","detail","id","process","requestid","target"]},"FonnteFailure":{"type":"object","properties":{"status":{"type":"boolean","const":false},"reason":{"type":"string","description":"`token invalid`, `tenant suspended`, `target invalid: …` (nomor tujuan salah), `parameter tidak didukung WartaHub: …`, `Kuota pesan paket …`, dst."},"requestid":{"type":"integer"}},"required":["status","reason","requestid"]}}}}