# API: időpontok

> Időpontok létrehozása, módosítása, állapotának váltása, lekérése, listázása és törlése az API-val.

Az időpontok végpontjaival külső rendszerből (például CRM-ből vagy saját admin felületről) hozhatsz létre, módosíthatsz, kérdezhetsz le, listázhatsz és törölhetsz időpontokat, valamint válthatsz az állapotukon.

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/)). Minden időponti végpont ugyanazt az alap útvonalat használja, csak a végpont része változik:

```text
{{az_oldalad_URL-je}}/wp-admin/admin-ajax.php?action=wpamelia_api&call=/api/v1
```

| Művelet | Metódus | Útvonal |
|---|---|---|
| Időpont létrehozása | `POST` | `/appointments` |
| Időpont módosítása | `POST` | `/appointments/{{idopont_id}}` |
| Állapot módosítása | `POST` | `/appointments/status/{{idopont_id}}` |
| Egy időpont lekérése | `GET` | `/appointments/{{idopont_id}}` |
| Időpontok listázása | `GET` | `/appointments` |
| Időpont törlése | `POST` | `/appointments/delete/{{idopont_id}}` |

## Időpont létrehozása

Az időpont kezdő dátumával és a foglalások tömbjével küldött `POST` kérés hozza létre.

Kötelező tulajdonságok:

| Tulajdonság | Típus | Leírás |
|---|---|---|
| `bookingStart` | szöveg | Az időpont kezdete, `ÉÉÉÉ-HH-NN ÓÓ:PP` formában. |
| `bookings` | tömb | A foglalások. Mindegyikben szerepelnie kell egy meglévő vásárló `customerId`-jének. Új vásárló egyidejű létrehozásához a `/bookings` végpontot használd. |
| `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. |
| `recurring` | tömb | Az ismétlődő időpontok. Csak akkor kötelező, ha az időpont ismétlődő. |

Nem kötelező tulajdonságok:

| Tulajdonság | Típus | Leírás |
|---|---|---|
| `internalNotes` | szöveg | Belső megjegyzés. |
| `notifyParticipants` | logikai | Értesítést kapjanak-e a vásárlók. Alapértelmezés: `false`. |
| `timeZone` | szöveg | A vásárló időzónája, például `Europe/Budapest`. |
| `lessonSpace` | szöveg | A Lesson Space azonosítója. Ha kihagyod, újat hozhat létre a rendszer. |
| `utc` | logikai | UTC-ben küldöd-e a dátumot és időt. Alapértelmezés: `false`. |

```bash
curl --location 'https://pelda.hu/wp-admin/admin-ajax.php?action=wpamelia_api&call=/api/v1/appointments' \
--header 'Content-Type: application/json' \
--header 'Amelia: AZ_API_KULCSOD' \
--data '{
  "bookingStart": "2026-01-14 13:00",
  "bookings": [
    {
      "customFields": "{\"1\":{\"label\":\"text\",\"value\":\"\",\"type\":\"text\"}}",
      "customerId": 10,
      "duration": 1800,
      "extras": [],
      "packageCustomerId": null,
      "persons": 1,
      "status": "approved"
    }
  ],
  "internalNotes": "",
  "lessonSpace": "",
  "locationId": 2,
  "notifyParticipants": 1,
  "providerId": 1,
  "recurring": [],
  "serviceId": 1,
  "timeZone": "Europe/Budapest",
  "utc": false
}'
```

A válasz az `appointment` objektumban adja vissza a létrehozott időpontot: az azonosítóját, a foglalásokat (vásárló, állapot, ár, személyek száma, fizetések), a szolgáltatás, a munkavállaló és a helyszín azonosítóját, a kezdő és a záró időpontot, valamint az esetleges Google Naptár-, Outlook-, Zoom- vagy Lesson Space-adatokat. A `recurring` tömbben az ismétlődő időpontok szerepelnek.

## Időpont módosítása

A módosításhoz csak azokat a mezőket küldd, amelyeket változtatni akarsz. Az útvonalban az időpont azonosítója áll.

| Tulajdonság | Típus | Leírás |
|---|---|---|
| `bookingStart` | szöveg | Az új kezdés, `ÉÉÉÉ-HH-NN ÓÓ:PP` formában. |
| `bookings` | tömb | A módosítandó foglalások (az `id`-jükkel). |
| `notifyParticipants` | logikai | Értesítést kapjanak-e a vásárlók. |
| `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. |
| `internalNotes` | szöveg | Belső megjegyzés. |
| `lessonSpace` | szöveg | A Lesson Space azonosítója. |
| `removedBookings` | tömb | Az eltávolítandó foglalások. |
| `recurring` | tömb | Az ismétlődő időpontok, ha az időpont ismétlődő. |

Az állapotot ezzel a végponttal nem lehet módosítani, ahhoz a `/appointments/status/{{idopont_id}}` való.

```bash
curl --location 'https://pelda.hu/wp-admin/admin-ajax.php?action=wpamelia_api&call=/api/v1/appointments/742' \
--header 'Content-Type: application/json' \
--header 'Amelia: AZ_API_KULCSOD' \
--data '{
  "bookingStart": "2026-02-06 11:00",
  "bookings": [
    {
      "id": 979,
      "customerId": 10,
      "duration": 1800,
      "extras": [],
      "packageCustomerId": null,
      "persons": 2,
      "status": "approved"
    }
  ],
  "internalNotes": "",
  "locationId": 2,
  "notifyParticipants": 1,
  "providerId": 1,
  "removedBookings": [],
  "serviceId": 1
}'
```

A válasz az `appointment` mellett jelzi, hogy változott-e az állapot (`appointmentStatusChanged`), átütemezték-e az időpontot (`appointmentRescheduled`), mi volt az eredeti kezdés és záró időpont (`initialAppointmentDateTime`), melyik foglalásnak változott az állapota (`bookingsWithChangedStatus`), cserélődött-e a munkavállaló, és hozzáadtak-e foglalást (`bookingAdded`).

## Állapot módosítása

Az új állapotot tartalmazó `POST` kérés váltja az időpont állapotát.

| Tulajdonság | Típus | Kötelező | Leírás |
|---|---|---|---|
| `status` | szöveg | igen | Az új állapot: `approved` (jóváhagyott), `pending` (függőben), `canceled` (lemondott), `rejected` (elutasított) vagy `no-show` (nem jelent meg). |
| `packageCustomerId` | egész | igen | A csomagvásárló azonosítója, ha az időpont csomaghoz tartozik, különben `null`. |

```bash
curl --location 'https://pelda.hu/wp-admin/admin-ajax.php?action=wpamelia_api&call=/api/v1/appointments/status/742' \
--header 'Content-Type: application/json' \
--header 'Amelia: AZ_API_KULCSOD' \
--data '{
  "status": "pending",
  "packageCustomerId": null
}'
```

A válasz tartalmazza a módosított időpontot, az új (`status`) és a korábbi (`oldStatus`) állapotot, a változott állapotú foglalásokat és egy üzenetet az állapotváltásról.

## Egy időpont lekérése

Az azonosító alapján adja vissza az időpontot. A kérésnek nincs törzse.

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

A válasz az `appointment` objektumban adja az időpontot, a `recurring` tömbben az ismétlődő társait.

## Időpontok listázása dátumtartományra

Dátumtartományra és lapozásra szűrt listát ad vissza.

| Paraméter | Típus | Leírás |
|---|---|---|
| `dates` | szöveg | A kezdő és záró dátum vesszővel elválasztva, például `2026-03-10,2026-03-11`. |
| `page` | egész | Oldalszám. Az oldalankénti darabszámot a beállítások határozzák meg. |
| `skipServices` | logikai | Kihagyja a szolgáltatások részleteit. |
| `skipProviders` | logikai | Kihagyja a munkavállalók részleteit. |
| `asArray` | logikai | `false` esetén dátumokkal kulcsolt objektumot, `true` esetén tömböt ad vissza. |

```bash
curl --location 'https://pelda.hu/wp-admin/admin-ajax.php?action=wpamelia_api&call=/api/v1/appointments&dates=2026-03-10,2026-03-11&page=1&skipServices=1&skipProviders=1' \
--header 'Amelia: AZ_API_KULCSOD'
```

A válasz az `appointments` objektumban napok szerint csoportosítva adja az időpontokat. Minden időpontnál szerepel a foglalások listája a vásárlók adataival és a fizetésekkel, valamint az, hogy lemondható (`cancelable`), átütemezhető (`reschedulable`), múltbeli (`past`) vagy csoportos (`isGroup`) az időpont. A válasz végén az összesítők: az összes időpont (`total`), a jóváhagyottak (`totalApproved`) és a függőben lévők (`totalPending`) száma.

## Időpont törlése

Az azonosító alapján töröl egy időpontot. A kérésnek nincs törzse.

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

A válasz a törölt időpontot adja vissza (a foglalások állapota `rejected`), és a `bookingsWithChangedStatus` tömbben azokat a foglalásokat, amelyeknek a törléskor változott az állapotuk.

## Tudnivalók éles használat előtt

- Először tesztelj egy próbaoldalon, és az integráció építésekor naplózd a kéréseket és a válaszokat is.
- Az időpont adatait a `/appointments/{{idopont_id}}`, az állapotát a `/appointments/status/{{idopont_id}}` végponton módosítsd.
- A módosításkor elég azt küldeni, amit változtatsz.
- Ha a `timeZone` és az `utc` értékét is megadod, az egész integrációban következetesen használd.
- Ismétlődő időpontnál add meg a `recurring` tömböt.
- Az API-kulcsot tárold biztonságosan, és soha ne add át a weboldal felületének (front end).