Góc API

Tạo khung, caption, sự kiện, bộ đôi và tủ đồ. Dùng API key hiện có qua X-API-Key hoặc Authorization: Bearer YOUR_API_KEY.

Bắt đầu

1. Gọi GET /api/v1/studio/accounts để chọn UID được phép. Có phân trang ?page=1&limit=100.
2. Nếu đơn chưa có UID, gọi POST /accounts/resolve với {"orderId":123} để đối chiếu riêng đơn đó. API không tự tạo user Locket.
3. Gọi GET /catalog và GET /users/USER_ID. Kiểm tra Gold còn hiệu lực và liên kết điện thoại theo hướng dẫn bên dưới; dùng POST /preview để thử.
4. Lưu bằng revision mới nhất sau khi đã liên kết. Nếu nhận 409, đọc lại trạng thái/cấu hình trước khi thử lại; không tự ghi đè hoặc lặp vô hạn.

Danh sách thao tác

Liên kết điện thoại

Đây là các đường dẫn của website, sau /api/v1/studio. Website giữ phiên VPS ở backend; các đường dẫn đọc/xác nhận/hủy dưới đây khác API VPS có sessionId.

Dùng cùng API key website trong suốt luồng. Mỗi key/actor giữ một phiên hiện tại tại backend, ràng buộc UID thuộc đơn thành công của bạn (hoặc quyền admin). Không nhận sessionId, UID ghi đè trong body/query hoặc URL máy chủ từ trình duyệt. Giữ key ở máy chủ/bot; phiên đăng nhập trên web dùng CSRF.

1. Khi chưa liên kết, tạo phiên rồi bật đúng DNS/hồ sơ. Mở lại Locket bằng tài khoản đã chọn, chụp thử ảnh → Chú thích/Caption → Liên kết điện thoại → đọc 8 số.
2. Gửi mã để xác nhận. Chỉ tiếp tục lưu khi linked: true và Gold vẫn còn hiệu lực. needs_admin_review cần hỗ trợ; không tự ghi đè.
3. Sau xác nhận, mở lại Locket với đúng DNS/hồ sơ để tải cấu hình. Khi chỉ đổi khung, giữ caption riêng hiện tại; caption admin vẫn đứng đầu.

Phiên/mã hết hạn sau 8 phút; theo expiresAt và serverTime. 400: mã sai/cũ; xem attemptsRemaining. 410: hết hạn. 429: chờ theo Retry-After; không tạo phiên để đặt lại lượt. Nếu mất phản hồi xác nhận, đọc lại trạng thái trước khi thử tiếp. Không cần polling liên tục; nếu dùng, cách nhau ít nhất 3 giây và dừng khi kết thúc/đổi tài khoản.

Ví dụ: đặt chủ đề và tâm trạng

Thay YOUR_API_KEY, USER_ID, REVISION_FROM_LATEST_RESPONSE bằng dữ liệu của bạn. Chỉ gửi key từ máy chủ/bot của bạn; không nhúng key vào trang công khai.

curl "https://locket.lunakey.net/api/v1/studio/accounts" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://locket.lunakey.net/api/v1/studio/users/USER_ID" \
  -H "X-API-Key: YOUR_API_KEY"

curl -X PUT "https://locket.lunakey.net/api/v1/studio/users/USER_ID/appearance" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"revision":"REVISION_FROM_LATEST_RESPONSE","themeId":"pastel","moodId":"chill"}'

POST /frames/render?userId=USER_ID
{"settings":{"color1":"#C4B5FD","color2":"#FBCFE8","textColor":"#3B2855","thickness":6,"radius":24,"pattern":"hearts","nickname":"Minh"}}

PUT /events/my_birthday
{"revision":"REVISION","event":{"id":"my_birthday","name":"Sinh nhật","enabled":true,"userId":"USER_ID","kind":"annual","month":11,"day":1,"themeId":"love"}}

PUT /couples/our_theme
{"revision":"REVISION","couple":{"id":"our_theme","name":"Chúng mình","enabled":true,"userIds":["USER_ID","PARTNER_ID"],"themeId":"love"}}

POST /wardrobe-links
{"userId":"USER_ID","allowedThemeIds":["pastel","love"],"allowMood":true,"allowNickname":true,"days":30}

Hiểu phản hồi

401: key/phiên không hợp lệ. 403: tài khoản ngoài phạm vi. 409: cấu hình vừa thay đổi. 429: chờ theo header Retry-After. Lỗi trả {"success":false,"error":"..."}; không gọi lại mù với một thao tác đang chờ.

Sự kiện → diện mạo riêng → bộ đôi → lịch chung → mặc định là thứ tự chọn diện mạo. Riêng caption admin luôn là nhóm đầu tiên trong runtime.captionGroups; phía khách nên hiển thị đúng mảng này.

Sau khi lưu, người dùng mở lại Locket với DNS/hồ sơ đúng để tải cấu hình; cần quyền Gold phù hợp. API không thể bật Locket Looks ✨ khi tính năng đó chưa được hỗ trợ. Trên website, Studio dùng phiên đăng nhập và CSRF; key upstream không gửi đến trình duyệt.