API Reference
REST API v1
Integrasikan layanan kami ke CRM, ERP, atau sistem internal Anda. Semua endpoint memakai autentikasi API key dan dibatasi oleh scope.
Base URL
https://staging.sugeh.id/api/v1Base URL otomatis mengikuti domain yang Anda akses.
Autentikasi
Sertakan API key sebagai Bearer token di tiap permintaan:
Authorization: Bearer tk_live_xxxxxBuat & kelola key di Dashboard → API Keys.
Header yang Dianjurkan
Content-Type: application/jsonWajib untuk request ber-body.Idempotency-Key: <uuid>Dianjurkan untuk POST — mencegah aksi terkirim ganda saat retry.Scope
Tiap API key punya kumpulan scope. Endpoint menolak key tanpa scope yang sesuai (403).
conversations:read | Baca daftar & detail percakapan |
conversations:write | Ubah percakapan (handoff, dll) |
messages:send | Kirim pesan ke percakapan |
products:read | Baca katalog produk |
products:write | Buat / ubah produk |
credits:read | Baca saldo credit |
usage:read | Baca laporan pemakaian |
admin:* | Akses penuh — beri hanya ke sistem terpercaya |
Percakapan
/api/v1/conversationsconversations:readDaftar percakapan. Mendukung filter status & paginasi cursor.
curl https://staging.sugeh.id/api/v1/conversations?status=HUMAN \ -H "Authorization: Bearer tk_live_xxxxx"
/api/v1/conversations/:idconversations:readDetail satu percakapan beserta pesan terakhirnya.
curl https://staging.sugeh.id/api/v1/conversations/{id} \
-H "Authorization: Bearer tk_live_xxxxx"/api/v1/conversations/:id/messagesmessages:sendKirim pesan ke percakapan (atas nama agen / sistem).
curl -X POST https://staging.sugeh.id/api/v1/conversations/{id}/messages \
-H "Authorization: Bearer tk_live_xxxxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{ "text": "Halo dari sistem kami", "as": "HUMAN_AGENT" }'/api/v1/conversations/:id/handoffconversations:writeAlihkan percakapan ke agen manusia (status → HUMAN).
curl -X POST https://staging.sugeh.id/api/v1/conversations/{id}/handoff \
-H "Authorization: Bearer tk_live_xxxxx"Produk
/api/v1/productsproducts:readDaftar produk katalog tenant.
curl https://staging.sugeh.id/api/v1/products \ -H "Authorization: Bearer tk_live_xxxxx"
/api/v1/productsproducts:writeBuat produk baru di katalog.
curl -X POST https://staging.sugeh.id/api/v1/products \
-H "Authorization: Bearer tk_live_xxxxx" \
-H "Content-Type: application/json" \
-d '{ "name": "Kemeja Batik", "price": 245000, "stock": 20 }'/api/v1/products/:idproducts:writePerbarui produk (harga, stok, dll) — sinkron dari sistem Anda.
curl -X PATCH https://staging.sugeh.id/api/v1/products/{id} \
-H "Authorization: Bearer tk_live_xxxxx" \
-H "Content-Type: application/json" \
-d '{ "stock": 5 }'Credit & Pemakaian
/api/v1/creditscredits:readSaldo credit tenant (allowance, rollover, top-up).
curl https://staging.sugeh.id/api/v1/credits \ -H "Authorization: Bearer tk_live_xxxxx"
/api/v1/usageusage:readRingkasan pemakaian credit & pesan dalam rentang waktu.
curl https://staging.sugeh.id/api/v1/usage?days=30 \ -H "Authorization: Bearer tk_live_xxxxx"
Utilitas
/api/v1/ping— (tanpa scope)Cek koneksi & validitas API key.
curl https://staging.sugeh.id/api/v1/ping \ -H "Authorization: Bearer tk_live_xxxxx"
Bentuk Respons
Semua respons berformat JSON dengan field ok.
// Sukses
{ "ok": true, "data": { ... } }
// Gagal
{ "ok": false, "error": { "code": "FORBIDDEN", "message": "..." } }Kode Error & Rate Limit
| HTTP | Kode | Arti |
|---|---|---|
| 400 | VALIDATION_ERROR | Input tidak valid — cek pesan error. |
| 401 | UNAUTHORIZED | API key tidak ada / tidak valid / sudah di-revoke. |
| 403 | FORBIDDEN | API key tidak punya scope yang dibutuhkan. |
| 404 | NOT_FOUND | Resource tidak ditemukan. |
| 429 | RATE_LIMITED | Melebihi batas rate limit key (default 60 rpm). |
| 500 | INTERNAL | Kesalahan server — coba lagi atau hubungi support. |
Rate limit default 60 permintaan/menit per key (dapat diatur saat membuat key). Melebihi batas → HTTP 429.