@extends('root') @section('title', 'API Documentation') @section('content')
@include('components.breadcrumb', [ 'title' => 'API Documentation', 'links' => [ ['url' => route('dashboard'), 'label' => 'Dashboard'], ], 'current' => 'API Documentation' ])

WABA SaaS API Documentation

Dokumentasi lengkap API untuk Reseller dan Client. Format RESTful dengan autentikasi API Key & Server Key.

@if($showClientApi ?? true)
Client API
Dokumentasi untuk Client
  • Send Message
  • Dedicated Number
  • Balance & Usage
Lihat Dokumentasi
@endif @if($showResellerApi ?? true)
Reseller API
Dokumentasi untuk Reseller
  • Margin Management
  • Client Management
  • Revenue Report
Lihat Dokumentasi
@endif @if($showAdminApi ?? false)
Admin API
Dokumentasi untuk Admin
  • Token Management
  • Approve/Reject
  • Inbox & Webhook
Lihat Dokumentasi
@endif
Dokumentasi Umum
API Overview

WABA SaaS API menyediakan akses programmatik untuk mengelola WhatsApp Business Account (WABA) melalui Meta Graph API. API ini dirancang dengan arsitektur RESTful, menggunakan JSON untuk request dan response.

Fitur Utama
Reseller
  • Kelola Client (Create, Update, Delete)
  • Reset API Key & Server Key
  • Manage Template (CRUD + Sync Meta)
  • Test Send Template
  • Manage Pricing & Markup
  • Monitor Usage & Balance
Client
  • Send Template Message
  • Send Campaign
  • List Available Templates
  • Test Send Template
  • Check Balance & Usage
  • Topup Balance
  • Manage IP Whitelist
  • Regenerate API Key
Arsitektur API
  • Base URL: {{ url('/api') }}
  • Protocol: HTTPS (wajib)
  • Format: JSON
  • Method: RESTful (GET, POST, PUT, DELETE)
  • Stateless: Setiap request independen
Use Cases
Use Case Role Endpoint
Buat client baru Reseller POST /api/v1/clients
Kirim pesan template Client POST /api/v1/message/send
Cek saldo Client GET /api/v1/balance
Buat template baru Reseller/Client POST /api/v1/templates
Topup saldo Client POST /api/v1/topup/create
Authentication
Semua request API memerlukan autentikasi menggunakan API Key dan Server Key yang dikirim melalui HTTP Header.
Tipe Autentikasi

Sistem menggunakan dual-key authentication:

  • API Key: Identifier unik untuk client/reseller
  • Server Key: Secret key untuk validasi keamanan
Cara Pengiriman

Kedua key harus dikirim melalui HTTP Header pada setiap request:

Authorization: Bearer {server_key}
X-Api-Key: {api_key}
Content-Type: application/json
Contoh Request
curl -X POST {{ url('/api/v1/balance') }} \
  -H "Authorization: Bearer 9d2c8f1a-4b5e-4c6d-8e9f-0a1b2c3d4e5f|a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "X-Api-Key: 4f8b9c2d-1e3f-4a5b-6c7d-8e9f0a1b2c3d" \
  -H "Content-Type: application/json"
Keamanan
Penting!
  • API Key dan Server Key tidak memiliki masa aktif tetapi harus di-rotate secara berkala
  • Jangan pernah membagikan Server Key kepada pihak ketiga
  • Simpan key di environment variable atau secret manager
  • Gunakan HTTPS untuk semua request
  • Monitor aktivitas API key secara berkala
Regenerate Key

Untuk regenerate API Key (Client):

POST {{ url('/api/v1/api-key/regenerate') }}
Headers:
  Authorization: Bearer {server_key}
  X-Api-Key: {api_key}

Response:
{
  "api_key": "new_generated_api_key"
}
Reseller API Endpoints
Create Client

Method: POST

Path: /api/v1/clients

Deskripsi: Reseller membuat client baru dan mengikat ke akun reseller.

Headers:
Authorization: Bearer {server_key}
X-Api-Key: {api_key}
Content-Type: application/json
Body (JSON):
{
  "name": "PT Maju Jaya",
  "email": "client@example.com",
  "password": "SandiKuat123",
  "package": "shared",
  "rate_limit_per_minute": 120
}
Response Success (200):
{
  "meta": {
    "code": 200,
    "status": "success",
    "message": "Client berhasil dibuat melalui API"
  },
  "data": {
    "id": 45,
    "name": "PT Maju Jaya",
    "email": "client@example.com",
    "reseller_id": 7,
    "balance": "0.0000",
    "rate_limit_per_minute": 120,
    "is_active": true
  }
}
Response Error (401):
{
  "meta": {
    "code": 401,
    "status": "error",
    "message": "API Key atau Server Key tidak valid"
  },
  "data": null
}
Create Template

Method: POST

Path: /api/v1/templates

Deskripsi: Buat template baru dan kirim ke Meta untuk approval.

Body (JSON):
{
  "waba_pool_id": 3,
  "name": "Order Confirm",
  "category": "utility",
  "language": "id",
  "header_type": "text",
  "header_text": "Judul {{1}}",
  "body_text": "Halo {{1}}, pesanan {{2}} telah dikirim.",
  "footer_text": "Terima kasih",
  "buttons": [
    {
      "type": "URL",
      "text": "Lihat Pesanan",
      "url": "https://domain.com/order/{{1}}"
    }
  ]
}
Response Success:
{
  "meta": {
    "code": 200,
    "status": "success",
    "message": "Template berhasil dibuat dan dikirim ke Meta untuk approval"
  },
  "data": {
    "template": {
      "id": 123,
      "name": "7_reseller_order_confirm",
      "status": "pending"
    },
    "meta": {
      "id": "12345"
    }
  }
}
Test Send Template

Method: POST

Path: /api/reseller/templates/{id}/test-send

Deskripsi: Kirim test template ke nomor WhatsApp tertentu.

URL Parameters:
  • id - ID template (integer)
Body (JSON):
{
  "phone_number": "6281234567890",
  "header_params": ["Judul X"],
  "body_params": ["Budi", "INV-123"]
}
Ringkasan Endpoint Reseller
Method Endpoint Deskripsi Auth
POST /api/v1/clients Buat client baru API Key + Server Key
POST /api/v1/templates Buat template & kirim ke Meta API Key + Server Key
POST /api/v1/templates/sync-status Sync status template dari Meta API Key + Server Key
GET /api/v1/templates List template API Key + Server Key
POST /api/reseller/templates/{id}/test-send Test send template API Key + Server Key
Client API Endpoints
Send Template Message

Method: POST

Path: /api/v1/message/send

Deskripsi: Kirim pesan template ke nomor WhatsApp. Pengiriman dilakukan secara sinkron (tanpa queue).

Body (JSON):
{
  "id_template": 12,
  "to": "628111223344",
  "parameters": ["Budi", "INV-123"]
}
Response Success (200):
{
  "status": "success",
  "message_id": "550e8400-e29b-41d4-a716-446655440000",
  "price": 376,
  "template": "client_12_order_confirm",
  "type": "Utility"
}
Response Error (403):
{
  "status": "error",
  "message": "Template tidak tersedia untuk client ini"
}
Get Balance

Method: GET

Path: /api/v1/balance

Deskripsi: Cek saldo akun client.

Response Success:
{
  "balance": 12500.0
}
List Templates

Method: GET

Path: /api/v1/templates

Deskripsi: Daftar template yang tersedia untuk client (template sendiri, reseller, atau admin).

Response Success:
{
  "data": [
    {
      "id": 12,
      "name": "client_12_order_confirm",
      "category": "utility",
      "status": "approved",
      "language": "id",
      "body": "Halo {{1}}, pesanan {{2}} telah dikirim."
    }
  ]
}
Create Topup

Method: POST

Path: /api/v1/topup/create

Deskripsi: Buat transaksi topup saldo melalui Midtrans.

Body (JSON):
{
  "amount": 50000
}
Response Success:
{
  "redirect_url": "https://app.midtrans.com/snap/v2/vtweb/...",
  "token": "abc123..."
}
Ringkasan Endpoint Client
Method Endpoint Deskripsi Auth
POST /api/v1/message/send Kirim template message API Key + Server Key
GET /api/v1/templates List template tersedia API Key + Server Key
POST /api/v1/templates Buat template baru API Key + Server Key
GET /api/v1/balance Cek saldo API Key + Server Key
POST /api/v1/topup/create Buat transaksi topup API Key + Server Key
GET /api/v1/usage Cek usage pesan API Key + Server Key
POST /api/v1/api-key/regenerate Regenerate API key API Key + Server Key
GET /api/v1/whitelist List IP whitelist API Key + Server Key
POST /api/v1/whitelist Tambah IP whitelist API Key + Server Key
DELETE /api/v1/whitelist/{id} Hapus IP whitelist API Key + Server Key
Error Codes
Code HTTP Status Message Penjelasan
1001 401 Invalid API Key API Key tidak valid atau tidak ditemukan
1002 401 Invalid Server Key Server Key salah atau tidak cocok dengan API Key
1003 401 Unauthorized Kombinasi API Key dan Server Key tidak valid
2001 400 Missing Parameter Parameter wajib tidak diisi dalam request
2002 400 Invalid Parameter Format atau nilai parameter tidak valid
2101 400 Language Invalid Kode bahasa tidak didukung (hanya: id, en_US, en, ar, hi)
2102 400 Components Invalid Struktur komponen template tidak sesuai standar Meta
2201 409 Duplicate Template Nama template sudah ada di akun WABA
3001 403 Template Not Allowed Client tidak memiliki akses ke template ini
3002 403 Client Inactive Akun client atau reseller tidak aktif
4004 404 Not Found Resource (template, client, dll) tidak ditemukan
4290 429 Rate Limit Exceeded Melebihi batas request per menit
5001 500 Meta API Error Kesalahan dari Meta Graph API (template/message)
5002 502 Upstream Error Kesalahan gateway atau koneksi ke Meta
5003 500 Internal Error Kesalahan internal server yang tidak terduga
Best Practices & Guidelines
Rate Limit & Throttling
  • Setiap client memiliki rate_limit_per_minute yang dapat dikonfigurasi
  • Default rate limit: 60 request per menit
  • Jika melebihi limit, akan mendapat HTTP 429 (Too Many Requests)
  • Implementasikan exponential backoff untuk retry
  • Contoh retry: 200ms, 400ms, 800ms, 1600ms (max 5x)
@if(isset($userRole) && $userRole === 'client')
Panduan Integrasi e-Billing
Badge: Integration Guide
Panduan ini khusus untuk Client yang ingin mengintegrasikan notifikasi MeeChat dengan sistem e-Billing.
Langkah-langkah Integrasi
1
Ambil API Key Meechat

Dapatkan kunci akses untuk menghubungkan akun Anda.

  1. Masuk ke aplikasi Meechat.
  2. Buka menu API Settings.
  3. Copy API Key yang tersedia.
2
Masuk ke Menu Data WAGW

Akses pengaturan integrasi di e-Billing.

  1. Masuk ke Dashboard e-Billing.
  2. Navigasi ke menu: Status WAGW → Data WAGW Pihak Ketiga.
3
Tambah Integrasi Meechat

Konfigurasikan provider Meechat di e-Billing.

  1. Klik tombol Tambah Data.
  2. Pilih Provider: meechat.id.
  3. Paste API Key yang telah disalin sebelumnya.
  4. Klik Simpan.
4
Ambil Nama Template Meechat

Pilih template pesan yang akan digunakan.

  1. Masuk kembali ke menu Templates di aplikasi Meechat.
  2. Salin nama template yang ingin digunakan.
  3. *Penting: Nama template harus sama persis (case-sensitive).
5
Hubungkan Template ke Notifikasi e-Billing

Finalisasi pengaturan notifikasi.

  1. Masuk ke e-Billing menu: Kelola Data → Data Notifikasi.
  2. Edit notifikasi yang ingin diintegrasikan.
  3. Paste nama template ke field nama_template.
  4. Klik Simpan.
Video Panduan
Tonton di YouTube
Catatan Penting
  • Rahasia: API Key bersifat rahasia. Jangan berikan kepada pihak yang tidak berkepentingan.
  • Case Sensitive: Nama template harus sama persis besar/kecil hurufnya dengan yang ada di Meechat.
  • Status Aktif: Pastikan integrasi sudah berstatus aktif sebelum melakukan pengujian notifikasi.
Butuh Bantuan?

Jika Anda mengalami kendala saat integrasi, hubungi tim support kami.

Hubungi Support
@endif
Retry Strategy

Retry untuk error berikut:

  • HTTP 429 (Rate Limit) - tunggu beberapa detik
  • HTTP 500/502/503 (Server Error) - retry dengan backoff
  • HTTP 504 (Gateway Timeout) - retry dengan timeout lebih lama

Jangan retry untuk:

  • HTTP 400 (Bad Request) - perbaiki request terlebih dahulu
  • HTTP 401/403 (Unauthorized/Forbidden) - perbaiki autentikasi
  • HTTP 404 (Not Found) - resource tidak ada
Kategori Pesan WhatsApp
Kategori Deskripsi Use Case
UTILITY Pesan transaksional Konfirmasi order, invoice, notifikasi pengiriman
OTP One-Time Password Verifikasi login, reset password
MARKETING Pesan promosi Promo produk, newsletter, campaign
SERVICE Pesan layanan Update akun, notifikasi sistem
Caching Template
  • Cache daftar template untuk mengurangi request ke API
  • Invalidate cache saat template baru dibuat atau status berubah
  • Cache struktur komponen template untuk validasi lokal
  • TTL cache disarankan: 5-15 menit
Debugging Request ke Meta
  • Log payload request sebelum dikirim ke Meta (tanpa credentials)
  • Log response dari Meta untuk troubleshooting
  • Periksa field language (harus: id, en_US, en, ar, hi)
  • Validasi struktur components sesuai spesifikasi Meta
  • Pastikan nama template sudah snake_case lowercase
  • Gunakan Meta Graph API Explorer untuk testing manual
Tips Keamanan
Penting!
  • Jangan share Server Key: Server Key adalah rahasia, jangan pernah membagikannya
  • Rotate Key Berkala: Regenerate API Key dan Server Key setiap 3-6 bulan
  • Gunakan HTTPS: Selalu gunakan HTTPS untuk semua request API
  • Validasi IP Whitelist: Aktifkan IP whitelist untuk keamanan tambahan
  • Monitor Aktivitas: Pantau log aktivitas API key secara berkala
  • Environment Variables: Simpan key di environment variable, jangan hardcode
  • Validasi Webhook: Validasi signature webhook dari Meta/Midtrans
Template Payload Meta

Aturan penting untuk payload template:

  • language harus salah satu: id, en_US, en, ar, hi
  • name harus snake_case lowercase (contoh: client_12_order_confirm)
  • Komponen BODY wajib ada
  • Variabel template menggunakan format {{1}}, {{2}}, dst (harus berurutan)
  • Header TEXT maksimal 1 variabel
  • Header MEDIA memerlukan contoh URL media
  • Button URL harus menggunakan https://
  • Button PHONE_NUMBER harus format internasional (+628xx)
Billing & Pricing
  • Harga final = base price (sesuai kategori & paket) + markup reseller
  • Paket: shared atau dedicated
  • Kategori: Marketing, Utility, OTP, Service
  • Pastikan saldo cukup sebelum mengirim pesan
  • Saldo akan terpotong otomatis setelah pesan berhasil dikirim
  • Jika saldo tidak cukup, request akan gagal dengan error "Saldo tidak mencukupi"
@endsection @push('scripts') @endpush