Tài liệu API

Bắt đầu nhanh

Thực hiện lệnh gọi API đầu tiên trong dưới 2 phút

1

Đăng ký và lấy API key từ Developer Dashboard

2

Gửi request đầu tiên

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.kello.app/api/v1/watches?per_page=5"

3

Khám phá kết quả trả về

{
  "data": [
    {
      "id": 1,
      "brand": "Rolex",
      "collection": "Submariner",
      "reference_number": "126610LN",
      "retail_price_usd": 10250,
      "current_market_price": 12800
    }
  ],
  "meta": { "current_page": 1, "per_page": 5, "total": 10432 }
}

Xác thực

Tất cả API request đều yêu cầu Bearer token trong header Authorization.

URL gốc

https://api.kello.app/api/v1

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.kello.app/api/v1/watches

Đăng ký và lấy API key từ Developer Dashboard

Endpoints

Các endpoint chính để truy cập dữ liệu đồng hồ

Lọc theo thông số JSONB

Lọc đồng hồ theo bất kỳ thông số nào được lưu trong cột JSONB specs bằng cú pháp tham số truy vấn spec[] đặc biệt.

Truyền các key thông số dưới dạng tham số truy vấn dấu ngoặc vuông. Nhiều bộ lọc spec được kết hợp bằng logic AND — tất cả phải khớp.

?spec[key]=value&spec[another_key]=value

Các key thông số phổ biến

spec[movement_type] spec[case_material] spec[dial_color] spec[water_resistance] spec[crystal] spec[power_reserve] spec[case_shape] spec[bracelet_material]

Thử ngay

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.kello.app/api/v1/watches?spec[movement_type]=automatic&spec[case_material]=gold"

Phản hồi lỗi

Tất cả lỗi trả về cấu trúc JSON nhất quán với mã trạng thái HTTP phù hợp.

401Unauthenticated

API key thiếu hoặc không hợp lệ. Thêm Bearer token hợp lệ vào header Authorization.

{ "message": "Unauthenticated." }

403Forbidden

Gói đăng ký của bạn không có quyền truy cập tài nguyên hoặc thao tác này.

{ "message": "Your plan does not include access to this resource." }

404Not Found

Tài nguyên được yêu cầu (đồng hồ, thương hiệu, webhook, v.v.) không tìm thấy.

{ "message": "Resource not found." }

422Validation Error

Dữ liệu request hoặc tham số truy vấn không hợp lệ. Kiểm tra object errors để biết chi tiết từng trường.

{
  "message": "The given data was invalid.",
  "errors": {
    "endpoint_url": ["The endpoint url field is required."]
  }
}

429Rate Limited

Bạn đã vượt quá giới hạn rate limit. Đợi đến khi hết thời gian Retry-After trước khi thử lại.

{
  "message": "Too many requests. Please retry after the period indicated in the Retry-After header."
}

Giới hạn tốc độ

Giới hạn API request theo từng gói đăng ký

Gói	request/ngày	Giá
Miễn phí	50	Miễn phí
ProPhổ biến	500	$59/tháng
Platinum	1,500	$79/tháng

Cần thêm request?

Nâng cấp gói

Header giới hạn tốc độ

Mọi phản hồi API đều bao gồm các header giúp bạn theo dõi mức sử dụng rate limit.

Header	Mô tả
X-RateLimit-Limit	Số request tối đa được phép mỗi ngày theo gói của bạn
X-RateLimit-Remaining	Số request còn lại trong kỳ hiện tại
X-RateLimit-Reset	Mốc thời gian Unix khi rate limit được đặt lại
Retry-After	Số giây cần đợi trước khi thử lại (chỉ xuất hiện khi bị 429)

Ví dụ

HTTP/1.1 200 OK
X-RateLimit-Limit: 50
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1712160000

HTTP/1.1 429 Too Many Requests
Retry-After: 3600
X-RateLimit-Limit: 50
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1712160000