رفتن به محتوای اصلی

مستندات عمومی API

مستندات عمومی API

وب‌سایت یا CMS شما می‌تواند محتوا را با یک قالب کمپین آماده به مقصدهای ایلیا ارسال کند.

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

برای تمام فیلدهای درخواست و ساختار پاسخ‌ها، مرجع تعاملی را ببینید.

بررسی اتصال

GET
/api/v1/publishing/connection/

فهرست قالب‌ها

GET
/api/v1/publishing/catalog/templates/

بارگذاری رسانه

POST
/api/v1/publishing/media/

وضعیت رسانه

GET
/api/v1/publishing/media/{media_id}/

ایجاد انتشار

POST
/api/v1/publishing/campaigns/

وضعیت انتشار

GET
/api/v1/publishing/requests/{request_id}/

احراز هویت و امضای درخواست

هر درخواست با HMAC-SHA256، زمان، nonce و هش دقیق بدنه امضا می‌شود.

رشتهٔ زیر را دقیقاً با نویسهٔ خط جدید LF بسازید. مسیر باید همان مسیر درخواست و هش بدنه باید SHA-256 بایت‌های دقیق بدنه باشد.

Canonical request
ILIYA-HMAC-SHA256
<TIMESTAMP>
<NONCE>
POST
/api/v1/publishing/campaigns/
<SHA256_BODY_HEX>
<IDEMPOTENCY_KEY>

کلید HMAC برابر SHA-256 بایت‌های UTF-8 کلید محرمانه است و امضا به‌صورت hex کوچک ارسال می‌شود.

قالب‌های قابل استفاده

مقصدها و تنظیمات پلتفرم از قالب موجود گرفته می‌شوند؛ API فقط کلید پایدار قالب را می‌فرستد.

برای بخش مجاز، یک قالب کمپین فعال با مقصدهای قابل استفاده بسازید.

نقطهٔ پایانی و بدنهٔ درخواست

درخواست POST باید JSON با HTML پالایش‌شدهٔ سازگار با کمپین و URL عمومی HTTPS رسانه داشته باشد.

POST
/api/v1/publishing/campaigns/
application/json
{
  "template": "breaking-news",
  "title": "عنوان خبر",
  "content": "<p>متن خبر...</p>",
  "media": [
    {
      "public_url": "https://example.com/media/news.jpg"
    }
  ]
}

پیگیری وضعیت عملیات

GET
/api/v1/publishing/requests/{request_id}/

نمونه‌های اتصال

نمونه‌ها الگوریتم واقعی امضا و Idempotency-Key را نشان می‌دهند. مقدارهای نمونه را با راز واقعی خود جایگزین کنید.

curl
#!/usr/bin/env sh
KEY_ID="ipub_REPLACE_ME"
SECRET="ipubsec_REPLACE_ME"
IDEMPOTENCY_KEY="cms-post-12345"
TIMESTAMP="$(date +%s)"
NONCE="$(openssl rand -hex 16)"
METHOD="POST"
PATH_VALUE="/api/v1/publishing/campaigns/"
BODY='{"template":"breaking-news","title":"عنوان خبر","content":"<p>متن خبر...</p>","media":[{"public_url":"https://example.com/media/news.jpg"}]}'
BODY_HASH="$(printf %s "$BODY" | openssl dgst -sha256 -binary | xxd -p -c 256)"
SIGNING_KEY_HEX="$(printf %s "$SECRET" | openssl dgst -sha256 -binary | xxd -p -c 256)"
CANONICAL="$(printf 'ILIYA-HMAC-SHA256\n%s\n%s\n%s\n%s\n%s\n%s' "$TIMESTAMP" "$NONCE" "$METHOD" "$PATH_VALUE" "$BODY_HASH" "$IDEMPOTENCY_KEY")"
SIGNATURE="$(printf %s "$CANONICAL" | openssl dgst -sha256 -mac HMAC -macopt "hexkey:$SIGNING_KEY_HEX" | awk '{print $NF}')"

curl -X POST "https://YOUR_ILIYA_HOST/api/v1/publishing/campaigns/" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "X-Iliya-Key-Id: $KEY_ID" \
  -H "X-Iliya-Timestamp: $TIMESTAMP" \
  -H "X-Iliya-Nonce: $NONCE" \
  -H "X-Iliya-Signature: $SIGNATURE" \
  --data-binary "$BODY"

محدودیت‌ها و سیاست رسانه

رسانه به‌صورت محدود و امن دریافت، با نوع واقعی بررسی و با سیاست پیش‌فرض امن در مخزن ایلیا ذخیره می‌شود.

محدودیت‌های فعلی و انواع رسانهٔ مجاز از نقطهٔ پایانی اتصال با درخواست امضاشده دریافت می‌شوند و به حساب و طرح شما وابسته‌اند.

پاسخ‌ها و خطاها

همهٔ خطاها دارای کد پایدار هستند. وضعیت عملیات پذیرفته‌شده را از status_url بخوانید.

202

عملیات پذیرفته شد یا نتیجهٔ همان کلید هم‌توانی بازگردانده شد.

400

بدنه، قالب، مقصد یا URL رسانه نامعتبر است.

401

امضا، زمان، nonce یا اعتبارنامه معتبر نیست.

403

بسته، زمینهٔ حساب یا بخش اجازهٔ استفاده ندارد.

404

درخواست در محدودهٔ این اعتبارنامه وجود ندارد.

409

کلید هم‌توانی قبلاً با بدنهٔ دیگری استفاده شده است.

413

بدنهٔ درخواست از حد مجاز بزرگ‌تر است؛ فایل راه‌دور بزرگ در وضعیت عملیات با REMOTE_MEDIA_TOO_LARGE شکست می‌خورد.

429

محدودیت نرخ اعمال شده؛ مقدار Retry-After را رعایت کنید.

503

صف یا سامانهٔ مشترک محدودسازی نرخ در دسترس نیست.