🔌 راهنمای API همکاران
با کلیدی که از مدیر کتابخانه گرفته‌اید، در سایت، اپ، کانال یا ربات خودتان به مشتریانتان پاسخ‌های مستند (با نام کتاب و شماره صفحه) بدهید. مشتریان شما لازم نیست وارد سایت ما شوند.
اعضای سایت می‌توانند خودشان از حساب کاربری ← دستیار هوشمند سایت من بسته را بخرند، قفسه‌های کتابخانه شخصی را برای پاسخ‌گویی انتخاب کنند، حوزه کاری و دستورالعمل پاسخ‌گویی بنویسند، متن‌های ویجت (عنوان، زیرعنوان، خوش‌آمد، رنگ) را تغییر دهند و کلید مخفی را بسازند. پاسخ‌ها فقط از منابع انتخاب‌شده ساخته می‌شود.
وردپرس: در همان بخش، «دانلود افزونه وردپرس» را بزنید؛ کلید ویجت از قبل داخل افزونه است. بعد از نصب و فعال‌سازی، دکمه گفتگو در سایت ظاهر می‌شود و با کد کوتاه [smart_library] می‌توانید جعبه گفتگو را داخل هر برگه بگذارید. راهنمای جوملا، ویکس، شاپیفای و سایت‌سازهای دیگر هم همان‌جاست.
۱) ساده‌ترین روش: ویجت گفتگو در سایت
این یک خط را قبل از </body> سایتتان بگذارید (کلید ویجت pk_… در حساب کاربری شما یا از مدیر). یک دکمه گفتگو گوشه صفحه ظاهر می‌شود. ویجت فقط روی دامنه‌هایی که برای کلیدتان ثبت شده کار می‌کند.
اختیاری: data-color="#0a5" و data-side="left" روی همان تگ script.
۲) API سرور به سرور
POST /api/v1/ask — هدر Authorization: Bearer sk_… (کلید مخفی را هرگز در کد صفحه وب یا اپ موبایل نگذارید؛ فقط روی سرور خودتان).
| فیلد ورودی | توضیح |
|---|---|
question | پرسش (تا ۴۰۰۰ نویسه؛ فارسی، عربی، انگلیسی، روسی یا چینی) |
mode | book (پیش‌فرض: فقط از متن کتاب) یا apply (کاربردی: اصول کتاب روی موقعیت مشتری، مثلاً «برای یک کلینیک») |
topic | اختیاری: نام یک قفسه، مثلاً «بازاریابی و فروش» |
conversation_id | اختیاری: برای ادامه همان گفتگو (عدد برگشتی پاسخ قبلی) |
user_ref | اختیاری: شناسه مشتری شما (مثلاً آیدی تلگرام) برای گزارش |
پاسخ:
{
"answer": "زنجیره ارزش شامل پنج فعالیت اصلی است ... [1]",
"mode": "book",
"conversation_id": 128,
"sources": [{"n": 1, "title": "مزیت رقابتی", "author": "مایکل پورتر", "page": "37", "cited": true}],
"usage": {"month_used": 41, "monthly_quota": 1000}
}
GET /api/v1/info — نام، محدوده، قفسه‌های مجاز و مصرف ماه جاری.
نمونه پایتون
نمونه PHP
نمونه ربات تلگرام (پایتون، بدون کتابخانه اضافه)
توکن ربات را از BotFather بگیرید. این ربات هر پیام را به کتابخانه می‌فرستد و پاسخ را با منابع برمی‌گرداند؛ گفتگوی هر کاربر جدا ادامه پیدا می‌کند.
خطاها
| کد HTTP | error.code | معنی |
|---|---|---|
| 401 | invalid_key | کلید نامعتبر |
| 403 | disabled / expired / topic_not_allowed | کلید غیرفعال، منقضی یا قفسه خارج از محدوده |
| 429 | quota_exceeded / rate_limited | سهمیه ماهانه تمام شده یا درخواست در دقیقه زیاد است |
| 400 | bad_question / empty_scope | پرسش خالی یا کتابی در محدوده نیست |
پاسخ‌ها فقط از کتاب‌های محدوده کلید شما ساخته می‌شوند. هر درخواست موفق یک واحد از سهمیه ماهانه کم می‌کند؛ اگر هوش مصنوعی پاسخ ندهد، کم نمی‌شود.