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://tanyakan.ai/api/v1

Base URL otomatis mengikuti domain yang Anda akses.

Autentikasi

Sertakan API key sebagai Bearer token di tiap permintaan:

Authorization: Bearer tk_live_xxxxx

Buat & 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

GET/api/v1/conversationsconversations:read

Daftar percakapan. Mendukung filter status & paginasi cursor.

curl https://tanyakan.ai/api/v1/conversations?status=HUMAN \
  -H "Authorization: Bearer tk_live_xxxxx"

GET/api/v1/conversations/:idconversations:read

Detail satu percakapan beserta pesan terakhirnya.

curl https://tanyakan.ai/api/v1/conversations/{id} \
  -H "Authorization: Bearer tk_live_xxxxx"

POST/api/v1/conversations/:id/messagesmessages:send

Kirim pesan ke percakapan (atas nama agen / sistem).

curl -X POST https://tanyakan.ai/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" }'

POST/api/v1/conversations/:id/handoffconversations:write

Alihkan percakapan ke agen manusia (status → HUMAN).

curl -X POST https://tanyakan.ai/api/v1/conversations/{id}/handoff \
  -H "Authorization: Bearer tk_live_xxxxx"

Produk

GET/api/v1/productsproducts:read

Daftar produk katalog tenant.

curl https://tanyakan.ai/api/v1/products \
  -H "Authorization: Bearer tk_live_xxxxx"

POST/api/v1/productsproducts:write

Buat produk baru di katalog.

curl -X POST https://tanyakan.ai/api/v1/products \
  -H "Authorization: Bearer tk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Kemeja Batik", "price": 245000, "stock": 20 }'

PATCH/api/v1/products/:idproducts:write

Perbarui produk (harga, stok, dll) — sinkron dari sistem Anda.

curl -X PATCH https://tanyakan.ai/api/v1/products/{id} \
  -H "Authorization: Bearer tk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "stock": 5 }'

Credit & Pemakaian

GET/api/v1/creditscredits:read

Saldo credit tenant (allowance, rollover, top-up).

curl https://tanyakan.ai/api/v1/credits \
  -H "Authorization: Bearer tk_live_xxxxx"

GET/api/v1/usageusage:read

Ringkasan pemakaian credit & pesan dalam rentang waktu.

curl https://tanyakan.ai/api/v1/usage?days=30 \
  -H "Authorization: Bearer tk_live_xxxxx"

Utilitas

GET/api/v1/ping— (tanpa scope)

Cek koneksi & validitas API key.

curl https://tanyakan.ai/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.