Tổng quan về API LinkHarbor

REST API cho phép bạn điều khiển LinkHarbor từ chương trình của riêng mình: tạo trang và liên kết, chỉnh sửa và xuất bản bản nháp, tạo liên kết rút gọn hoặc đưa thống kê vào báo cáo riêng. Bài này dành cho nhà phát triển và giải thích các quy tắc cơ bản áp dụng cho mọi endpoint.

#Cách nào phù hợp?

#URL gốc và phiên bản

URL gốc

https://dock.at-harbor.com – mọi endpoint của sản phẩm nằm dưới /v1, ví dụ https://dock.at-harbor.com/v1/pages.

Phiên bản

Hiện chỉ có phiên bản v1. Số phiên bản là một phần của đường dẫn.

Giao thức

Chỉ HTTPS.

OpenAPI

Bản mô tả máy đọc được (OpenAPI 3.1) nằm tại https://dock.at-harbor.com/openapi.yaml. Bạn có thể nạp nó vào Postman, Insomnia hoặc một trình tạo mã.

#Thử nghiệm trong sandbox

Để phát triển và thử nghiệm, có một sandbox riêng. Nó hoạt động như API thật nhưng tách biệt hoàn toàn: tài khoản riêng, dữ liệu riêng, và không có gì lọt vào không gian làm việc thật của bạn.

API

https://drydock.at-harbor.com, với cùng các đường dẫn như trên, ví dụ https://drydock.at-harbor.com/v1/pages.

Bảng điều khiển

https://sandbox-deck.linkharbor.com, ví dụ để tạo khóa API.

Trang

Trang đã xuất bản xuất hiện tại https://<handle>.sandbox.linkharbor.com.

Tài khoản

Tài khoản LinkHarbor thật của bạn không dùng được ở đó. Hãy tạo một tài khoản sandbox riêng.

Sandbox không gửi email. Nếu bạn đăng ký qua API (POST /v1/auth/register), mã xác minh được trả về trực tiếp trong phản hồi, ở trường _dev_verification. Điều tương tự áp dụng cho đặt lại mật khẩu và đổi email. Trường này chỉ có trong sandbox, vì vậy đừng dựa vào nó trong mã của bạn.

• Thông báo đẩy bị tắt
• Thanh toán chạy qua chế độ thử nghiệm của Stripe, không có tiền thật được chuyển
• Giới hạn tần suất khoảng một phần ba giá trị thật, và tài khoản mới bị giới hạn 5 tài khoản mỗi giờ cho mỗi địa chỉ IP
• Vào ngày 1 hằng tháng lúc 3:00 UTC, sandbox bị xóa sạch hoàn toàn, sau đó mọi tài khoản và dữ liệu đều mất
• Mọi phản hồi đều kèm header X-Environment: sandbox

#Tóm tắt về xác thực

1. Với vai trò chủ sở hữu hoặc quản trị viên, tạo một khóa API với các phạm vi cần thiết trong bảng điều khiển ở “Callback & API” (từ Creator Pro)
2. Đổi ID khóa và mã bí mật của khóa lấy access token qua POST /v1/token
3. Gửi token với mọi yêu cầu trong header Authorization: Bearer …
4. Lấy token mới sau 15 phút

Mọi chi tiết có trong Khóa API và token, các quyền có trong Phạm vi.

#Yêu cầu và phản hồi

Định dạng

Yêu cầu và phản hồi là JSON theo UTF-8. Tải tệp lên còn dùng multipart/form-data.

Content-Type

Gửi header Content-Type: application/json với mọi yêu cầu có phần thân. Mọi loại khác đều bị từ chối với 400 bad_request – kể cả loại mà curl tự đặt cho -d khi thiếu header này.

Trường không xác định

Các trường mà endpoint không biết dẫn đến 422 validation_failed. Phản hồi nêu tên các trường không xác định.

JSON hỏng

Dẫn đến 400 invalid_json.

Kích thước

Tùy endpoint, phần thân tối đa 64 KB, 1 MB hoặc 2 MB, và tệp tải lên tối đa 10 MB. Nếu lớn hơn, API phản hồi 413 request_too_large. Mọi giới hạn được liệt kê trong Giới hạn tần suất.

Danh sách

Trả về dạng object với trường items, ví dụ {"items":[…]}.

Tạo mới

Phản hồi HTTP 201 kèm ID mới, ví dụ {"id":123}.

Thao tác không có giá trị trả về

Phản hồi {"ok":true}.

Lỗi

Luôn có định dạng cố định với mã máy đọc được. Xem Định dạng lỗi và mã lỗi.

#Phân trang

Không có một cơ chế phân trang chung. Phần lớn danh sách nhỏ và được trả về đầy đủ; chỉ một vài endpoint có tham số:

Với sort của liên kết rút gọn có created_desc, created_asc, redirects_desc và redirects_asc; q tìm trong slug, tiêu đề và URL đích (tối đa 100 ký tự, không phân biệt hoa thường). Với thống kê, period nhận 24h, 7d, 30d, 90d, this_month, last_month, last_30d và custom; hoặc bạn truyền from và to. granularity là hour hoặc day.

#Request ID và ngôn ngữ

• Mọi phản hồi đều kèm header X-Request-Id – hãy gửi kèm khi liên hệ bộ phận hỗ trợ
• Nếu bạn tự gửi header X-Request-Id, API sẽ dùng nó
• Văn bản lỗi trong message theo ngôn ngữ tài khoản của chủ sở hữu không gian làm việc, nếu không thì theo Accept-Language; mã trong error luôn giữ nguyên

#Gọi từ trình duyệt?

Về mặt kỹ thuật, API cho phép gọi từ trình duyệt (CORS). Nhưng mã bí mật của khóa không bao giờ được nằm trong mã chạy phía khách truy cập – không trong website, cũng không trong ứng dụng. Hãy luôn gọi API từ máy chủ của bạn.

#Gói

Không có hạn mức lệnh gọi API theo gói. Chỉ có giới hạn tần suất theo phút. Giới hạn nội dung của gói – như số trang, liên kết hay khối mỗi trang – áp dụng qua API giống như trong bảng điều khiển. Xem So sánh các gói.

#Lệnh gọi đầu tiên

# Đổi khóa lấy token
curl -X POST https://dock.at-harbor.com/v1/token \
  -H "Content-Type: application/json" \
  -d '{"key_id":"6F668EA6598B0692","key_secret":"lt_…"}'
# → {"token":"eyJ…","expires_in":900}

export LH_TOKEN="eyJ…"

# Liệt kê trang (phạm vi read:pages)
curl https://dock.at-harbor.com/v1/pages \
  -H "Authorization: Bearer $LH_TOKEN"

Một ví dụ đầy đủ về thêm liên kết, đổi thiết kế và xuất bản có trong Cập nhật trang qua API.