# API quick start

Kull ma tagħmel id-dashboard huwa disponibbli bħala JSON REST API. Użi tipiċi: toħloq bookings mill-PMS jew mill-booking engine tiegħek, iddaħħal il-link tal-portal tal-mistednin fil-messaġġi tiegħek, taqra d-data tal-check-in online, jew iddaħħal ir-return tal-MTA fil-kontabilità.

Ir-referenza sħiħa tinsab fuq [/api/docs](/api/docs), f'format li jinqara mill-magni bħala [OpenAPI 3.1](/api/v1/openapi.json).

## 1. Oħloq API key

**Settings → API keys** (owners biss): agħti isem liċ-ċavetta u **rwol**. Iċ-ċavetta tista' tagħmel eżatt dak li jista' jagħmel dak ir-rwol — uża *Viewer* għal integrazzjonijiet ta' qari biss. Iċ-ċavetta sħiħa (`gpk_…`) tintwera **darba biss**; aħżinha fis-secret store tiegħek. Tista' tirrevokaha minn hemm meta trid.

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

## 2. Agħmel l-ewwel sejħa

Ibgħat iċ-ċavetta bħala bearer token. Il-base URL huwa l-indirizz tal-portal tiegħek.

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

It-tweġiba tgħidlek it-tenant, ir-rwol taċ-ċavetta u l-permessi tagħha.

## 3. Oħloq booking

```
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
  }'
```

- B'`source` + `externalId` is-sejħa hija **upsert**: jekk tibgħat l-istess riżervazzjoni mill-ġdid, din tiġi aġġornata minflok ma tinħoloq duplikata.
- Dati li jikkoinċidu jagħtu **409**; żid `"allowOverlap": true` jekk dan ikun intenzjonat.
- It-tweġiba fiha l-booking b'`portalUrl` — il-link personali tal-mistieden.

L-IDs tal-proprjetajiet jiġu minn `GET /api/v1/properties`.

## 4. Aqra l-istatus u d-data tal-check-in

- `GET /api/v1/bookings?from=2026-11-01&to=2026-11-30` — lista bl-istati tal-ħlas (`eco.status`, `deposit.status`), `stayState` u `unlocked`.
- `GET /api/v1/bookings/{id}` — il-booking sħiħa inkluża d-data tal-check-in online u l-activity log.
- `GET /api/v1/bookings?format=csv` — esportazzjoni bħala spreadsheet.

## Aktar endpoints

| Endpoint | X'jagħmel |
|---|---|
| `GET /api/v1/reports/stats?propertyId=&from=&to=` | [Statistika](/docs/statistics) għal kull proprjetà u perjodu (`format=csv` għal CSV) |
| `GET /api/v1/reports/owner-statement?propertyId=&from=&to=` | Statement tal-eco contribution għas-sid; `POST …/owner-statement/send` jibagħtu bl-email |
| `GET`/`PUT /api/v1/properties/{id}/translations` | It-[traduzzjonijiet](/docs/guest-languages) tal-gwida għal kull lingwa; `POST …/translations/auto` jimla dawk neqsin |
| `PATCH /api/v1/settings` | Jinkludi `stayTimes` ([early/late](/docs/early-check-in-late-check-out)), `journey` ([messaġġi lill-mistednin](/docs/guest-message-timeline)), `pushArrivalHours` u `checkin.formType` (`short` jew `long`) |
| `POST /api/v1/settings/journey/test` | Jibgħatlek pass wieħed mit-timeline tal-messaġġi bħala test |
| `GET /api/v1/push`, `POST /api/v1/push/subscribe` | [Notifiki fuq it-telefon](/docs/host-app-notifications) tal-utent li jkun idħol |

L-API tal-mistednin taċċetta l-header `X-GP-Lang` (`en`, `de`, `it`, `fr`, `es`, `nl`, `pl`, `mt`) u tagħti l-gwida b'dik il-lingwa.

## 5. Irreaġixxi għall-events

Minflok polling, irreġistra webhook (**Settings → Webhooks**) u irċievi events iffirmati bħal `checkin.completed`, `payment.completed` jew `feedback.received` — ara [Webhooks](/docs/webhooks).

## Konvenzjonijiet

| Suġġett | Regola |
|---|---|
| Format | JSON fid-dħul u fil-ħruġ, UTF-8; dati `YYYY-MM-DD`, timestamps ISO 8601 UTC |
| Żbalji | Status HTTP + `{ "error": "message" }` — 400 input invalidu, 401 ċavetta ħażina, 403 mhux permess, 404 ma nstabx, 409 kunflitt, 429 wisq requests |
| Flus | Numri deċimali fil-munita tal-kont (EUR b'mod default) |
| Sigrieti | Moħbija fit-tweġibiet; ibgħat valur vojt biex iżżomm sigriet maħżun |

## Mistoqsijiet frekwenti

### Hemm sandbox?

Uża l-[kont demo](/demo) biex tesplora, u s-sandbox mode ta' Revolut għall-pagamenti. L-API keys ma jistgħux jinħolqu fid-demo — oħloq kont b'xejn għall-iżvilupp.

### Hemm API għall-operaturi tal-pjattaforma?

Iva: il-platform API (`/api/platform/v1`, ċwievet li jibdew b'`gpp_`) toħloq tenants u dominji. Ara s-sezzjoni platform tar-[referenza tal-API](/api/docs#platform).