Dokumentacija · API

REST API za vaš lokal, s ključem na kratkem povodcu.

Vse, kar počne nadzorna plošča, počne prek tega API-ja. Govori JSON prek HTTPS, odziva se na api.guestavo.com, klicatelj pa vstopi s ključem, ki pripada eni sami organizaciji in odpre le tisto, kar ste odkljukali.

Ključi so vklopljeni. Ta stran je orientacija, ključ pa ustvarite v nastavitvah.

Na voljo od zdaj

Ključ ustvarite v nastavitvah

Ključ pripada organizaciji, zato nastane tam: Nastavitve, nato Organizacije, nato izbrana, nato njen zavihek ključi API. Izberete lokale, kjer sme delati, in dejanja, ki jih sme tam izvesti, vrednost pa kopirate enkrat, ker je nikoli več ne pokažemo. Naprej je to ena glava pri vsaki zahtevi. Prekličete ga, kadar želite, in naslednji klic se vrne kot 401.

Izberite organizacijo, v kateri naj nastane

Oblika

Preprost REST, brez presenečenj

Kdor je v zadnjem desetletju uporabljal katerikoli JSON API, že ve, kako se ta obnaša.

Osnovni naslov: https://api.guestavo.com, izključno HTTPS. Vse dokumentirane poti so pod /api.
Zapis: JSON noter, JSON ven. Pri vsem, kar ima telo, pošljite Content-Type: application/json. Telesa se preverijo po shemi, preden jih vidi obravnavalnik.
Metode: GET bere, POST ustvari, PATCH posodobi, DELETE odstrani. Branje nikoli ničesar ne spremeni.
Identifikatorji: UUID-ji. Datumi so koledarski po ISO (2026-09-14), ure pa 24-urne (19:30) v časovnem pasu lokala.
Ponovni poskusi: Nekaj poti, ki ustvarjajo zapise, sprejme glavo Idempotency-Key in na ponovitev odgovori s prvim odgovorom, namesto da bi zapisala še en zapis.

Preverjanje pristnosti

Ena glava, ena organizacija

Ključ je žeton bearer. Dajte ga v glavo Authorization pri vsakem zahtevku. Drugega ni: nobene menjave žetonov, nobenega osveževanja.

Authorization: Bearer gvsk_your_key_here
Content-Type: application/json

01
Pripet na eno organizacijo
Ključ pripada eni sami organizaciji in do druge ne seže. Če ga uperite drugam, dobite 403, ki pove, da ključ za to organizacijo ne velja, ne da bi izdal identifikator, ki ga ne smete videti.
02
Omejen z obsegi
Obsegi so po modulu in po smeri: booking:read, booking:write, menu:read, staff:read, analytics:read in tako naprej. Pisalni obseg s seboj prinese bralno polovico in nastavitve to povedo naglas, namesto da bi ostalo neizrečeno. Denar ima svoj obseg: analytics:read vrne prihodek, maržo in plače, in nič drugega ga ne prinese s seboj.
03
Še ožje, če želite
Poleg obsegov je ključ mogoče omejiti na določene lokale in določena dejanja. Ključ, ki sme ustvarjati rezervacije na pomolu in povsod drugod brati le jedilnik, je čisto običajna stvar.
04
Poteče
Devetdeset dni, če ne rečete drugače, in največ leto. Menjava nič ne stane: ustvarite novega, starega prekličite.
05
Je skrivnost
Ključi se začnejo z gvsk_ in se vedejo kot geslo za lokal. Torej na strežnik, nikoli v brskalnik ali mobilno aplikacijo in nikoli v repozitorij.

Odgovori

Vsak odgovor nosi isto ovojnico

Uspeh ali napaka, vrhnja oblika je ista, zato se odjemalec lahko odloči po eni logični vrednosti, preden pogleda karkoli drugega.

Uspeh

{
  "success": true,
  "data": [ ... ],
  "meta": {
    "pagination": {
      "type": "offset",
      "totalCount": 214,
      "filteredCount": 12,
      "count": 12,
      "page": 1,
      "limit": 20,
      "hasMore": false
    }
  }
}

data nosi vsebino. Seznam doda meta.pagination s stranjo, omejitvijo, filtriranim številom in podatkom, ali kaj še čaka. Nekatere poti dodajo sporočilo za človeka, ustvarjanje pa odgovori s 201.

Napaka

{
  "success": false,
  "error": {
    "message": "This API key is not permitted to use create_booking",
    "code": "FORBIDDEN",
    "details": { "reason": "tool_not_granted" }
  }
}

error.code je strojno berljivi del in tisti, po katerem se odločate. error.message je angleška proza za dnevnik, details pa ob kršitvi sheme nosi težave po posameznih poljih.

Trije, ki jih boste res srečali

401Ni preverjeno
Ključ manjka, je neberljiv, potekel ali preklican, ali pa računa lastnika ni več.
Nehajte poskušati. Ključ v tem stanju si sam nikoli ne opomore, zato ustvarite novega in ga zamenjajte.
403Prepovedano
S ključem je vse v redu, z zahtevkom pa ne. Ali manjka obseg, ali je ključ pripet na drugo organizacijo, ali pa njegova dovoljenja tega dejanja oziroma tega lokala ne odpirajo.
Preberite error.details.reason. Tam piše, kateri od primerov je bil, in le enega lahko popravi klicatelj: nerazrešen lokal pomeni, da zahtevek ni navedel propertyId, na katerem ključ sme delovati, zato ga navedite in poskusite znova.
429Preveč zahtevkov
Eden od spodnjih vedrov je prazen.
Umaknite se in poskusite znova po glavi Retry-After ali po vrednosti v X-RateLimit-Reset, če glave Retry-After ni. Razporejanje istega dela na več ključev ne pomaga, ker ju skupni vedri seštejeta.

Ostalo

Status 400 je napačen zahtevek ali kršitev sheme, 404 zapis, ki ne obstaja ali ga vaš ključ ne sme videti, 409 spor, na primer rezervacija, ki ne gre več skupaj, 500 smo mi, 503 pa pomeni, da baza ali kaka druga odvisnost ni dosegljiva. Zadnja dva se splača ponoviti z naraščajočim zamikom.

Omejevanje prometa

Štiri vedra, ne eno

Zahtevek s ključem se šteje štirikrat in prvo prazno vedro ga zavrne. Ena omejitev na ključ ne bi bila omejitev, saj bi drugi ključ preprosto odprl drugo vedro.

600na minuto
Na klicoči gostitelj
Porabi se, še preden se pot sploh poišče, tako da tipanje stane tistega, ki tipa. Postavljeno visoko, ker en gostitelj lahko posreduje za ducat lokalov.
120na minuto
Na ključ
Šteje se na žetonu, kakršen pride, še pred preverjanjem. Neveljaven ključ se torej šteje tudi.
300na minuto
Na lastnika ključev
Vse, kar ustvarijo ključi ene osebe, kolikor jih pač ima.
600na minuto
Na organizacijo
Vse, kar posrka en lokal, ne glede na to, kdo drži ključe.

Zahtevke brez ključa ločeno omejuje splošna meja 100 na minuto na naslov. Šteje se po vseh instancah skupaj, X-RateLimit-Limit, X-RateLimit-Remaining in X-RateLimit-Reset pa pridejo nazaj z odgovorom, da si odjemalec lahko sam odmeri tempo, namesto da odkrije zid.

Primer

Kdo pride nocoj

Ena prava končna točka od začetka do konca. GET /api/bookings našteje rezervacije organizacije, filtrirati jih je mogoče po lokalu, obdobju, statusu in imenu gosta. Potrebuje booking:read, ki ga ključ z booking:write že ima.

Zahtevek

curl -G https://api.guestavo.com/api/bookings \
  -H "Authorization: Bearer gvsk_your_key_here" \
  --data-urlencode "organizationId=8f14e45f-ceea-467a-9f4c-1b2c3d4e5f60" \
  --data-urlencode "dateFrom=2026-09-14" \
  --data-urlencode "dateTo=2026-09-14" \
  --data-urlencode "status=confirmed" \
  --data-urlencode "limit=20"

Odgovor

{
  "success": true,
  "data": [
    {
      "id": "b7a0c5d2-1f3e-4a58-9c21-6d0e7f8a9b10",
      "propertyId": "3c9d1a77-2b4e-4f60-8d5a-11e2f3a4b5c6",
      "name": "Hribar",
      "date": "2026-09-14",
      "time": "19:30",
      "partySize": 6,
      "status": "confirmed",
      "notes": "Window table if there is one"
    }
  ],
  "meta": { "pagination": { "type": "offset", "count": 1, "page": 1, "limit": 20, "hasMore": false } }
}

01
organizationId je obvezen in mora biti organizacija, na katero je ključ pripet.
02
propertyId, status, dateFrom, dateTo in search so neobvezni filtri, page skupaj z limit pa lista po zadetkih.
03
Ključ brez analytics:read dobi iste rezervacije brez denarnih polj namesto zavrnitve, saj naj tisti, ki vpraša po nocojšnjem večeru, dobi nocojšnji večer.

Celotna pogodba

Ta stran ni referenca

API registrira krepko čez tisoč poti, ta stran pa namenoma dokumentira eno. Kaj potrebujete naprej, je odvisno od tega, kaj gradite.

01
Dokument OpenAPI
Nastane iz istih shem, po katerih preverja strežnik, zato od poti ne more odstopati. Interaktivni pregledovalnik je v produkciji namenoma ugasnjen, saj bi objava vseh poti in shem bila zemljevid, ki bi napadalca razveselil. Ko API teče lokalno, je na /docs.
02
Površina za agente
Če priklapljate pomočnika in ne pišete odjemalca, je nabor orodij precej krajši od tega API-ja in je opisan na svoji strani.
Dokumentacija za agente
03
Vprašajte človeka
Ločene podporne vrste za razvijalce še ni. Povejte nam, kaj gradite in kaj API počne namesto tega, in to bo prebral človek.
Pišite nam

REST API za vaš lokal, s ključem na kratkem povodcu.

Ključ ustvarite v nastavitvah

Preprost REST, brez presenečenj

Ena glava, ena organizacija

Pripet na eno organizacijo

Omejen z obsegi

Še ožje, če želite

Poteče

Je skrivnost

Vsak odgovor nosi isto ovojnico

Trije, ki jih boste res srečali

Štiri vedra, ne eno

Na klicoči gostitelj

Na ključ

Na lastnika ključev

Na organizacijo

Kdo pride nocoj

Ta stran ni referenca

Dokument OpenAPI

Površina za agente

Vprašajte človeka