Skip to Content
مرجع APIاسناد (Documents)

اسناد

تمام مسیرها زیر v1/assistants/:assistantCode/documents هستند. پردازش در همه‌جا ناهم‌زمان است: Endpointهای نوشتن یک Job در صف را برمی‌گردانند، نه یک سند نهایی — به پایش وضعیت پردازش اسناد مراجعه کنید.

هیچ وب‌هوک/اعلان Pushای برای پایان پردازش وجود ندارد. باید GET .../documents/jobs/:jobId را تا رسیدن Job به یک وضعیت نهایی Poll کنید.

فرمت‌های فایل پشتیبانی‌شده

متن، PDF، Word (.docx/.doc قدیمی)، تصویر و صوت. این بررسی با خواندن بایت‌های واقعی فایل انجام می‌شود (همان روشی که موتور استخراج خودش استفاده می‌کند)، نه با اعتماد به پسوند فایل یا هدر Content-Type — یک فایل با پسوند تغییریافته، بر اساس محتوای واقعی‌اش قضاوت می‌شود. یک فایل پشتیبانی‌نشده (آرشیو، فایل اجرایی، ویدیو و …) بلافاصله با 415 و documents.unsupported_file_type رد می‌شود، نه اینکه بعداً به‌صورت خاموش به‌شکل یک Job با errorMessage: "ingest_failed" شکست بخورد.

بارگذاری فایل‌ها

POST /v1/assistants/:assistantCode/documents

multipart/form-data. نام فیلد فایل files است (تکرارشونده — می‌توانید چند فایل را در یک درخواست بارگذاری کنید، حداکثر ۱۰ فایل در هر درخواست، هر فایل تا ۲۵ مگابایت). فیلد اختیاری فرم folderId (۳۲ کاراکتر Hex با حروف کوچک) اسناد را در یک پوشه قرار می‌دهد.

curl
curl -X POST "https://api.plexit.ir/v1/assistants/<assistantCode>/documents" \
  -H "Authorization: Bearer $PLEXIT_API_KEY" \
  -F "files=@./handbook.pdf" \
  -F "files=@./pricing.pdf" \
  -F "folderId=1a2b3c4d5e6f70819293a4b5c6d7e8f9"
const form = new FormData();
form.append("files", fileBlob, "handbook.pdf");
// form.append("folderId", "1a2b3c4d5e6f70819293a4b5c6d7e8f9"); // اختیاری
 
const res = await fetch(
  `https://api.plexit.ir/v1/assistants/${assistantCode}/documents`,
  {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.PLEXIT_API_KEY}` },
    body: form,
  },
);

ساخت سند از متن خام

بدون نیاز به فایل — برای محتوایی که از پیش به‌شکل رشته دارید (مثلاً تولید پویا یک مقاله‌ی پشتیبانی).

POST /v1/assistants/:assistantCode/documents/text

بدنه

فیلدنوعالزامیمحدودیت‌ها
folderIdstringخیر۳۲ کاراکتر Hex با حروف کوچک
filenamestringبلهباید با الگوی ^[^/\\]+\.[A-Za-z0-9]+$ مطابقت داشته باشد — یک نام فایل ساده همراه با پسوند، مثل notes.txt، بدون جداکننده‌ی مسیر
contentstringبله۱ تا ۲٬۰۰۰٬۰۰۰ کاراکتر
curl
curl -X POST "https://api.plexit.ir/v1/assistants/<assistantCode>/documents/text" \
  -H "Authorization: Bearer $PLEXIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "return-policy.txt",
    "content": "Items can be returned within 30 days of purchase..."
  }'

هر دو Endpoint بارگذاری، یکسان پاسخ می‌دهند

{
  "data": {
    "list": [
      {
        "id": "5c6d7e8f90a1b2c3d4e5f60718293a4b",
        "status": "queued",
        "path": "/handbook.pdf",
        "kind": "create",
        "resultFileId": null,
        "resultNChunks": null,
        "resultSizeBytes": null,
        "errorMessage": null,
        "createdAt": "2026-09-19T12:00:00.000Z",
        "updatedAt": "2026-09-19T12:00:00.000Z"
      }
    ],
    "count": 1
  },
  "response": { "status": "success", "message": "..." }
}

این همان DocumentIngestJobResponse است — یک ورودی برای هر فایل بارگذاری‌شده (یا یک ورودی برای سندِ متنیِ تکی). این نشان‌دهنده‌ی یک Job در صف است، نه یک سند نهایی. مقادیر resultFileId/resultNChunks/resultSizeBytes تا پایان Job برابر null هستند.

پایش وضعیت یک Job

GET /v1/assistants/:assistantCode/documents/jobs/:jobId

:jobId همان id از پاسخ بارگذاری بالاست.

{
  "data": {
    "id": "5c6d7e8f90a1b2c3d4e5f60718293a4b",
    "status": "ready",
    "path": "/handbook.pdf",
    "kind": "create",
    "resultFileId": "9a8b7c6d5e4f30211f0e1d2c3b4a5968",
    "resultNChunks": 42,
    "resultSizeBytes": 184320,
    "errorMessage": null,
    "createdAt": "2026-09-19T12:00:00.000Z",
    "updatedAt": "2026-09-19T12:00:07.000Z"
  },
  "response": { "status": "success", "message": "..." }
}

فیلدهای DocumentIngestJobResponse

فیلدنوعتوضیح
idstringشناسه‌ی Job — برای Poll کردن از این استفاده کنید.
statusstringیکی از queued، processing، ready، failed. مقادیر ready و failed نهایی هستند — Poll را متوقف کنید.
pathstringمسیر مقصد سند (پوشه + نام فایل).
kindstringیکی از create، replace — اینکه آیا این Job یک سند جدید می‌سازد یا یک سند موجود را جایگزین می‌کند.
resultFileIdstring | nullپس از رسیدن status به ready مقداردهی می‌شود؛ همان شناسه‌ای که باید در Endpointهای فهرست/حذف استفاده شود.
resultNChunksnumber | nullپس از ready مقداردهی می‌شود.
resultSizeBytesnumber | nullپس از ready مقداردهی می‌شود.
errorMessagestring | nullزمانی که status برابر failed باشد مقداردهی می‌شود.
createdAt / updatedAtstring (ISO 8601)

برای الگوی پیشنهادیِ Backoff به راهنمای پایش وضعیت مراجعه کنید.

فهرست اسناد

GET /v1/assistants/:assistantCode/documents?folderId=<optional>

اسناد نهایی و پردازش‌شده را فهرست می‌کند — این Endpoint مستقیماً از retrieval می‌خواند، نه از جدول Job محلی، پس فقط شامل اسنادی است که Job پردازش آن‌ها از پیش به ready رسیده باشد.

{
  "data": {
    "list": [
      {
        "fileId": "9a8b7c6d5e4f30211f0e1d2c3b4a5968",
        "path": "/handbook.pdf",
        "nChunks": 42,
        "size": 184320,
        "createdAt": 1758283207
      }
    ],
    "count": 1
  },
  "response": { "status": "success", "message": "..." }
}

مقدار createdAt در اینجا یک عدد صحیح از نوع Unix-epoch بر حسب ثانیه است — نه یک رشته‌ی ISO. هر برچسب‌زمان دیگری در این API از نوع ISO 8601 است. فقط همین یک فیلد، در همین یک Endpoint، این‌طور نیست، چون مستقیماً از created_at خودِ retrieval منعکس شده. آن را بدون تبدیل مستقیماً به new Date(createdAt) ندهید — ابتدا در ۱۰۰۰ ضرب کنید: new Date(createdAt * 1000).

حذف اسناد

DELETE /v1/assistants/:assistantCode/documents

بدنه

فیلدنوعالزامیمحدودیت‌ها
fileIdsstring[]بلهحداقل ۱ عنصر — از مقادیر fileId در فهرست اسناد استفاده کنید
curl
curl -X DELETE "https://api.plexit.ir/v1/assistants/<assistantCode>/documents" \
  -H "Authorization: Bearer $PLEXIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fileIds": ["9a8b7c6d5e4f30211f0e1d2c3b4a5968"]}'
{ "data": null, "response": { "status": "success", "message": "..." } }
گفتگو (Chat)محصولات (Products)