Sari la conținut
← Înapoi la Ghiduri

Referința API

11 min de citit

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 folosi app.prewalk.co: face o redirecționare (308), iar majoritatea clienților HTTP renunță la antetul Authorization la 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 429 cu un antet Retry-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 calePermisiuneCe face
GET /api/mereadContul, profilurile și permisiunile cheii
GET /api/toursreadListează tururile contului (limit ≤ 50, cursor, profileId)
GET /api/tours/{id}readUn tur cu scenele, hotspoturile și setările lui
GET /api/tours/{id}/eventsreadProgresul procesării, ca flux de evenimente trimise de server
POST /api/tourswriteCreează un tur ({"title": "…"})
PATCH /api/tours/{id}writeModifică titlul, descrierea, categoria, locația, etichetele, slug (adresa lizibilă), ordinea scenelor, scena de start, numele scenelor
POST /api/tours/{id}/sceneswriteÎncarcă o imagine 360° ca corp brut
POST /api/content/{id}/visibilitywritePublică un tur sau un proiect, îl face doar cu link sau îl protejează cu parolă
GET /api/projectsreadListează proiectele contului (limit, cursor, profileId)
GET /api/projects/{id}readUn proiect cu tururile, imaginile, videoclipurile și schițele lui
GET /api/stats/{contentId}statsVizualizările unui tur sau proiect (range în zile)
GET /api/stats/{contentId}/export.csvstatsAcelaș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ă sau null pentru scena de start;
  • scenes: un obiect cu id-urile scenelor drept chei, cu name, view ({"yaw", "pitch", "fov"}) și north (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/tiff sau image/webp;
  • x-file-name: numele fișierului, codificat pentru URL (encodeURIComponent); scena primește numele după el, așa că 01-living-room.jpg devine „01 living room”;
  • x-pw-upload-batch și x-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; o category este obligatorie (seteaz-o mai întâi cu PATCH) ș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; omite password ca 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"]}}
EvenimentCândDate
scene.readyScena 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.sharpenedTile-urile la rezoluție completă sunt la locul lorstage: "refine", ok (false când etapa a fost abandonată și scena rămâne la calitatea de previzualizare), pending
scene.vr_readyTexturile VR sunt la locul lorstage: "vr", ok, pending
scene.failedProcesarea a eșuat definitiverror cu motivul
pingButonul „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

StatusCodSemnificație
400invalid_requestUn câmp lipsește sau nu este valid; field îl numește
400unsupported_format, unsupported_ratio, unreadable_image, rights_required, category_required, project_needs_contentCondiții prealabile pentru încărcare sau publicare (un proiect are nevoie de un tur public, o imagine sau un videoclip)
401unauthorized, invalid_api_keyNicio cheie sau o cheie greșit formatată ori revocată
402plan_required, quota_exceededPlanul nu include funcția sau o limită a fost atinsă (feature sau limit spune care)
403api_key_forbidden, api_scope_missingEndpointul nu este disponibil pentru chei sau cheii îi lipsește permisiunea
404not_foundNu îți aparține, a fost șters sau nu există un astfel de id
409revision_conflict, slug_taken, in_password_projectEditare concurentă (turul actual este inclus), adresă deja folosită, regula parolei proiectului
413file_too_largePeste limita de dimensiune
429rate_limitedPrea multe cereri; așteaptă Retry-After secunde
503maintenancePrewalk 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ște project_needs_public_tour și project_needs_tour, care nu se mai trimit. GET /api/projects adaugă videoCount.
  • 22 octombrie 2026: scene.ready conține pending; evenimente noi: scene.sharpened și scene.vr_ready; antete pentru ordinea încărcării: x-pw-upload-batch și x-pw-upload-index; GET /api/me apelat 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