Generic Site API v1

مستندات اتصال سایت‌های غیر وردپرسی به دستیار سایت

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

شروع اتصال در پنل مشاهده شروع سریع

Contract: v1 Auth: Bearer Token Batch: حداکثر ۵۰۰ آیتم Callback: /dastyar/v1/*

Project سایت یا اپلیکیشن اختصاصی Laravel، Node، Django، PHP خام، CMS اختصاصی یا هر stack دیگر

Project → Platform health / handshake / sync / AI

Platform دستیار سایت ذخیره داده، تولید محتوا، billing، delivery و retry

Platform → Project callback / publish / schema / resolve

Callback API /dastyar/v1/* endpointهایی که پروژه مقصد باید روی دامنه عمومی خودش پیاده‌سازی کند

مسیر پیاده‌سازی

از ثبت سایت تا publish خروجی

اگر اولین بار است این اتصال را پیاده‌سازی می‌کنید، همین ترتیب را دنبال کنید تا مسیرهای پلتفرم و مسیرهای callback با هم اشتباه نشوند.

ثبت سایت با روش Generic API

در onboarding یا صفحه سایت‌ها، روش اتصال «پروژه اختصاصی/API» را انتخاب کنید و دامنه اصلی پروژه را ثبت کنید.

دریافت اطلاعات اتصال

پنل برای همان سایت، Site Code، Connection Token و Platform API Base URL را نمایش می‌دهد. token فقط باید در backend یا secret manager نگهداری شود.

پیاده‌سازی health سمت پروژه

روی دامنه عمومی پروژه مسیر GET /dastyar/v1/health را با Bearer token، ok:true و contract_version:v1 آماده کنید.

ثبت Callback Base URL و تست اتصال

Callback Base URL باید public، بدون redirect، بدون localhost/private IP و ترجیحا HTTPS باشد. پلتفرم health را بدون دنبال‌کردن redirect تست می‌کند.

Handshake و معرفی قابلیت‌ها

پروژه با POST /handshake نسخه قرارداد، نام client و منابعی که sync/publish می‌کند را اعلام می‌کند.

Initial Sync

ابتدا دسته‌بندی‌ها، سپس نوشته‌ها/محصولات و در پایان دیدگاه‌ها را با idempotency key پایدار ارسال کنید.

پیاده‌سازی publish callbackها

پروژه باید خروجی‌های AI را در مسیرهای /dastyar/v1/publish/* دریافت کند و external_id پایدار برگرداند.

تست، مانیتورینگ و انتشار

401، 422، retry، replay با idempotency key، queue و لاگ‌های بدون token را قبل از production بررسی کنید.

اطلاعات پایه

چه چیزهایی باید در پروژه ذخیره شود؟

بعد از ثبت سایت، مقادیر زیر را از پنل بردارید و فقط در محیط امن backend نگهداری کنید.

DASTYAR_PLATFORM_API_BASE_URL=https://dastyar.site/api/v1/sites/ABCDE
DASTYAR_SITE_CODE=ABCDE
DASTYAR_CONNECTION_TOKEN=replace-with-real-secret
DASTYAR_CALLBACK_BASE_URL=https://example.com

قانون طلایی مسیرها

مسیرهای /api/v1/sites/... روی پلتفرم دستیار سایت هستند و پروژه آن‌ها را صدا می‌زند. مسیرهای /dastyar/v1/... روی پروژه مقصد هستند و پلتفرم آن‌ها را صدا می‌زند.

توکن را در JavaScript، HTML، repository یا لاگ ذخیره نکنید.
تمام درخواست‌های دوطرفه باید Authorization: Bearer CONNECTION_TOKEN داشته باشند.
برای sync، publish و AI retry از X-Dastyar-Idempotency-Key پایدار استفاده کنید.

Project → Platform

endpointهای پلتفرم

تمام routeهای زیر با base URL سایت شما در پلتفرم شروع می‌شوند: https://dastyar.site/api/v1/sites/{SITE_CODE}

Method	Path	کاربرد	نکته
GET	`/api/v1/sites/{SITE_CODE}/health`	بررسی سلامت اتصال و مشاهده وضعیت سایت در پلتفرم	نیازمند Bearer token
GET	`/api/v1/sites/{SITE_CODE}/contract`	دریافت قرارداد فنی نسخه v1، فیلدهای منابع و callbackها	برای auto-discovery کلاینت مناسب است
POST	`/api/v1/sites/{SITE_CODE}/handshake`	ثبت نسخه قرارداد، مشخصات کلاینت و capabilityهای پروژه	اتصال را connected می‌کند
POST	`/api/v1/sites/{SITE_CODE}/sync/post-categories`	ارسال دسته‌بندی نوشته‌ها از پروژه به پلتفرم	حداکثر ۵۰۰ آیتم در هر درخواست
POST	`/api/v1/sites/{SITE_CODE}/sync/posts`	ارسال نوشته‌ها، برگه‌ها و محتوای متنی قابل هدف‌گیری	external_id برای هر آیتم الزامی است
POST	`/api/v1/sites/{SITE_CODE}/sync/product-categories`	ارسال دسته‌بندی محصولات	برای فروشگاه‌های اختصاصی
POST	`/api/v1/sites/{SITE_CODE}/sync/products`	ارسال محصولات، SKU، توضیحات، ویژگی‌ها و SEO meta	external_id یا id لازم است
POST	`/api/v1/sites/{SITE_CODE}/sync/comments`	ارسال دیدگاه‌ها و اتصال آن‌ها به نوشته یا محصول	target_type برابر post یا product
GET	`/api/v1/sites/{SITE_CODE}/ai/health`	بررسی آماده بودن کیف پول و قابلیت تولید متن	پاسخ شامل balance و feature flags است
GET	`/api/v1/sites/{SITE_CODE}/ai/models`	دریافت مدل‌های billable فعال و اطلاعات هزینه	فقط مدل‌های provider فعال نمایش داده می‌شوند
POST	`/api/v1/sites/{SITE_CODE}/ai/chat/completions`	ارسال درخواست مستقیم تولید متن شبیه Chat Completions	از idempotency برای جلوگیری از هزینه تکراری استفاده کنید

نمونه درخواست‌ها

شروع سریع با curl

۱. تست health پلتفرم

curl --request GET "$DASTYAR_PLATFORM_API_BASE_URL/health" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer $DASTYAR_CONNECTION_TOKEN"

۲. handshake

curl --request POST "$DASTYAR_PLATFORM_API_BASE_URL/handshake" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $DASTYAR_CONNECTION_TOKEN" \
  --data '{
    "contract_version": "v1",
    "client": {"name": "Custom Laravel App", "version": "1.0.0"},
    "capabilities": {
      "sync": ["posts", "products", "comments"],
      "publish": ["posts", "products", "comments", "schema"]
    }
  }'

۳. sync نوشته

curl --request POST "$DASTYAR_PLATFORM_API_BASE_URL/sync/posts" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $DASTYAR_CONNECTION_TOKEN" \
  --header "X-Dastyar-Idempotency-Key: post-100-updated-v1" \
  --data '{
    "contract_version": "v1",
    "action": "updated",
    "event_id": "post-100-updated",
    "items": [{
      "external_id": "post-100",
      "url": "https://example.com/posts/100",
      "title": "عنوان نوشته",
      "content": "متن کامل یا خلاصه محتوای قابل استفاده",
      "categories": [{"external_id": "cat-1", "name": "آموزش"}],
      "seo_meta": {"title": "SEO title", "description": "SEO description"}
    }]
  }'

Sync Contract

قرارداد ارسال داده از پروژه به پلتفرم

در نسخه v1، درخواست sync باید contract_version: v1، حداقل یک آیتم و idempotency key داشته باشد. actionهای رایج به created، updated یا deleted نرمال می‌شوند.

post-categories

دسته‌بندی نوشته

external_id, name, slug, parent_external_id, description, meta

posts

نوشته/برگه

external_id, url, title, content, type, seo_meta, categories, category_external_ids

product-categories

دسته‌بندی محصول

external_id, name, slug, parent_external_id, description, meta

products

محصول

external_id, sku, name, description, attributes, seo_meta, categories

comments

دیدگاه

external_id, target_type, target_external_id, content, sentiment

حذف داده

برای حذف، همان endpoint resource را با action شامل delete، trash یا remove ارسال کنید. پلتفرم بر اساس external_id رکورد متناظر را حذف می‌کند.

idempotency

یک event باید همیشه با همان key تکرار شود. اگر پردازش قبلا کامل شده باشد، پاسخ قبلی با idempotent_replay: true برمی‌گردد.

Platform → Project

callback API که پروژه مقصد باید پیاده‌سازی کند

پلتفرم برای تست اتصال، publish خروجی، schema و دریافت تصویر شاخص، endpointهای زیر را روی DASTYAR_CALLBACK_BASE_URL صدا می‌زند.

Method	Path	کاربرد	پاسخ مورد انتظار
GET	`/dastyar/v1/health`	پلتفرم برای تأیید callback و contract_version فراخوانی می‌کند	ok, contract_version, site_url, client, capabilities
POST	`/dastyar/v1/publish/posts`	دریافت نوشته تولیدشده یا ویرایش‌شده از پلتفرم	external_id و url
POST	`/dastyar/v1/publish/products`	دریافت محصول یا توضیحات محصول تولیدشده	external_id و url
POST	`/dastyar/v1/publish/comments`	دریافت پاسخ دیدگاه یا دیدگاه تولیدشده	external_id و url
POST	`/dastyar/v1/publish/comment-summary`	دریافت خلاصه دیدگاه‌ها برای یک هدف	external_id و url
POST	`/dastyar/v1/publish/images`	دریافت تصویر تولیدشده یا ویرایش‌شده	external_id، url و در صورت نیاز attachment_id
POST	`/dastyar/v1/publish/podcasts`	دریافت فایل صوتی/پادکست تولیدشده	external_id و url
GET	`/dastyar/v1/publish/resolve`	بازیابی نتیجه publish بر اساس idempotency_key	external_id و url
GET	`/dastyar/v1/featured-image`	دریافت تصویر شاخص یک نوشته یا محصول برای استفاده در تولید	data.url و metadata تصویر
POST	`/dastyar/v1/schema`	ذخیره JSON-LD ساخته‌شده برای یک نوشته یا محصول	ok و schema_status
POST	`/dastyar/v1/schema/settings`	ذخیره تنظیمات profile مربوط به Schema Engine	ok
DELETE	`/dastyar/v1/schema/{EXTERNAL_ID}`	حذف یا غیرفعال‌سازی schema یک محتوای مقصد	ok و deleted

نمونه پاسخ health پروژه

{
  "ok": true,
  "contract_version": "v1",
  "site_url": "https://example.com",
  "client": {"name": "Example App", "version": "1.0.0"},
  "capabilities": {
    "sync": ["posts", "products", "comments"],
    "publish": ["posts", "products", "comments", "schema"]
  }
}

نمونه پاسخ publish

{
  "ok": true,
  "external_id": "post-100",
  "url": "https://example.com/posts/100"
}

AI Provider API

درخواست مستقیم تولید متن از پروژه

پروژه اختصاصی می‌تواند مثل Chat Completions، مدل‌های فعال را بگیرد و درخواست تولید متن ثبت کند. billing روی کیف پول مالک سایت اعمال می‌شود.

GET /ai/health وضعیت کیف پول و قابلیت text_generation را نشان می‌دهد.
GET /ai/models مدل‌های billable فعال، context window و محدودیت هزینه را برمی‌گرداند.
POST /ai/chat/completions از messages، temperature، top_p، max_tokens و response_format پشتیبانی می‌کند.
برای retry حتما همان X-Dastyar-Idempotency-Key را ارسال کنید تا هزینه تکراری ایجاد نشود.

curl --request POST "$DASTYAR_PLATFORM_API_BASE_URL/ai/chat/completions" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $DASTYAR_CONNECTION_TOKEN" \
  --header "X-Dastyar-Idempotency-Key: ai-summary-post-100-v1" \
  --data '{
    "model": "MODEL_ID",
    "messages": [
      {"role": "system", "content": "You are a helpful content assistant."},
      {"role": "user", "content": "یک خلاصه فارسی برای این محصول بنویس."}
    ],
    "temperature": 0.7,
    "max_tokens": 500
  }'

خطاها، محدودیت‌ها و retry

رفتار قابل انتظار در production

200

درخواست موفق

health، contract، replay موفق یا پردازش sync بدون خطا.

202

در حال پردازش

برای replay همزمان یک idempotency key که هنوز processing است.

401

توکن نامعتبر

هدر Authorization وجود ندارد، Bearer نیست یا با token سایت برابر نیست.

402

موجودی ناکافی

در API تولید متن، کیف پول مالک سایت برای درخواست کافی نیست.

422

قرارداد نامعتبر

contract_version، external_id، idempotency key یا فیلدهای payload مشکل دارد.

429

Rate limit

site-api: ۱۲۰ درخواست در دقیقه برای هر سایت و ۲۴۰ برای هر IP؛ site-sync: ۳۰۰ برای هر سایت و ۶۰۰ برای هر IP.

5xx

خطای موقت

در callbackهای پروژه، پلتفرم delivery را failed ثبت و بر اساس retry schedule دوباره تلاش می‌کند.

زمان‌بندی retry callback

اگر publish به callback پروژه با خطا مواجه شود، delivery در پلتفرم failed ثبت می‌شود. تلاش‌های بعدی به ترتیب با تأخیر حدود ۶۰ ثانیه، ۵ دقیقه، ۱۵ دقیقه و سپس ۱ ساعت زمان‌بندی می‌شوند.

قواعد امنیت callback

Callback Base URL نباید localhost، loopback، private IP، URL دارای username/password یا مسیر دارای redirect باشد. پاسخ‌ها باید JSON معتبر و بدون افشای token باشند.

Production Checklist

چک‌لیست نهایی قبل از تحویل

اتصال

health پلتفرم با token درست، ۲۰۰ و با token اشتباه، ۴۰۱ می‌دهد.
health پروژه، ok:true و contract_version:v1 برمی‌گرداند.
دامنه site_url با دامنه ثبت‌شده در پنل یکی است.
handshake با capabilityهای واقعی پروژه انجام شده است.

Sync و publish

create، update و delete برای هر resource تست شده است.
batch بالای ۵۰۰ آیتم ارسال نمی‌شود.
replay با همان idempotency key رکورد تکراری نمی‌سازد.
callback publish همیشه external_id معتبر برمی‌گرداند.

امنیت و عملیات

token در log، repository، frontend و responseهای خطا ظاهر نمی‌شود.
queue و monitoring برای retry sync/publish فعال است.
محدودیت حجم body و فایل برای image/podcast اعمال شده است.
dashboard delivery، webhook event و خطاهای ۴xx/۵xx مانیتور می‌شود.

اتصال پروژه اختصاصی را با قرارداد v1 شروع کنید

بعد از ورود به پنل، سایت جدید را با روش پروژه اختصاصی/API بسازید و مقادیر اتصال را در backend پروژه قرار دهید.

ورود به پنل و ساخت اتصال