API

KK Team27/1/25Khoảng 5 phútapiapirestdocumentation

API Documentation

Tổng quan

Hệ thống API của KKauto.net cung cấp các endpoint RESTful để tích hợp và quản lý các chức năng tự động hóa mạng xã hội. Tất cả các API đều tuân thủ chuẩn RESTful và sử dụng phiên bản v2 với cấu trúc response nhất quán.

Kiến trúc Đa Hệ thống

Hệ thống được xây dựng theo mô hình đa hệ thống, trong đó:

Mỗi khách hàng là một hệ thống riêng biệt
Mỗi hệ thống có dữ liệu và cấu hình độc lập
Tất cả các API đều hoạt động trong phạm vi hệ thống của khách hàng
Dữ liệu giữa các hệ thống được cách ly hoàn toàn

Khi sử dụng API, bạn chỉ có thể truy cập và quản lý các tác vụ, dữ liệu trong hệ thống của mình.

Xác thực (Authentication)

Tất cả các API đều yêu cầu xác thực thông qua Bearer Token (JWT). Token phải được gửi trong header của mỗi request:

Authorization: Bearer YOUR_JWT_TOKEN

Token của Hệ thống

Mỗi hệ thống có thể tạo một hoặc nhiều token riêng để kết nối với API:

Token được tạo trong hệ thống của khách hàng
Mỗi token chỉ có quyền truy cập vào dữ liệu của hệ thống đó
Token có thể được quản lý (tạo, xóa, vô hiệu hóa) trong giao diện quản trị của hệ thống
Có thể tạo nhiều token cho các mục đích khác nhau (development, production, integration, etc.)

Lấy Token

Để tạo token cho hệ thống của bạn:

Đăng nhập vào hệ thống quản trị của bạn subdomain*.kkwebsite.com
Truy cập phần Menu Accounts Chọn Tokens trong hệ thống của bạn
Tạo token mới và lưu lại token để sử dụng

Cấu trúc Response

Tất cả các API đều trả về response theo định dạng chuẩn:

Response thành công

{
  "status": "success",
  "data": {
    // Dữ liệu trả về
  },
  "pagination": {
    // Thông tin phân trang (nếu có)
  }
}

Response lỗi

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

Danh sách API

Facebook APIs

Quản lý và tự động hóa các hoạt động trên Facebook.

Facebook Accounts

Quản lý tài khoản Facebook
CRUD operations cho tài khoản
Lọc và tìm kiếm tài khoản
Quản lý trạng thái và cấp độ tài khoản

Facebook Posts

Quản lý bài viết Facebook
Tạo, cập nhật, xóa bài viết
Lọc bài viết theo loại và trạng thái
Quản lý bài viết sản phẩm và tương tác

Other APIs

Các API hỗ trợ cho các chức năng khác của hệ thống.

Products API

Quản lý sản phẩm
CRUD operations đầy đủ
Upload và quản lý hình ảnh sản phẩm
Tìm kiếm và lọc nâng cao
Quản lý danh mục và thuộc tính

Images API

Quản lý hình ảnh
Upload và tải xuống hình ảnh
Lấy hình ảnh ngẫu nhiên
Tìm kiếm và phân loại hình ảnh

Source Crawlers API

Quản lý các crawler nguồn dữ liệu
Cấu hình và theo dõi crawler
Quản lý nguồn dữ liệu tự động

Source Posts API

Quản lý bài viết từ nguồn
Đồng bộ và quản lý nội dung
Tích hợp với crawler

Base URL

Tất cả các API đều sử dụng base URL:

https://kkdemo.kkwebsite.com/api/v2/

Phân trang (Pagination)

Các API hỗ trợ phân trang đều sử dụng các tham số chuẩn:

Tham số	Kiểu	Mô tả
`page`	Integer	Số trang (mặc định: 1)
`limit`	Integer	Số lượng items mỗi trang (mặc định: 10, tối đa: 100)

Response phân trang:

{
  "pagination": {
    "current_page": 1,
    "per_page": 10,
    "total": 100,
    "total_pages": 10
  }
}

Mã lỗi HTTP

Mã	Mô tả
`200`	Thành công
`201`	Tạo thành công
`400`	Request không hợp lệ
`401`	Chưa xác thực hoặc token không hợp lệ
`403`	Không có quyền truy cập
`404`	Không tìm thấy resource
`422`	Validation error
`500`	Lỗi server

Rate Limiting

API có giới hạn số lượng request để đảm bảo hiệu suất hệ thống:

Rate limit: 100 requests/phút cho mỗi token
Burst limit: 20 requests/giây

Khi vượt quá giới hạn, API sẽ trả về mã lỗi 429 Too Many Requests.

Cách hoạt động với Hệ thống

Khi bạn sử dụng token của hệ thống để gọi API:

Hệ thống tự động xác định hệ thống từ token
Tất cả các thao tác (GET, POST, PUT, DELETE) chỉ ảnh hưởng đến dữ liệu trong hệ thống của bạn
Dữ liệu trả về chỉ bao gồm các bản ghi thuộc hệ thống của bạn
Không thể truy cập dữ liệu của các hệ thống khác

Ví dụ: Khi bạn gọi API lấy danh sách sản phẩm, bạn chỉ nhận được các sản phẩm trong hệ thống của mình, không phải tất cả sản phẩm trong toàn bộ nền tảng.

Ví dụ sử dụng

cURL

# Sử dụng token của hệ thống để truy cập API
curl -X GET "https://kkdemo.kkwebsite.com/api/v2/products?page=1&limit=10" \
  -H "Authorization: Bearer YOUR_SYSTEM_TOKEN"

JavaScript (Fetch)

// Token này chỉ có quyền truy cập dữ liệu trong hệ thống của bạn
const response = await fetch('https://kkdemo.kkwebsite.com/api/v2/products?page=1&limit=10', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_SYSTEM_TOKEN',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
// data chỉ chứa sản phẩm trong hệ thống của bạn

N8N Integration

Các API có thể được tích hợp dễ dàng với N8N thông qua HTTP Request node:

Tạo HTTP Request node
Cấu hình URL endpoint
Thêm header Authorization: Bearer YOUR_SYSTEM_TOKEN (sử dụng token của hệ thống)
Thiết lập method và parameters

Lưu ý: Đảm bảo sử dụng đúng token của hệ thống mà bạn muốn truy cập dữ liệu.

Hỗ trợ

Nếu bạn gặp vấn đề hoặc cần hỗ trợ khi sử dụng API, vui lòng:

Xem tài liệu chi tiết của từng API
Liên hệ đội ngũ hỗ trợ kỹ thuật
Kiểm tra Hướng dẫn sử dụng để biết thêm thông tin

Changelog

Version 2.0

Chuẩn hóa tất cả API theo RESTful
Thống nhất cấu trúc response
Cải thiện authentication với JWT
Bổ sung phân trang cho tất cả endpoints
Tối ưu hiệu suất và rate limiting