Referința API
API-ul Prewalk face parte din planul Enterprise. Cu o cheie API, propriul tău software poate crea tururi, încărca scene, publica, citi proiecte și statistici și poate primi un webhook semnat la fiecare etapă de procesare. Această pagină este referința; studioul și playerul public funcționează în continuare ca până acum.
URL de bază și convenții
- URL de bază:
https://prewalk.co. Nu folosiapp.prewalk.co: face o redirecționare (308), iar majoritatea clienților HTTP renunță la antetulAuthorizationla o redirecționare către alt host. - Format: JSON la intrare și la ieșire (
Content-Type: application/json), cu excepția încărcării scenelor, care trimit imaginea ca corp brut al cererii. - ID-urile au 12 litere mici și cifre, de exemplu
teeg8crtm0u0. Datele calendaristice sunt în format ISO 8601, în UTC. - Erorile arată mereu la fel: un status HTTP și
{"error": {"code": "…", "message": "…"}}; erorile de validare adaugăfield. Codurile sunt enumerate la sfârșitul acestei pagini. - Limita de cereri: 600 de cereri pe minut pentru fiecare cheie. Peste ea primești
429cu un antetRetry-After(în secunde).
Autentificare
Creează o cheie în Setări → API (proprietarul sau un administrator al contului, Enterprise). O cheie aparține contului, poate fi limitată la un singur profil de brand și are până la trei permisiuni: read, write și stats. Cheia completă este afișată o singură dată; lista arată doar prefixul ei. Cel mult 20 de chei pe cont; o cheie revocată încetează imediat să funcționeze.
Authorization: Bearer pw_…
O cheie acționează pentru un singur cont. GET /api/me descrie ce poate vedea cheia: contul și limitele planului său, profilurile acelui cont, profilul în numele căruia acționează cheia (actor) și cheia însăși, cu permisiunile ei. Nu returnează niciodată e-mailul proprietarului cheii sau celelalte conturi ale acestuia.
Endpointuri
| Metodă și cale | Permisiune | Ce face |
|---|---|---|
GET /api/me | read | Contul, profilurile și permisiunile cheii |
GET /api/tours | read | Listează tururile contului (limit ≤ 50, cursor, profileId) |
GET /api/tours/{id} | read | Un tur cu scenele, hotspoturile și setările lui |
GET /api/tours/{id}/events | read | Progresul procesării, ca flux de evenimente trimise de server |
POST /api/tours | write | Creează un tur ({"title": "…"}) |
PATCH /api/tours/{id} | write | Modifică titlul, descrierea, categoria, locația, etichetele, slug (adresa lizibilă), ordinea scenelor, scena de start, numele scenelor |
POST /api/tours/{id}/scenes | write | Încarcă o imagine 360° ca corp brut |
POST /api/content/{id}/visibility | write | Publică un tur sau un proiect, îl face doar cu link sau îl protejează cu parolă |
GET /api/projects | read | Listează proiectele contului (limit, cursor, profileId) |
GET /api/projects/{id} | read | Un proiect cu tururile, imaginile, videoclipurile și schițele lui |
GET /api/stats/{contentId} | stats | Vizualizările unui tur sau proiect (range în zile) |
GET /api/stats/{contentId}/export.csv | stats | Același lucru în CSV (table = daily, scenes sau referrers) |
Orice alt endpoint răspunde cu 403 api_key_forbidden când este apelat cu o cheie. Contul, echipa, facturarea, cheile API și webhookurile se gestionează în browser.
Tururi
Listare. GET /api/tours?limit=50 returnează {"items": […], "next": "…", "usage": {…}}. Trimite next înapoi ca cursor pentru pagina următoare; usage conține numărul de scene și limitele contului. Fiecare element are id, title, visibility, publishedAt, createdAt, updatedAt, profilul și numărul de scene.
Citire. GET /api/tours/{id} returnează turul complet: title, description, category, location, tags, slug, visibility (public, link sau password), hasPassword, publishedAt, profile, projectId, startScene, coverScene, revision, scenes în ordine, hotspots, settings, audio și links (player este adresa care se poate distribui, post pagina publică după publicare).
O scenă are id, name, status (queued, processing, ready sau error), createdAt, opțional view (direcția inițială: yaw, pitch și fov în radiani), north (radiani; 0 este centrul imaginii, crescând spre dreapta), iar cât timp este procesată, stage și pct. O scenă gata conține meta, cu nivelurile de tile-uri și rădăcina fișierelor media.
Creare. POST /api/tours cu {"title": "Harbor View — Unit 4"} returnează turul nou. Fără titlu, se numește „Tur fără titlu”.
Actualizare. PATCH /api/tours/{id} acceptă oricare dintre aceste câmpuri și returnează turul:
title,description,category,location,tags(array de șiruri),slug(adresa publică: litere mici, cifre și cratime),commentsEnabled;order: un array de id-uri de scene, în ordinea dorită; scenele pe care le omiți își păstrează locul după cele enumerate;startScene: un id de scenă; scena este mutată pe primul loc (prima scenă este scena de start);coverScene: un id de scenă saunullpentru scena de start;scenes: un obiect cu id-urile scenelor drept chei, cuname,view({"yaw", "pitch", "fov"}) șinorth(grade).
Trimite If-Match: "<revision>" cu ultima revision citită ca să refuzi o scriere peste modificarea altcuiva: răspunsul este atunci 409 revision_conflict, cu turul actual în error.tour. Fără If-Match, câștigă ultima scriere.
Încărcarea scenelor
POST /api/tours/{id}/scenes cu fișierul imagine drept corp brut. Antete:
Content-Type:image/jpeg,image/png,image/tiffsauimage/webp;x-file-name: numele fișierului, codificat pentru URL (encodeURIComponent); scena primește numele după el, așa că01-living-room.jpgdevine „01 living room”;x-pw-upload-batchșix-pw-upload-index(opționale): când încarci în paralel mai multe fișiere dintr-o selecție, dă-le același id de lot (litere, cifre,-și_, până la 32 de caractere) și indexul lor în selecție; serverul păstrează atunci această ordine, indiferent care fișier se termină primul. Fără ele, scenele se adaugă în ordinea sosirii.
Imagini acceptate: panorame echirectangulare 2:1 până la lățimea permisă de plan (8K pe planul Gratuit, 16K de la planul Pro în sus) sau panorame stereo 1:1 top-bottom de la planul Pro în sus (ochiul stâng sus), de cel mult 1 GiB. Răspunsul este scena (status: "queued"). Procesarea se face în etape: mai întâi scena devine vizibilă (tile-uri de previzualizare), apoi sosesc tile-urile la rezoluție completă („clarificarea”) și, de la planul Pro în sus, texturile VR; cele două rulează în paralel și oricare se poate termina prima. meta.pending al scenei, fluxul de evenimente și webhookurile îți spun ce etape încă rulează.
Erori: 400 unsupported_format (nu este JPG, PNG, TIFF sau WebP), 400 unsupported_ratio (nu este 2:1 sau 1:1 top-bottom), 400 unreadable_image (fișier deteriorat), 402 plan_required (16K sau stereo pe un plan care nu le include), 402 quota_exceeded (limita de scene a contului), 413 file_too_large.
Progresul procesării
GET /api/tours/{id}/events este un flux de evenimente trimise de server (text/event-stream). Evenimente: hello la conectare, queue (poziția în coadă a scenelor care așteaptă și un rezumat al turului, la câteva secunde cât timp rulează ceva), scene (status, stage, pct sau error) și tour (turul s-a modificat; citește-l din nou). Pentru integrarea de la server la server, folosește de preferință webhookurile de mai jos.
Publicare și vizibilitate
POST /api/content/{id}/visibility funcționează pentru tururi și proiecte și returnează conținutul:
{"visibility": "link"}– accesibil doar prin adresa lui (setarea implicită a oricărui tur nou);{"visibility": "public", "rightsAccepted": true}– pe profil, în Explorează și indexabil; ocategoryeste obligatorie (seteaz-o mai întâi cuPATCH) și confirmi că ai dreptul să publici imaginile. Pentru un proiect, adaugă"tourIds": [...]ca să publici tururi împreună cu el;{"visibility": "password", "password": "…"}– de la planul Pro în sus; omitepasswordca să păstrezi parola actuală.
Un tur dintr-un proiect protejat cu parolă nu poate deveni public și nu poate primi propria parolă (409 in_password_project); parola proiectului este cea care controlează accesul.
Proiecte
Deocamdată, proiectele pot fi doar citite prin API. GET /api/projects le listează cu id, title, slug, visibility, category, coverUrl, tourCount, imageCount, videoCount și date; GET /api/projects/{id} adaugă description, location, tags, urls (public și linkul privat), tours cu scenele lor, precum și galeria images, videos și floorplans cu marcaje. Creează proiecte și adaugă fișiere media în studio.
Statistici
GET /api/stats/{contentId}?range=30 returnează vizualizările unui tur sau proiect. Ce primești depinde de plan: total din toate timpurile pe planul Gratuit; o serie daily completată cu zerouri (from, to, până la 90 de zile) pe planul Pro; până la 365 de zile plus sources (pagină, încorporare, direct), devices (telefon, desktop, ochelari VR), scenes și site-urile care încorporează (referrers) pe planurile Office și Enterprise. …/export.csv?range=30&table=daily oferă tabelul zilnic, table=scenes vizualizările pe scenă și table=referrers site-urile care încorporează. Vizualizările se numără pe adresă de vizitator și conținut, o dată la 30 de minute; nu se stochează nimic personal.
Webhookuri
Adaugă până la cinci webhookuri în Setări → API. Trimitem un POST semnat, cu un corp JSON:
{"eventId": "evt_…", "eventType": "scene.ready", "occurredAt": "2026-10-22T09:12:03.000Z",
"data": {"tourId": "…", "sceneId": "…", "status": "ready", "pending": ["refine", "vr"]}}
| Eveniment | Când | Date |
|---|---|---|
scene.ready | Scena este vizibilă (tile-uri de previzualizare) | pending: etapele care încă rulează – refine (tile-uri la rezoluție completă) și vr (texturi pentru ochelari); [] când previzualizarea este finală |
scene.sharpened | Tile-urile la rezoluție completă sunt la locul lor | stage: "refine", ok (false când etapa a fost abandonată și scena rămâne la calitatea de previzualizare), pending |
scene.vr_ready | Texturile VR sunt la locul lor | stage: "vr", ok, pending |
scene.failed | Procesarea a eșuat definitiv | error cu motivul |
ping | Butonul „Trimite un test” | gol |
Antete: Prewalk-Signature: ts=<unix seconds>;h1=<hex>, unde h1 este HMAC-SHA256 pentru ts + ":" + body cu secretul webhookului tău (calculat pe exact octeții primiți), plus Prewalk-Event-Id și Prewalk-Event-Type. Cât timp este în curs o rotire a secretului, antetul conține două valori h1 (ts=…;h1=<new>;h1=<old>) până când secretul anterior expiră: acceptă livrarea dacă oricare dintre ele se verifică. Verifică semnătura, respinge un timestamp mai vechi de câteva minute și elimină duplicatele după eventId: o livrare este reîncercată până când endpointul tău răspunde cu 2xx (zece încercări, 30 s, apoi intervalul se dublează, cam patru ore în total), iar corpul reîncercat este identic la nivel de octet. După 20 de livrări eșuate la rând, webhookul este dezactivat, iar proprietarul contului primește un e-mail. Endpointurile trebuie să fie https pe o adresă publică; redirecționările nu sunt urmate. Secretul poate fi rotit; cel anterior rămâne valabil 24 de ore.
Un exemplu pas cu pas
# 1. create a 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. upload two scenes in order
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. set a category and publish
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. views of the last 30 days
curl -s "https://prewalk.co/api/stats/$TOUR?range=30" -H "Authorization: Bearer $PW_KEY"
Încorporare
Încorporarea nu necesită o cheie: fiecare tur are https://prewalk.co/embed/{id}, iar embed.js dimensionează cadrul și îl deschide pe tot ecranul în pagina ta. Ce site-uri pot afișa încorporările tale se setează în Setări → Identitate vizuală. Ghidul de încorporare are detaliile.
Coduri de eroare
| Status | Cod | Semnificație |
|---|---|---|
| 400 | invalid_request | Un câmp lipsește sau nu este valid; field îl numește |
| 400 | unsupported_format, unsupported_ratio, unreadable_image, rights_required, category_required, project_needs_content | Condiții prealabile pentru încărcare sau publicare (un proiect are nevoie de un tur public, o imagine sau un videoclip) |
| 401 | unauthorized, invalid_api_key | Nicio cheie sau o cheie greșit formatată ori revocată |
| 402 | plan_required, quota_exceeded | Planul nu include funcția sau o limită a fost atinsă (feature sau limit spune care) |
| 403 | api_key_forbidden, api_scope_missing | Endpointul nu este disponibil pentru chei sau cheii îi lipsește permisiunea |
| 404 | not_found | Nu îți aparține, a fost șters sau nu există un astfel de id |
| 409 | revision_conflict, slug_taken, in_password_project | Editare concurentă (turul actual este inclus), adresă deja folosită, regula parolei proiectului |
| 413 | file_too_large | Peste limita de dimensiune |
| 429 | rate_limited | Prea multe cereri; așteaptă Retry-After secunde |
| 503 | maintenance | Prewalk se actualizează; reîncearcă după un minut |
Modificări
- 10 noiembrie 2026: un proiect poate fi publicat sau protejat cu parolă doar cu imagini sau videoclipuri. Un proiect fără nimic de afișat răspunde cu
400 project_needs_content, fie public, fie cu parolă; codul înlocuieșteproject_needs_public_tourșiproject_needs_tour, care nu se mai trimit.GET /api/projectsadaugăvideoCount. - 22 octombrie 2026:
scene.readyconținepending; evenimente noi:scene.sharpenedșiscene.vr_ready; antete pentru ordinea încărcării:x-pw-upload-batchșix-pw-upload-index;GET /api/meapelat cu o cheie descrie doar contul cheii.
Ai întrebări sau îți lipsește un endpoint? Scrie-ne la hello@prewalk.co.
Distribuie: Distribuie pe X LinkedIn WhatsApp



