مستندات عمومی API
وبسایت یا CMS شما میتواند محتوا را با یک قالب کمپین آماده به مقصدهای ایلیا ارسال کند.
عملیات پشتیبانیشده
برای تمام فیلدهای درخواست و ساختار پاسخها، مرجع تعاملی را ببینید.
بررسی اتصال
/api/v1/publishing/connection/فهرست قالبها
/api/v1/publishing/catalog/templates/بارگذاری رسانه
/api/v1/publishing/media/وضعیت رسانه
/api/v1/publishing/media/{media_id}/ایجاد انتشار
/api/v1/publishing/campaigns/وضعیت انتشار
/api/v1/publishing/requests/{request_id}/احراز هویت و امضای درخواست
هر درخواست با HMAC-SHA256، زمان، nonce و هش دقیق بدنه امضا میشود.
رشتهٔ زیر را دقیقاً با نویسهٔ خط جدید LF بسازید. مسیر باید همان مسیر درخواست و هش بدنه باید SHA-256 بایتهای دقیق بدنه باشد.
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 رسانه داشته باشد.
/api/v1/publishing/campaigns/{
"template": "breaking-news",
"title": "عنوان خبر",
"content": "<p>متن خبر...</p>",
"media": [
{
"public_url": "https://example.com/media/news.jpg"
}
]
}پیگیری وضعیت عملیات
/api/v1/publishing/requests/{request_id}/نمونههای اتصال
نمونهها الگوریتم واقعی امضا و Idempotency-Key را نشان میدهند. مقدارهای نمونه را با راز واقعی خود جایگزین کنید.
#!/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 بخوانید.
عملیات پذیرفته شد یا نتیجهٔ همان کلید همتوانی بازگردانده شد.
بدنه، قالب، مقصد یا URL رسانه نامعتبر است.
امضا، زمان، nonce یا اعتبارنامه معتبر نیست.
بسته، زمینهٔ حساب یا بخش اجازهٔ استفاده ندارد.
درخواست در محدودهٔ این اعتبارنامه وجود ندارد.
کلید همتوانی قبلاً با بدنهٔ دیگری استفاده شده است.
بدنهٔ درخواست از حد مجاز بزرگتر است؛ فایل راهدور بزرگ در وضعیت عملیات با REMOTE_MEDIA_TOO_LARGE شکست میخورد.
محدودیت نرخ اعمال شده؛ مقدار Retry-After را رعایت کنید.
صف یا سامانهٔ مشترک محدودسازی نرخ در دسترس نیست.