Từng bước: cập nhật trang qua API

Trong ví dụ này, bạn cập nhật một trang có sẵn hoàn toàn qua API: thêm một liên kết, đưa nó lên đầu, đổi kiểu nút, kiểm tra bản nháp và xuất bản. Các lệnh chạy trong mọi shell có curl và jq.

#1. Tạo khóa API

1. Mở “Callback & API” trong bảng điều khiển
2. Nhấp “+ Tạo khóa mới”
3. Chọn “Ghi” cho cả “Trang” và “Liên kết” (bao gồm quyền đọc)
4. Nhấp “Tạo khóa” và sao chép mã bí mật của khóa
5. Sao chép ID khóa từ danh sách

Lưu cả hai giá trị dưới dạng biến môi trường, không đặt trong script:

export LH_KEY_ID="6F668EA6598B0692"
export LH_KEY_SECRET="lt_…"
export API="https://dock.at-harbor.com"

#2. Lấy access token

LH_TOKEN=$(curl -sS -X POST "$API/v1/token" \
  -H "Content-Type: application/json" \
  -d "{\"key_id\":\"$LH_KEY_ID\",\"key_secret\":\"$LH_KEY_SECRET\"}" \
  | jq -r .token)

Token có hiệu lực 15 phút. Nếu script chạy lâu hơn, hãy lấy token mới giữa chừng.

#3. Tìm trang

curl -sS "$API/v1/pages" -H "Authorization: Bearer $LH_TOKEN" \
  | jq '.items[] | {id, handle, title, status, current_version}'

Ghi lại id của trang. Trong ví dụ này là 42:

PAGE_ID=42

#4. Thêm liên kết

LINK_ID=$(curl -sS -X POST "$API/v1/pages/$PAGE_ID/links" \
  -H "Authorization: Bearer $LH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Autumn sale","target_url_template":"https://shop.example.com/autumn","enabled":true}' \
  | jq -r .id)
echo "New link: $LINK_ID"

API phản hồi HTTP 201 kèm ID mới. Liên kết mới được đặt cuối danh sách. Nếu đạt giới hạn liên kết của gói, bạn nhận 409 link_limit_reached.

#5. Đưa liên kết lên đầu

curl -sS -X POST "$API/v1/pages/$PAGE_ID/links/reorder" \
  -H "Authorization: Bearer $LH_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"order\":[$LINK_ID]}"

Chỉ cần gửi các ID cần đưa lên trước. Mọi liên kết khác giữ nguyên thứ tự phía sau.

#6. Đổi thiết kế trong bản nháp

theme_config bị thay thế hoàn toàn khi PATCH. Vì vậy bạn đọc bản nháp trước, chỉ đổi giá trị mong muốn rồi gửi lại toàn bộ object:

THEME=$(curl -sS "$API/v1/pages/$PAGE_ID/draft" -H "Authorization: Bearer $LH_TOKEN" \
  | jq -c '(.theme_config // {}) | .button_style = "pill"')

curl -sS -X PATCH "$API/v1/pages/$PAGE_ID/draft" \
  -H "Authorization: Bearer $LH_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"theme_config\":$THEME}"

button_style nhận rounded, pill và square. Các trường theme_config khác gồm bg_color, text_color, button_color, button_text_color và background.

#7. Kiểm tra bản nháp

curl -sS "$API/v1/pages/$PAGE_ID/draft/validate" -H "Authorization: Bearer $LH_TOKEN"
# → {"ok":true,"valid":true,"issues":[]}

Nếu valid là false, issues liệt kê các vấn đề. Hãy sửa chúng trước khi xuất bản. Bản nháp có khác phiên bản trực tuyến hay không được thể hiện qua GET /v1/pages/$PAGE_ID ở trường has_unpublished_changes – nếu là false, bạn có thể bỏ qua bước xuất bản.

#8. Xuất bản

curl -sS -X POST "$API/v1/pages/$PAGE_ID/publish" -H "Authorization: Bearer $LH_TOKEN"
# → {"ok":true,"version":8,"checksum":"…"}

Giờ khách truy cập thấy phiên bản mới – kể cả liên kết mới, thứ tự và thiết kế. Nếu bạn có webhook cho page.published, webhook giờ nhận một lượt gửi. Nếu bản nháp không xuất bản được, API phản hồi 409 draft_not_publishable kèm danh sách trong details.issues.

#9. Hoàn tác

Nếu không thích kết quả, hãy đưa phiên bản trước trở lại bản nháp và xuất bản lại:

curl -sS -X POST "$API/v1/pages/$PAGE_ID/versions/7/restore" -H "Authorization: Bearer $LH_TOKEN"
curl -sS -X POST "$API/v1/pages/$PAGE_ID/publish" -H "Authorization: Bearer $LH_TOKEN"

Thay vì số phiên bản, bạn có thể truyền current: thao tác này bỏ mọi thay đổi trong bản nháp kể từ lần xuất bản gần nhất. Việc khôi phục đưa lại thiết kế, mẫu, CSS tùy chỉnh, SEO, khối và liên kết; tiêu đề, handle và chế độ hiển thị không được lưu phiên bản.

#Lỗi thường gặp

400 bad_request

Thiếu header Content-Type: application/json. Không có nó, curl -d gửi một loại khác.

401 invalid_token

Token đã hết hạn sau 15 phút. Hãy lấy token mới.

403 insufficient_scope

Khóa thiếu một phạm vi, ví dụ “Ghi” cho liên kết.

Thiết kế bỗng bị đặt lại

theme_config được gửi chỉ với một trường và đã thay thế toàn bộ giao diện. Hãy gửi lại giao diện đầy đủ, hoặc dùng restore current để bỏ mọi thay đổi trong bản nháp kể từ lần xuất bản gần nhất.

Mọi mã được giải thích trong Định dạng lỗi và mã lỗi, và mọi endpoint được liệt kê trong Các endpoint theo khu vực.