Żviluppaturi · għal Żviluppaturi

API quick start

Q: 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.

Oħloq API key, agħmel l-ewwel sejħa, oħloq bookings mill-PMS tiegħek, aqra l-istatus tal-check-in u tal-ħlas u rreaġixxi għall-events b'webhooks.

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, f'format li jinqara mill-magni bħala OpenAPI 3.1.

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.

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 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 tal-gwida għal kull lingwa; `POST …/translations/auto` jimla dawk neqsin
`PATCH /api/v1/settings`	Jinkludi `stayTimes` (early/late), `journey` (messaġġi lill-mistednin), `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 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.

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