# API — szybki start

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](/api/docs), w formie czytelnej maszynowo jako [OpenAPI 3.1](/api/v1/openapi.json).

## 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ć.

![Settings → API keys (Ustawienia → Klucze API)](/site/img/docs/d-settings-apikeys.webp "Settings → API keys (Ustawienia → Klucze API)")

## 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](/docs/statistics) 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](/docs/guest-languages) przewodnika dla każdego języka; `POST …/translations/auto` uzupełnia brakujące |
| `PATCH /api/v1/settings` | Zawiera `stayTimes` ([wcześniej/później](/docs/early-check-in-late-check-out)), `journey` ([wiadomości do gości](/docs/guest-message-timeline)), `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](/docs/host-app-notifications) 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](/docs/webhooks).

## 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](/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](/api/docs#platform).