Dla programistów · dla Programiści

API — szybki start

Q: Czy jest API dla operatorów platformy?

Tak: API platformy (/api/platform/v1, klucze zaczynające się od gpp_) tworzy najemców (tenantów) i domeny. Zobacz sekcję platformy w dokumentacji API.

Utwórz klucz API, wykonaj pierwsze wywołanie, twórz rezerwacje z PMS, odczytuj status zameldowania i płatności, reaguj na zdarzenia przez webhooki.

Wszystko, co robi panel, jest dostępne jako JSON REST API. Typowe zastosowania: tworzenie rezerwacji z Twojego PMS lub silnika rezerwacyjnego, umieszczanie linku do portalu gościa we własnych wiadomościach, odczyt danych z zameldowania online lub pobieranie deklaracji dla MTA do księgowości.

Pełna dokumentacja znajduje się pod adresem /api/docs, w formie czytelnej maszynowo jako OpenAPI 3.1.

1. Utwórz klucz API #

Settings → API keys (Ustawienia → Klucze API; tylko właściciele): nadaj kluczowi nazwę i rolę. Klucz może robić dokładnie to, co dana rola — dla integracji tylko do odczytu używaj roli Viewer. Pełny klucz (gpk_…) jest pokazywany tylko raz; zapisz go w swoim magazynie sekretów. Możesz go tam w każdej chwili unieważnić.

2. Wykonaj pierwsze wywołanie #

Wyślij klucz jako token typu bearer. Bazowy URL to adres Twojego portalu.

curl https://stay.example.com/api/v1/me \
  -H "Authorization: Bearer gpk_xxxxxxxxxxxx"

Odpowiedź zawiera najemcę platformy (tenant), rolę klucza i jego uprawnienia.

3. Utwórz rezerwację #

curl -X POST https://stay.example.com/api/v1/bookings \
  -H "Authorization: Bearer gpk_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "propertyId": "p_xxxxxxxxxx",
    "checkIn": "2026-11-18", "checkOut": "2026-11-23",
    "adults": 2, "children": 0,
    "guest": { "firstName": "Sofia", "lastName": "Rossi", "email": "sofia@example.com", "phone": "+39 333 1234567" },
    "source": "mypms", "externalId": "RES-48213",
    "sendPortalLink": true
  }'

Z source + externalId wywołanie działa jako upsert: ponowne wysłanie tej samej rezerwacji aktualizuje ją zamiast tworzyć duplikat.
Nakładające się daty zwracają 409; dodaj "allowOverlap": true, jeśli jest to zamierzone.
Odpowiedź zawiera rezerwację z portalUrl — osobistym linkiem gościa.

ID obiektów pobierzesz z GET /api/v1/properties.

4. Odczytaj status i dane zameldowania #

GET /api/v1/bookings?from=2026-11-01&to=2026-11-30 — lista ze statusami płatności (eco.status, deposit.status), stayState i unlocked.
GET /api/v1/bookings/{id} — pełna rezerwacja, w tym dane zameldowania online i dziennik aktywności.
GET /api/v1/bookings?format=csv — eksport do arkusza kalkulacyjnego.

Więcej endpointów #

Endpoint	Co robi
`GET /api/v1/reports/stats?propertyId=&from=&to=`	Statystyki dla obiektu i okresu (`format=csv` dla CSV)
`GET /api/v1/reports/owner-statement?propertyId=&from=&to=`	Zestawienie opłaty ekologicznej dla właściciela; `POST …/owner-statement/send` wysyła je e-mailem
`GET`/`PUT /api/v1/properties/{id}/translations`	Tłumaczenia przewodnika dla każdego języka; `POST …/translations/auto` uzupełnia brakujące
`PATCH /api/v1/settings`	Zawiera `stayTimes` (wcześniej/później), `journey` (wiadomości do gości), `pushArrivalHours` i `checkin.formType` (`short` lub `long`)
`POST /api/v1/settings/journey/test`	Wysyła Ci jeden krok harmonogramu wiadomości jako test
`GET /api/v1/push`, `POST /api/v1/push/subscribe`	Powiadomienia na telefon zalogowanego użytkownika

API gościa akceptuje nagłówek X-GP-Lang (en, de, it, fr, es, nl, pl, mt) i zwraca przewodnik w tym języku.

5. Reaguj na zdarzenia #

Zamiast odpytywania zarejestruj webhook (Settings → Webhooks) i odbieraj podpisane zdarzenia, takie jak checkin.completed, payment.completed czy feedback.received — zobacz Webhooki.

Konwencje #

Temat	Zasada
Format	JSON na wejściu i wyjściu, UTF-8; daty `YYYY-MM-DD`, znaczniki czasu ISO 8601 UTC
Błędy	Status HTTP + `{ "error": "message" }` — 400 nieprawidłowe dane, 401 zły klucz, 403 brak uprawnień, 404 nie znaleziono, 409 konflikt, 429 zbyt wiele żądań
Kwoty	Liczby dziesiętne w walucie konta (domyślnie EUR)
Sekrety	Maskowane w odpowiedziach; wyślij pustą wartość, aby zachować zapisany sekret

Najczęściej zadawane pytania #

Czy jest środowisko testowe (sandbox)? #

Do poznania systemu użyj konta demo, a do płatności trybu sandbox Revolut. W wersji demo nie można tworzyć kluczy API — do prac programistycznych załóż bezpłatne konto.

Czy jest API dla operatorów platformy? #

Tak: API platformy (/api/platform/v1, klucze zaczynające się od gpp_) tworzy najemców (tenantów) i domeny. Zobacz sekcję platformy w dokumentacji API.