اولین درخواست به API عمومی Plexit

API عمومی Plexit به سرور شما اجازه می‌دهد بدون ویجت با دستیارها گفت‌وگو کنید و پایگاه دانش را مدیریت کنید. همهٔ مسیرها زیر نشانی https://api.plexit.ir/v1 هستند. مرجع کامل در مستندات توسعه‌دهندگان و مسیر کامل گام‌به‌گام در شروع سریع آمده است؛ این راهنما نسخهٔ کوتاه آن است.

پیش‌نیاز

• یک کلید API از صفحهٔ کلیدهای API کنسول: ساخت کلید API
• دست‌کم یک دستیار فعال با چند سند آماده در پایگاه دانش

۱. احراز هویت

هر درخواست باید هدر Authorization را با مقدار Bearer و کلید خام داشته باشد:

export PLEXIT_API_KEY="pk_live_..."

curl https://api.plexit.ir/v1/assistants \
  -H "Authorization: Bearer $PLEXIT_API_KEY"

پاسخ فهرست دستیارهای حساب است. مقدار id هر دستیار را یادداشت کنید؛ در مسیرهای بعدی به‌جای :assistantCode از همین مقدار استفاده می‌شود.

۲. ارسال پیام

curl -X POST "https://api.plexit.ir/v1/assistants/ASSISTANT_ID/chat" \
  -H "Authorization: Bearer $PLEXIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"principal": "user-42", "message": "ساعت کاری شما چیست؟"}'

فیلد principal شناسهٔ پایدار کاربر نهایی در سیستم خود شماست؛ مثلاً شناسهٔ کاربر در اپلیکیشنتان. Plexit گفت‌وگوها و حافظهٔ دستیار را بر اساس همین مقدار از هم جدا می‌کند.

۳. خواندن پاسخ

پاسخ موفق در فیلد data قرار دارد: متن پاسخ در text، منابع استفاده‌شده در sources و شناسهٔ گفت‌وگو در conversationId. برای ادامهٔ همان گفت‌وگو، conversationId را در درخواست بعدی بفرستید.

const res = await fetch(
  `https://api.plexit.ir/v1/assistants/${assistantId}/chat`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.PLEXIT_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      principal: "user-42",
      message: "هزینهٔ ارسال چقدر است؟",
      conversationId, // اختیاری: برای ادامهٔ گفت‌وگوی قبلی
    }),
  },
);

const { data, response } = await res.json();
if (!res.ok) throw new Error(`${response.status}: ${response.message}`);
console.log(data.text, data.sources);

۴. مدیریت خطا

۵. ادامهٔ گفت‌وگو و جداسازی کاربران

برای اینکه دستیار سابقهٔ گفت‌وگو را در نظر بگیرد، conversationId پاسخ قبلی را همراه پیام بعدی بفرستید. اگر آن را نفرستید، یک گفت‌وگوی تازه شروع می‌شود. برای هر کاربر نهایی یک principal ثابت نگه دارید و conversationId را کنار شناسهٔ همان کاربر در پایگاه دادهٔ خودتان ذخیره کنید تا بعداً بتوانید گفت‌وگو را از همان‌جا ادامه دهید.

پیام‌هایی که از طریق API ارسال می‌شوند، مثل پیام‌های ویجت، از بودجهٔ هفتگی پلن و در صورت نیاز از کیف پول حساب پرداخت می‌شوند و در صفحهٔ مصرف کنسول دیده می‌شوند.

قدم‌های بعدی

• آپلود سند و ساخت سند متنی از طریق API، و پیگیری وضعیت پردازش: مستندات اسناد
• فهرست کامل خطاها: صفحهٔ خطاها