Source Posts

KK Team15/1/25Khoảng 9 phútapiapisource-postsrestapiautocrawler

API Source Posts - Hướng dẫn sử dụng

Tổng quan

API Source Posts cung cấp các endpoint RESTful để quản lý bài viết nguồn một cách toàn diện, bao gồm CRUD operations, tìm kiếm, lọc, thống kê và tích hợp với source crawler.

Base URL và Authentication

Base URL

https://your-domain.com/apiauto/source-posts

Authentication

API yêu cầu xác thực thông qua Bearer token:

Authorization: Bearer YOUR_API_TOKEN

Các endpoint chính

1. Lấy danh sách bài viết nguồn

Endpoint: GET /apiauto/source-posts

Lấy danh sách bài viết nguồn với phân trang và bộ lọc.

Query Parameters

Tham số	Kiểu	Bắt buộc	Mô tả
`page`	Integer	Không	Số trang (mặc định: 1)
`limit`	Integer	Không	Số lượng bài viết mỗi trang (mặc định: 10)
`source_platform`	String	Không	Lọc theo nền tảng (facebook, instagram, twitter, youtube, tiktok, reddit, pinterest, website, other)
`status`	String	Không	Lọc theo trạng thái (pending, approved, rejected, waiting_confirmation)
`topic_type`	String	Không	Lọc theo loại chủ đề (normal, tutorial, share, review, comparison, introduction, promotion, news, event)
`post_type`	String	Không	Lọc theo loại bài viết (short, long)
`hashtag`	String	Không	Lọc theo tên hashtag
`date_from`	String	Không	Lọc từ ngày (format: YYYY-MM-DD)
`date_to`	String	Không	Lọc đến ngày (format: YYYY-MM-DD)
`search`	String	Không	Tìm kiếm theo tiêu đề, nội dung, kênh, tác giả
`source_crawler_id`	Integer	Không	Lọc theo ID của source crawler
`order_by`	String	Không	Sắp xếp theo trường (mặc định: published_at)
`order_direction`	String	Không	Thứ tự sắp xếp ASC/DESC (mặc định: DESC)

Response

{
    "status": "success",
    "data": [
        {
            "id": 1,
            "title": "Tiêu đề bài viết",
            "content": "Nội dung bài viết",
            "source_platform": "facebook",
            "source_channel": "Kênh nguồn",
            "source_author": "Tác giả",
            "source_url": "https://example.com/post/1",
            "status": "approved",
            "topic_type": "normal",
            "post_type": "short",
            "published_at": "2024-01-01 10:00:00",
            "created_at": "2024-01-01 10:00:00",
            "source_crawler_id": 5
        }
    ],
    "pagination": {
        "page": 1,
        "limit": 10,
        "total": 100,
        "total_pages": 10,
        "nextpage": "https://your-domain.com/apiauto/source-posts?page=2&limit=10"
    }
}

CURL Example

curl -X GET "https://your-domain.com/apiauto/source-posts?page=1&limit=20&status=approved&source_platform=facebook" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

N8N Example

Cấu hình HTTP Request Node:

URL: https://your-domain.com/apiauto/source-posts
Method: GET

Query Parameters:

page: 1
limit: 20
status: approved
source_platform: facebook
source_crawler_id: 5

Headers:
```
Authorization: Bearer YOUR_API_TOKEN
```

PHP Example

function getSourcePosts($token, $params = []) {
    $url = 'https://your-domain.com/apiauto/source-posts?' . http_build_query($params);
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $token
    ]);
    $response = curl_exec($ch);
    curl_close($ch);
    return json_decode($response, true);
}

// Sử dụng
$params = [
    'page' => 1,
    'limit' => 20,
    'status' => 'approved',
    'source_platform' => 'facebook',
    'source_crawler_id' => 5
];
$result = getSourcePosts('YOUR_API_TOKEN', $params);

Python Example

import requests

def get_source_posts(token, params=None):
    url = 'https://your-domain.com/apiauto/source-posts'
    headers = {
        'Authorization': f'Bearer {token}'
    }
    
    response = requests.get(url, params=params, headers=headers)
    return response.json()

# Sử dụng
params = {
    'page': 1,
    'limit': 20,
    'status': 'approved',
    'source_platform': 'facebook',
    'source_crawler_id': 5
}
result = get_source_posts('YOUR_API_TOKEN', params)

2. Lấy chi tiết một bài viết

Endpoint: GET /apiauto/source-posts/{id}

Lấy thông tin chi tiết của một bài viết nguồn, bao gồm media, hashtags, analytics, quality check và thông tin crawler.

Response

{
    "status": "success",
    "data": {
        "id": 1,
        "title": "Tiêu đề bài viết",
        "content": "Nội dung bài viết",
        "source_platform": "facebook",
        "source_channel": "Kênh nguồn",
        "source_author": "Tác giả",
        "source_url": "https://example.com/post/1",
        "source_post_id": "fb_post_123",
        "status": "approved",
        "topic_type": "normal",
        "post_type": "short",
        "published_at": "2024-01-01 10:00:00",
        "collected_at": "2024-01-01 10:05:00",
        "quality_score": 8.5,
        "popularity_score": 100,
        "source_crawler_id": 5,
        "created_at": "2024-01-01 10:00:00",
        "updated_at": "2024-01-01 10:00:00",
        "media": [
            {
                "id": 1,
                "post_id": 1,
                "media_type": "image",
                "media_url": "https://example.com/image.jpg"
            }
        ],
        "hashtags": [
            {
                "id": 1,
                "name": "#hashtag1",
                "description": "Mô tả hashtag"
            }
        ],
        "comments": [],
        "analytics": {
            "likes_count": 100,
            "shares_count": 50,
            "comments_count": 25,
            "views_count": 1000,
            "engagement_rate": 17.5,
            "sentiment_score": 0.8
        },
        "quality_check": {
            "content_quality_score": 8.0,
            "language_quality_score": 7.5,
            "relevance_score": 9.0,
            "overall_score": 8.2
        },
        "crawler": {
            "id": 5,
            "source_name": "Facebook Group ABC",
            "source_url": "https://facebook.com/groups/abc",
            "platform_type": "facebook",
            "source_type": "group",
            "status": "active"
        }
    }
}

CURL Example

curl -X GET "https://your-domain.com/apiauto/source-posts/1" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

N8N Example

Cấu hình HTTP Request Node:

URL: https://your-domain.com/apiauto/source-posts/1
Method: GET
Headers:
```
Authorization: Bearer YOUR_API_TOKEN
```

3. Tạo bài viết mới

Endpoint: POST /apiauto/source-posts

Tạo một bài viết nguồn mới.

Request Body

Tham số	Kiểu	Bắt buộc	Mô tả
`title`	String	Có	Tiêu đề bài viết (3-500 ký tự)
`content`	String	Có	Nội dung bài viết
`source_platform`	String	Không	Nền tảng nguồn (mặc định: other)
`source_channel`	String	Không	Tên kênh nguồn
`source_author`	String	Không	Tên tác giả
`source_url`	String	Không	URL nguồn (phải là URL hợp lệ)
`source_post_id`	String	Không	ID bài viết nguồn
`published_at`	String	Không	Ngày đăng bài (format: YYYY-MM-DD HH:MM:SS)
`status`	String	Không	Trạng thái (mặc định: pending)
`topic_type`	String	Không	Loại chủ đề (mặc định: normal)
`post_type`	String	Không	Loại bài viết (mặc định: short)
`source_crawler_id`	Integer	Không	ID của source crawler (phải tồn tại)
`media`	Array	Không	Mảng các media items
`media[].media_type`	String	Không	Loại media (image, video)
`media[].media_url`	String	Không	URL của media
`hashtag_ids`	Array	Không	Mảng các ID hashtag
`analytics`	Object	Không	Dữ liệu analytics
`analytics.likes_count`	Integer	Không	Số lượt thích
`analytics.shares_count`	Integer	Không	Số lượt chia sẻ
`analytics.comments_count`	Integer	Không	Số lượt bình luận
`analytics.views_count`	Integer	Không	Số lượt xem

Request Example

{
    "title": "Tiêu đề bài viết mới",
    "content": "Nội dung bài viết mới",
    "source_platform": "facebook",
    "source_channel": "Kênh nguồn",
    "source_author": "Tác giả",
    "source_url": "https://example.com/post/new",
    "status": "pending",
    "topic_type": "normal",
    "post_type": "short",
    "source_crawler_id": 5,
    "media": [
        {
            "media_type": "image",
            "media_url": "https://example.com/image.jpg"
        }
    ],
    "hashtag_ids": [1, 2, 3],
    "analytics": {
        "likes_count": 0,
        "shares_count": 0,
        "comments_count": 0,
        "views_count": 0
    }
}

Response

{
    "status": "success",
    "message": "Tạo bài viết thành công",
    "data": {
        "id": 123,
        "title": "Tiêu đề bài viết mới",
        "content": "Nội dung bài viết mới",
        ...
    }
}

CURL Example

curl -X POST "https://your-domain.com/apiauto/source-posts" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Tiêu đề bài viết mới",
    "content": "Nội dung bài viết mới",
    "source_platform": "facebook",
    "source_crawler_id": 5,
    "hashtag_ids": [1, 2, 3]
  }'

N8N Example

Cấu hình HTTP Request Node:

URL: https://your-domain.com/apiauto/source-posts
Method: POST

Headers:

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

Body (JSON):

{
  "title": "Tiêu đề bài viết mới",
  "content": "Nội dung bài viết mới",
  "source_platform": "facebook",
  "source_crawler_id": 5
}

PHP Example

function createSourcePost($token, $data) {
    $url = 'https://your-domain.com/apiauto/source-posts';
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $token,
        'Content-Type: application/json'
    ]);
    $response = curl_exec($ch);
    curl_close($ch);
    return json_decode($response, true);
}

// Sử dụng
$data = [
    'title' => 'Tiêu đề bài viết mới',
    'content' => 'Nội dung bài viết mới',
    'source_platform' => 'facebook',
    'source_crawler_id' => 5
];
$result = createSourcePost('YOUR_API_TOKEN', $data);

4. Cập nhật bài viết

Endpoint: PUT /apiauto/source-posts/{id}

Cập nhật thông tin của một bài viết nguồn.

Request Body

Tương tự như tạo bài viết, nhưng tất cả các trường đều không bắt buộc (chỉ cập nhật các trường được gửi lên).

Response

{
    "status": "success",
    "message": "Cập nhật bài viết thành công",
    "data": {
        "id": 1,
        "title": "Tiêu đề đã cập nhật",
        ...
    }
}

CURL Example

curl -X PUT "https://your-domain.com/apiauto/source-posts/1" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Tiêu đề đã cập nhật",
    "status": "approved"
  }'

5. Xóa bài viết

Endpoint: DELETE /apiauto/source-posts/{id}

Xóa một bài viết nguồn.

Response

{
    "status": "success",
    "message": "Xóa bài viết thành công"
}

CURL Example

curl -X DELETE "https://your-domain.com/apiauto/source-posts/1" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

6. Tìm kiếm bài viết

Endpoint: GET /apiauto/source-posts/search

Tìm kiếm bài viết với các bộ lọc nâng cao.

Query Parameters

Tham số	Kiểu	Bắt buộc	Mô tả
`q`	String	Có	Từ khóa tìm kiếm
`page`	Integer	Không	Số trang (mặc định: 1)
`limit`	Integer	Không	Số lượng kết quả (mặc định: 10)
`source_platform`	String	Không	Lọc theo nền tảng
`status`	String	Không	Lọc theo trạng thái
`topic_type`	String	Không	Lọc theo loại chủ đề
`post_type`	String	Không	Lọc theo loại bài viết
`source_crawler_id`	Integer	Không	Lọc theo ID crawler
`date_from`	String	Không	Lọc từ ngày
`date_to`	String	Không	Lọc đến ngày

CURL Example

curl -X GET "https://your-domain.com/apiauto/source-posts/search?q=tutorial&status=approved&source_crawler_id=5" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

7. Lấy random posts

Endpoint: GET /apiauto/source-posts/random

Lấy danh sách bài viết ngẫu nhiên.

Query Parameters

Tham số	Kiểu	Bắt buộc	Mô tả
`limit`	Integer	Không	Số lượng bài viết (mặc định: 10)
`status`	String	Không	Lọc theo trạng thái (mặc định: approved)

CURL Example

curl -X GET "https://your-domain.com/apiauto/source-posts/random?limit=5&status=approved" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

8. Lấy thống kê

Endpoint: GET /apiauto/source-posts/statistics

Lấy thống kê tổng quan về bài viết nguồn.

Response

{
    "status": "success",
    "data": {
        "total_posts": 1000,
        "by_status": [
            {"status": "approved", "count": 800},
            {"status": "pending", "count": 150},
            {"status": "rejected", "count": 50}
        ],
        "by_platform": [
            {"source_platform": "facebook", "count": 600},
            {"source_platform": "instagram", "count": 400}
        ],
        "by_topic": [
            {"topic_type": "normal", "count": 500},
            {"topic_type": "tutorial", "count": 300}
        ],
        "by_month": [
            {"month": "2024-01", "count": 100},
            {"month": "2024-02", "count": 120}
        ]
    }
}

CURL Example

curl -X GET "https://your-domain.com/apiauto/source-posts/statistics" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

9. Duyệt hàng loạt

Endpoint: POST /apiauto/source-posts/bulk-approve

Duyệt nhiều bài viết cùng lúc.

Request Body

{
    "post_ids": [1, 2, 3, 4, 5]
}

Response

{
    "status": "success",
    "message": "Đã duyệt 5 bài viết",
    "data": {
        "success_count": 5,
        "total": 5
    }
}

CURL Example

curl -X POST "https://your-domain.com/apiauto/source-posts/bulk-approve" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"post_ids": [1, 2, 3, 4, 5]}'

10. Từ chối hàng loạt

Endpoint: POST /apiauto/source-posts/bulk-reject

Từ chối nhiều bài viết cùng lúc.

Request Body

{
    "post_ids": [1, 2, 3]
}

11. Cập nhật trạng thái

Endpoint: PATCH /apiauto/source-posts/{id}/status

Cập nhật trạng thái của một bài viết.

Request Body

{
    "status": "approved",
    "notes": "Ghi chú (tùy chọn)"
}

Response

{
    "status": "success",
    "message": "Cập nhật trạng thái thành công",
    "data": {
        "id": 1,
        "status": "approved",
        ...
    }
}

CURL Example

curl -X PATCH "https://your-domain.com/apiauto/source-posts/1/status" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "approved"}'

12. Lấy hashtags của post

Endpoint: GET /apiauto/source-posts/{id}/hashtags

Lấy danh sách hashtags của một bài viết.

Response

{
    "status": "success",
    "data": [
        {
            "id": 1,
            "name": "#hashtag1",
            "description": "Mô tả hashtag",
            "is_active": 1
        }
    ]
}

13. Cập nhật hashtags của post

Endpoint: PUT /apiauto/source-posts/{id}/hashtags

Cập nhật hashtags của một bài viết.

Request Body

{
    "hashtag_ids": [1, 2, 3, 4]
}

Response

{
    "status": "success",
    "message": "Cập nhật hashtags thành công",
    "data": [
        {
            "id": 1,
            "name": "#hashtag1"
        }
    ]
}

Endpoints liên kết Source Crawler

14. Lấy thông tin crawler của post

Endpoint: GET /apiauto/source-posts/{id}/crawler

Lấy thông tin source crawler liên kết với một bài viết.

Response

{
    "status": "success",
    "data": {
        "id": 5,
        "source_name": "Facebook Group ABC",
        "source_url": "https://facebook.com/groups/abc",
        "author_name": "Tác giả",
        "author_url": "https://facebook.com/author",
        "platform_type": "facebook",
        "source_type": "group",
        "crawl_interval": 60,
        "status": "active",
        "last_crawled_at": "2024-01-01 10:00:00",
        "total_crawled": 100
    }
}

CURL Example

curl -X GET "https://your-domain.com/apiauto/source-posts/1/crawler" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

15. Lấy posts của một crawler

Endpoint: GET /apiauto/source-crawlers/{id}/posts

Lấy tất cả bài viết của một source crawler cụ thể.

Query Parameters

Tham số	Kiểu	Bắt buộc	Mô tả
`page`	Integer	Không	Số trang (mặc định: 1)
`limit`	Integer	Không	Số lượng bài viết (mặc định: 10)

Response

{
    "status": "success",
    "data": {
        "crawler": {
            "id": 5,
            "source_name": "Facebook Group ABC",
            "platform_type": "facebook",
            "status": "active"
        },
        "posts": [
            {
                "id": 1,
                "title": "Bài viết 1",
                "status": "approved",
                ...
            }
        ]
    },
    "pagination": {
        "page": 1,
        "limit": 10,
        "total": 50,
        "total_pages": 5,
        "nextpage": "https://your-domain.com/apiauto/source-crawlers/5/posts?page=2"
    }
}

CURL Example

curl -X GET "https://your-domain.com/apiauto/source-crawlers/5/posts?page=1&limit=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Error Responses

API trả về các mã lỗi chuẩn HTTP và format lỗi thống nhất:

Format lỗi

{
    "status": "error",
    "code": "ERROR_CODE",
    "message": "Mô tả lỗi chi tiết"
}

Các mã lỗi thường gặp

HTTP Status	Code	Mô tả
400	`VALIDATION_ERROR`	Dữ liệu không hợp lệ
400	`MISSING_ID`	Thiếu ID bài viết
400	`MISSING_QUERY`	Thiếu query string cho search
400	`INVALID_CRAWLER_ID`	Source crawler không tồn tại
404	`NOT_FOUND`	Không tìm thấy bài viết
500	`SYSTEM_ERROR`	Lỗi hệ thống

Ví dụ lỗi

{
    "status": "error",
    "code": "VALIDATION_ERROR",
    "message": {
        "title": "Tiêu đề bài viết là bắt buộc",
        "content": "Nội dung bài viết là bắt buộc"
    }
}

Best Practices

Pagination: Luôn sử dụng pagination khi lấy danh sách lớn để tối ưu hiệu suất
Filtering: Sử dụng các bộ lọc phù hợp để giảm số lượng dữ liệu trả về
Error Handling: Luôn kiểm tra status trong response để xử lý lỗi đúng cách
Rate Limiting: API có rate limiting, tránh gọi quá nhiều request trong thời gian ngắn
Crawler Integration: Sử dụng source_crawler_id để liên kết bài viết với crawler, giúp quản lý tốt hơn

Notes

Tất cả các endpoint đều yêu cầu authentication
Timestamps sử dụng format YYYY-MM-DD HH:MM:SS
URL phải là URL hợp lệ khi cung cấp source_url
source_crawler_id phải tồn tại trong hệ thống trước khi liên kết
Khi cập nhật media hoặc hashtags, dữ liệu cũ sẽ bị thay thế hoàn toàn