{"openapi":"3.1.0","info":{"title":"Tanyakan.ai API","version":"1.0.0","description":"API publik Tanyakan.ai untuk menyambungkan sistem Anda (CRM, ERP, toko online) ke percakapan pelanggan.\n\n**Autentikasi.** Sertakan kunci API pada tiap permintaan:\n`Authorization: Bearer tk_live_...`\nKunci dibuat di dashboard, menu Developer → API Keys. Tiap kunci wajib diberi minimal satu izin (scope).\n\n**Pengulangan aman.** Untuk POST/PATCH, sertakan `Idempotency-Key` berisi UUID. Bila permintaan yang sama dikirim ulang (mis. jaringan putus), hasil pertama dikembalikan — tindakannya tidak terjadi dua kali.\n\n**Batas laju.** 60 permintaan per menit per kunci. Saat terlampaui, balasannya 429 beserta header `Retry-After`.\n\n**Bentuk balasan.** Sukses selalu `{ \"ok\": true, \"data\": ... }`. Gagal selalu `{ \"ok\": false, \"error\": { \"code\", \"message\" } }`."},"servers":[{"url":"https://tanyakan.ai/api/v1","description":"Produksi"}],"security":[{"KunciApi":[]}],"tags":[{"name":"Percakapan","description":"Membaca percakapan dan mengirim pesan"},{"name":"Produk","description":"Katalog produk"},{"name":"Akun","description":"Saldo dan pemakaian"}],"paths":{"/ping":{"get":{"tags":["Akun"],"summary":"Uji kunci API","description":"Panggilan paling murah untuk memastikan kunci Anda dikenali. Tidak memerlukan izin khusus. Pakai ini lebih dulu sebelum menduga ada yang salah di endpoint lain.","security":[{"KunciApi":[]}],"responses":{"200":{"description":"Kunci dikenali.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"pong":{"type":"boolean"},"ts":{"type":"string","format":"date-time"}}}}}},"401":{"description":"Kunci API tidak ada, salah, atau sudah dicabut.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}}}}},"/conversations":{"get":{"tags":["Percakapan"],"summary":"Daftar percakapan","description":"Diurutkan dari pesan terbaru. Gunakan `pagination.next_cursor` untuk halaman berikutnya; bila nilainya `null`, tidak ada lagi.","parameters":[{"name":"status","in":"query","description":"AUTO = dijawab bot · HUMAN = sedang dipegang agen · PAUSED = bot dihentikan sementara · CLOSED = selesai.","schema":{"type":"string","enum":["AUTO","HUMAN","CLOSED","PAUSED"]}},{"name":"channelId","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"cursor","in":"query","description":"Ambil dari `pagination.next_cursor` respons sebelumnya.","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":30}}],"responses":{"200":{"description":"Berhasil.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/RingkasanPercakapan"}},"pagination":{"$ref":"#/components/schemas/Halaman"}}}}}},"400":{"description":"Permintaan tidak valid — periksa isi badan permintaan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}},"401":{"description":"Kunci API tidak ada, salah, atau sudah dicabut.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}},"403":{"description":"Kunci API tidak punya izin (scope) untuk tindakan ini.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}},"404":{"description":"Data tidak ditemukan, atau bukan milik akun kunci ini.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}},"429":{"description":"Terlalu banyak permintaan. Tunggu sesuai header Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}},"500":{"description":"Galat di sisi kami.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}}}}},"/conversations/{id}":{"get":{"tags":["Percakapan"],"summary":"Detail percakapan beserta riwayat pesan","description":"Menyertakan hingga 200 pesan terlama lebih dulu.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Berhasil."},"400":{"description":"Permintaan tidak valid — periksa isi badan permintaan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}},"401":{"description":"Kunci API tidak ada, salah, atau sudah dicabut.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}},"403":{"description":"Kunci API tidak punya izin (scope) untuk tindakan ini.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}},"404":{"description":"Data tidak ditemukan, atau bukan milik akun kunci ini.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}},"429":{"description":"Terlalu banyak permintaan. Tunggu sesuai header Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}},"500":{"description":"Galat di sisi kami.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}}}}},"/conversations/{id}/messages":{"post":{"tags":["Percakapan"],"summary":"Kirim pesan ke percakapan","description":"Pesan dikirim ke dalam percakapan yang sudah ada, bukan ke nomor telepon lepas — sehingga balasan pelanggan tetap masuk ke satu utas yang sama. Cari dahulu percakapannya lewat `GET /conversations`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string","minLength":1,"maxLength":4000},"as":{"type":"string","enum":["BOT","HUMAN_AGENT","SYSTEM"],"default":"HUMAN_AGENT","description":"Menentukan pesan tercatat sebagai balasan siapa di kotak masuk. Tidak memengaruhi isi yang diterima pelanggan."}}},"example":{"text":"Halo, pesanan Anda sudah kami kirim.","as":"HUMAN_AGENT"}}}},"responses":{"201":{"description":"Pesan terkirim dan tercatat."},"400":{"description":"Permintaan tidak valid — periksa isi badan permintaan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}},"401":{"description":"Kunci API tidak ada, salah, atau sudah dicabut.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}},"403":{"description":"Kunci API tidak punya izin (scope) untuk tindakan ini.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}},"404":{"description":"Data tidak ditemukan, atau bukan milik akun kunci ini.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}},"429":{"description":"Terlalu banyak permintaan. Tunggu sesuai header Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}},"500":{"description":"Galat di sisi kami.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}}}}},"/conversations/{id}/handoff":{"post":{"tags":["Percakapan"],"summary":"Alihkan percakapan ke agen manusia","description":"Bot berhenti menjawab percakapan ini sampai dikembalikan. Berguna saat sistem Anda mendeteksi kasus yang harus ditangani orang.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Percakapan kini berstatus HUMAN."},"400":{"description":"Permintaan tidak valid — periksa isi badan permintaan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}},"401":{"description":"Kunci API tidak ada, salah, atau sudah dicabut.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}},"403":{"description":"Kunci API tidak punya izin (scope) untuk tindakan ini.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}},"404":{"description":"Data tidak ditemukan, atau bukan milik akun kunci ini.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}},"429":{"description":"Terlalu banyak permintaan. Tunggu sesuai header Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}},"500":{"description":"Galat di sisi kami.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}}}}},"/products":{"get":{"tags":["Produk"],"summary":"Daftar produk aktif","parameters":[{"name":"search","in":"query","schema":{"type":"string"}},{"name":"cursor","in":"query","description":"Ambil dari `pagination.next_cursor` respons sebelumnya.","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Berhasil."},"400":{"description":"Permintaan tidak valid — periksa isi badan permintaan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}},"401":{"description":"Kunci API tidak ada, salah, atau sudah dicabut.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}},"403":{"description":"Kunci API tidak punya izin (scope) untuk tindakan ini.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}},"404":{"description":"Data tidak ditemukan, atau bukan milik akun kunci ini.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}},"429":{"description":"Terlalu banyak permintaan. Tunggu sesuai header Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}},"500":{"description":"Galat di sisi kami.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}}}},"post":{"tags":["Produk"],"summary":"Tambah produk","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProdukBaru"},"example":{"name":"Kaos Polos Hitam","sku":"KP-HTM-L","price":75000,"stock":40}}}},"responses":{"201":{"description":"Produk dibuat."},"400":{"description":"Permintaan tidak valid — periksa isi badan permintaan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}},"401":{"description":"Kunci API tidak ada, salah, atau sudah dicabut.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}},"403":{"description":"Kunci API tidak punya izin (scope) untuk tindakan ini.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}},"404":{"description":"Data tidak ditemukan, atau bukan milik akun kunci ini.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}},"429":{"description":"Terlalu banyak permintaan. Tunggu sesuai header Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}},"500":{"description":"Galat di sisi kami.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}}}}},"/products/{id}":{"patch":{"tags":["Produk"],"summary":"Ubah produk","description":"Kirim hanya kolom yang ingin diubah.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":2},"description":{"type":"string"},"price":{"type":"number","minimum":0},"stock":{"type":"integer","minimum":0},"category":{"type":"string"},"isActive":{"type":"boolean"}}},"example":{"stock":12,"price":79000}}}},"responses":{"200":{"description":"Produk diperbarui."},"400":{"description":"Permintaan tidak valid — periksa isi badan permintaan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}},"401":{"description":"Kunci API tidak ada, salah, atau sudah dicabut.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}},"403":{"description":"Kunci API tidak punya izin (scope) untuk tindakan ini.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}},"404":{"description":"Data tidak ditemukan, atau bukan milik akun kunci ini.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}},"429":{"description":"Terlalu banyak permintaan. Tunggu sesuai header Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}},"500":{"description":"Galat di sisi kami.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}}}}},"/credits":{"get":{"tags":["Akun"],"summary":"Sisa saldo pemakaian","responses":{"200":{"description":"Berhasil."},"400":{"description":"Permintaan tidak valid — periksa isi badan permintaan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}},"401":{"description":"Kunci API tidak ada, salah, atau sudah dicabut.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}},"403":{"description":"Kunci API tidak punya izin (scope) untuk tindakan ini.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}},"404":{"description":"Data tidak ditemukan, atau bukan milik akun kunci ini.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}},"429":{"description":"Terlalu banyak permintaan. Tunggu sesuai header Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}},"500":{"description":"Galat di sisi kami.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}}}}},"/usage":{"get":{"tags":["Akun"],"summary":"Ringkasan pemakaian pada rentang waktu","description":"Tanpa parameter, rentangnya 30 hari terakhir.","parameters":[{"name":"from","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Berhasil.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"period":{"type":"object","properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"}}},"messages_total":{"type":"integer"},"credit_consumed":{"type":"integer"}}}}}}}},"400":{"description":"Permintaan tidak valid — periksa isi badan permintaan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}},"401":{"description":"Kunci API tidak ada, salah, atau sudah dicabut.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}},"403":{"description":"Kunci API tidak punya izin (scope) untuk tindakan ini.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}},"404":{"description":"Data tidak ditemukan, atau bukan milik akun kunci ini.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}},"429":{"description":"Terlalu banyak permintaan. Tunggu sesuai header Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}},"500":{"description":"Galat di sisi kami.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Galat"}}}}}}}},"components":{"securitySchemes":{"KunciApi":{"type":"http","scheme":"bearer","description":"Kunci API dibuat di dashboard: Developer → API Keys.\n\nTiap kunci wajib diberi minimal satu izin (scope). Berikan sesempit mungkin — kunci yang hanya membaca status pesanan tidak perlu izin mengirim pesan, sehingga kalau bocor kerusakannya terbatas.\n\nIzin yang tersedia:\n- `conversations:read` — Membaca daftar & detail percakapan\n- `conversations:write` — Mengubah percakapan (mis. alihkan ke agen manusia)\n- `messages:send` — Mengirim pesan ke percakapan\n- `products:read` — Membaca katalog produk\n- `products:write` — Membuat & mengubah produk\n- `credits:read` — Membaca sisa saldo pemakaian\n- `usage:read` — Membaca ringkasan pemakaian"}},"schemas":{"Galat":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"Halaman":{"type":"object","properties":{"next_cursor":{"type":["string","null"],"format":"uuid","description":"null bila tidak ada halaman berikutnya."}}},"RingkasanPercakapan":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"customerIdentifier":{"type":"string"},"customerName":{"type":["string","null"]},"status":{"type":"string","enum":["AUTO","HUMAN","CLOSED","PAUSED"]},"unreadCount":{"type":"integer"},"lastMessageAt":{"type":["string","null"],"format":"date-time"},"channel":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"displayName":{"type":["string","null"]}}}}},"ProdukBaru":{"type":"object","required":["name","price"],"properties":{"name":{"type":"string","minLength":2},"sku":{"type":"string"},"description":{"type":"string"},"price":{"type":"number","minimum":0},"stock":{"type":"integer","minimum":0,"default":0},"category":{"type":"string"},"images":{"type":"array","items":{"type":"string","format":"uri"}},"attributes":{"type":"object","additionalProperties":true}}}}}}