# API: foglalások

> Időpont-, esemény- és csomagfoglalás létrehozása, a foglalás utáni műveletek futtatása, átütemezés, lemondás és törlés az API-val.

A foglalások végpontjaival külső rendszerből (egyedi alkalmazásból, CRM-ből vagy köztes szolgáltatásból) hozhatsz létre időpont-, esemény- és csomagfoglalást, ütemezhetsz át, mondhatsz le és törölhetsz foglalásokat.

Az API az Elite licenchez tartozik, használatához programozási ismeret kell, a szokásos támogatás nem terjed ki rá. A hitelesítés az **Amelia** fejlécben küldött API-kulccsal történik ([részletek](https://hub.hellowp.io/hu/plugins/ameliabooking/fejlesztoknek-api-attekintes/)). Az alap útvonal: `{{az_oldalad_URL-je}}/wp-admin/admin-ajax.php?action=wpamelia_api&call=/api/v1`.

| Művelet | Metódus | Útvonal |
|---|---|---|
| Foglalás létrehozása | `POST` | `/bookings` |
| Foglalás utáni műveletek futtatása | `POST` | `/bookings/success/{{foglalas_id}}` |
| Átütemezés | `POST` | `/bookings/reassign/{{foglalas_id}}` |
| Lemondás | `POST` | `/bookings/cancel/{{foglalas_id}}` |
| Törlés | `POST` | `/bookings/delete/{{foglalas_id}}` |

## Időpontfoglalás létrehozása

A `type` mező értéke `appointment`.

**Kötelező tulajdonságok**

| Tulajdonság | Típus | Leírás |
|---|---|---|
| `type` | szöveg | A foglalás típusa: `appointment`, `event` vagy `package`. |
| `bookings` | tömb | Egyelemű tömb: a foglalás objektuma a vásárló és az egyéni mezők adataival. |
| `bookingStart` | szöveg | Az időpont kezdete `ÉÉÉÉ-HH-NN ÓÓ:PP` formában. |
| `payment` | objektum | A fizetés adatai: `gateway`, `currency`, `data`. |
| `locationId` | egész | A helyszín azonosítója. |
| `providerId` | egész | A munkavállaló azonosítója. |
| `serviceId` | egész | A szolgáltatás azonosítója. |

**Opcionális tulajdonságok**

| Tulajdonság | Típus | Leírás |
|---|---|---|
| `locale` | szöveg | A vásárló nyelve, például `hu_HU`. |
| `timeZone` | szöveg | A vásárló időzónája, például `Europe/Budapest`. |
| `recurring` | tömb | Az ismétlődő időpontok, az első nélkül. |
| `couponCode` | szöveg | Kuponkód. |
| `runInstantPostBookingActions` | logikai | Lefussanak-e a foglalás utáni műveletek (e-mailek, Google és Outlook naptáresemény, Zoom-megbeszélés, webhookok) ugyanebben a hívásban. Alapértelmezetten `false`; ilyenkor utána a `/bookings/success/{{foglalas_id}}` végpontot kell meghívnod. |

Kérés:

```bash
curl --location 'https://pelda.hu/wp-admin/admin-ajax.php?action=wpamelia_api&call=/api/v1/bookings' \
--header 'Content-Type: application/json' \
--header 'Amelia: AZ_API_KULCSOD' \
--data-raw '{
  "type": "appointment",
  "bookings": [
    {
      "extras": [],
      "customFields": { "1": { "label": "text", "type": "text", "value": "Egyéni mező értéke" } },
      "deposit": true,
      "locale": "hu_HU",
      "utcOffset": null,
      "persons": 1,
      "customerId": null,
      "customer": {
        "id": null,
        "firstName": "Anna",
        "lastName": "Minta",
        "email": "anna.minta@example.test",
        "phone": "",
        "countryPhoneIso": "",
        "externalId": null
      },
      "duration": 1800
    }
  ],
  "payment": { "gateway": "onSite", "currency": "HUF", "data": {} },
  "bookingStart": "2026-02-12 13:00",
  "notifyParticipants": 1,
  "locationId": 2,
  "providerId": 1,
  "serviceId": 1
}'
```

A válasz `message` mezője „Successfully added booking”, a `data` objektum pedig a létrejött időpontot (`appointment`), a foglalást (`booking`), a vásárlót (`customer`), a szolgáltatást (`bookable`), a fizetést (`payment`, `paymentId`), az UTC-ben számolt idősávot (`utcTime`) és a vásárlói felület címét (`customerCabinetUrl`) tartalmazza.

## Eseményfoglalás létrehozása

A `type` mező értéke `event`.

**Kötelező tulajdonságok:** `type`, `bookings`, `payment` (mint fent), valamint az `eventId` (egész), az esemény azonosítója.

**Opcionális tulajdonságok:** `locale`, `timeZone`, `couponCode` és `runInstantPostBookingActions`, ugyanúgy, mint az időpontfoglalásnál.

Ha az esemény nem használ jegyeket, a `persons` mezőben add meg a létszámot. Ha jegyeket használ, a foglalás objektumában a `ticketsData` tömböt töltsd ki: elemei a jegy azonosítóját (`eventTicketId`), a darabszámot (`persons`) és az árat (`price`) tartalmazzák.

```bash
curl --location 'https://pelda.hu/wp-admin/admin-ajax.php?action=wpamelia_api&call=/api/v1/bookings' \
--header 'Content-Type: application/json' \
--header 'Amelia: AZ_API_KULCSOD' \
--data-raw '{
  "type": "event",
  "bookings": [
    {
      "customer": {
        "email": "bela.pelda@example.test",
        "externalId": null,
        "firstName": "Béla",
        "lastName": "Példa",
        "phone": "",
        "countryPhoneIso": "hu"
      },
      "customFields": { "1": { "label": "text", "value": "", "type": "text" } },
      "customerId": 0,
      "persons": 1,
      "ticketsData": [
        { "eventTicketId": 25, "persons": 0, "price": 20 },
        { "eventTicketId": 24, "persons": 2, "price": 10 }
      ],
      "utcOffset": null,
      "deposit": false
    }
  ],
  "payment": { "amount": "40.00", "gateway": "onSite", "currency": "HUF" },
  "recaptcha": false,
  "locale": "hu_HU",
  "timeZone": "Europe/Budapest",
  "couponCode": "",
  "eventId": 54
}'
```

A válasz az esemény adatait (`event`, benne a foglalásokkal, időszakokkal és jegyekkel), a foglalást, a vásárlót és a fizetést adja vissza.

## Csomagfoglalás létrehozása

A `type` mező értéke `package`.

**Kötelező tulajdonságok:** `type`, `bookings`, `payment` (mint fent), a `packageId` (egész, a csomag azonosítója) és a `package` (tömb: a csomagból lefoglalt időpontok).

**Opcionális tulajdonságok:**

| Tulajdonság | Típus | Leírás |
|---|---|---|
| `locale`, `timeZone`, `couponCode`, `runInstantPostBookingActions` | | Mint az időpontfoglalásnál. |
| `packageRules` | tömb | Az egyes szolgáltatásokhoz választott munkavállaló és helyszín. Ezeket használja a rendszer, amikor a vásárló a vásárlói felületen tovább foglal a csomagjából, és a munkavállaló kiválasztása ki van kapcsolva. |

A `package` tömb elemei egy-egy időpontot írnak le: `bookingStart`, `serviceId`, `providerId`, `locationId`, `utcOffset`, `notifyParticipants`.

```bash
curl --location 'https://pelda.hu/wp-admin/admin-ajax.php?action=wpamelia_api&call=/api/v1/bookings' \
--header 'Content-Type: application/json' \
--header 'Amelia: AZ_API_KULCSOD' \
--data-raw '{
  "type": "package",
  "bookings": [
    {
      "customFields": { "2": { "label": "Text", "type": "text", "value": "" } },
      "deposit": true,
      "locale": "hu_HU",
      "utcOffset": null,
      "customerId": null,
      "customer": {
        "firstName": "Nóra",
        "lastName": "Teszt",
        "email": "nora.teszt@example.test",
        "phone": "",
        "countryPhoneIso": "",
        "externalId": null,
        "translations": null
      },
      "persons": 1
    }
  ],
  "payment": { "gateway": "onSite", "currency": "HUF", "data": {} },
  "locale": "hu_HU",
  "timeZone": "Europe/Budapest",
  "package": [
    { "bookingStart": "2026-03-05 07:30", "serviceId": 1, "providerId": 4, "locationId": 8, "utcOffset": 120, "notifyParticipants": 1 },
    { "bookingStart": "2026-03-04 10:00", "serviceId": 11, "providerId": 4, "locationId": 8, "utcOffset": 120, "notifyParticipants": 1 }
  ],
  "packageId": 1,
  "packageRules": [
    { "serviceId": 1, "providerId": 2, "locationId": 1 },
    { "serviceId": 11, "providerId": null, "locationId": null }
  ],
  "utcOffset": 120,
  "couponCode": null
}'
```

A válasz `package` tömbje a csomagból lefoglalt időpontokat tartalmazza, mellette a `packageCustomerId` a csomagvásárlás azonosítója.

## Foglalás utáni műveletek futtatása

A `/bookings/success/{{foglalas_id}}` végpont lefuttatja azokat a műveleteket, amelyeket a foglalás létrehozásakor kihagytál: értesítések küldése, Google és Outlook naptáresemény létrehozása, Zoom-megbeszélés létrehozása, webhookok hívása.

| Tulajdonság | Típus | Leírás |
|---|---|---|
| `type` | szöveg | `appointment`, `event` vagy `package`. |
| `appointmentStatusChanged` | logikai | Megváltozott-e az időpont állapota a foglalás hozzáadása után. |
| `customerId` | egész | A vásárló azonosítója. |
| `paymentId` | egész | A fizetés azonosítója. |
| `packageCustomerId` | egész | A csomagvásárlás azonosítója, csomagfoglalásnál kötelező. |
| `packageId` | egész | A csomag azonosítója, csomagfoglalásnál kötelező. |
| `recurring` | tömb | Az ismétlődő időpontok, ismétlődő foglalásnál kötelező. |

```bash
curl --location 'https://pelda.hu/wp-admin/admin-ajax.php?action=wpamelia_api&call=/api/v1/bookings/success/900' \
--header 'Content-Type: application/json' \
--header 'Amelia: AZ_API_KULCSOD' \
--data '{
  "type": "appointment",
  "appointmentStatusChanged": false,
  "recurring": [],
  "packageId": null,
  "customerId": 64,
  "paymentId": 916,
  "packageCustomerId": null
}'
```

## Foglalás átütemezése

A `/bookings/reassign/{{foglalas_id}}` végpont egy időpont dátumát és időpontját módosítja.

| Tulajdonság | Típus | Leírás |
|---|---|---|
| `bookingStart` | szöveg | Kötelező. Az új kezdet `ÉÉÉÉ-HH-NN ÓÓ:PP` formában. |
| `utcOffset` | egész | Opcionális. Az UTC-eltolás percben. |
| `timeZone` | szöveg | Opcionális. Az időzóna, például `Europe/Budapest`. |

```bash
curl --location 'https://pelda.hu/wp-admin/admin-ajax.php?action=wpamelia_api&call=/api/v1/bookings/reassign/975' \
--header 'Content-Type: application/json' \
--header 'Amelia: AZ_API_KULCSOD' \
--data '{ "bookingStart": "2026-01-09 09:30", "utcOffset": null, "timeZone": "Europe/Budapest" }'
```

A válasz tartalmazza a módosított foglalást (`booking`), a régi időpontot (`oldAppointment`), az új vagy már létező időpontot (`newAppointment`, `existingAppointment`) és az eredeti időpont adatait (`initialAppointmentDateTime`).

## Foglalás lemondása

A `/bookings/cancel/{{foglalas_id}}` végpont lemondja a foglalást. A kérés törzsében a `type` mezőt add meg.

```bash
curl --location 'https://pelda.hu/wp-admin/admin-ajax.php?action=wpamelia_api&call=/api/v1/bookings/cancel/965' \
--header 'Content-Type: application/json' \
--header 'Amelia: AZ_API_KULCSOD' \
--data '{ "type": "appointment" }'
```

A válaszban a foglalás és az időpont állapota `canceled`.

## Foglalás törlése

A `/bookings/delete/{{foglalas_id}}` végpont törli a foglalást.

```bash
curl --location --request POST 'https://pelda.hu/wp-admin/admin-ajax.php?action=wpamelia_api&call=/api/v1/bookings/delete/974' \
--header 'Amelia: AZ_API_KULCSOD'
```

A válasz jelzi, hogy a foglalás (`bookingDeleted`) és az időpont (`appointmentDeleted`) törlődött-e.

## Amire figyelj

- Ha a `runInstantPostBookingActions` értéke `false`, a foglalás értesítések, naptáresemények, Zoom-megbeszélés és webhookok nélkül jön létre. Ezeket a `/bookings/success/{{foglalas_id}}` hívással pótolhatod.
- Eseményfoglalásnál jegyek nélküli eseményen a `persons`, jegyes eseményen a `ticketsData` mezőt használd.
- Mindig a saját Amelia-telepítésed valódi azonosítóit add meg (`serviceId`, `providerId`, `locationId`, `eventId`, `packageId`).
- Ha az integrációd több időzónában is dolgozik, a `timeZone` és az `utcOffset` mezőt következetesen használd.