Stacking — Register#

Worker auth service account vào Google Drive folder đã được assign tạo sẵn. Giai đoạn này xác nhận service account có quyền truy cập folder và sẵn sàng tạo file.

Base URL: https://manager.likepion.com/api/v1/stacking

1. Lấy danh sách task #

# Không gửi status → trả cả register + connect (worker tự xử lý theo status từng task)
curl -X GET 'https://manager.likepion.com/api/v1/stacking/links?limit=5' \
  -H 'X-API-Key: <api_key>'

# Lọc riêng từng phase (tuỳ chọn):
curl -X GET 'https://manager.likepion.com/api/v1/stacking/links?limit=5&status=register' \
  -H 'X-API-Key: <api_key>'
ParamMặc địnhMô tả
limit5Số task muốn pull (tối đa 1000)
status(cả register + connect)Lọc theo trạng thái task. Không gửi → trả về cả 2 phase. Gửi register chỉ task phase 1, gửi connect chỉ task phase 2 (auth xong, đang chờ tạo file).

💡 Khuyến nghị: Worker nên KHÔNG gửi status để pull cả 2 phase, sau đó dispatch dựa vào field status trong từng task response. Tránh phải gọi 2 endpoint riêng cho register/connect.

Response#

{
  "success": true,
  "data": [
    {
      "id": "c5d8e912-3a4b-5c6d-7e8f-abc123def456",
      "request_id": "f37e0e54-d93a-4b06-98cc-1002301c696c",
      "status": "register",
      "domain": "docs.google.com",
      "website": "https://likepion.com",
      "title": "Dịch vụ SEO chuyên nghiệp 2026",
      "about": "<p>Nội dung bài viết...</p>",
      "phone": "0987654321",
      "address": "123 ABC",
      "location": "Ha Noi",
      "image_url": "https://s3.likepion.com/stack/cover.jpg",
      "folder_id": "1AiNsOTpmIlINZa_2QaXmpQxOGLNEAz2a",
      "link_post": ""
    }
  ]
}

Giải thích fields#

FieldMô tả
idID task — dùng khi gọi start/complete/fail
request_idID request cha
statusTrạng thái hiện tại (register)
domainNền tảng Drive (docs.google.com, slides.google.com, sheets.google.com)
websiteWebsite khách hàng (anchor backlink trỏ về đây)
titleTiêu đề file Drive
aboutNội dung bài viết HTML (đã xử lý spin)
phoneSố điện thoại chèn vào file
addressĐịa chỉ chèn vào file
locationVị trí / thành phố
image_urlS3 URL ảnh insert vào file Drive
folder_idID folder Drive assign chỉ định cho task này
link_postURL Drive folder đã tạo — chuỗi rỗng "" nếu chưa complete lần nào (retry từ profile_failed sẽ có giá trị)

2. Lấy chi tiết task #

Lấy thông tin 1 task cụ thể theo id. Không cần filter server/status. Không thay đổi DB.

curl -X GET 'https://manager.likepion.com/api/v1/stacking/links/TASK_ID' \
  -H 'X-API-Key: <api_key>'

Response#

Trả về 1 object (không bọc trong mảng) — schema giống bước 1.

{ "success": true, "data": { ...task fields... } }

Nếu task không tồn tại hoặc đã soft-delete → HTTP 404 {"success": false, "message": "task not found"}.

3. Báo đang xử lý #

Sau khi pull task, bắt buộc gọi API này để chuyển task từ register → registering.

Trạng thái trướcTrạng thái sau
registerregistering

Lưu ý: API chỉ chấp nhận task có status = register. Task ở trạng thái khác sẽ bị từ chối.

curl -X POST 'https://manager.likepion.com/api/v1/stacking/links/<task_id>/start' \
  -H 'X-API-Key: <api_key>'

Response#

{ "success": true }

4. Báo hoàn thành #

Báo register thành công — task chuyển từ registering → profiled. Worker cần hoàn tất auth service account + tạo file Drive + điền nội dung + backlink trong 1 lần call (stacking không có intermediate auth-only).

Trạng thái trướcTrạng thái sau
registeringprofiled

Assign barrier per-folder: khi tất cả task trong CÙNG 1 folder_id đã thoát phase 1 (profiled / final_failed / cancel), batch transition profiled → connect cho riêng folder đó — không đợi folder khác. Mỗi Link Folder tiến độ độc lập. Request-level flip sang connecting khi mọi folder đều đã phase 2.

Lưu ý: link_post chính là URL của Google Drive folder (https://drive.google.com/drive/folders/<id>).

curl -X POST 'https://manager.likepion.com/api/v1/stacking/links/<task_id>/complete' \
  -H 'X-API-Key: <api_key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "link_post": "https://drive.google.com/drive/folders/1AiNsOTpmIlINZa_2QaXmpQxOGLNEAz2a",
    "note": "auth + files created"
  }'
FieldBắt buộcMô tả
link_post✔URL folder Google Drive
noteGhi chú (tuỳ chọn)

Response#

{ "success": true }

5. Báo thất bại #

Task chuyển từ registering → profile_failed. Retry manager tự re-queue nếu còn retry_count < max_retries.

Trạng thái trướcTrạng thái sau
registeringprofile_failed
curl -X POST 'https://manager.likepion.com/api/v1/stacking/links/<task_id>/fail' \
  -H 'X-API-Key: <api_key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "error_message": "Drive quota exceeded when creating doc",
    "note": "auth_ok_but_file_creation_failed"
  }'
FieldBắt buộcMô tả
error_message✔Mô tả ngắn lỗi (≤1000 ký tự)
noteGhi chú thêm

Response#

{ "success": true }

6. Check trạng thái folder #

Check xem folder đã có task nào chuyển sang phase connect chưa. Worker poll endpoint này trước khi pull task phase 2 — nếu ready=false thì chưa cần gọi /stacking/links?status=connect.

Chỉ đếm task được gán cho server đang gọi (filter theo X-API-Key).

curl -X GET 'https://manager.likepion.com/api/v1/stacking/folders/1AiNsOTpmIlINZa_2QaXmpQxOGLNEAz2a/connect-status' \
  -H 'X-API-Key: <api_key>'

Response#

{
  "success": true,
  "folder_id": "1AiNsOTpmIlINZa_2QaXmpQxOGLNEAz2a",
  "ready": true,
  "total_tasks": 11,
  "phase1_active": 0,
  "profiled": 0,
  "connect_count": 9,
  "by_status": {
    "connect": 9,
    "final_failed": 2
  }
}
FieldMô tả
readytrue nếu đã có ≥1 task status ∈ (connect / connecting / connect_failed) — folder đã bước phase 2
total_tasksTổng task của folder này thuộc server đang gọi
phase1_activeTask còn ở phase 1 (pending/queued/running/register/registering/profile_failed/…) — chưa xong barrier
profiledTask đã profiled, chờ completer transition sang connect
connect_countTask đã ở phase 2
by_statusBreakdown chi tiết theo từng status

Lỗi:

CodeMô tả
400Thiếu folder_id trong path
403 service_key_mismatchAPI key không thuộc server có service google_stacking / stacking
403 server_not_onlineServer đang offline — gọi /worker/health trước để hồi phục
Backward Google Stacking Connect — Liên kết file Forward