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.

Header yang Dianjurkan

Scope

Tiap API key punya kumpulan scope. Endpoint menolak key tanpa scope yang sesuai (403).

Percakapan

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

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

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" }'

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

Produk

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

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 }'

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

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

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

Utilitas

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": "..." } }

Rate limit default 60 permintaan/menit per key (dapat diatur saat membuat key). Melebihi batas → HTTP 429.

Webhook keluar

Alih-alih sistem Anda menanyai kami berulang kali, kami yang mengirim ke alamat Anda begitu sesuatu terjadi. Alamat penerima didaftarkan di dashboard (Developer → Webhooks), dan tiap alamat mendapat kunci rahasianya sendiri.

Header tiap kiriman

X-BantuCS-Event: order.paid
X-BantuCS-Event-Id: evt_2f9c...        # sama untuk semua percobaan ulang
X-BantuCS-Delivery: dlv_8a31...        # unik per percobaan
X-BantuCS-Timestamp: 1754470800
X-BantuCS-Signature: t=1754470800,v1=9f86d081884c7d65...

Memverifikasi tanda tangan

Tanda tangan adalah HMAC-SHA256 atas timestamp, titik, lalu badan permintaan mentah. Hitung ulang dengan kunci rahasia alamat Anda dan bandingkan. Pakai badan mentah — mengurai lalu menyusun ulang JSON akan mengubah satu byte dan tanda tangannya tidak akan pernah cocok.

// Node.js — verifikasi sebelum memproses isi kiriman
import { createHmac, timingSafeEqual } from 'node:crypto';

function sahkah(header, badanMentah, rahasia) {
  const bagian = Object.fromEntries(
    header.split(',').map((x) => x.split('=')),
  );
  // Tolak kiriman yang terlalu tua — mencegah kiriman lama diputar ulang.
  const umurDetik = Math.abs(Date.now() / 1000 - Number(bagian.t));
  if (!Number.isFinite(umurDetik) || umurDetik > 300) return false;

  const harapan = createHmac('sha256', rahasia)
    .update(`${bagian.t}.${badanMentah}`)
    .digest('hex');

  const a = Buffer.from(harapan);
  const b = Buffer.from(bagian.v1 ?? '');
  return a.length === b.length && timingSafeEqual(a, b);
}

Percobaan ulang

Kami mencoba 7 kali selama kira-kira 38 jam bila alamat Anda tidak membalas 2xx: segera, lalu +1 menit, +5 menit, +30 menit, +2 jam, +12 jam, +24 jam. Batas waktu tiap percobaan 10 detik.

Karena ada percobaan ulang, alamat Anda bisa menerima kejadian yang sama lebih dari sekali — misalnya bila balasan Anda terlambat padahal isinya sudah diproses. Gunakan X-BantuCS-Event-Id sebagai penanda: simpan yang sudah diproses, dan abaikan yang berulang. Balas cepat (di bawah 10 detik) lalu kerjakan pekerjaan beratnya di belakang layar.

Balasan 410 Gone kami perlakukan sebagai permintaan berhenti: alamat itu langsung dinonaktifkan dan tidak dihubungi lagi sampai Anda mengaktifkannya kembali.

Bentuk isi kiriman

{
  "id": "evt_2f9c8b14-...",
  "type": "order.paid",
  "created_at": "2026-08-06T03:20:00.000Z",
  "tenant_id": "3a7f...",
  "livemode": true,
  "data": {
    "order_id": "9c2e...",
    "order_number": "INV-20260806-0042",
    "status": "PAID",
    "payment_status": "PAID",
    "customer_name": "Rina",
    "customer_phone": "628123456789",
    "total": 175000,
    "tracking_number": null,
    "paid_at": "2026-08-06T03:19:58.000Z"
  }
}

Kejadian yang bisa dilanggani

Bisa didaftarkan satu per satu (order.paid), per kelompok (order.*), atau semuanya (*).

Spesifikasi mesin (OpenAPI)

Seluruh endpoint di atas tersedia sebagai berkas OpenAPI 3.1 — bisa langsung diimpor ke Postman, Insomnia, Swagger Editor, atau gateway API Anda untuk membuat klien secara otomatis, tanpa menyalin ulang dengan tangan.

curl -O ${baseUrl.replace(//api/v1$/, "")}/docs/api/openapi.json

Buka openapi.json →