Chuyển đến nội dung
← Quay lại Hướng dẫn

Tài liệu tham khảo API

13 phút đọc

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ùng app.prewalk.co: địa chỉ này chuyển hướng (308) và hầu hết HTTP client bỏ header Authorization khi 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êm field. 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 429 kèm header Retry-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ẫnPhạm vi quyềnChức năng
GET /api/mereadTài khoản, hồ sơ và phạm vi quyền của khóa
GET /api/toursreadLiệt kê các tour của tài khoản (limit ≤ 50, cursor, profileId)
GET /api/tours/{id}readMột tour kèm cảnh, hotspot và cài đặt
GET /api/tours/{id}/eventsreadTiến trình xử lý dưới dạng luồng server-sent event
POST /api/tourswriteTạ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}/sceneswriteTải lên một ảnh 360° dưới dạng phần thân thô
POST /api/content/{id}/visibilitywriteXuấ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/projectsreadLiệt kê các dự án của tài khoản (limit, cursor, profileId)
GET /api/projects/{id}readMột dự án kèm tour, ảnh, video và sơ đồ mặt bằng
GET /api/stats/{contentId}statsLượt xem của một tour hoặc dự án (range tính bằng ngày)
GET /api/stats/{contentId}/export.csvstatsDữ 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ặc null để dùng cảnh bắt đầu;
  • scenes: một object có khóa là id cảnh, với name, 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/tiff hoặc image/webp;
  • x-file-name: tên tệp, mã hóa URL (encodeURIComponent); cảnh được đặt tên theo tệp, nên 01-living-room.jpg trở thành “01 living room”;
  • x-pw-upload-batch và 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ằng PATCH) 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ệnThời điểmDữ liệu
scene.readyCả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.sharpenedCác tile độ phân giải đầy đủ đã sẵn sàngstage: "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_readyTexture VR đã sẵn sàngstage: "vr", ok, pending
scene.failedXử lý thất bại hẳnerror kèm lý do
pingNú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áiMãÝ nghĩa
400invalid_requestMột trường bị thiếu hoặc không hợp lệ; field cho biết trường nào
400unsupported_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)
401unauthorized, invalid_api_keyHoàn toàn không có khóa, hoặc khóa sai định dạng hay đã bị thu hồi
402plan_required, quota_exceededGó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)
403api_key_forbidden, api_scope_missingEndpoint không mở cho khóa API, hoặc khóa thiếu phạm vi quyền
404not_foundKhông thuộc về bạn, đã bị xóa, hoặc không có id này
409revision_conflict, slug_taken, in_password_projectChỉ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
413file_too_largeVượt quá giới hạn kích thước
429rate_limitedQuá nhiều yêu cầu; chờ Retry-After giây
503maintenancePrewalk đ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 cho project_needs_public_tour và project_needs_tour, vốn không còn được gửi. GET /api/projects có thêm videoCount.
  • 22 tháng 10 năm 2026: scene.ready mang pending; sự kiện mới scene.sharpened và scene.vr_ready; header thứ tự tải lên x-pw-upload-batch và x-pw-upload-index; GET /api/me khi 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