Tài liệu tham khảo API
API Prewalk là một phần của gói Enterprise. Với một khóa API, phần mềm của riêng bạn có thể tạo tour, tải lên cảnh, xuất bản, đọc dự án và thống kê, và nhận một webhook có chữ ký ở mọi giai đoạn xử lý. Trang này là tài liệu tham khảo; studio và trình xem công khai vẫn hoạt động như trước.
URL gốc và quy ước
- URL gốc:
https://prewalk.co. Không dùngapp.prewalk.co: địa chỉ này chuyển hướng (308) và hầu hết HTTP client bỏ headerAuthorizationkhi chuyển hướng sang một host khác. - Định dạng: JSON cho cả đầu vào lẫn đầu ra (
Content-Type: application/json), trừ việc tải lên cảnh, vốn gửi ảnh dưới dạng phần thân thô của yêu cầu. - ID gồm 12 chữ cái thường và chữ số, ví dụ
teeg8crtm0u0. Ngày giờ theo chuẩn ISO 8601, múi giờ UTC. - Lỗi luôn có cùng một dạng: một mã trạng thái HTTP và
{"error": {"code": "…", "message": "…"}}; lỗi xác thực dữ liệu có thêmfield. Danh sách mã lỗi nằm ở cuối trang này. - Giới hạn tần suất: 600 yêu cầu mỗi phút cho mỗi khóa. Khi vượt quá, bạn nhận
429kèm headerRetry-After(tính bằng giây).
Xác thực
Tạo khóa trong Cài đặt → API (chủ sở hữu hoặc quản trị viên tài khoản, gói Enterprise). Một khóa thuộc về tài khoản, có thể được giới hạn cho một hồ sơ thương hiệu, và có tối đa ba phạm vi quyền: read, write và stats. Khóa đầy đủ chỉ hiện một lần; danh sách chỉ hiện tiền tố của khóa. Tối đa 20 khóa mỗi tài khoản; khóa bị thu hồi sẽ ngừng hoạt động ngay lập tức.
Authorization: Bearer pw_…
Một khóa hoạt động thay mặt cho một tài khoản. GET /api/me mô tả những gì khóa có thể thấy: tài khoản và giới hạn gói của tài khoản đó, các hồ sơ của tài khoản, hồ sơ mà khóa đại diện (actor) và chính khóa cùng các phạm vi quyền của nó. Endpoint này không bao giờ trả về email của chủ khóa hay các tài khoản khác của người đó.
Các endpoint
| Phương thức và đường dẫn | Phạm vi quyền | Chức năng |
|---|---|---|
GET /api/me | read | Tài khoản, hồ sơ và phạm vi quyền của khóa |
GET /api/tours | read | Liệt kê các tour của tài khoản (limit ≤ 50, cursor, profileId) |
GET /api/tours/{id} | read | Một tour kèm cảnh, hotspot và cài đặt |
GET /api/tours/{id}/events | read | Tiến trình xử lý dưới dạng luồng server-sent event |
POST /api/tours | write | Tạo một tour ({"title": "…"}) |
PATCH /api/tours/{id} | write | Đổi tiêu đề, mô tả, danh mục, địa điểm, thẻ, slug (địa chỉ dễ đọc), thứ tự cảnh, cảnh bắt đầu, tên cảnh |
POST /api/tours/{id}/scenes | write | Tải lên một ảnh 360° dưới dạng phần thân thô |
POST /api/content/{id}/visibility | write | Xuất bản, đặt chế độ chỉ người có liên kết, hoặc bảo vệ bằng mật khẩu cho tour hoặc dự án |
GET /api/projects | read | Liệt kê các dự án của tài khoản (limit, cursor, profileId) |
GET /api/projects/{id} | read | Một dự án kèm tour, ảnh, video và sơ đồ mặt bằng |
GET /api/stats/{contentId} | stats | Lượt xem của một tour hoặc dự án (range tính bằng ngày) |
GET /api/stats/{contentId}/export.csv | stats | Dữ liệu tương tự dưới dạng CSV (table = daily, scenes hoặc referrers) |
Mọi endpoint khác đều trả về 403 api_key_forbidden khi gọi bằng khóa. Tài khoản, nhóm, thanh toán, khóa API và webhook được quản lý trong trình duyệt.
Tour
Liệt kê. GET /api/tours?limit=50 trả về {"items": […], "next": "…", "usage": {…}}. Gửi lại next dưới dạng cursor để lấy trang tiếp theo; usage chứa số cảnh và các giới hạn của tài khoản. Mỗi mục có id, title, visibility, publishedAt, createdAt, updatedAt, hồ sơ và số lượng cảnh.
Đọc. GET /api/tours/{id} trả về toàn bộ tour: title, description, category, location, tags, slug, visibility (public, link hoặc password), hasPassword, publishedAt, profile, projectId, startScene, coverScene, revision, scenes theo thứ tự, hotspots, settings, audio và links (player là địa chỉ để chia sẻ, post là trang công khai khi đã xuất bản).
Một cảnh có id, name, status (queued, processing, ready hoặc error), createdAt, có thể có view (hướng nhìn mở đầu: yaw, pitch và fov tính bằng radian), north (radian; 0 là tâm ảnh, tăng dần sang phải), và trong lúc đang xử lý có stage và pct. Một cảnh đã sẵn sàng mang meta với các cấp tile và thư mục gốc của media.
Tạo. POST /api/tours với {"title": "Harbor View — Unit 4"} trả về tour mới. Nếu không có tiêu đề, tour được đặt tên là “Tour chưa đặt tên”.
Cập nhật. PATCH /api/tours/{id} nhận bất kỳ trường nào sau đây và trả về tour:
title,description,category,location,tags(mảng chuỗi),slug(địa chỉ công khai, gồm chữ cái thường, chữ số và dấu gạch ngang),commentsEnabled;order: một mảng id cảnh theo thứ tự bạn muốn; các cảnh bạn không liệt kê giữ vị trí của chúng sau những cảnh đã liệt kê;startScene: một id cảnh; cảnh này được chuyển lên đầu (cảnh đầu tiên là cảnh bắt đầu);coverScene: một id cảnh, hoặcnullđể dùng cảnh bắt đầu;scenes: một object có khóa là id cảnh, vớiname,view({"yaw", "pitch", "fov"}) vànorth(độ).
Gửi If-Match: "<revision>" với revision bạn đọc gần nhất để từ chối ghi đè lên thay đổi của người khác: khi đó câu trả lời là 409 revision_conflict kèm tour hiện tại trong error.tour. Nếu không có If-Match, lần ghi sau cùng sẽ thắng.
Tải lên cảnh
POST /api/tours/{id}/scenes với tệp ảnh làm phần thân thô. Các header:
Content-Type:image/jpeg,image/png,image/tiffhoặcimage/webp;x-file-name: tên tệp, mã hóa URL (encodeURIComponent); cảnh được đặt tên theo tệp, nên01-living-room.jpgtrở thành “01 living room”;x-pw-upload-batchvàx-pw-upload-index(tùy chọn): khi bạn tải lên song song nhiều tệp của cùng một lần chọn, gán cho chúng cùng một id lô (chữ cái, chữ số,-và_, tối đa 32 ký tự) và chỉ số của từng tệp trong lần chọn; khi đó máy chủ giữ đúng thứ tự ấy, bất kể tệp nào xong trước. Nếu không có hai header này, cảnh được thêm vào theo thứ tự đến.
Ảnh được chấp nhận: ảnh toàn cảnh equirectangular 2:1 đến chiều rộng tối đa của gói (8K với gói Miễn phí, 16K từ gói Pro trở lên), hoặc ảnh toàn cảnh stereo top-bottom 1:1 từ gói Pro trở lên (mắt trái ở trên), tối đa 1 GiB. Câu trả lời là cảnh (status: "queued"). Quá trình xử lý chạy theo từng giai đoạn: cảnh hiện ra trước (tile xem trước), sau đó các tile độ phân giải đầy đủ được thêm vào (“làm nét”), cùng texture VR từ gói Pro trở lên; hai giai đoạn này chạy song song và giai đoạn nào cũng có thể xong trước. meta.pending của cảnh, luồng sự kiện và webhook cho bạn biết giai đoạn nào vẫn đang chạy.
Lỗi: 400 unsupported_format (không phải JPG, PNG, TIFF hoặc WebP), 400 unsupported_ratio (không phải 2:1, hoặc 1:1 top-bottom), 400 unreadable_image (tệp bị hỏng), 402 plan_required (16K hoặc stereo trên gói không có tính năng này), 402 quota_exceeded (giới hạn cảnh của tài khoản), 413 file_too_large.
Tiến trình xử lý
GET /api/tours/{id}/events là một luồng server-sent event (text/event-stream). Các sự kiện: hello khi kết nối, queue (vị trí trong hàng đợi của các cảnh đang chờ và bản tóm tắt tour, vài giây một lần khi có tác vụ đang chạy), scene (status, stage, pct hoặc error) và tour (tour đã thay đổi; đọc lại tour). Để tích hợp giữa máy chủ với máy chủ, nên dùng webhook ở bên dưới.
Xuất bản và chế độ hiển thị
POST /api/content/{id}/visibility dùng được cho cả tour và dự án, và trả về nội dung đó:
{"visibility": "link"}– chỉ truy cập được qua địa chỉ của nội dung (mặc định của mọi tour mới);{"visibility": "public", "rightsAccepted": true}– hiện trên hồ sơ, trong Khám phá và được lập chỉ mục; bắt buộc phải cócategory(đặt trước bằngPATCH) và bạn xác nhận rằng mình có quyền xuất bản các hình ảnh. Với dự án, thêm"tourIds": [...]để xuất bản các tour cùng với dự án;{"visibility": "password", "password": "…"}– từ gói Pro trở lên; bỏpasswordđể giữ mật khẩu hiện tại.
Một tour nằm trong dự án được bảo vệ bằng mật khẩu không thể chuyển sang công khai hay có mật khẩu riêng (409 in_password_project); mật khẩu của dự án là lớp bảo vệ.
Dự án
Hiện tại, dự án chỉ đọc được qua API. GET /api/projects liệt kê dự án với id, title, slug, visibility, category, coverUrl, tourCount, imageCount, videoCount và ngày tháng; GET /api/projects/{id} có thêm description, location, tags, urls (public và liên kết riêng tư), tours kèm cảnh, cùng thư viện images, videos và floorplans kèm ghim. Hãy tạo dự án và thêm media trong studio.
Thống kê
GET /api/stats/{contentId}?range=30 trả về lượt xem của một tour hoặc dự án. Dữ liệu bạn nhận được tùy theo gói: total từ trước đến nay với gói Miễn phí; chuỗi daily có điền số 0 (from, to, tối đa 90 ngày) với gói Pro; tối đa 365 ngày cùng sources (trang, bản nhúng, truy cập trực tiếp), devices (điện thoại, máy tính, kính VR), scenes và referrers nhúng với gói Office và Enterprise. …/export.csv?range=30&table=daily cho bảng theo ngày, table=scenes cho lượt xem theo từng cảnh và table=referrers cho các trang web nhúng. Lượt xem được tính theo địa chỉ người truy cập và nội dung, mỗi 30 phút một lần; không lưu thông tin cá nhân nào.
Webhook
Thêm tối đa năm webhook trong Cài đặt → API. Chúng tôi gửi một POST có chữ ký với phần thân JSON:
{"eventId": "evt_…", "eventType": "scene.ready", "occurredAt": "2026-10-22T09:12:03.000Z",
"data": {"tourId": "…", "sceneId": "…", "status": "ready", "pending": ["refine", "vr"]}}
| Sự kiện | Thời điểm | Dữ liệu |
|---|---|---|
scene.ready | Cảnh đã hiển thị được (tile xem trước) | pending: các giai đoạn vẫn đang chạy – refine (tile độ phân giải đầy đủ) và vr (texture cho kính VR); [] khi bản xem trước là bản cuối cùng |
scene.sharpened | Các tile độ phân giải đầy đủ đã sẵn sàng | stage: "refine", ok (false khi giai đoạn này bị bỏ qua và cảnh giữ chất lượng xem trước), pending |
scene.vr_ready | Texture VR đã sẵn sàng | stage: "vr", ok, pending |
scene.failed | Xử lý thất bại hẳn | error kèm lý do |
ping | Nút “Gửi thử” | trống |
Header: Prewalk-Signature: ts=<unix seconds>;h1=<hex>, trong đó h1 là HMAC-SHA256 của ts + ":" + body với secret webhook của bạn (tính trên đúng các byte bạn nhận được), cùng với Prewalk-Event-Id và Prewalk-Event-Type. Trong lúc đang xoay vòng secret, header mang hai giá trị h1 (ts=…;h1=<new>;h1=<old>) cho đến khi secret trước hết hạn: chấp nhận lần gửi khi bất kỳ giá trị nào xác minh hợp lệ. Xác minh chữ ký, từ chối timestamp cũ hơn vài phút, và loại bỏ trùng lặp theo eventId: một lần gửi được thử lại cho đến khi endpoint của bạn trả về 2xx (mười lần thử, 30 giây rồi tăng gấp đôi, tổng cộng khoảng bốn giờ) và phần thân gửi lại giống hệt đến từng byte. Sau 20 lần gửi thất bại liên tiếp, webhook bị tắt và chủ sở hữu tài khoản nhận được email. Endpoint phải dùng https trên một địa chỉ công khai; chúng tôi không đi theo chuyển hướng. Secret có thể được xoay vòng; secret trước vẫn hợp lệ trong 24 giờ.
Ví dụ từng bước
# 1. tạo một tour
curl -s https://prewalk.co/api/tours -H "Authorization: Bearer $PW_KEY" \
-H "Content-Type: application/json" -d '{"title":"Harbor View — Unit 4"}'
# 2. tải lên hai cảnh theo thứ tự
curl -s https://prewalk.co/api/tours/$TOUR/scenes -H "Authorization: Bearer $PW_KEY" \
-H "Content-Type: image/jpeg" -H "x-file-name: 01-living-room.jpg" \
-H "x-pw-upload-batch: sel-1" -H "x-pw-upload-index: 0" --data-binary @01-living-room.jpg
curl -s https://prewalk.co/api/tours/$TOUR/scenes -H "Authorization: Bearer $PW_KEY" \
-H "Content-Type: image/jpeg" -H "x-file-name: 02-kitchen.jpg" \
-H "x-pw-upload-batch: sel-1" -H "x-pw-upload-index: 1" --data-binary @02-kitchen.jpg
# 3. đặt danh mục và xuất bản
curl -s -X PATCH https://prewalk.co/api/tours/$TOUR -H "Authorization: Bearer $PW_KEY" \
-H "Content-Type: application/json" -d '{"category":"real-estate","location":"Istanbul"}'
curl -s https://prewalk.co/api/content/$TOUR/visibility -H "Authorization: Bearer $PW_KEY" \
-H "Content-Type: application/json" -d '{"visibility":"public","rightsAccepted":true}'
# 4. lượt xem trong 30 ngày qua
curl -s "https://prewalk.co/api/stats/$TOUR?range=30" -H "Authorization: Bearer $PW_KEY"
Nhúng
Nhúng không cần khóa: mỗi tour có https://prewalk.co/embed/{id}, và embed.js điều chỉnh kích thước khung và mở tour toàn màn hình trên trang của bạn. Những website nào được hiển thị bản nhúng của bạn được thiết lập trong Cài đặt → Nhận diện thương hiệu. Hướng dẫn nhúng có đầy đủ chi tiết.
Mã lỗi
| Trạng thái | Mã | Ý nghĩa |
|---|---|---|
| 400 | invalid_request | Một trường bị thiếu hoặc không hợp lệ; field cho biết trường nào |
| 400 | unsupported_format, unsupported_ratio, unreadable_image, rights_required, category_required, project_needs_content | Điều kiện tiên quyết khi tải lên hoặc xuất bản (dự án cần có một tour công khai, một ảnh hoặc một video) |
| 401 | unauthorized, invalid_api_key | Hoàn toàn không có khóa, hoặc khóa sai định dạng hay đã bị thu hồi |
| 402 | plan_required, quota_exceeded | Gói không có tính năng này, hoặc đã đạt giới hạn (feature hoặc limit cho biết cái nào) |
| 403 | api_key_forbidden, api_scope_missing | Endpoint không mở cho khóa API, hoặc khóa thiếu phạm vi quyền |
| 404 | not_found | Không thuộc về bạn, đã bị xóa, hoặc không có id này |
| 409 | revision_conflict, slug_taken, in_password_project | Chỉnh sửa đồng thời (kèm tour hiện tại), địa chỉ đã được dùng, quy tắc mật khẩu của dự án |
| 413 | file_too_large | Vượt quá giới hạn kích thước |
| 429 | rate_limited | Quá nhiều yêu cầu; chờ Retry-After giây |
| 503 | maintenance | Prewalk đang cập nhật; thử lại sau một phút |
Thay đổi
- 10 tháng 11 năm 2026: dự án có thể được xuất bản hoặc bảo vệ bằng mật khẩu chỉ với ảnh hoặc video. Dự án không có gì để hiển thị sẽ trả về
400 project_needs_content, dù công khai hay có mật khẩu; mã này thay choproject_needs_public_tourvàproject_needs_tour, vốn không còn được gửi.GET /api/projectscó thêmvideoCount. - 22 tháng 10 năm 2026:
scene.readymangpending; sự kiện mớiscene.sharpenedvàscene.vr_ready; header thứ tự tải lênx-pw-upload-batchvàx-pw-upload-index;GET /api/mekhi gọi bằng khóa chỉ mô tả tài khoản của khóa đó.
Có câu hỏi hoặc cần một endpoint chưa có? Viết cho chúng tôi tại hello@prewalk.co.
Chia sẻ: Chia sẻ lên X LinkedIn WhatsApp



