مستندات API

احراز هویت چطور است؟

یک هدر. کلید را از پنل می‌سازی و فقط همان یک بار می‌بینی‌اش.

Authorization: Bearer bbk_...

بررسی کلید

GET/api/v1/public/me

ارزان‌ترین درخواست ممکن، برای اینکه ببینی کلید کار می‌کند. اعتباری مصرف نمی‌کند.

درخواست

curl https://bababot.ir/api/v1/public/me \
  -H "Authorization: Bearer bbk_..."

پاسخ

{
  "tenant": "فروشگاه من",
  "bot": { "id": "...", "name": "دستیار" },
  "credits_remaining": 1183,
  "rate_limit_per_minute": 30
}

یک پاسخ

POST/api/v1/public/chat

همان موتوری که ویجت استفاده می‌کند. user_id شناسه‌ی کاربر نهایی در سیستم خودت است؛ قبل از ذخیره هش می‌شود، پس لازم نیست از قبل ناشناس باشد.

درخواست

curl -X POST https://bababot.ir/api/v1/public/chat \
  -H "Authorization: Bearer bbk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "message": "گارانتی چند ماهه است؟",
    "user_id": "customer-4471"
  }'

پاسخ

{
  "answer": "گارانتی همه‌ی محصولات ۱۸ ماه است.",
  "refused": false,
  "conversation_id": "8f3c...",
  "message_id": 12904,
  "sources": [{ "title": "شرایط گارانتی", "url": "https://..." }],
  "cached": false,
  "credits_charged": 1,
  "model": "gpt-5.6-luna",
  "latency_ms": 2140
}

سینک محصولات

POST/api/v1/public/products

هر محصول یک رکورد ساخت‌یافته با فیلدهای جدا — نه یک تکه متن. فقط name، brand و category در رتبه‌بندی دخالت می‌کنند؛ specs و description به پاسخ کمک می‌کنند ولی رتبه را عوض نمی‌کنند.

درخواست

curl -X POST https://bababot.ir/api/v1/public/products \
  -H "Authorization: Bearer bbk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "products": [{
      "external_id": "4471",
      "name": "لپ‌تاپ ایسوس ROG Strix G16",
      "brand": "ASUS",
      "category": "لپ‌تاپ گیمینگ",
      "price": 78500000,
      "availability": true,
      "url": "https://shop.example/p/4471",
      "specs": { "رم": "۱۶ گیگ", "پردازنده": "i7-13650HX" }
    }]
  }'

پاسخ

{ "received": 1, "written": 1, "embedded": 1 }

خطاها چه شکلی‌اند؟

هر خطا یک code ماشین‌خوان، یک پیام فارسی و یک request_id دارد. آن شناسه را در تیکت بفرست تا کل ماجرا را در لاگ پیدا کنیم.

{
  "error": {
    "code": "rate_limited",
    "message": "سقف ۳۰ درخواست در دقیقه برای این کلید پر شده.",
    "request_id": "62adee26c466497e9bb196adf9f3eda2"
  }
}