SNSTrackerSNSTracker

Tham chiếu API

Tổng quan

API SNSTracker cho phép bạn quản lý các feed và kênh theo dõi bằng lập trình. Bạn có thể tạo feed (video, bài đăng, v.v.) và kênh (tài khoản, hồ sơ), làm mới chúng để lấy dữ liệu mới nhất và nhận thông báo theo thời gian thực qua webhook.

Xác thực

Tất cả yêu cầu API đều cần xác thực bằng API key. Hãy đưa API key vào header X-API-Key.

Cách lấy API key:

  1. Đăng nhập vào SNSTracker
  2. Vào Settings → API Keys
  3. Tạo API key mới hoặc dùng key hiện có
  4. Sao chép API key (bạn chỉ thấy một lần khi tạo)

Điểm cuối API

1. Tạo Feed

Tạo các feed theo dõi bằng cách gửi URL của feed (video, bài đăng, v.v.).

POST /api/v1/feeds

Yêu cầu

Headers:

  • X-API-Key: API key của bạn (bắt buộc)
  • Content-Type: application/json

Request Body:

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

Tham số:

  • urls (bắt buộc): Mảng URL feed cần theo dõi. Tối đa 200 URL mỗi yêu cầu.
  • collectionId (tùy chọn): ID bộ sưu tập nơi các feed sẽ được thêm. Nếu không cung cấp, sẽ dùng bộ sưu tập mặc định của nhóm bạn.

Phản hồi

Phản hồi thành công (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."
  }
}

Trường phản hồi:

  • success: Số feed tạo thành công
  • failed: Số feed tạo thất bại
  • total: Tổng số URL được cung cấp
  • results: Mảng kết quả cho từng URL
    • index: Chỉ số bắt đầu từ 0 trong mảng yêu cầu
    • url: URL đã được xác thực và chuẩn hóa
    • platform: Nền tảng được phát hiện (tiktok, instagram, youtube, v.v.)
    • feedId: Định danh duy nhất của feed đã tạo
    • success: Feed có được tạo thành công hay không
    • skipped: (tùy chọn) Feed bị bỏ qua vì đã tồn tại
    • resumed: (tùy chọn) Feed đã dừng được khôi phục
    • error: (tùy chọn) Thông báo lỗi nếu tạo thất bại
  • errors: Mảng lỗi cho các URL thất bại

Ví dụ yêu cầu

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. Làm mới Feed

Làm mới các feed hiện có để lấy dữ liệu mới nhất ngay lập tức. Chỉ những feed có trạng thái "Pending" hoặc "Tracked" mới có thể làm mới.

POST /api/v1/feeds/refresh

Yêu cầu

Headers:

  • X-API-Key: API key của bạn (bắt buộc)
  • Content-Type: application/json

Request Body:

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

Tham số:

  • feedIds (bắt buộc): Mảng ID feed cần làm mới

Phản hồi

Phản hồi thành công (200):

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

Trường phản hồi:

  • success: Thao tác làm mới có thành công hay không
  • feedIds: Mảng ID feed đã được làm mới
  • total: Số feed đã được làm mới
  • message: Thông báo thành công

Ví dụ yêu cầu

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. Tạo Kênh

Tạo các kênh theo dõi bằng cách gửi URL kênh (hồ sơ tài khoản, v.v.).

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

Yêu cầu

Headers:

  • X-API-Key: API key của bạn (bắt buộc)
  • Content-Type: application/json

Request Body:

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

Tham số:

  • urls (bắt buộc): Mảng URL kênh cần theo dõi. Tối đa 5 URL mỗi yêu cầu.
  • collectionId (tùy chọn): ID bộ sưu tập nơi các kênh sẽ được thêm. Nếu không cung cấp, sẽ dùng bộ sưu tập mặc định của nhóm bạn.

Phản hồi

Phản hồi thành công (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."
  }
}

Trường phản hồi:

  • success: Số kênh tạo thành công
  • failed: Số kênh tạo thất bại
  • total: Tổng số URL được cung cấp
  • results: Mảng kết quả cho từng URL
    • index: Chỉ số bắt đầu từ 0 trong mảng yêu cầu
    • url: URL đã được xác thực và chuẩn hóa
    • platform: Nền tảng được phát hiện (tiktok, instagram, youtube, v.v.)
    • channelId: Định danh duy nhất của kênh đã tạo
    • success: Kênh có được tạo thành công hay không
    • skipped: (tùy chọn) Kênh bị bỏ qua vì đã tồn tại
    • resumed: (tùy chọn) Kênh đã dừng được khôi phục
    • error: (tùy chọn) Thông báo lỗi nếu tạo thất bại
  • errors: Mảng lỗi cho các URL thất bại

Ví dụ yêu cầu

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. Làm mới Kênh

Làm mới các kênh hiện có để lấy dữ liệu mới nhất ngay lập tức. Chỉ những kênh có trạng thái "Pending" hoặc "Tracked" mới có thể làm mới.

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

Yêu cầu

Headers:

  • X-API-Key: API key của bạn (bắt buộc)
  • Content-Type: application/json

Request Body:

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

Tham số:

  • channelIds (bắt buộc): Mảng ID kênh cần làm mới

Phản hồi

Phản hồi thành công (200):

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

Trường phản hồi:

  • success: Thao tác làm mới có thành công hay không
  • channelIds: Mảng ID kênh đã được làm mới
  • total: Số kênh đã được làm mới
  • message: Thông báo thành công

Ví dụ yêu cầu

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. Đồng bộ Feed

Đồng bộ dữ liệu feed trực tiếp từ dịch vụ scrapy. Endpoint này lấy dữ liệu feed mới nhất ngay lập tức và trừ credit khi đồng bộ thành công. Tất cả thành viên và API key của nhóm dùng chung một giới hạn cho tất cả endpoint đồng bộ. Giới hạn dùng chung là 1 cho Starter hoặc khi không có gói đăng ký còn hiệu lực, 5 cho Standard và 10 cho Premium.

⚠️ Lưu ý quan trọng: Endpoint đồng bộ này là độc lập và KHÔNG tích hợp với nền tảng web. Các thao tác đồng bộ sẽ:

  • KHÔNG tạo hoặc cập nhật bản ghi feed trên dashboard web
  • KHÔNG hiển thị trong danh sách feed hoặc bộ sưu tập của bạn
  • KHÔNG kích hoạt webhook hoặc thông báo
  • CHỈ trả dữ liệu đã lấy trực tiếp trong phản hồi API

Endpoint này được thiết kế cho việc lấy dữ liệu một lần qua API. Để tạo các feed theo dõi lâu dài xuất hiện trên nền tảng web, hãy dùng endpoint Create Feeds.

POST /api/v1/feeds/sync

Yêu cầu

Headers:

  • X-API-Key: API key của bạn (bắt buộc)
  • Content-Type: application/json

Request Body:

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

Tham số:

  • url (bắt buộc): URL feed cần đồng bộ. Phải là chuỗi hợp lệ, không rỗng.

Phản hồi

Phản hồi thành công (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
    }
  }
}

Trường phản hồi:

  • success: Thao tác đồng bộ có thành công hay không
  • url: URL feed đã đồng bộ
  • feedInfo: Thông tin feed đầy đủ bao gồm chỉ số, mô tả, hashtag, v.v.

Phản hồi lỗi:

  • 429 Too Many Requests: Đã đạt giới hạn đồng thời chung của nhóm. Yêu cầu không được đưa vào hàng đợi.
  • 400 Bad Request: Thiếu credit hoặc URL không hợp lệ

Ví dụ yêu cầu

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. Đồng bộ Kênh

Đồng bộ dữ liệu kênh trực tiếp từ dịch vụ scrapy. Endpoint này lấy dữ liệu kênh mới nhất ngay lập tức và trừ credit khi đồng bộ thành công. Tất cả thành viên và API key của nhóm dùng chung một giới hạn cho tất cả endpoint đồng bộ. Giới hạn dùng chung là 1 cho Starter hoặc khi không có gói đăng ký còn hiệu lực, 5 cho Standard và 10 cho Premium.

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

⚠️ Lưu ý quan trọng: Endpoint đồng bộ này là độc lập và KHÔNG tích hợp với nền tảng web. Các thao tác đồng bộ sẽ:

  • KHÔNG tạo hoặc cập nhật bản ghi kênh trên dashboard web
  • KHÔNG hiển thị trong danh sách kênh hoặc bộ sưu tập của bạn
  • KHÔNG kích hoạt webhook hoặc thông báo
  • CHỈ trả dữ liệu đã lấy trực tiếp trong phản hồi API

Endpoint này được thiết kế cho việc lấy dữ liệu một lần qua API. Để tạo các kênh theo dõi lâu dài xuất hiện trên nền tảng web, hãy dùng endpoint Create Channels.

POST /api/v1/channels/sync

Yêu cầu

Headers:

  • X-API-Key: API key của bạn (bắt buộc)
  • Content-Type: application/json

Request Body:

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

Tham số:

  • url (bắt buộc): URL kênh cần đồng bộ. Phải là chuỗi hợp lệ, không rỗng.

Phản hồi

Phản hồi thành công (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
    }
  }
}

Trường phản hồi:

  • success: Thao tác đồng bộ có thành công hay không
  • url: URL kênh đã đồng bộ
  • channelInfo: Thông tin kênh đầy đủ bao gồm chỉ số, mô tả, v.v.

Phản hồi lỗi:

  • 429 Too Many Requests: Đã đạt giới hạn đồng thời chung của nhóm. Yêu cầu không được đưa vào hàng đợi.
  • 400 Bad Request: Thiếu credit hoặc URL không hợp lệ

Ví dụ yêu cầu

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. Đồng bộ nội dung kênh

Trả về một trang, tối đa 12 mục mỗi yêu cầu cho Instagram và Reels, không tự động tải trang tiếp theo. instagram gồm ảnh, video và bài carousel; reels trả về video 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 là số nguyên dương không bắt buộc, chỉ số mục mong muốn trên trang này và không có giá trị mặc định. Giới hạn tùy theo nền tảng: Instagram và Reels trả về tối đa 12 mục mỗi yêu cầu, số mục thực tế có thể ít hơn. Nếu bỏ qua, kích thước trang mặc định của nền tảng được sử dụng.
  • Bỏ cursor để lấy trang đầu. Với trang tiếp theo, gửi nguyên next_cursor trước đó, giữ nguyên platform và channel_name. Khi hết trang: has_more=false, next_cursor=null.
{
  "platform": "instagram",
  "channel_name": "instagram",
  "cursor": "previous-next-cursor"
}

Mỗi trang được lấy thành công tốn 10 tín dụng, kể cả trang rỗng. Chỉ yêu cầu thất bại mới không tính phí; cần ít nhất 10 tín dụng trước khi gọi. Dùng chung giới hạn đồng thời của nhóm với các API đồng bộ khác và không tạo bản ghi trên bảng điều khiển.

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.

Các chỉ số trong items, như lượt xem (view_count), lượt thích (like_count), lượt lưu (bookmark_count) và bình luận (comment_count), phụ thuộc vào nền tảng và dữ liệu danh sách nội dung của nền tảng đó. Một số chỉ số có thể không khả dụng. Chỉ số không lấy được trả về null, không có nghĩa là 0.

Để tra cứu các chỉ số còn thiếu, hãy gọi riêng POST /api/v1/feeds/sync, truyền url của mục vào trường url trong nội dung yêu cầu. Yêu cầu chi tiết được tính phí riêng theo quy định của endpoint đó. Kết quả vẫn phụ thuộc vào dữ liệu nền tảng cung cấp; không bảo đảm lấy được tất cả chỉ số còn thiếu.

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. Lấy thông tin bổ sung của hồ sơ

POST /api/v1/channels/about/sync

Chỉ hỗ trợ Instagram và Reels. Đầu vào url bắt buộc giống /api/v1/channels/sync: https://www.instagram.com/lunacut.edit/ hoặc https://www.instagram.com/lunacut.edit/reels/. Không cần platform, count, cursor. Không hỗ trợ liên kết bài đăng hoặc nền tảng khác.

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/"}'

Mỗi yêu cầu thành công tốn 80 tín dụng, kể cả khi các trường là null. Lỗi không bị tính phí; cần ít nhất 80 tín dụng trước khi gọi. Dùng chung giới hạn đồng thời của nhóm với mọi API đồng bộ: Starter/không có thuê bao hiệu lực 1, Standard 5, Premium 10. Không tạo bản ghi bảng điều khiển hay webhook.

Phản hồi minh họa; trường dữ liệu phụ thuộc thông tin công khai của tài khoản.

{
  "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: quốc gia/khu vực công khai chỉ khi country_visible=true, không phải vị trí IP thời gian thực. country_visible: trạng thái công khai hoặc null nếu chưa rõ. date_joined: tháng tham gia (YYYY-MM), null nếu thiếu/không nhận dạng. date_joined_text: văn bản ngày gốc hoặc null. Không có bio, số người theo dõi hay tên cũ.

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

Tích hợp Webhook

SNSTracker hỗ trợ webhook để nhận thông báo theo thời gian thực khi nội dung được theo dõi đạt ngưỡng bạn cấu hình. Bạn có thể cấu hình webhook để nhận thông báo về:

  • Cập nhật feed: Khi lượt xem, tương tác (like + bình luận + chia sẻ) tăng theo ngưỡng của bạn
  • Cập nhật kênh: Khi số người theo dõi, đang theo dõi hoặc lượt thích tăng theo ngưỡng của bạn

Thiết lập Webhook

  1. Cấu hình đích webhook trong phần cài đặt Collections
  2. Bật thông báo trong cấu hình Collection của bạn
  3. Thiết lập ngưỡng cho các chỉ số bạn muốn theo dõi

Để biết hướng dẫn chi tiết về cấu hình webhook, vui lòng tham khảo Hướng dẫn cấu hình Webhook.

Phản hồi lỗi

Tất cả các endpoint có thể trả về các phản hồi lỗi sau:

401 Unauthorized - Thiếu API Key

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

401 Unauthorized - API Key không hợp lệ

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

400 Bad Request - Dữ liệu đầu vào không hợp lệ

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

400 Bad Request - Quá nhiều URL (Tạo Feed)

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

400 Bad Request - Quá nhiều URL (Tạo Kênh)

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

400 Bad Request - Không đủ Credit

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

429 Too Many Requests - Giới hạn đồng thời của nhóm

{
  "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 - Bộ sưu tập không hợp lệ

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

404 Not Found

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

hoặc

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

Ví dụ sử dụng

Ví dụ Python - Tạo Feed

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']}")

Ví dụ JavaScript - Làm mới Feed

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}`);
}

Lưu ý quan trọng

  1. Xác thực URL: Tất cả URL được tự động xác thực trước khi tạo. URL không hợp lệ sẽ bị từ chối.

  2. Mục trùng lặp: Nếu một mục có cùng URL đã tồn tại trong bộ sưu tập:

    • Nếu đang hoạt động, sẽ bị bỏ qua (đánh dấu skipped: true)
    • Nếu đã dừng, sẽ được khôi phục (đánh dấu resumed: true)

  3. Thu thập dữ liệu: Sau khi tạo thành công, các mục sẽ được xếp hàng để thu thập dữ liệu. Dữ liệu sẽ có sẵn trong thời gian ngắn sau khi tạo.

  4. Trạng thái làm mới: Chỉ những mục có trạng thái "Pending" hoặc "Tracked" mới có thể làm mới. Các mục có trạng thái khác sẽ bị lọc bỏ.

  5. Credit: Hãy đảm bảo bạn có đủ credit trước khi gửi yêu cầu. Các thao tác đồng bộ trừ credit ngay khi lấy dữ liệu thành công. Xiaohongshu channel tasks are priced separately and currently cost 10 credits per successful request. /api/v1/channels/feeds/sync: Mỗi trang được lấy thành công tốn 10 tín dụng, kể cả trang rỗng. Chỉ yêu cầu thất bại mới không tính phí; cần ít nhất 10 tín dụng trước khi gọi. Dùng chung giới hạn đồng thời của nhóm với các API đồng bộ khác và không tạo bản ghi trên bảng điều khiển. /api/v1/channels/about/sync: Mỗi yêu cầu thành công tốn 80 tín dụng, kể cả khi các trường là null. Lỗi không bị tính phí; cần ít nhất 80 tín dụng trước khi gọi. Dùng chung giới hạn đồng thời của nhóm với mọi API đồng bộ: Starter/không có thuê bao hiệu lực 1, Standard 5, Premium 10. Không tạo bản ghi bảng điều khiển hay webhook.

  6. Giới hạn đồng thời của nhóm (/api/v1/feeds/sync + /api/v1/channels/sync + /api/v1/channels/feeds/sync + /api/v1/channels/about/sync): Tất cả thành viên và API key của nhóm dùng chung một giới hạn cho tất cả endpoint đồng bộ. Giới hạn dùng chung là 1 cho Starter hoặc khi không có gói đăng ký còn hiệu lực, 5 cho Standard và 10 cho Premium. Giới hạn tự động theo gói đăng ký đang có hiệu lực; cấu hình riêng cho nhóm do hỗ trợ chính thức đặt sẽ được ưu tiên. Để tăng giới hạn của nhóm, hãy liên hệ hỗ trợ chính thức.

  7. Đồng bộ vs Tạo: Các endpoint đồng bộ (/api/v1/feeds/sync và /api/v1/channels/sync + /api/v1/channels/feeds/sync + /api/v1/channels/about/sync) là độc lập và KHÔNG tích hợp với nền tảng web. Chúng chỉ trả dữ liệu trong phản hồi API và không tạo bản ghi trên dashboard. Để tạo các mục theo dõi lâu dài xuất hiện trên nền tảng web, hãy dùng các endpoint Tạo (/api/v1/feeds và /api/v1/channels).

  8. Thử lại: Sau phản hồi 429, chờ một yêu cầu đang chạy hoàn tất rồi thử lại với khoảng chờ tăng dần, tuân theo Retry-After. Sau phản hồi 503, hãy thử lại sau.

  9. Nền tảng được hỗ trợ: TikTok, Instagram, YouTube và các nền tảng mạng xã hội lớn khác.

Khắc phục sự cố

Vấn đề: "X-API-Key header is required"
Giải pháp: Đảm bảo bạn đã thêm header X-API-Key trong yêu cầu.

Vấn đề: "Invalid API key"
Giải pháp: Kiểm tra API key của bạn có đúng không. Bạn có thể tạo key mới trong Settings → API Keys.

Vấn đề: "Maximum URLs allowed per request"
Giải pháp: Chia URL thành nhiều yêu cầu. Feed cho phép tối đa 200 URL, kênh cho phép tối đa 5 URL mỗi yêu cầu.

Vấn đề: "No collection found"
Giải pháp: Tạo bộ sưu tập trước trong dashboard hoặc chỉ định một collection ID hiện có.

Vấn đề: "Insufficient credits"
Giải pháp: Mua thêm credit hoặc kiểm tra gói đăng ký của bạn.

Vấn đề: "No refreshable items found"
Giải pháp: Chỉ những mục có trạng thái "Pending" hoặc "Tracked" mới có thể làm mới. Hãy kiểm tra trạng thái của các mục.

Vấn đề: Một số URL không vượt qua xác thực
Giải pháp: Kiểm tra mảng errors trong phản hồi để biết thông báo lỗi cụ thể. Đảm bảo URL thuộc các nền tảng được hỗ trợ và có thể truy cập công khai.

Hướng dẫn cấu hình Webhook

Next Page

On this page

Tổng quan
Xác thực
Điểm cuối API
1. Tạo Feed
Yêu cầu
Phản hồi
Ví dụ yêu cầu
2. Làm mới Feed
Yêu cầu
Phản hồi
Ví dụ yêu cầu
3. Tạo Kênh
Yêu cầu
Phản hồi
Ví dụ yêu cầu
4. Làm mới Kênh
Yêu cầu
Phản hồi
Ví dụ yêu cầu
5. Đồng bộ Feed
Yêu cầu
Phản hồi
Ví dụ yêu cầu
6. Đồng bộ Kênh
Yêu cầu
Phản hồi
Ví dụ yêu cầu
7. Đồng bộ nội dung kênh
Request and pagination
Response example (placeholder cursor) — reels, lunacut.edit, count=1
8. Lấy thông tin bổ sung của hồ sơ
Tích hợp Webhook
Thiết lập Webhook
Phản hồi lỗi
401 Unauthorized - Thiếu API Key
401 Unauthorized - API Key không hợp lệ
400 Bad Request - Dữ liệu đầu vào không hợp lệ
400 Bad Request - Quá nhiều URL (Tạo Feed)
400 Bad Request - Quá nhiều URL (Tạo Kênh)
400 Bad Request - Không đủ Credit
429 Too Many Requests - Giới hạn đồng thời của nhóm
403 Forbidden - Bộ sưu tập không hợp lệ
404 Not Found
Ví dụ sử dụng
Ví dụ Python - Tạo Feed
Ví dụ JavaScript - Làm mới Feed
Lưu ý quan trọng
Khắc phục sự cố