---
title: "API, CLI és MCP referencia | NaptárAI"
description: "REST-végpontok curl példákkal, CLI-parancsok, MCP-eszközök, hitelesítés és korlátok."
canonical: https://naptarai.hu/api
source: https://naptarai.hu/api.md
---
API-dokumentáció
# NaptárAI API, MCP és CLI referencia
Ez az oldal a NaptárAI programozható felületeinek teljes referenciája: minden nyilvános REST-végpont, a parancssori eszköz összes parancsa, és az MCP-szerver eszközei. Ha még nem döntötted el, melyik felület kell, [a fejlesztői áttekintés](https://naptarai.hu/fejlesztok) onnan indul.
Végpontonként külön oldal, paraméterekkel és futtatható példákkal, a teljes dokumentációban van: [naptarai.hu/dokumentacio/api/vegpontok](https://naptarai.hu/dokumentacio/api/vegpontok).
## Hogyan működik
A NaptárAI három felületen ugyanazt a munkaterületet kezeli, mint a webes felület. A **REST API** a saját kódodból, a **parancssori eszköz** a terminálból és a szkriptjeidből, az **MCP-szerver** pedig egy AI-ügynökből. Mindhárom ugyanazokat a jogosultságokat és korlátokat használja, ezért amit az egyiken megtehetsz, megteheted a másikon is.
A REST API alapcíme `https://naptarai.hu/api/public/v1`. A verzió az útvonalban van, és minden válasz JSON.
### Csatlakozás három lépésben
1. Regisztrálj a [naptarai.hu/regisztracio](https://naptarai.hu/regisztracio) címen. Nincs értékesítési hívás, nincs várólista.
2. Kösd be legalább egy közösségi fiókodat a felületen. Ezt a lépést API-ból nem lehet elvégezni, mert a platform beleegyezést kér egy embertől.
3. Hozz létre magadnak egy kulcsot: Beállítások → Fejlesztők. A kulcs egyszer látszik, a létrehozás pillanatában.
Az első hívásod ellenőrizheti, hogy minden a helyén van. Ez a végpont kulcs nélkül is válaszol, és megmondja, hol találsz meg mindent:
```
curl https://naptarai.hu/api/public/v1/status
```
Az első hitelesített hívás pedig a platformjaidat listázza:
```
curl https://naptarai.hu/api/public/v1/integrations \
-H "Authorization: psty_a_kulcsod"
```
### Hitelesítés
Kétféle hitelesítő adat működik. Az **API-kulcs** a teljes `Authorization` fejléc értéke (`psty_…`), és a saját kódodhoz való. Az **OAuth 2.1** hozzáférési token (`Bearer pos_…`) akkor kell, ha egy másik alkalmazás a te felhasználóid nevében fér hozzá a NaptárAI-hoz; a folyamat PKCE-vel megy, a metaadatok pedig géppel olvashatók.
Egy kulcs jogosultsága a tulajdonosa aktuális szerepkörével mozog: ha valaki lefokozódik vagy kikerül a munkaterületről, a kulcsa azonnal annyit tud, amennyit ő. Ha egy kulcs több munkaterülethez tartozik, a `showorg` fejléc választ közülük.
## Végpontok
Minden útvonal a `https://naptarai.hu/api/public/v1` alatt van. A „Jogosultság" oszlop azt mutatja, milyen scope kell a kulcsra; ha hiányzik, a válasz 403, és megnevezi a hiányzót.
| Metódus | Útvonal | Mit csinál | Jogosultság |
| --- | --- | --- | --- |
| GET | /status | Állapot és felderítés. Az egyetlen útvonal, amely kulcs nélkül is válaszol. | \- |
| GET | /is-connected | Ellenőrzi, hogy a kulcs érvényes munkaterületre mutat-e. | \- |
| GET | /properties | A munkaterület szálláshelyei azonosítóval, státusszal, pénznemmel. | pms:read |
| GET | /properties/:id | Egy szálláshely: cím, egységek, árcsomagok. | pms:read |
| GET | /properties/:id/units | Egy szálláshely kiadható egységei és árcsomagjai. | pms:read |
| GET | /units | Kiadható egységek, opcionálisan egy szálláshelyre szűrve. | pms:read |
| GET | /calendar | Naptár from/to szerint: eladható, foglalt és zárolt éjszakák egységenként. | pms:read |
| GET | /reservations | Foglalások időszak, státusz, egység vagy vendégnév szerint. | pms:read |
| GET | /reservations/:id | Egy foglalás: dátumok, vendég, összegek, fizetés. | pms:read |
| POST | /reservations | Kézi vagy direkt foglalás rögzítése. OTA-foglalást soha nem kell begépelni. | pms:write |
| POST | /reservations/:id/cancel | Foglalás lemondása, az éjszakák visszakerülnek a piacra. | pms:write |
| PUT | /reservations/:id/dates | Foglalás dátumainak (és opcionálisan egységének) mozgatása. | pms:write |
| GET | /rates | Éjszakai árak és tartózkodási korlátok árcsomagonként. | pms:read |
| PUT | /rates | Ár és korlátok beállítása időszakra, lapos törzzsel. | pms:write |
| POST | /blocks | Éjszakák kivétele az értékesítésből (saját használat vagy karbantartás). | pms:write |
| DELETE | /blocks | Zárolás feloldása unitId, from és to szerint. | pms:write |
| GET | /connections | OTA-kapcsolatok állapota, utolsó szinkron és utolsó hiba. | pms:read |
| GET | /reports/summary | Bevétel, kihasználtság, ADR egy időszakra, csatornánként. | pms:read |
| GET | /messages | Vendégüzenet-szálak, opcionálisan egy foglalásra szűrve. | pms:read |
| GET | /messages/:id | Egy beszélgetés üzenetei időrendben. | pms:read |
A pontos kérés- és válaszsémákat, mezőnként, az [OpenAPI 3 leírás](https://naptarai.hu/openapi.json) tartalmazza. Abból ügyfélkódot is tudsz generáltatni.
### Példa: REST-hívás
A dátum mindig UTC, ISO 8601 formátumban. A `type` lehet `draft`, `schedule` vagy `now`.
```
curl -X POST https://naptarai.hu/api/public/v1/posts \
-H "Authorization: psty_a_kulcsod" \
-H "Content-Type: application/json" \
-d '{
"type": "schedule",
"date": "2026-09-15T09:00:00.000Z",
"shortLink": false,
"posts": [{
"integration": { "id": "a_platform_azonositoja" },
"value": [{ "content": "Sziasztok!
" }]
}]
}'
```
A válasz platformonként egy sort ad vissza, benne a `postId` értékkel, amit a törléshez és az állapotváltáshoz használsz.
## Hibák
Minden hiba JSON. A NaptárAI által kiváltott hibákban a `msg` mező hordozza az emberi mondatot; a kérés formai ellenőrzésén elbukó hívások a keretrendszer alakját kapják (`statusCode`, `message`, `error`). A jogosultsági 403 megnevezi a hiányzó scope-ot és a kulcstulajdonos szerepkörét, mert a leggyakoribb ok nem a rossz kulcs, hanem a lefokozott felhasználó.
A státuszkód mondja meg, érdemes-e újrapróbálni: a 400, 401, 403 és 404 addig nem múlik el, amíg nem változtatsz valamin; a 429 és az 5xx igen. Az `ApiError` séma mindezt géppel olvashatóan is leírja az OpenAPI dokumentumban.
## Hívási korlátok
Minden válasz viszi a `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` (másodpercben, nem időbélyeg) és `RateLimit-Policy` fejléceket. A 429 mellé `Retry-After` is érkezik. Minden útvonalnak külön kerete van, kulcsonként. Ne a 429-re várj: a maradék értékből előre tudsz lassítani.
## Verziózás és kivezetés
A verzió az útvonalban van: minden nyilvános hívás a `/public/v1` alatt él. Törő változás új verzióként jelenne meg (`/public/v2`), a v1 pedig tartja a szerződését. Bővítés , új opcionális mező, új útvonal, új felsorolt érték, a v1-en belül történik, ezért a kódod hagyja figyelmen kívül azokat a mezőket, amiket nem ismer.
Ha egy útvonalat kivezetnénk, a válasza `Deprecation: true` fejlécet kap, mellé `Sunset` fejlécben a dátumot, ami után már nem működik. Ez a dátum soha nem lehet közelebb 180 napnál. Minden válasz visz egy `Link` fejlécet is `rel="sunset"` kapcsolattal, ami erre a szakaszra mutat. Jelenleg semmi nincs kivezetés alatt.
## Parancssori eszköz
A parancs neve `szh`, ugyanezt az API-t használja terminálból. A kézikönyv a [dokumentációban](https://naptarai.hu/dokumentacio/cli) van. Az npm-csomag még nincs kiadva. Belépés:
```
szh auth:login
szh integrations:list
```
A bejelentkezés böngészőt nyit, a kulcsot pedig a gépeden tárolja, így a szkriptjeidbe nem kell beleírnod. Minden parancs tud `--json` kimenetet adni, ami gépi feldolgozásra való.
Hitelesítés
| stay login | Böngészős belépés vagy API-kulcs. |
| --- | --- |
| stay logout | A tárolt kulcs törlése. |
Naptár és árak
| stay calendar --next 14d | Naptár a következő N napra. |
| --- | --- |
| stay properties | Szálláshelyek listája. |
| stay units | Kiadható egységek. |
| stay rates set : <árFt> | Éjszakai ár beállítása időszakra. |
| stay block \[:\] | Éjszakák zárolása. |
| stay unblock \[:\] | Zárolás feloldása. |
Foglalások
| stay bookings | Foglalások listája. |
| --- | --- |
| stay booking | Egy foglalás részletei. |
| stay revenue --month 2026-08 | Havi bevétel. |
Csatornák és üzenetek
| stay channels status | OTA-kapcsolatok állapota. |
| --- | --- |
| stay messages list | Vendégüzenet-szálak. |
## MCP-szerver
Az MCP-szerver címe `https://naptarai.hu/api/mcp-oauth`, streamable HTTP átvitellel, OAuth 2.1 hitelesítéssel. Az ügynököd ezeket az eszközöket látja:
| Eszköz | Mit csinál | Ír? |
| --- | --- | --- |
| get\_workspace\_context | A pontos idő UTC-ben, a felhasználó időzónája és a munkaterület neve. | nem |
| properties\_list | A munkaterület szálláshelyei azonosítóval, státusszal, pénznemmel. | nem |
| properties\_get | Egy szálláshely részletei: cím, be- és kijelentkezés, egységek, árcsomagok. | nem |
| units\_list | Egy szálláshely kiadható egységei és azok árcsomagjai. | nem |
| calendar\_get | A naptár: éjszakánként és egységenként eladható szoba, foglalások, zárolások. | nem |
| availability\_get | A szabad éjszakák és az összefüggő szabad időszakok, hossz és nap szerint szűrve. | nem |
| rates\_get | Éjszakai árak és tartózkodási korlátozások árcsomagonként. | nem |
| reservations\_list | Foglalások szálláshely, egység, időszak, státusz, forrás vagy név szerint. | nem |
| reservations\_get | Egy foglalás részletei: dátumok, vendég, létszám, összegek, fizetési állapot. | nem |
| guests\_get | Egy vendég azonosító alapján, vagy keresés név és e-mail szerint. | nem |
| channels\_status | Az OTA-kapcsolatok állapota, utolsó szinkron és utolsó hiba. | nem |
| analytics\_summary | Mai érkezések és távozások, havi kihasználtság, bevétel, direkt/OTA arány. | nem |
| website\_get | A saját foglalási weboldal állapota és tartalma. Egy szálláshelyre piszkozatot hoz létre. | igen |
| calendar\_block | Éjszakák kivétele az értékesítésből (saját használat vagy karbantartás). | igen |
| calendar\_unblock | Zárolás feloldása. Saját használatú zárolást csak külön megerősítéssel. | igen |
| rates\_set | Egy éjszakai ár beállítása időszakra, akár csak adott hétköznapokra. | igen |
| rates\_adjust | Meglévő árak mozgatása százalékkal vagy fix összeggel. Legfeljebb ±50%. | igen |
| restrictions\_set | Minimum és maximum éjszaka, érkezés- és távozászárás, értékesítés leállítása. | igen |
| reservation\_create | Direkt vagy kézi foglalás rögzítése. OTA-foglalást soha nem kell begépelni. | igen |
| reservation\_cancel | Foglalás lemondása. Megerősített foglaláshoz külön megerősítés kell. | igen |
| message\_draft | Vendégüzenet előkészítése. Nem küld el és nem tárol semmit. | igen |
| properties\_set\_cancellation\_policy | Lemondási feltétel (FLEXIBLE, MODERATE, FIRM, STRICT, NON\_REFUNDABLE). Airbnb-re kimegy. | igen |
| properties\_set\_booking\_settings | Azonnali foglalás és érkezési időablak. Airbnb-re kimegy; Booking.com manual. | igen |
| units\_set\_listing\_settings | Hétvégi ár, extra vendég, takarítás, kedvezmény, előfoglalás, turnover, be- és kijelentkezési napok. | igen |
A kapcsolat hitelesítést kér: hitelesítő adat nélkül a szerver 401-et ad, és a `WWW-Authenticate` fejlécben megmondja, hol lehet engedélyt kérni. Ez nem hiba, hanem az MCP szabvány szerinti folyamat kezdete. Az eszközök listája ettől függetlenül olvasható a [manifesztből](https://naptarai.hu/.well-known/mcp.json).
## Gépi olvasásra
Minden dokumentum, amit egy ügynök vagy egy generátor kér:
- OpenAPI 3: [https://naptarai.hu/openapi.json](https://naptarai.hu/openapi.json)
- MCP manifeszt: [https://naptarai.hu/.well-known/mcp.json](https://naptarai.hu/.well-known/mcp.json)
- Állapot és felderítés: `https://naptarai.hu/api/public/v1/status`
- OAuth metaadatok: `https://naptarai.hu/api/.well-known/oauth-protected-resource`
- Rövid összefoglaló ügynököknek: [https://naptarai.hu/llms.txt](https://naptarai.hu/llms.txt)
Kezdd el egy naptárral
## A foglalásaid legyenek egy helyen, ne nyolc böngészőfülön
Kösd össze a szállásodat, lásd együtt a foglalásokat, és tereld a vendégeket a 0% platformjutalékos saját oldaladra.
[Ingyenes próba indítása](https://naptarai.hu/regisztracio)
7 nap ingyen · 0% foglalási jutalék · bármikor lemondható