URL Dasar
Semua permintaan API harus dikirim ke:
Arsitektur API
CSKU AI API Publik mengikuti konvensi RESTful dan menyediakan endpoint untuk:
- Pemeriksaan Kesehatan - Memantau status dan versi sistem
- Pengelolaan Pesan - Mengirim dan mengambil pesan
- Pengelolaan Catatan - Mengirim catatan internal
- Pengelolaan Percakapan - Mengelola percakapan dan intervensi manusia
Content-Type
Semua permintaan POST harus menyertakan:
Content-Type: application/json
Autentikasi
Sertakan header autentikasi (lihat Autentikasi):
Metode 1: Header Terpisah
Business: your_biz_id
Secret: your_secret_key
Authorization: Bearer {base64_encoded_credentials}
Respons Sukses
Respons sukses mengikuti struktur ini:
{
"status": 1,
"message": "Sukses",
"data": { ... }
}
Respons Error
Error mengikuti format yang konsisten:
{
"status": 0,
"rc": 400,
"error_msg": "Deskripsi pesan error"
}
Selalu periksa field status. Nilai 1 menunjukkan sukses, sedangkan 0 menunjukkan error.
Kode Status HTTP
| Kode | Deskripsi |
|---|
| 200 | Sukses - Permintaan berhasil diselesaikan |
| 400 | Permintaan Buruk - Parameter atau data tidak valid |
| 401 | Tidak Terotorisasi - Autentikasi tidak valid atau tidak ada |
| 403 | Terlarang - Izin tidak mencukupi |
| 404 | Tidak Ditemukan - Sumber daya tidak ditemukan |
| 429 | Terlalu Banyak Permintaan - Batas rate terlampaui |
| 500 | Kesalahan Server Internal - Error sisi server |
Versi API
Versi API saat ini: v1.3
Endpoint versi:
API mendukung tipe media berikut:
| Tipe | Deskripsi | Contoh Tipe MIME |
|---|
| image | File gambar | image/jpeg, image/png, image/gif |
| video | File video | video/mp4, video/avi |
| audio | File audio | audio/mp3, audio/wav |
| document | File dokumen | application/pdf, application/msword |
Paginasi
Saat ini, pengambilan pesan tidak mendukung paginasi. Semua pesan dalam percakapan dikembalikan dalam satu permintaan.
Versi mendatang akan menyertakan dukungan paginasi untuk percakapan yang besar.
Pembatasan Rate
API menerapkan pembatasan rate:
| Tipe Permintaan | Batas |
|---|
| Terautentikasi | 100 permintaan/menit |
| Tidak Terautentikasi | 10 permintaan/menit |
Webhooks
Untuk notifikasi real-time, konfigurasikan webhooks di pengaturan bisnis Anda:
Event yang Didukung:
message.incoming - Pesan baru diterimamessage.sent - Pesan berhasil dikirimconversation.assigned - Percakapan ditugaskan ke manusia
Konfigurasi webhook dilakukan melalui dashboard, bukan melalui API.
Penanganan Error
Memeriksa Error
Selalu periksa field status dalam respons:
const response = await fetch(...);
const data = await response.json();
if (data.status === 0) {
console.error('Error:', data.error_msg);
// Tangani error berdasarkan rc (kode respons)
switch(data.rc) {
case 401:
// Tidak terotorisasi - periksa kredensial
break;
case 400:
// Permintaan buruk - periksa parameter
break;
case 429:
// Rate terbatas - terapkan backoff
break;
default:
// Error lainnya
}
}
Kode Error Umum
| Kode | Deskripsi | Tindakan |
|---|
| 400 | Permintaan Buruk | Periksa parameter permintaan |
| 401 | Tidak Terotorisasi | Verifikasi kredensial |
| 403 | Terlarang | Periksa izin |
| 404 | Tidak Ditemukan | Verifikasi sumber daya ada |
| 429 | Terlalu Banyak Permintaan | Terapkan backoff dan coba lagi |
| 500 | Error Internal | Hubungi dukungan jika berlanjut |
Praktik Terbaik
- Selalu periksa field
status sebelum memproses data respons
- Terapkan logika retry untuk error 5xx dengan exponential backoff
- Gunakan timeout yang sesuai untuk permintaan API
- Validasi data input sebelum membuat permintaan
- Tangani batas rate dengan baik menggunakan strategi backoff
- Jaga keamanan kredensial - jangan pernah ekspos di kode sisi klien
Dukungan
Untuk dukungan teknis atau pertanyaan:
