API változásnapló

Ez a napló a REST API és az AI-összekötő (MCP) partner-látható felületének változásait tartalmazza: új végpontokat, új mezőket, új hibakódokat és viselkedés-változásokat. A belső fejlesztések (teljesítmény, tesztek, felületi munka) nem kerülnek bele.

A bejegyzések dátuma a változás kiadásának napja, a legfrissebb elöl.

Hogyan olvasd

Minden tétel egy címkével kezdődik:

Címke	Jelentése
Új végpont	Új útvonal, a meglévők érintetlenül maradnak.
Új mező	Új kérés- vagy válaszmező. A kérésben mindig opcionális, a válaszban csak akkor jelenik meg, ha van értéke.
Új hibakód	Új error.code érték. Mindig egy korábban is hibás esetre jött, nem egy addig sikeres hívásra.
Változás	A meglévő viselkedés megváltozott. Ha ez érinthet egy futó integrációt, a bejegyzés kiírja.
Javítás	A viselkedés a dokumentált vagy elvárt működésre állt.

Verziózás

Az API verziója (2026-06-15) az első kiadás óta nem változott. Ez szándékos: a dátum alapú verzió a visszafelé nem kompatibilis változásokat követi, és ilyen eddig nem volt. Az itt felsorolt bővítések mind additívak, a javítások pedig a dokumentált működést állították helyre.

Amikor egy változás mégis törne egy futó integrációt, az API új verziót kap, a régi pedig a kulcsokon pinnelve tovább él. A verziózás működését az Áttekintés írja le.

2026-08-11

Új végpont GET /v1/materials, GET /v1/materials/{id} és GET /v1/materials/{id}/stock. A tételtörzs listázása, egy tétel lekérése és a raktárankénti készlete. Jogosultság: materials:read. A lista kurzoros lapozású, legújabb elöl, és cikkszámra, illetve tétel-típusra szűr; szabad szöveges kereséshez az AI-összekötő search_materials művelete való. A készlet-végpont válaszában a totalStock a raktárankénti sorok összege, mellette raktáranként a mennyiség, a foglalás, a tárolóhely és a készlet-állapot (out_of_stock, low_stock, ok, overstock). Készlet nélküli tételnél nulla és üres lista, nem hiba. Részletek: API referencia.

Új hibakód MATERIAL_NOT_FOUND (404). Nem létező tétel lekérdezésekor, a WORKSHEET_NOT_FOUND mintájára.

Új jogosultság materials:read. Meglévő kulcsokra nem kerül rá automatikusan, a fiók tulajdonosa adhatja hozzá a beállításokban. A készlet modul Pro csomagtól él, tehát alacsonyabb csomagon az olvasó végpontok is 403 MODULE_NOT_AVAILABLE hibát adnak.

Új AI-műveletek search_materials és check_stock az AI-összekötőn. A keresés ugyanazt a találati sorrendet adja, mint a felület keresőmezője, és a magyar összetett szavakat is kezeli; a cikkszámra és a vonalkódra pontos egyezést vár. A készlet szándékosan külön művelet, mert az a raktári nyilvántartásból olvas, nem a keresőindexből: így a mennyiség nem lehet elavult. Egy hívásban legfeljebb húsz tétel készlete kérdezhető le. Mindkettő Pro csomagtól él, alacsonyabb csomagon meg sem jelenik az AI eszközei között. Az AI készletet továbbra sem módosíthat.

2026-08-10

Új végpont POST /v1/quotes, GET /v1/quotes és GET /v1/quotes/{id}. Árajánlat létrehozása meglévő ügyfélre, valamint az ajánlatok listázása és lekérdezése. Jogosultság: quotes:create a létrehozásra, quotes:read az olvasásra. Az ajánlat mindig draft státuszban jön létre, és a végpont nem küldi ki az ügyfélnek: a kiküldés, az elfogadás és az elutasítás a felületen marad, megosztási link sem keletkezik. Az összegeket a szerver számolja a tételsorokból, ugyanazzal a kalkulátorral, amit a felület használ. Részletek: API referencia.

Új hibakód QUOTE_LIMIT_EXCEEDED (403). Akkor jön, ha a fiók havi árajánlat kerete betelt (Ingyenes 3, Alap 20, Profi és Üzleti korlátlan). A details.limit a keret, a details.current az eddigi darabszám ebben a hónapban. Szándékosan 403 és nem 429: a keret a naptári hónap fordulóján nullázódik, tehát az újrapróbálás ezen a hónapon belül nem segít, a csomagváltás igen. A felületen készített ajánlatok ugyanebből a keretből fogynak.

Új hibakód QUOTE_NOT_FOUND (404). Nem létező vagy a kulcs hatókörén kívüli árajánlat lekérdezésekor, a WORKSHEET_NOT_FOUND mintájára.

Új AI-műveletek create_quote, list_quotes és get_quote az AI-összekötőn. Ugyanaz az üzleti működés, mint a REST végpontokon: meglévő ügyfél, piszkozat státusz, szerver-oldali összegzés, és a kiküldés marad a felületen. A műveletek minden csomagban megjelennek, a havi keret a hívásnál dől el. Egy megismételt kérés nem hoz létre második ajánlatot.

Új végpont POST /v1/materials. Tétel felvétele a tételtörzsbe (anyag, munkadíj, kiszállás). Jogosultság: materials:create. A hívás match-or-create: ha a cikkszám, vagy cikkszám hiányában a név, egység és típus hármas már létezik, a meglévő tétel jön vissza 200-zal és matched: true jelöléssel, új tételnél 201 és matched: false. Így egy megismételt hívás nem duplikálja a törzset. Az eladási ár elhagyható: ilyenkor a fiók felár-beállításából számolódik a beszerzési árból. A végpont nyitókészletet nem állít, a bevételezés a felületen marad. Részletek: API referencia.

Új hibakód MODULE_NOT_AVAILABLE (403). Akkor jön, ha a végpont olyan modult érint, amit a fiók előfizetése nem tartalmaz. Ma egyetlen ilyen van: a készlet modul Pro csomagtól él. Szándékosan külön kód a MISSING_PERMISSION-től, mert az a kulcs jogosultságain múlik, ez pedig a csomagon: a kulcs átállítása nem segít rajta.

Új jogosultság materials:create. Meglévő kulcsokra nem kerül rá automatikusan, a fiók tulajdonosa adhatja hozzá a beállításokban.

Új AI-művelet create_material az AI-összekötőn. Egy hívásban legfeljebb ötven tétel vehető fel, per-sor eredménnyel, tehát egy hibás sor nem buktatja a köteget. Ugyanaz a match-or-create és ugyanaz az árazás, mint a REST végponton. A művelet Pro csomagtól él, alacsonyabb csomagon meg sem jelenik az AI eszközei között.

2026-08-03

Javítás a dokumentációban, három ponton. A felület működése egyikben sem változott, a leírás állt a kódhoz.

• A hibakód-katalógusból hiányzott hat kód. Három olyan, amit a REST végpontok ténylegesen visszaadnak (ADDRESS_LIMIT_EXCEEDED, ADDRESS_NOT_FOUND, ADDRESS_PRIMARY_IMMUTABLE), és három, ami csak az alkalmazás belső műveleteiben fordul elő (CONVERSION_CONFLICT, GROUPING_CONFLICT, REVISION_CONFLICT); az utóbbiak az „Egyéb kódok“ közé kerültek. Emellett az EXTERNAL_ID_NOT_SINGLE_TOKEN is bekerült a katalógusba, ami eddig csak az API-referenciában szerepelt.
• A munkalap tételein 2026-07-15 óta kimegy a deviceLocalId, de sem az OpenAPI leírás, sem a referencia nem ismerte. Most mindkettőben szerepel.
• Új oldal: TypeScript kliens, másolható kóddal (típusok, újrapróbálás, lapozás, webhook aláírás-ellenőrzés), és ez a változásnapló.

Hogy ez ne fordulhasson elő újra, a kód és a leírás eltérését mostantól gépi ellenőrzés fogja: az útvonalakat, a válaszmezőket és a hibakódokat minden ellenőrző futás összeveti.

2026-08-02

Új végpont GET /v1/service-locations. A fiók aktív telephelyeit adja vissza névsorban, azonosítóval, kóddal és címmel. Az isDefaultForRepairs jelöli, melyik telephelyre kerül a munkalap, ha nem adsz meg helyszínt. Jogosultság: worksheets:read. Telephely nélküli fióknál üres lista, nem hiba.

Új mező serviceLocation és serviceLocationType a munkalap létrehozásán. Szerviz módú (worksheetMode: "service") munkalapon megadható a javítás helyszíne, vagy azonosítóval ({ "id": "..." }), vagy névvel ({ "name": "Soproni műhely" }). A név illesztése a magyar toldalékokat is kezeli. Megadás nélkül a fiók alapértelmezett telephelyére kerül: az utoljára használt, ennek hiányában az első aktív telephely, telephely nélküli fióknál a cég címe.

Új mező a munkalap válaszában: szerviz munkalapon mindig megjelenik a serviceLocationType, műhelyes javításnál pedig a serviceLocation objektum a telephely nevével és kódjával. A korábbi, mező nélküli szerviz munkalapok is beszédes site értéket adnak.

Új hibakód SERVICE_LOCATION_NOT_FOUND (404) és SERVICE_LOCATION_AMBIGUOUS (409). Mindkét hibaüzenet felsorolja a választható telephelyeket, így a hívó egy körben javítani tud. Részletek: Hibakódok.

Javítás a dokumentációban: az OpenAPI leírás és az API referencia eddig nem ismerte a júliusi szerviz mezőket (worksheetMode, isSurvey, devices, intakeCondition). A felület működése nem változott, a leírás állt a kódhoz.

AI-összekötő: új list_service_locations eszköz, és a szerviz munkalap nyitásakor az összekötő visszaigazolja, melyik műhelybe került a gép.

2026-07-31

Változás a POST végpontok idempotencia-garanciájában. Eddig egy olyan létrehozás, amelyik az írás után hibázott el, ugyanazzal az Idempotency-Key kulccsal megismételve második rekordot hozott létre, mert a hibás válasz után a kulcs felszabadult. Mostantól a létrehozó végpontok az erőforrás azonosítóját magából a kérésből képzik, ezért az ismételt hívás ugyanarra az erőforrásra fut rá, és a már létrejöttet adja vissza. A garancia nem az, hogy a művelet legfeljebb egyszer fut le, hanem hogy legfeljebb egy rekord jön létre.

Érintett végpontok: POST /v1/customers, POST /v1/worksheets, POST /v1/customers/{id}/addresses.

Ennek egy következménye van, amivel érdemes számolni: egy kulcs ugyanahhoz a végponthoz véglegesen egy erőforrást jelent, a 24 órás gyorsítótár lejárta után is. Ha szándékosan új erőforrást hozol létre, mindig új Idempotency-Key kulcsot küldj. Idempotency-Key nélkül a viselkedés változatlan. Részletek: Idempotencia.

2026-07-26

Új végpont GET /v1/team-members. A fiók csapattagjait adja vissza azonosítóval és névvel, hogy a hozzárendeléshez ne kelljen kitalálni az azonosítót. Új jogosultság tartozik hozzá: team:read. A meglévő kulcsok ezt nem kapják meg automatikusan, a Beállítások → Integrációk → Kulcsok oldalon adható hozzá.

Új végpont POST /v1/worksheets/{id}/assign. Kollégákat rendel a munkalaphoz szerepkörrel. A kérés a kívánt végállapotot adja meg, ezért az ismételt hívás ugyanazzal a listával nem változtat semmin.

Új mező a munkalap létrehozásán: assignments (hozzárendelés már létrehozáskor, team:read jogosultsággal), worksheetMode, isSurvey, devices és intakeCondition.

Új mező a munkalap válaszában: assignments a hozzárendelt kollégákkal (szerepkör, azonosító, név), valamint a worksheetMode és az isSurvey, amelyek mindig kimennek.

Változás a sorszám-prefixben. A gépi úton létrehozott munkalap eddig mindig ML prefixet kapott. Mostantól a worksheetMode és az isSurvey párosából adódik mind a négy bizonylat-típus: munkalap (ML), szerviz munkalap (SZ), felmérés (FE) és szerviz felmérés (SZF). A felmérések külön számlálón futnak.

Javítás: a gépi úton létrehozott munkalapra eddig nem került csapat-azonosító, ezért a sima tag jogosultságú csapattag nem látta a saját fiókjában.

Új hibakód TEAM_MEMBER_NOT_FOUND (404).

2026-07-17

Új végpont GET /v1/worksheet-statuses. A fiók munkalap-státuszainak definícióit adja vissza (technikai érték, magyar címke, szín, mód). A munkalap status mezője nyers értéket ad, egyedi státusznál custom_ előtaggal, a megjelenítéshez pedig kell a definíció. A GET /v1/custom-fields mintáját követi.

Változás a külső azonosítók keresésében: egy mezőben több azonosító is állhat, és azonosítónként külön kereshető. A névterek egyesével állnak át erre; az át nem állított névtereken a korábbi, teljes szöveges illesztés változatlanul működik, tehát a futó integrációk nem törnek el az átállítás pillanatáig. Részletek: API referencia.

Javítás: ha megadtad az externalSystem paramétert, és a keresett érték elválasztó karaktert tartalmazott (/, ,, ;), a válasz néma 404 volt. Mostantól 400 jön EXTERNAL_ID_NOT_SINGLE_TOKEN kóddal, ami megmondja, hogy azonosítónként kell keresni.

2026-07-15

Javítás a PATCH /v1/customers/{id} mezőtörlésében. Az üres string ("") küldése eddig némán nem csinált semmit: a válasz 200 volt, de az érték a helyén maradt. Mostantól az üres string törli a mezőt, ugyanúgy, ahogy a telefonszámnál és a címnél már működött. Érintett mezők: email, company, taxNumber, notes, siteContactName, siteContactPhone, siteContactEmail.

Ha az integrációd eddig üres stringet küldött abban a hitben, hogy az nem változtat semmin, ez a mezőt mostantól törli.

Javítás a munkalap számlázási címében. A POST /v1/worksheets eddig csak a munkavégzési címet töltötte ki, számlázási címet soha. Ha a munkalap workAddress mezője eltért az ügyfél címétől, a bizonylatokon és a számlázó rendszerekben a munkacím jelent meg számlázási címként. Mostantól a létrehozás az ügyfél törzsadataiból írja a számlázási pillanatképet, ugyanúgy, ahogy a felületen kitöltött munkalap.

Új mező a munkalap válaszában: devices a javításra átvett eszközökkel, a tételeken pedig deviceLocalId, amely megmondja, melyik eszközhöz tartozik az adott sor.

2026-07-14

Új mező warnings a POST /v1/worksheets válaszában. Ha a hívás createIfMissing móddal új ügyfelet is létrehozott, az ügyfélre vonatkozó figyelmeztetések (például ADDRESS_UNSTRUCTURED) mostantól a válasz gyökerében megjelennek, ugyanabban az alakban, ahogy a POST /v1/customers adja őket. Eddig ezek elvesztek.

Változás a szabad szöveges címek feldolgozásában. Ha csak fullText címet küldesz, a rendszer megpróbálja irányítószámra, városra és utcára bontani. Sikeres bontásnál az addressParseStatus értéke parsed_from_fulltext, és nem jön figyelmeztetés; a fullText referenciaként megmarad. Bizonytalan bontásnál a korábbi viselkedés marad: unstructured státusz és ADDRESS_UNSTRUCTURED figyelmeztetés. A bontás konzervatív, tehát inkább nem bont, mint rosszul.

2026-07-13

Új mező siteContactEmail az ügyfél létrehozásán és módosításán. A helyszíni kapcsolattartó email címe. Csak írható: a válaszban és a webhook üzenetekben nem jelenik meg.

A bizonylat-emailek címzett-sorrendje ezzel bővült, a siteContactEmail az utolsó a sorban: a bizonylatra írt cím, majd az ügyfél email címe, majd a címekhez tartozó email, végül a helyszíni kapcsolattartóé. Az utolsó helyre azért került, hogy egy már működő integráció automata címzettjét ne írja felül.

2026-06-24

Új mező a munkalap tételein: isWarranty, warrantyDuration, warrantyUnit (month vagy year) és warrantyNote. Létrehozáskor megadhatók, a válaszban pedig csak garanciás tételnél jelennek meg. A katalógusból behúzott tétel a saját garanciáját is hozza.

2026-06-23

Új végpont négy darab az ügyfél címeihez:

Végpont	Művelet
POST /v1/customers/{id}/addresses	Cím hozzáadása
PATCH /v1/customers/{id}/addresses/{addressId}	Cím módosítása
DELETE /v1/customers/{id}/addresses/{addressId}	Cím törlése
POST /v1/customers/{id}/addresses/{addressId}/primary	Elsődleges cím beállítása

Egy ügyfélhez így több helyszín, számlázási cím és kapcsolattartó tartozhat, nem csak egyetlen cím.

Új mező addresses az ügyfél válaszában, a további címekkel. Létrehozáskor a POST /v1/customers is fogad addresses tömböt, a PATCH /v1/customers/{id} viszont szándékosan nem: a meglévő ügyfél címeit a fenti négy végponttal kezeld, hogy egy részleges módosítás ne törölhessen véletlenül címeket.

AI-összekötő: ugyanez a négy művelet eszközként is elérhető.

2026-06-21

Új hibakód EXTERNAL_ID_AMBIGUOUS (409). Ha egy külső azonosító több élő ügyfélre illeszkedik, a rendszer egyikhez sem köti, és a keresés vagy a munkalap-generálás 409 hibával utasít el. Eddig ilyenkor csendben az egyik ügyfél jött vissza, vagy a createIfMissing új ügyfelet hozott létre, tehát a munkalap rossz ügyfélhez került.

Amint az ütközés a forrásrendszerben feloldódik, és egy azonosító újra egy ügyfelet jelöl, a kötés automatikusan helyreáll, beavatkozás nélkül.

2026-06-18

Változás: egy kulcs mostantól több külső azonosító névteret kezelhet (legfeljebb tízet), közülük az egyik az elsődleges. A cél-névteret az externalSystem paraméterrel adhatod meg mind a négy külső azonosítós folyamatban.

Új hibakód három, a több névteres működéshez: EXTERNAL_SYSTEM_AMBIGUOUS (400), EXTERNAL_ID_FIELD_MISMATCH (400) és EXTERNAL_NAMESPACE_FORBIDDEN (403). A dokumentáció korábban tévesen azt állította, hogy az utóbbit a REST API nem adja vissza. Részletek: Hitelesítés.

2026-06-17

Változás: a külső azonosítóként leképzett egyedi mezők kikerültek a customFields blokkból. Az értékük az externalIds mezőn megy ki, a kulcs saját névterére szűrve. Így egy kulcs nem látja egy másik rendszer azonosítóját ugyanarról az ügyfélről.

Ha az integrációd a külső azonosítót a customFields blokkból olvasta ki, azt az externalIds mezőből kell kiolvasnia. A GET /v1/custom-fields válasza megjelöli, mely mezők tartoznak külső azonosító névtérhez.

2026-06-16

Változás: a munkalap tételei engedélyezési listára kerültek a válaszban és a webhook üzenetekben. Ekkor kilenc mező maradt: id, type, description, quantity, unit, unitPrice, totalPrice, vatRate, note. A belső mezők, köztük a beszerzési ár, az anyag-azonosító, a forrásraktár, a nettó egységár, a kedvezmény, a számlázhatóság és a képhivatkozás, kikerültek.

A tétel-mezők listája azóta bővült (garancia, eszköz-hivatkozás), de a lista azóta is zárt: csak az kerül bele, ami dokumentált. A tétel aktuális mezőit az API referencia sorolja.

Ez a változás az első kiadást követő napon történt, a partner-integrációk indulása előtt.

2026-06-15

Az első nyilvános kiadás, 2026-06-15 API verzióval. Hét útvonalon tíz művelet az ügyfelekhez és a munkalapokhoz, webhook értesítések, egyedi mező felderítés, valamint a teljes fejlesztői dokumentáció: Áttekintés, Hitelesítés, API referencia, Webhookok, Hibakódok és Integrációs példa.