ZS

ZS WhatsApp Gateway

WhatsApp Gateway untuk developer & bisnis

Dokumentasi API

ZS WhatsApp Gateway menyediakan REST API untuk mengirim pesan WhatsApp lewat nomor Anda sendiri. Hubungkan instance, buat API key, lalu kirim pesan melalui endpoint sederhana.

Base URL

https://api.zs-whatsapp-gateway.fajarhidayat.dev

Prefix

/api/v1

Autentikasi

API memakai dua jenis kredensial tergantung endpoint:

  • JWT (pengguna dashboard)

    Header Authorization: Bearer <token>. Token didapat dari endpoint login. Endpoint admin butuh JWT dengan role = admin.

  • API key (akses gateway)

    Header x-api-key: <key> (atau Authorization: Bearer <key>).

Login (dapatkan JWT) 
curl -X POST https://api.zs-whatsapp-gateway.fajarhidayat.dev/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@zsgateway.local","password":"admin123"}'

Format Respons

Semua respons memakai amplop yang konsisten.

Sukses 
{
  "success": true,
  "message": "OK",
  "data": { }
}
Paginated 
{
  "success": true,
  "message": "OK",
  "data": [],
  "pagination": { "page": 1, "limit": 20, "total": 0, "totalPages": 1 }
}
Error 
{
  "success": false,
  "message": "Validation failed",
  "errors": []
}

Rate Limit

Endpoint pengiriman pesan (/gateway/send dan /gateway/send-media) dibatasi per API key/IP. Jika melebihi batas, server membalas 429 dengan { "success": false, "message": "Rate limit exceeded" }.

Auth

Registrasi, login, verifikasi, dan profil pengguna dashboard.

POST /api/v1/auth/register Publik

Buat akun (belum terverifikasi), kirim tautan verifikasi email. Body: name, email, phone, password, passwordConfirmation.

POST /api/v1/auth/login Publik

Login (akun harus terverifikasi), balas user + JWT. Body: email, password.

POST /api/v1/auth/verify-email Publik

Verifikasi akun via token tautan. Body: token.

POST /api/v1/auth/resend-verification Publik

Kirim ulang tautan verifikasi (enumeration-safe). Body: email.

POST /api/v1/auth/reset-methods Publik

Daftar kanal reset yang tersedia. Body: email -> { methods, whatsappAvailable, maskedEmail, maskedPhone }.

POST /api/v1/auth/forgot-password Publik

Kirim tautan reset via email atau whatsapp. Body: email, channel.

POST /api/v1/auth/reset-password Publik

Set password baru via token. Body: token, password, passwordConfirmation.

GET /api/v1/auth/me JWT

Profil pengguna saat ini.

PATCH /api/v1/auth/me JWT

Perbarui profil. Body: name?, phone?.

POST /api/v1/auth/change-password JWT

Ganti password. Body: currentPassword, newPassword.

Alur lupa password (berbasis tautan)

  1. reset-methods mengembalikan kanal yang valid. WhatsApp tersedia hanya jika nomor terdaftar sebagai WA valid.
  2. forgot-password mengirim tautan via kanal terpilih; jatuh ke email bila WA tidak tersedia. Respons selalu sukses (enumeration-safe).
  3. reset-password menyetel password baru. Tautan menuju {APP_URL}/reset-password?token=...

Instances

Kelola koneksi WhatsApp (semua butuh JWT).

POST /api/v1/instances JWT

Buat instance. Body: name.

GET /api/v1/instances JWT

Daftar (paginated). Query: page, limit, status, search.

GET /api/v1/instances/:id JWT

Detail + status live + QR.

PATCH /api/v1/instances/:id JWT

Ganti nama. Body: name.

DELETE /api/v1/instances/:id JWT

Hapus + wipe session.

POST /api/v1/instances/:id/connect JWT

Mulai sesi Baileys. Body: method (qr|code), phoneNumber (wajib bila code).

POST /api/v1/instances/:id/reconnect JWT

Restart sesi. Body: method (qr|code), phoneNumber (wajib bila code).

GET /api/v1/instances/:id/qr JWT

Ambil QR (data URL) + status.

POST /api/v1/instances/:id/pairing-code JWT

Ambil pairing code 8 digit (poll sampai muncul). Body: phoneNumber?.

POST /api/v1/instances/:id/logout JWT

Logout + hapus kredensial.

Metode koneksi: qr (poll GET /qr) atau code (poll POST /pairing-code). Status instance: disconnected | connecting | qr_required | pairing_required | connected.

Buat instance 
curl -X POST https://api.zs-whatsapp-gateway.fajarhidayat.dev/api/v1/instances \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{"name":"My Instance"}'

API Keys

Kelola kunci akses gateway (butuh JWT). Kunci mentah hanya ditampilkan sekali.

POST /api/v1/api-keys JWT

Buat key (raw ditampilkan sekali). Body: name, instanceId?.

GET /api/v1/api-keys JWT

Daftar key. Query: page, limit, instanceId.

POST /api/v1/api-keys/:id/regenerate JWT

Kunci baru, record sama.

POST /api/v1/api-keys/:id/revoke JWT

Cabut key.

DELETE /api/v1/api-keys/:id JWT

Hapus key.

Gateway

Endpoint pengiriman pesan, diautentikasi dengan API key.

GET /api/v1/gateway/status API key

Status koneksi. Query: instanceId?.

POST /api/v1/gateway/send API key

Kirim teks (rate-limited). Body: to, message, instanceId?.

POST /api/v1/gateway/send-media API key

Kirim media (multipart). Field: to, mediaType, caption?, instanceId?, file.

mediaType = image | video | audio | document. Jika API key terikat ke sebuah instance, instanceId opsional dan binding diberlakukan.

Kirim teks 
curl -X POST https://api.zs-whatsapp-gateway.fajarhidayat.dev/api/v1/gateway/send \
  -H "x-api-key: zs_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"to":"6281234567890","message":"Hello"}'
Kirim media 
curl -X POST https://api.zs-whatsapp-gateway.fajarhidayat.dev/api/v1/gateway/send-media \
  -H "x-api-key: zs_live_xxxxx" \
  -F "to=6281234567890" \
  -F "mediaType=image" \
  -F "caption=Hi" \
  -F "file=@./photo.jpg"

Logs

Riwayat pesan & event (butuh JWT).

GET /api/v1/logs JWT

Daftar log. Query: page, limit, instanceId, status, direction, search, from, to.

GET /api/v1/logs/export JWT

Ekspor log (download). Query: filter + format=csv|json.

GET /api/v1/logs/:id JWT

Detail satu log.

status = pending | sent | delivered | failed. direction = inbound | outbound.

Ekspor log ke CSV 
curl "https://api.zs-whatsapp-gateway.fajarhidayat.dev/api/v1/logs/export?format=csv" \
  -H "Authorization: Bearer <JWT>" -o logs.csv

Dashboard

Metrik operasional (butuh JWT).

GET /api/v1/dashboard/stats JWT

Metrik operasional.

GET /api/v1/dashboard/recent-activity JWT

10 event log terbaru.

Plans

Paket langganan. Daftar paket aktif bersifat publik (halaman pricing).

GET /api/v1/plans Publik

Daftar paket aktif (untuk halaman pricing FE).

GET /api/v1/plans/all Admin

Semua paket termasuk nonaktif.

POST /api/v1/plans Admin

Buat paket. Body: code, name, price, interval, maxInstances, maxApiKeys, maxMonthlyCredits, features[].

PATCH /api/v1/plans/:id Admin

Update paket.

DELETE /api/v1/plans/:id Admin

Hapus (atau nonaktifkan bila masih ada langganan).

features berupa array terstruktur [{ icon, label, included }] (bukan HTML). Kuota (maxInstances/maxApiKeys/maxMonthlyCredits) di-enforce server; -1 = unlimited.

Subscriptions

Langganan pengguna (butuh JWT).

GET /api/v1/subscriptions/active JWT

Langganan aktif (fallback ke free bila belum punya).

GET /api/v1/subscriptions/history JWT

Riwayat langganan.

POST /api/v1/subscriptions/subscribe JWT

Mulai langganan. Body: planCode. Gratis -> aktif; berbayar -> balas payment (QRIS).

POST /api/v1/subscriptions/:id/cancel JWT

Batalkan langganan.

Alur berbayar: subscribe -> type=payment_required + objek payment (QRIS) -> user bayar -> webhook Qrispy -> langganan otomatis aktif.

Payments (QRIS)

Pembayaran QRIS via Qrispy (butuh JWT, kecuali webhook).

POST /api/v1/payments/generate JWT

Buat QRIS baru. Body: amount, paymentReference?, returnUrl?.

GET /api/v1/payments JWT

List pembayaran lokal milik user. Query: page, limit, status.

GET /api/v1/payments/:qrisId/status JWT

Cek status (sinkron dari Qrispy).

POST /api/v1/payments/:qrisId/cancel JWT

Batalkan QRIS pending.

GET /api/v1/payments/transactions JWT

Proxy list transaksi dari Qrispy.

GET /api/v1/payments/balance Admin

Saldo merchant Qrispy.

POST /api/v1/payments/webhook Publik

Webhook payment.received (diverifikasi X-Qrispy-Signature).

amount integer IDR (min 100). Status: pending | paid | expired | cancelled | failed. Response generate berisi qrImageBase64 (data URL siap tampil) + expiresInSeconds.

Admin

Butuh JWT dengan role = admin.

GET /api/v1/admin/stats Admin

Statistik seluruh platform.

GET /api/v1/admin/users Admin

Daftar user. Query: page, limit, search.

PATCH /api/v1/admin/users/:id/active Admin

Aktifkan/nonaktifkan user. Body: isActive.

PATCH /api/v1/admin/users/:id/role Admin

Ubah role. Body: role (user|admin).

GET /api/v1/admin/audit-logs Admin

Jejak audit. Query: page, limit, action, userId.

Config

Konfigurasi runtime publik untuk FE (1x hit).

GET /api/v1/config Publik

Branding app, urls, storage provider, Google client id, OTP expiry, dan batas upload per tipe.

App Settings (Master Aplikasi)

Branding & identitas aplikasi.

GET /api/v1/app-settings/branding Publik

Branding publik (nama app, tagline, logo, ikon, warna).

GET /api/v1/app-settings Admin

Seluruh pengaturan aplikasi.

PATCH /api/v1/app-settings Admin

Update master aplikasi. Body: appName?, tagline?, description?, primaryColor?, dll.

POST /api/v1/app-settings/assets Admin

Upload aset branding (multipart: logo?, icon?, favicon?).

Aset yang diupload disajikan di /uploads/.... logoUrl/iconUrl/faviconUrl dibangun otomatis dari API_BASE_URL.

System

GET /api/v1/health Publik

Liveness + uptime.

GET / Publik

Nama API + versi.

GET /uploads/* Publik

Berkas upload lokal (logo/ikon branding).

Siap berintegrasi?

Buat akun dan kirim pesan pertama Anda.

Mulai Gratis