مرجع API

نمای کلی

API اس‌ان‌اس‌ترکر به شما اجازه می‌دهد فیدها و کانال‌های پایش را به‌صورت برنامه‌نویسی مدیریت کنید. می‌توانید فیدها (ویدئوها، پست‌ها و غیره) و کانال‌ها (اکانت‌ها، پروفایل‌ها) را ایجاد کنید، برای دریافت جدیدترین داده‌ها آن‌ها را رفرش کنید و از طریق وبهوک‌ها اعلان‌های لحظه‌ای دریافت کنید.

احراز هویت

تمام درخواست‌های API نیاز به احراز هویت با استفاده از کلید API دارند. کلید API خود را در هدر X-API-Key قرار دهید.

نحوه دریافت کلید API:

  1. وارد SNSTracker شوید
  2. به Settings → API Keys بروید
  3. یک کلید API جدید بسازید یا از کلید موجود استفاده کنید
  4. کلید API را کپی کنید (فقط هنگام ایجاد یک‌بار نمایش داده می‌شود)

نقاط پایانی API

1. ایجاد فیدها

با ارسال URL فیدها (ویدئوها، پست‌ها و غیره) فیدهای پایش ایجاد کنید.

POST /api/v1/feeds

درخواست

Headers:

  • X-API-Key: کلید API شما (الزامی)
  • Content-Type: application/json

Request Body:

{
  "urls": [
    "https://www.tiktok.com/@user/video/1234567890",
    "https://www.instagram.com/p/ABC123/"
  ],
  "collectionId": "coll_abc123xyz"
}

Parameters:

  • urls (الزامی): آرایه‌ای از URLهای فید برای پایش. حداکثر 200 URL در هر درخواست.
  • collectionId (اختیاری): شناسه کالکشن که فیدها به آن افزوده می‌شوند. اگر ارائه نشود، کالکشن پیش‌فرض تیم شما استفاده می‌شود.

پاسخ

Success Response (200):

{
  "code": 0,
  "message": "ok",
  "data": {
    "success": 2,
    "failed": 0,
    "total": 2,
    "results": [
      {
        "index": 0,
        "url": "https://www.tiktok.com/@user/video/1234567890",
        "platform": "tiktok",
        "feedId": "feed_abc123xyz",
        "success": true
      },
      {
        "index": 1,
        "url": "https://www.instagram.com/p/ABC123/",
        "platform": "instagram",
        "feedId": "feed_def456uvw",
        "success": true
      }
    ],
    "errors": [],
    "message": "Feeds created successfully. Data will be updated shortly."
  }
}

Response Fields:

  • success: تعداد فیدهای با موفقیت ایجادشده
  • failed: تعداد ایجاد فیدهای ناموفق
  • total: تعداد کل URLهای ارائه‌شده
  • results: آرایه‌ای از نتایج برای هر URL
    • index: اندیس صفرمبنا در آرایه درخواست
    • url: URL اعتبارسنجی‌شده و استانداردشده
    • platform: پلتفرم تشخیص‌داده‌شده (tiktok, instagram, youtube و غیره)
    • feedId: شناسه یکتای فید ایجادشده
    • success: آیا فید با موفقیت ایجاد شد یا خیر
    • skipped: (اختیاری) آیا فید به‌دلیل وجود قبلی رد شد
    • resumed: (اختیاری) آیا فید متوقف‌شده از سر گرفته شد
    • error: (اختیاری) پیام خطا در صورت شکست ایجاد
  • errors: آرایه خطاها برای URLهای ناموفق

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

curl -X POST https://snstracker.com/api/v1/feeds \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://www.tiktok.com/@user/video/1234567890"
    ]
  }'

2. رفرش فیدها

برای دریافت فوری جدیدترین داده‌ها، فیدهای موجود را رفرش کنید. فقط فیدهایی با وضعیت "Pending" یا "Tracked" قابل رفرش هستند.

POST /api/v1/feeds/refresh

درخواست

Headers:

  • X-API-Key: کلید API شما (الزامی)
  • Content-Type: application/json

Request Body:

{
  "feedIds": ["feed_abc123xyz", "feed_def456uvw"]
}

Parameters:

  • feedIds (الزامی): آرایه‌ای از شناسه‌های فید برای رفرش

پاسخ

Success Response (200):

{
  "code": 0,
  "message": "ok",
  "data": {
    "success": true,
    "feedIds": ["feed_abc123xyz", "feed_def456uvw"],
    "total": 2,
    "message": "Successfully refreshed 2 feed(s)"
  }
}

Response Fields:

  • success: آیا عملیات رفرش موفق بوده است یا خیر
  • feedIds: آرایه‌ای از شناسه‌های فید رفرش‌شده
  • total: تعداد فیدهای رفرش‌شده
  • message: پیام موفقیت

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

curl -X POST https://snstracker.com/api/v1/feeds/refresh \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "feedIds": ["feed_abc123xyz"]
  }'

3. ایجاد کانال‌ها

با ارسال URL کانال‌ها (پروفایل اکانت و غیره) کانال‌های پایش ایجاد کنید.

Channel pricing note: Xiaohongshu channel tasks are priced separately from the default channel task price and currently cost 10 credits per successful request.

POST /api/v1/channels

درخواست

Headers:

  • X-API-Key: کلید API شما (الزامی)
  • Content-Type: application/json

Request Body:

{
  "urls": [
    "https://www.tiktok.com/@username",
    "https://www.instagram.com/username/"
  ],
  "collectionId": "coll_abc123xyz"
}

Parameters:

  • urls (الزامی): آرایه‌ای از URLهای کانال برای پایش. حداکثر 5 URL در هر درخواست.
  • collectionId (اختیاری): شناسه کالکشن که کانال‌ها به آن افزوده می‌شوند. اگر ارائه نشود، کالکشن پیش‌فرض تیم شما استفاده می‌شود.

پاسخ

Success Response (200):

{
  "code": 0,
  "message": "ok",
  "data": {
    "success": 2,
    "failed": 0,
    "total": 2,
    "results": [
      {
        "index": 0,
        "url": "https://www.tiktok.com/@username",
        "platform": "tiktok",
        "channelId": "channel_abc123xyz",
        "success": true
      },
      {
        "index": 1,
        "url": "https://www.instagram.com/username/",
        "platform": "instagram",
        "channelId": "channel_def456uvw",
        "success": true
      }
    ],
    "errors": [],
    "message": "Channels created successfully. Data will be updated shortly."
  }
}

Response Fields:

  • success: تعداد کانال‌های با موفقیت ایجادشده
  • failed: تعداد ایجاد کانال‌های ناموفق
  • total: تعداد کل URLهای ارائه‌شده
  • results: آرایه‌ای از نتایج برای هر URL
    • index: اندیس صفرمبنا در آرایه درخواست
    • url: URL اعتبارسنجی‌شده و استانداردشده
    • platform: پلتفرم تشخیص‌داده‌شده (tiktok, instagram, youtube و غیره)
    • channelId: شناسه یکتای کانال ایجادشده
    • success: آیا کانال با موفقیت ایجاد شد یا خیر
    • skipped: (اختیاری) آیا کانال به‌دلیل وجود قبلی رد شد
    • resumed: (اختیاری) آیا کانال متوقف‌شده از سر گرفته شد
    • error: (اختیاری) پیام خطا در صورت شکست ایجاد
  • errors: آرایه خطاها برای URLهای ناموفق

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

curl -X POST https://snstracker.com/api/v1/channels \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://www.tiktok.com/@username"
    ]
  }'

4. رفرش کانال‌ها

برای دریافت فوری جدیدترین داده‌ها، کانال‌های موجود را رفرش کنید. فقط کانال‌هایی با وضعیت "Pending" یا "Tracked" قابل رفرش هستند.

Channel pricing note: Xiaohongshu channel tasks are priced separately from the default channel task price and currently cost 10 credits per successful request.

POST /api/v1/channels/refresh

درخواست

Headers:

  • X-API-Key: کلید API شما (الزامی)
  • Content-Type: application/json

Request Body:

{
  "channelIds": ["channel_abc123xyz", "channel_def456uvw"]
}

Parameters:

  • channelIds (الزامی): آرایه‌ای از شناسه‌های کانال برای رفرش

پاسخ

Success Response (200):

{
  "code": 0,
  "message": "ok",
  "data": {
    "success": true,
    "channelIds": ["channel_abc123xyz", "channel_def456uvw"],
    "total": 2,
    "message": "Successfully refreshed 2 channel(s)"
  }
}

Response Fields:

  • success: آیا عملیات رفرش موفق بوده است یا خیر
  • channelIds: آرایه‌ای از شناسه‌های کانال رفرش‌شده
  • total: تعداد کانال‌های رفرش‌شده
  • message: پیام موفقیت

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

curl -X POST https://snstracker.com/api/v1/channels/refresh \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "channelIds": ["channel_abc123xyz"]
  }'

5. همگام‌سازی فید

داده‌های فید را مستقیماً از سرویس اسکرپی همگام‌سازی کنید. این اندپوینت فوراً جدیدترین داده‌های فید را واکشی می‌کند و پس از همگام‌سازی موفق، اعتبار مصرف می‌کند. همه اعضا و کلیدهای API تیم برای همه مسیرهای همگام‌سازی یک محدودیت مشترک دارند. سقف مشترک برای استارتر یا بدون اشتراک معتبر 1، استاندارد 5 و پرمیوم 10 درخواست همزمان است.

⚠️ نکته مهم: این اندپوینت همگام‌سازی مستقل است و با پلتفرم وب ادغام نمی‌شود. عملیات همگام‌سازی:

  • هیچ رکورد فیدی را در داشبورد وب ایجاد یا به‌روزرسانی نمی‌کند
  • در فهرست فیدها یا کالکشن‌های شما نمایش داده نمی‌شود
  • وبهوک‌ها یا اعلان‌ها را فعال نمی‌کند
  • فقط داده‌های واکشی‌شده را مستقیم در پاسخ API برمی‌گرداند

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

POST /api/v1/feeds/sync

درخواست

Headers:

  • X-API-Key: کلید API شما (الزامی)
  • Content-Type: application/json

Request Body:

{
  "url": "https://www.tiktok.com/@user/video/1234567890"
}

Parameters:

  • url (الزامی): URL فید برای همگام‌سازی. باید یک رشته معتبر و غیرخالی باشد.

پاسخ

Success Response (200):

{
  "code": 0,
  "message": "ok",
  "data": {
    "success": true,
    "url": "https://www.tiktok.com/@user/video/1234567890",
    "feedInfo": {
      "feed_id": "1234567890",
      "platform": 1,
      "platform_name": "tiktok",
      "url": "https://www.tiktok.com/@user/video/1234567890",
      "views": 1000000,
      "likes": 200000,
      "comments": 1000,
      "shares": 2000,
      "bookmarks": 200,
      "engagement": 512000,
      "description": "Video description",
      "hashtags": ["tag1", "tag2"],
      "publish_at": 1234567890
    }
  }
}

Response Fields:

  • success: آیا عملیات همگام‌سازی موفق بوده است یا خیر
  • url: URL فید همگام‌سازی‌شده
  • feedInfo: اطلاعات کامل فید شامل متریک‌ها، توضیحات، هشتگ‌ها و غیره

Error Responses:

  • 429 Too Many Requests: محدودیت همزمانی مشترک تیم پر شده است. درخواست در صف قرار نمی‌گیرد.
  • 400 Bad Request: اعتبار ناکافی یا URL نامعتبر

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

curl -X POST https://snstracker.com/api/v1/feeds/sync \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.tiktok.com/@user/video/1234567890"
  }'

6. همگام‌سازی کانال

داده‌های کانال را مستقیماً از سرویس اسکرپی همگام‌سازی کنید. این اندپوینت فوراً جدیدترین داده‌های کانال را واکشی می‌کند و پس از همگام‌سازی موفق، اعتبار مصرف می‌کند. همه اعضا و کلیدهای API تیم برای همه مسیرهای همگام‌سازی یک محدودیت مشترک دارند. سقف مشترک برای استارتر یا بدون اشتراک معتبر 1، استاندارد 5 و پرمیوم 10 درخواست همزمان است.

Channel pricing note: Xiaohongshu channel tasks are priced separately from the default channel task price and currently cost 10 credits per successful request.

⚠️ نکته مهم: این اندپوینت همگام‌سازی مستقل است و با پلتفرم وب ادغام نمی‌شود. عملیات همگام‌سازی:

  • هیچ رکورد کانالی را در داشبورد وب ایجاد یا به‌روزرسانی نمی‌کند
  • در فهرست کانال‌ها یا کالکشن‌های شما نمایش داده نمی‌شود
  • وبهوک‌ها یا اعلان‌ها را فعال نمی‌کند
  • فقط داده‌های واکشی‌شده را مستقیم در پاسخ API برمی‌گرداند

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

POST /api/v1/channels/sync

درخواست

Headers:

  • X-API-Key: کلید API شما (الزامی)
  • Content-Type: application/json

Request Body:

{
  "url": "https://www.tiktok.com/@username"
}

Parameters:

  • url (الزامی): URL کانال برای همگام‌سازی. باید یک رشته معتبر و غیرخالی باشد.

پاسخ

Success Response (200):

{
  "code": 0,
  "message": "ok",
  "data": {
    "success": true,
    "url": "https://www.tiktok.com/@username",
    "channelInfo": {
      "id": "1234567890",
      "platform": 1,
      "platform_name": "tiktok",
      "username": "username",
      "nickname": "User Name",
      "description": "Channel description",
      "followers": 1000000,
      "followings": 2000,
      "likes": 200000000,
      "total_count": 1000,
      "track_count": 1000,
      "status": 1
    }
  }
}

Response Fields:

  • success: آیا عملیات همگام‌سازی موفق بوده است یا خیر
  • url: URL کانال همگام‌سازی‌شده
  • channelInfo: اطلاعات کامل کانال شامل متریک‌ها، توضیحات و غیره

Error Responses:

  • 429 Too Many Requests: محدودیت همزمانی مشترک تیم پر شده است. درخواست در صف قرار نمی‌گیرد.
  • 400 Bad Request: اعتبار ناکافی یا URL نامعتبر

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

curl -X POST https://snstracker.com/api/v1/channels/sync \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.tiktok.com/@username"
  }'

7. همگام‌سازی محتوای کانال

برای Instagram و Reels یک صفحه با حداکثر 12 مورد در هر درخواست برمی‌گرداند و خودکار به صفحه بعد نمی‌رود. instagram پست‌های تصویر، ویدیو و آلبوم را برمی‌گرداند؛ reels ویدیوهای Reels را.

POST /api/v1/channels/feeds/sync
X-API-Key: your-api-key
Content-Type: application/json

Request and pagination

{
  "platform": "instagram",
  "channel_name": "instagram"
}
  • count یک عدد صحیح مثبت اختیاری برای تعیین تعداد دلخواه موارد در این صفحه است و مقدار پیش‌فرض ندارد. محدودیت تعداد به پلتفرم بستگی دارد: Instagram و Reels در هر درخواست حداکثر 12 مورد برمی‌گردانند و تعداد واقعی ممکن است کمتر باشد. با حذف این پارامتر، اندازه پیش‌فرض صفحه پلتفرم استفاده می‌شود.
  • برای صفحه اول cursor را نفرستید. برای صفحه بعد، next_cursor قبلی را بدون تغییر با همان platform و channel_name ارسال کنید. در پایان: has_more=false و next_cursor=null.
{
  "platform": "instagram",
  "channel_name": "instagram",
  "cursor": "previous-next-cursor"
}

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

Response example (placeholder cursor) — reels, lunacut.edit, count=1

{
  "code": 0,
  "message": "ok",
  "data": {
    "success": true,
    "platform": "reels",
    "channel_name": "lunacut.edit",
    "channel_url": "https://www.instagram.com/lunacut.edit/",
    "requested_count": 1,
    "returned_count": 1,
    "has_more": true,
    "next_cursor": "cursor-from-response",
    "items": [
      {
        "feed_id": "4009169989985582972",
        "platform": 5,
        "platform_name": "reels",
        "type": "video",
        "url": "https://www.instagram.com/reel/Dejbt1JPz98/",
        "author_username": "lunacut.edit",
        "publish_at": 1792150387,
        "duration": 70.077,
        "view_count": 310475
      }
    ]
  }
}

platform and channel_name are required. channel_name is the username, not the display name; leading @ is accepted and dots are preserved. requested_count is null when count is omitted; returned_count equals items.length. Unknown metrics/timestamps are null. Posts may lack timestamps and carousel details. items uses the existing feed fields, including video_url, image_urls and cover_url; the example shows only selected fields. publish_at is Unix seconds and duration is seconds. Upstream order is preserved, without a most-popular sorting option; deduplicate across pages by feed_id. Empty pages can still have a next cursor; a carousel counts as one post.

معیارهای موجود در items، مانند بازدید (view_count)، پسندیدن (like_count)، ذخیره (bookmark_count) و نظر (comment_count)، به پلتفرم و داده‌های فهرست محتوای آن بستگی دارند. ممکن است برخی معیارها در دسترس نباشند. معیارهای دریافت‌نشده با مقدار null برگردانده می‌شوند؛ این مقدار به معنی صفر نیست.

برای بررسی معیارهای موجودنبوده در فهرست، POST /api/v1/feeds/sync را جداگانه فراخوانی کنید و url آن مورد را در فیلد url بدنه درخواست قرار دهید. درخواست جزئیات طبق قوانین همان رابط، جداگانه محاسبه می‌شود. نتیجه همچنان به داده‌های ارائه‌شده توسط پلتفرم بستگی دارد و دریافت همه معیارهای ناقص تضمین نمی‌شود.

HTTP: 400 invalid input/cursor or insufficient initial credits; 401 invalid API key; 403 disabled team or inaccessible channel; 402 insufficient credits at settlement; 429 team concurrency limit (Retry-After: 1); 502 upstream/invalid page; 503 service unavailable; 504 timeout.

8. دریافت اطلاعات تکمیلی پروفایل

POST /api/v1/channels/about/sync

فقط Instagram و Reels پشتیبانی می‌شوند. ورودی همان url اجباری در /api/v1/channels/sync است: https://www.instagram.com/lunacut.edit/ یا https://www.instagram.com/lunacut.edit/reels/. به platform، count یا cursor نیازی نیست. لینک پست و پلتفرم‌های دیگر پشتیبانی نمی‌شوند.

curl -X POST https://snstracker.com/api/v1/channels/about/sync \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.instagram.com/lunacut.edit/"}'

هر درخواست موفق 80 اعتبار هزینه دارد، حتی اگر فیلدها null باشند. خطا هزینه ندارد؛ پیش از درخواست حداقل 80 اعتبار لازم است. سقف همزمانی با تمام APIهای همگام تیم مشترک است: Starter/بدون اشتراک فعال 1، Standard 5، Premium 10. رکورد داشبورد یا webhook ایجاد نمی‌شود.

نمونه پاسخ؛ موجود بودن فیلدها به اطلاعات عمومی حساب بستگی دارد.

{
  "code": 0,
  "message": "ok",
  "data": {
    "success": true,
    "url": "https://www.instagram.com/lunacut.edit/",
    "channelAbout": {
      "platform": 6,
      "platform_name": "instagram",
      "username": "lunacut.edit",
      "channel_url": "https://www.instagram.com/lunacut.edit/",
      "country": "Brazil",
      "country_visible": true,
      "date_joined": "2020-05",
      "date_joined_text": "May 2020"
    }
  }
}

country: کشور/منطقه عمومی فقط وقتی country_visible=true است؛ مکان لحظه‌ای IP نیست. country_visible: وضعیت نمایش یا null اگر نامعلوم باشد. date_joined: ماه عضویت با قالب YYYY-MM یا null در صورت نبودن یا ناشناخته بودن. date_joined_text: متن اصلی تاریخ یا null. بیو، تعداد دنبال‌کنندگان و نام‌های قبلی شامل نمی‌شوند.

400 / 401 / 402 / 403 / 429 (Retry-After: 1) / 502 / 503 / 504.

یکپارچه‌سازی وبهوک

SNSTracker از وبهوک‌ها پشتیبانی می‌کند تا زمانی که محتوای پایش‌شده به آستانه‌های پیکربندی‌شده شما برسد، اعلان‌های لحظه‌ای دریافت کنید. می‌توانید وبهوک‌ها را برای دریافت اعلان درباره موارد زیر پیکربندی کنید:

  • به‌روزرسانی فید: وقتی بازدیدها و تعامل (لایک + کامنت + اشتراک‌گذاری) به اندازه آستانه شما افزایش یابد
  • به‌روزرسانی کانال: وقتی دنبال‌کننده‌ها، دنبال‌شونده‌ها یا لایک‌ها به اندازه آستانه شما افزایش یابد

راه‌اندازی وبهوک‌ها

  1. اهداف وبهوک را پیکربندی کنید در تنظیمات کالکشن‌ها
  2. اعلان‌ها را فعال کنید در پیکربندی کالکشن
  3. آستانه‌ها را تنظیم کنید برای متریک‌هایی که می‌خواهید پایش کنید

برای دستورالعمل‌های دقیق پیکربندی وبهوک، لطفاً به Webhook Configuration Guide مراجعه کنید.

پاسخ‌های خطا

همه اندپوینت‌ها ممکن است پاسخ‌های خطای زیر را برگردانند:

401 Unauthorized - Missing API Key

{
  "code": -1,
  "message": "X-API-Key header is required"
}

401 Unauthorized - Invalid API Key

{
  "code": -1,
  "message": "Invalid API key"
}

400 Bad Request - Invalid Input

{
  "code": -1,
  "message": "Invalid request: urls must be an array"
}

400 Bad Request - Too Many URLs (Create Feeds)

{
  "code": -1,
  "message": "Maximum 200 URLs allowed per request"
}

400 Bad Request - Too Many URLs (Create Channels)

{
  "code": -1,
  "message": "Maximum 200 URLs allowed per request"
}

400 Bad Request - Insufficient Credits

{
  "code": -1,
  "message": "Insufficient credits. Required: 10, Available: 5"
}

429 Too Many Requests - محدودیت همگام‌سازی همزمان تیم

{
  "code": -1,
  "message": "Maximum concurrent sync requests (1) reached for this team. Currently active: 1. Wait for a request to complete, or contact official support to increase the limit."
}

403 Forbidden - Invalid Collection

{
  "code": -1,
  "message": "Collection not found or does not belong to your team"
}

404 Not Found

{
  "code": -1,
  "message": "No feeds found"
}

or

{
  "code": -1,
  "message": "No channels found"
}

نمونه‌های استفاده

نمونه پایتون - ایجاد فیدها

import requests

url = "https://snstracker.com/api/v1/feeds"
headers = {
    "X-API-Key": "your-api-key-here",
    "Content-Type": "application/json"
}
data = {
    "urls": [
        "https://www.tiktok.com/@user/video/1234567890",
        "https://www.instagram.com/p/ABC123/"
    ]
}

response = requests.post(url, json=data, headers=headers)
result = response.json()

if result["code"] == 0:
    print(f"Successfully created {result['data']['success']} feeds")
    for feed in result["data"]["results"]:
        print(f"  - {feed['url']}: {feed['feedId']}")
else:
    print(f"Error: {result['message']}")

نمونه جاوااسکریپت - رفرش فیدها

const response = await fetch('https://snstracker.com/api/v1/feeds/refresh', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your-api-key-here',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    feedIds: ['feed_abc123xyz', 'feed_def456uvw'],
  }),
});

const result = await response.json();

if (result.code === 0) {
  console.log(`Successfully refreshed ${result.data.total} feeds`);
  result.data.feedIds.forEach((feedId) => {
    console.log(`  - ${feedId}`);
  });
} else {
  console.error(`Error: ${result.message}`);
}

نکات مهم

  1. اعتبارسنجی URL: همه URLها قبل از ایجاد به‌طور خودکار اعتبارسنجی می‌شوند. URLهای نامعتبر رد خواهند شد.

  2. اقلام تکراری: اگر آیتمی با همان URL از قبل در کالکشن وجود داشته باشد:

    • اگر فعال باشد، رد می‌شود (با skipped: true مشخص می‌شود)
    • اگر متوقف شده باشد، از سر گرفته می‌شود (با resumed: true مشخص می‌شود)
  3. گردآوری داده: پس از ایجاد موفق، آیتم‌ها برای گردآوری داده در صف قرار می‌گیرند. داده‌ها کمی بعد از ایجاد در دسترس خواهند بود.

  4. وضعیت رفرش: فقط آیتم‌هایی با وضعیت "Pending" یا "Tracked" قابل رفرش هستند. آیتم‌هایی با وضعیت‌های دیگر فیلتر می‌شوند.

  5. اعتبارها: قبل از ارسال درخواست‌ها مطمئن شوید اعتبار کافی دارید. عملیات همگام‌سازی بلافاصله پس از دریافت موفق داده، اعتبار مصرف می‌کنند. Xiaohongshu channel tasks are priced separately and currently cost 10 credits per successful request. /api/v1/channels/feeds/sync: هر صفحه موفق، حتی صفحه خالی، 10 اعتبار هزینه دارد. فقط درخواست ناموفق رایگان است؛ پیش از درخواست حداقل 10 اعتبار لازم است. محدودیت همزمانی تیم با دیگر APIهای همگام‌سازی مشترک است و رکورد داشبورد ایجاد نمی‌شود. /api/v1/channels/about/sync: هر درخواست موفق 80 اعتبار هزینه دارد، حتی اگر فیلدها null باشند. خطا هزینه ندارد؛ پیش از درخواست حداقل 80 اعتبار لازم است. سقف همزمانی با تمام APIهای همگام تیم مشترک است: Starter/بدون اشتراک فعال 1، Standard 5، Premium 10. رکورد داشبورد یا webhook ایجاد نمی‌شود.

  6. محدودیت همگام‌سازی همزمان تیم (/api/v1/feeds/sync + /api/v1/channels/sync + /api/v1/channels/feeds/sync + /api/v1/channels/about/sync): همه اعضا و کلیدهای API تیم برای همه مسیرهای همگام‌سازی یک محدودیت مشترک دارند. سقف مشترک برای استارتر یا بدون اشتراک معتبر 1، استاندارد 5 و پرمیوم 10 درخواست همزمان است. سقف به‌طور خودکار از اشتراک معتبر فعلی پیروی می‌کند؛ تنظیم اختصاصی تیم توسط پشتیبانی رسمی اولویت دارد. برای افزایش محدودیت تیم، با پشتیبانی رسمی تماس بگیرید.

  7. همگام‌سازی در برابر ایجاد: اندپوینت‌های همگام‌سازی (/api/v1/feeds/sync و /api/v1/channels/sync + /api/v1/channels/feeds/sync + /api/v1/channels/about/sync) مستقل هستند و با پلتفرم وب ادغام نمی‌شوند. آن‌ها فقط داده را در پاسخ API برمی‌گردانند و در داشبورد رکوردی ایجاد نمی‌کنند. برای ایجاد آیتم‌های پایش ماندگار که در پلتفرم وب نمایش داده شوند، از اندپوینت‌های Create (/api/v1/feeds و /api/v1/channels) استفاده کنید.

  8. تلاش دوباره: پس از 429، منتظر پایان یک درخواست فعال بمانید و با رعایت Retry-After و افزایش فاصله زمانی دوباره تلاش کنید. پس از 503، بعداً تلاش کنید.

  9. پلتفرم‌های پشتیبانی‌شده: TikTok، Instagram، YouTube و سایر پلتفرم‌های اصلی شبکه‌های اجتماعی.

عیب‌یابی

مشکل: "X-API-Key header is required"
راه‌حل: مطمئن شوید هدر X-API-Key را در درخواست خود قرار داده‌اید.

مشکل: "Invalid API key"
راه‌حل: بررسی کنید کلید API شما درست است. می‌توانید از Settings → API Keys یک کلید جدید بسازید.

مشکل: "Maximum URLs allowed per request"
راه‌حل: URLهای خود را به چند درخواست تقسیم کنید. فیدها تا 200 URL و کانال‌ها تا 5 URL در هر درخواست اجازه دارند.

مشکل: "No collection found"
راه‌حل: ابتدا در داشبورد یک کالکشن بسازید، یا شناسه یک کالکشن موجود را مشخص کنید.

مشکل: "Insufficient credits"
راه‌حل: اعتبار بیشتری خریداری کنید یا پلن اشتراک خود را بررسی کنید.

مشکل: "No refreshable items found"
راه‌حل: فقط آیتم‌هایی با وضعیت "Pending" یا "Tracked" قابل رفرش هستند. وضعیت آیتم‌های خود را بررسی کنید.

مشکل: برخی URLها اعتبارسنجی را رد می‌شوند
راه‌حل: آرایه errors در پاسخ را برای پیام‌های خطای مشخص بررسی کنید. مطمئن شوید URLها از پلتفرم‌های پشتیبانی‌شده هستند و دسترسی عمومی دارند.