API: Persediaan, Pengesahan & Ujian Pertama

REST API membolehkan sistem anda membaca data atau menjalankan tindakan yang disokong tanpa mengendalikan UI secara manual. Mulakan dengan permintaan baca sahaja.

Persediaan

1. Buka Settings → Developers dan semak API key serta akses yang dibenarkan.
2. Simpan key pada server atau secret store. Jangan masukkan key sebenar dalam dokumentasi, kod frontend atau log awam.
3. Gunakan base URL aplikasi: https://nakwasap.my/api/v1.
4. Hantar header X-API-Key: YOUR_API_KEY. Untuk badan JSON, tambah Content-Type: application/json.
5. Mulakan dengan GET instances untuk mengenal pasti ID dan status sambungan sebelum menggunakan endpoint penghantaran.

Permintaan pertama

curl --request GET 'https://nakwasap.my/api/v1/instances' \
  --header 'X-API-Key: YOUR_API_KEY'

Gantikan YOUR_API_KEY secara setempat. Jangan hantar placeholder sebagai kelayakan sebenar. Rujuk senarai instance yang dipulangkan; ID nombor bukan nombor telefon.

Membaca hasil

Respons API berbentuk JSON. Semak status HTTP dan kandungan respons. Struktur khusus boleh berbeza mengikut endpoint, contohnya senarai contact menggunakan contacts, total, page dan limit. Jangan anggap semua endpoint mempunyai pembungkus data yang sama.

Ralat dan retry

• 401/403: semak key dan permission. Jangan mengulang tanpa membetulkan akses.
• 400 atau ralat validasi: semak medan wajib, jenis nilai dan format telefon.
• 429: perlahankan permintaan; ikut header had/masa menunggu jika dipulangkan.
• 5xx atau timeout: catat masa serta rujukan permintaan. Bagi penghantaran mesej, semak status dahulu sebelum retry supaya tidak menghantar dua kali.

Header rate-limit yang mungkin dipaparkan termasuk X-RateLimit-Limit, X-RateLimit-Remaining dan X-RateLimit-Reset. Gunakan nilai respons sebenar; jangan menetapkan had rekaan dalam integrasi.

Semakan sebelum operasi

Uji pengesahan, instance yang betul, pengendalian data kosong, pagination dan ralat. Contoh payload dalam dokumentasi menggunakan data contoh; sesuaikan kepada medan serta versi API yang digunakan. API dan AI Assistant (MCP) ialah dua cara integrasi yang berlainan.

Kawalan Settings > Developers

Rujukan setiap butang dan medan

Butang / medan	Fungsi dan cara penggunaan
Create New Key	Buka borang Key Name untuk mengenali kegunaan kunci. Create menghasilkan credential sebenar; gunakan hanya apabila sambungan memang diperlukan.
Key Name	Nama dalaman seperti integrasi CRM; jangan letakkan rahsia dalam nama.
Cancel / Close	Tutup borang tanpa menghasilkan kunci.
Instance Status / Refresh	Semak semula keadaan sambungan peranti sebelum request API.
API Keys: Name / Token / Created / Last Used	Kenal pasti kegunaan, tarikh penciptaan dan penggunaan terakhir. Token ialah credential dan tidak patut dimasukkan ke screenshot atau kod frontend.
Access / Edit	Semak dan tetapkan skop kebenaran kunci mengikut keperluan integrasi. Jangan luaskan akses hanya untuk memudahkan ujian.
Read messages	Kebenaran membaca mesej; aktifkan hanya jika aplikasi penerima memang memerlukannya.
Open Integrations	Buka tetapan sambungan AI Assistant seperti yang dirujuk pada halaman.
Copy JSON	Salin spesifikasi rujukan API; bukan butang menjalankan request.
Management	Rujukan senarai instance, QR dan kumpulan.
Messaging	Rujukan endpoint penghantaran mesej dan media.
WABA	Templat Meta, tetingkap perbualan dan status akaun.
Data	Rujukan Contacts dan Chats dengan pagination.
Full Spec	Spesifikasi penuh, parameter, keperluan dan bentuk respons.

Urutan integrasi

Tentukan operasi yang diperlukan, semak skop akses, baca endpoint dalam tab yang sesuai dan simpan kunci di bahagian pelayan aplikasi. Header authentication ialah Authorization: Bearer <API_KEY>; gantikan placeholder hanya dalam konfigurasi persekitaran sendiri. Mula dengan permintaan baca sahaja yang dibenarkan sebelum sebarang operasi penghantaran.

Bezakan request GET untuk membaca data daripada POST yang boleh menghantar mesej atau mengemas kini rekod. Jangan menjalankan contoh penghantaran dengan nombor pelanggan sebenar. Tutorial ini menerangkan API tanpa mencipta kunci atau menjalankan request.

Screenshot rujukan menu

Padankan nama butang pada gambar dengan penerangan di atas. Maklumat sensitif tidak ditunjukkan dalam screenshot panduan.