API-ul de integrare

API-ul de integrare Gridbeds îi permite unei aplicații să lucreze cu rezervările și oaspeții organizației care a instalat-o. Fiecare pagină de la Endpoint-uri este generată din documentul OpenAPI al API-ului, același fișier după care API-ul este construit și verificat, iar playground-ul trimite cereri reale. Paginile de referință sunt în engleză, ca documentul din care sunt generate. URL-ul de bază din producție este https://api.gridbeds.com/api, iar fiecare cale începe cu /v1/integration/. Meniul de servere al playground-ului oferă și sandbox-ul.

Autentificare

Trimite un token de integrare la fiecare cerere:

Authorization: Bearer <token>

Un token aparține unei singure instalări a unei aplicații. Cineva de la proprietate care are dreptul de a gestiona integrările conectează aplicația în Gridbeds, din Setări → Integrări (Marketplace de aplicații), și emite acolo token-ul, acordând permisiunile (scope-urile) cerute de aplicație sau doar o parte din ele. Token-ul este afișat o singură dată; emiterea unuia nou îl revocă pe cel anterior. Fiecare operație numește permisiunea de care are nevoie:

Permisiune	Operații
niciuna	Get the calling installation
`reservations.read`	List reservations, Get a reservation
`reservations.write`	Create a reservation
`guests.read`	List guests
`guests.write`	Create a guest

Începe cu Get the calling installation: răspunde cu instalarea, organizația ei, starea ei, aplicația și permisiunile acordate token-ului, și nu cere nicio permisiune.

O singură organizație per token

Fiecare cerere citește și scrie datele organizației care a instalat aplicația, și nimic altceva. O înregistrare a altei organizații răspunde cu 404, exact ca una care nu există.

Erori

O cerere refuzată răspunde cu un corp JSON:

Câmp
`message`	Ce nu a mers, într-o propoziție pentru un om. Nu te baza pe ea: formularea se poate schimba și urmează limba cererii.
`code`	Un identificator stabil al refuzului, prezent când există, de exemplu `idempotency_key_reused`. Pe acesta te bazezi.
`errors`	La o validare eșuată: mesajele pentru fiecare câmp care nu a trecut, după numele câmpului.

Cod	Când
401	Token-ul lipsește, este necunoscut sau revocat, ori este token-ul de autentificare al unui utilizator.
403	Token-ului nu i s-a acordat permisiunea operației, sau instalarea lui este dezactivată ori în eroare.
404	Nu există o astfel de înregistrare în organizația token-ului.
409	Prima cerere cu acest `Idempotency-Key` este încă în lucru (`idempotency_in_flight`). Reîncearcă în scurt timp.
422	Cererea nu a trecut validarea sau cere ceva ce organizația nu poate face (`code` spune ce).
429	Instalarea a depășit limita de cereri.

Limita de cereri

O instalare poate face 120 de cereri pe minut. Peste atât, API-ul răspunde cu 429 și antetul Retry-After, secundele de așteptat, alături de X-RateLimit-Limit, X-RateLimit-Remaining și X-RateLimit-Reset (când se încheie fereastra, ca timestamp Unix). Corpul conține error, message și retry_after.

Reîncercarea sigură a unei creări

Create a reservation și Create a guest acceptă antetul Idempotency-Key. Timp de cel puțin 24 de ore, aceeași cheie cu același corp răspunde cu primul răspuns, în loc să creeze o a doua înregistrare. Aceeași cheie cu alt corp este refuzată cu 422 (idempotency_key_reused).

Versiuni

Versiunea API-ului este în cale: /v1/. Referința afișează versiunea documentului OpenAPI; o schimbare care ar strica un client deja construit pe el, cum ar fi o operație sau un câmp de răspuns eliminat ori un câmp de cerere devenit obligatoriu, este publicată doar ca o nouă versiune majoră a documentului.

Identity

Cui aparține token-ul: instalarea, organizația ei și permisiunile ei.

Reservations

Listează, citește și creează rezervările organizației.

Guests

Listează și creează profilurile de oaspeți pentru care se face o rezervare.

​Autentificare

​O singură organizație per token

​Erori

​Limita de cereri

​Reîncercarea sigură a unei creări

​Versiuni