API Tích hợp (Open API)

Tài liệu này mô tả chi tiết các Open API của hệ thống SerpUpdate dành cho khách hàng tích hợp. Bạn có thể sử dụng các API này để tạo task kiểm tra thứ hạng từ khóa, tra cứu mã địa lý, ngôn ngữ và tự động nhận kết quả qua Webhook.

1. Quy Trình Sử Dụng#

1. Gọi API Get Locations và Get Languages để lấy mã locationCode và languageCode.
2. Gọi API Create Task với thông tin từ khóa, location, language → nhận về taskId.
3. Chờ hệ thống xử lý. Khi có kết quả, hệ thống sẽ gọi Ping Back (Webhook) về server của bạn. Hoặc bạn có thể chủ động gọi API Get Task Result với taskId để lấy kết quả.

2. Xác Thực (Authentication)#

Tất cả các request đều yêu cầu gửi kèm API Key trong header. Khách hàng tạo tài khoản trên app.serpupdate.com. API Key được cấp riêng cho từng tài khoản.

Header yêu cầu:
X-API-KEY: <your_api_key>

3. Cấu Trúc Response Chung#

Tất cả các API đều trả về cùng một cấu trúc JSON bao ngoài:

Danh sách Mã Lỗi (Error Codes)#

4. Danh Sách Endpoints#

API #1: Create Task#

Tạo tác vụ kiểm tra thứ hạng từ khóa trên công cụ tìm kiếm. Mỗi request có thể gửi nhiều từ khóa cùng lúc.

Endpoint: POST /api/v1/open-api/create-task

Request Body

Keyword Object

Response — content.tasks[]

Ví dụ cURL & Response

curl --location 'https://app.serpupdate.com/api/v1/open-api/create-task' 
  --header 'X-API-KEY: <your_api_key>' 
  --header 'Content-Type: application/json' 
  --data '{
    "deviceCode": "desktop",
    "locationCode": 2704,
    "languageCode": "vi",
    "searchEngineCode": "GOOGLE",
    "keywords": [
      { "cstmKeywordId": "1", "keyword": "Dien thoai gia re" },
      { "cstmKeywordId": "2", "keyword": "Dien thoai dep" }
    ]
  }'

{
  "errorCode": null,
  "content": {
    "tasks": [
      { "taskId": 4, "cstmKeywordId": "1", "keyword": "Dien thoai gia re", "isSuccess": true },
      { "taskId": 5, "cstmKeywordId": "2", "keyword": "Dien thoai dep", "isSuccess": true }
    ]
  },
  "message": null,
  "isSuccess": true
}

API #2: Get Locations#

Tra cứu danh sách địa điểm (location) hỗ trợ bởi hệ thống. Kết quả có phân trang và hỗ trợ tìm kiếm mở theo tên.

Endpoint: POST /api/v1/open-api/locations

Request Body

Response — content.content[] (Location Object)

Ví dụ Response

{
  "errorCode": null,
  "content": {
    "content": [
      {
        "locationCode": 2704,
        "locationName": "Vietnam",
        "locationCodeParent": null,
        "countryIsoCode": "VN",
        "locationType": "Country"
      }
    ],
    "totalElements": 245,
    "totalPages": 25,
    "numberOfElements": 10
  },
  "message": null,
  "isSuccess": true
}

API #3: Get Languages#

Lấy danh sách mã ngôn ngữ được hỗ trợ. Không cần truyền tham số.

Endpoint: POST /api/v1/open-api/languages

curl --location --request POST 'https://app.serpupdate.com/api/v1/open-api/languages' 
  --header 'X-API-KEY: <your_api_key>' 
  --header 'Content-Type: application/json' 
  --data ''

API #4: Get Task Result#

Lấy kết quả thứ hạng SERP của một task đã tạo thông qua taskId.

Endpoint: POST /api/v1/open-api/task-result

Request Body

Cần truyền vào tham số bắt buộc: { "taskId": 4 }

Response — content

SerpItem Object (serpItems)

AiOverview Object

Ví dụ Response

{
  "errorCode": null,
  "content": {
    "taskId": 4,
    "serpItems": [
      {
        "rank": 1,
        "url": "https://www.thegioididong.com/dtdd",
        "domain": "thegioididong.com",
        "title": "Dien thoai gia re - The Gioi Di Dong",
        "description": "Danh sach dien thoai gia re..."
      }
    ],
    "aiOverview": {
      "markdown": "## Dien thoai gia re tot nhat...",
      "references": [
        { "rank": 1, "url": "https://...", "domain": "...", "title": "...", "description": "..." }
      ]
    }
  },
  "message": null,
  "isSuccess": true
}

API #5: Ping Back (Webhook)#

Thay vì liên tục chủ động gọi Get Task Result, bạn có thể đăng ký một Endpoint (URL Callback) với đội ngũ SerpUpdate.

Ngay khi task hoàn thành, hệ thống sẽ tự động gọi HTTP POST truyền kết quả về Server của bạn.

Payload hệ thống gửi cho bạn

Dữ liệu JSON gửi trực tiếp đến bạn có cấu trúc chính xác như phần content của API Get Task Result.

POST https://your-server.com/your-callback-endpoint
Content-Type: application/json

{
  "taskId": 4,
  "serpItems": [
    {
      "rank": 1,
      "url": "https://...",
      "domain": "...",
      "title": "...",
      "description": "..."
    }
  ],
  "aiOverview": {
    "markdown": "## ...",
    "references": []
  }
}

Ví dụ xử lý (Java Spring Boot)

@PostMapping("/your-callback-endpoint")
public ResponseEntity receivePingBack(@RequestBody TaskOpenApiResponse payload) {
    // Xử lý dữ liệu: payload.getTaskId(), payload.getSerpItems()...
    log.info("Received task result: {}", payload);
    
    // Trả về 200 OK để hệ thống ghi nhận thành công
    return ResponseEntity.ok().build();
}

Xem thêm#

• Giới thiệu Rank Checker
• Hồ sơ và cài đặt tài khoản
• Đăng ký tài khoản
• Trang Rank Checker