BUSINESS API · v1.5.1 · AVAILABLE · 10/08/2026
Catlo Business API
Đăng, cập nhật và quản lý sản phẩm từ WordPress, Laravel, ERP hoặc phần mềm bán hàng bằng contract tối giản và an toàn.
Bắt đầu nhanh trong 4 bước
- Đăng ký và được duyệt Business.
- Tạo Application.
- Tạo API key, lưu một lần và chỉ dùng phía server.
- Gửi sản phẩm đầu tiên bằng payload tối giản.
Xác thực
Authorization: Bearer $CATLO_API_KEYKhông gửi key qua query string, JavaScript frontend hoặc log. Key phải có đúng scope và Business/Application phải active.
Kiểm tra Business với /me
{"business":{"status":"approved","default_location":{"region_id":42,"region_name":"Đắk Lắk","city_id":501,"city_name":"Phường Buôn Ma Thuột","source":"business"}}}Client dùng /api/v1/me để kiểm tra Business đã sẵn sàng đăng tin hay chưa. source là business, personal_profile_fallback, hoặc default_location là null.
Quy tắc tốc độ
| Loại | Giới hạn |
|---|---|
| Read API | 120 request/phút |
| Write API | 30 request/phút |
| Media API | 10 request/phút |
| External product mới | 1 sản phẩm/10 phút/Business |
Cadence 10 phút chỉ áp dụng khi tạo external product mới. Nhiều key, Application hoặc IP không tăng quota. Replay, upload ảnh, đọc và PATCH dùng giới hạn riêng. Honor Retry-After; reschedule queue job, không sleep worker.
Tạo tin tối giản
curl -X POST "https://catlo.vn/api/v1/listings" \
-H "Authorization: Bearer $CATLO_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: woo-product-29736-v1" \
-d '{"external_source":"woocommerce","external_listing_id":"29736","title":"Thẻ nhớ Dahua 32GB","description":"Thẻ nhớ chính hãng, tốc độ đọc cao."}'{"success":true,"data":{"id":123,"status":"published","is_active":true,"location_source":"business_default"},"request_id":"req_..."}Catlo tự lấy địa phương mặc định từ Business và tự xử lý danh mục bằng external mapping/AI nếu client không gửi các trường này.
Required và Optional
| Field | Contract | Kiểu | Ghi chú |
|---|---|---|---|
| external_source | Required | string | 1–64: a-z, số, . _ - |
| external_listing_id | Required | string | ID ổn định từ nguồn |
| title | Required | string | 3–100 ký tự |
| description | Required | string | Tối đa 20.000 ký tự |
| category_id, price, currency, condition, warranty, delivery_methods, location, media_ids | Optional | mixed | Chỉ validate khi có gửi; không cần null, "", [] hoặc {} |
Danh mục và AI
category_id tùy chọn. Catlo ưu tiên category client hợp lệ, external mapping, rồi AI bất đồng bộ. Listing có thể public trước khi AI hoàn tất; AI có retry riêng và không rollback listing hợp lệ. Client không bắt buộc tải hoặc hardcode category.
Địa phương — Snapshot khi tạo
Thứ tự resolve là request.location → Business structured default → personal profile structured fallback → 422 BUSINESS_LOCATION_REQUIRED. Location client luôn override cho riêng tin đó.
Các Business cũ chưa có địa phương riêng có thể tạm thời sử dụng địa phương đã xác thực trong hồ sơ tài khoản. Chúng tôi khuyến nghị Business cập nhật địa phương riêng để tránh phụ thuộc hồ sơ cá nhân.
Catlo dùng mô hình Việt Nam hai cấp: region_id là tỉnh/thành phố và city_id là xã/phường terminal. Địa phương được snapshot vào tin tại CREATE; đổi hồ sơ cá nhân hoặc Business sau này không làm đổi tin cũ. PATCH không gửi location giữ nguyên snapshot.
Giao nhận — Optional
Chỉ chấp nhận ["cod"], ["direct"] hoặc ["cod","direct"]. Bỏ field vẫn tạo tin; sai kiểu/mã trả 422 DELIVERY_METHODS_INVALID.
Hình ảnh — Optional
Upload từng file bằng multipart field file tới /api/v1/media. JPEG/PNG/WebP, tối đa 8 MiB và 40 triệu pixel; tối đa 12 media_ids/listing. Một file lỗi không xóa media đã thành công và client có thể tiếp tục với số ảnh còn lại hoặc 0 ảnh.
Idempotency
POST/PATCH cần Idempotency-Key. Cùng key + cùng raw body trả response cũ; body khác trả 409. Replay không chịu cadence mới. Cặp Business + external_source + external_listing_id cũng unique.
Cập nhật tin
curl -X PATCH "https://catlo.vn/api/v1/listings/123" \
-H "Authorization: Bearer $CATLO_API_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: woo-29736-update-2" -d '{"price":990000}'PATCH chỉ cập nhật tin cùng Business, không tạo listing mới và không chịu product cadence. Bỏ location giữ nguyên địa phương; chỉ payload gửi rõ location mới thay thế snapshot sau khi validate.
Xử lý lỗi
| HTTP | Code | Retry? | Xử lý |
|---|---|---|---|
| 401 | AUTH_REQUIRED / AUTH_INVALID | Không | Kiểm tra key |
| 403 | SCOPE_REQUIRED / BUSINESS_NOT_APPROVED | Sau khi cấp quyền | Kiểm tra Business/app/scope |
| 409 | IDEMPOTENCY_CONFLICT | Không | Giữ body cũ hoặc key mới |
| 415 | MEDIA_TYPE_INVALID | Không | Chuyển JPEG/PNG/WebP |
| 422 | BUSINESS_LOCATION_REQUIRED | Không | Cập nhật địa phương mặc định trong hồ sơ Business hoặc gửi location trong request. |
| 422 | BUSINESS_LOCATION_INVALID | Không | Địa phương mặc định không còn hợp lệ; cập nhật lại hồ sơ Business. |
| 422 | DELIVERY_METHODS_INVALID | Không | Dùng cod/direct |
| 429 | RATE_LIMITED | Có | Honor Retry-After |
| 429 | PRODUCT_PUBLISH_INTERVAL / PRODUCT_PUBLISH_IN_PROGRESS | Có | Reschedule cùng key |
| 500/503 | INTERNAL_ERROR / unavailable | Có | Backoff, giữ request_id |
Công thức khuyến nghị
WooCommerce
Queue sản phẩm còn hàng, external ID ổn định, một sản phẩm mỗi 10 phút trở lên và 3–5 ảnh khuyến nghị.
Laravel
Scheduler chạy mỗi phút, queue chỉ claim sản phẩm khi next_allowed_at đã tới; không sleep worker 600 giây.
Changelog
1.5.1 — Business default location: POST fallback và snapshot, client override, PATCH preserve/replace, /me readiness, cùng lỗi REQUIRED/INVALID; cadence, media và AI category không đổi.
1.5.0 — Business product cadence, optional category/location/delivery/media, PATCH idempotency, media và error/rate header contract.
1.4.0 — Atomic auto-publish và lifecycle sau commit.