Integrációk fejlesztőknek: webhook, IoT adatbeküldés, API-kulcs
Hogyan kapcsolódik a Terepbázis más rendszerekhez: eseményértesítés webhookon, mérési adat beküldése IoT eszközökről, és mit kell tudnia egy fejlesztőnek, aki ezt bekötné.
Mit tud ma, és mit nem
A Terepbázis két irányban kapcsolódik külső rendszerhez. Kifelé: eseményekről HTTPS-értesítést küld a saját szerveredre (webhook). Befelé: mérési adatot fogad IoT eszközökről vagy egy köztes gateway-ből. Mindkettő bérlőnként külön konfigurálható, és mindkettőhöz saját titok tartozik.
Amit őszintén meg kell mondani
A kézbesítő motor 2026. augusztus 11-én állt üzembe. Hat adatkör küld eseményt: a munkalapok, a raktári feladatok, az IoT-riasztások, az ajánlatok, a számlák és a projektek — mindegyik létrejöttkor és módosuláskor. Fontos szerkezeti tulajdonság: esemény csak akkor keletkezik, ha van hozzá aktív, feliratkozott endpoint; ha nincs, a rendszer nem gyűjti a sorba, tehát a bekapcsolás előtti időszak nem játszható vissza.
- Webhook: HTTPS POST a te végpontodra, HMAC-SHA256 aláírással, újrapróbálkozással.
- IoT adatbeküldés: eszközönkénti titokkal hitelesített HTTPS POST a Terepbázis felé.
- API-kulcsok: az Integrációs központban generálhatók, a nyers kulcs csak egyszer jelenik meg.
Webhook beállítása (a felületen)
- Nyisd meg a Cégem → Integrációs központ oldalt. A modul Enterprise csomagtól érhető el.
- A Webhook endpointok blokkban kattints az új endpoint hozzáadására.
- Adj neki nevet, és írd be a cél-URL-t. Kizárólag HTTPS fogadható el, és a belső címek (localhost, 10.x, 192.168.x, 169.254.x, .local, .internal) el vannak zárva — ezt a rendszer a mentéskor ellenőrzi.
- Az eseménytípusoknál üresen hagyva minden támogatott eseményt megkapsz; ha felsorolsz típusokat, csak azokat.
- Állítsd be az időtúllépést (1 és 60 másodperc között). A te végpontodnak ennyi ideje van válaszolni.
- Mentés után az Endpoint health blokkban látod a kézbesítés állapotát: utolsó siker, utolsó hiba, egymás utáni hibák száma.
A cél-URL ellenőrzése két helyen fut: a mentéskor és közvetlenül a küldés előtt. Ez nem felesleges ismétlés — egy régebbi, még ellenőrzés nélkül felvett cím így sem tud kimenő kérést kiváltani.
Amit a szervered kapni fog
A kérés HTTP POST, a törzse JSON, a fejlécekben pedig ott az esemény típusa, a kézbesítés azonosítója, a küldés időbélyege, és — ha generáltál aláíró titkot — a HMAC-SHA256 aláírás.
Az esemény típusa mindig tábla.művelet alakú, ahol a művelet insert vagy update. Ma ezek fordulhatnak elő:
| Esemény | Mikor keletkezik |
|---|---|
| work_orders.insert | új munkalap jön létre |
| work_orders.update | munkalap bármely mezője módosul (lezárás, ütemezés, átosztás) |
| warehouse_tasks.insert | új raktári feladat jön létre |
| warehouse_tasks.update | raktári feladat módosul |
| iot_alerts.insert | új IoT-riasztás keletkezik |
| iot_alerts.update | IoT-riasztás módosul (például nyugtázás) |
| quotes.insert | új ajánlat jön létre |
| quotes.update | ajánlat módosul (elfogadás, árazás, státuszváltás) |
| invoices.insert | új számla jön létre |
| invoices.update | számla módosul (például fizetettre állítás) |
| projects.insert | új projekt jön létre |
| projects.update | projekt módosul |
| integration.test | az Integrációs központ teszt-gombja |
Az update nem mondja meg, MI változott
Egy work_orders.update ugyanúgy szól egy lezárásról, mint egy átütemezésről, és egy quotes.update ugyanúgy egy elfogadásról, mint egy árazás-javításról — a mezőnkénti különbséget a rendszer nem küldi el. Ha a te oldaladon a lezárás vagy az elfogadás számít, az aggregate.id alapján kérdezd vissza az állapotot, és a saját oldaladon dönts. Aki eseménynévből következtet üzleti tényre, hamis riasztást fog kapni.
| Fejléc | Tartalom |
|---|---|
| X-Terepbazis-Event | az esemény típusa, például work_orders.update |
| X-Terepbazis-Delivery | a kézbesítés egyedi azonosítója (újrapróbálkozásnál ugyanaz) |
| X-Terepbazis-Timestamp | a küldés Unix-időbélyege másodpercben |
| X-Terepbazis-Signature | sha256=<hexadecimális HMAC>, csak ha van aláíró titok |
| User-Agent | Terepbazis-Webhook/1.0 |
Az aláírás ellenőrzése
A HMAC a titok kulccsal, a timestamp és a nyers törzs PONTTAL összefűzött alakja felett képződik: HMAC-SHA256(titok, timestamp + '.' + nyers_body). A törzset a nyers formájában használd, ne az újraszerializált JSON-t — a szóközök és a kulcssorrend számít. Az összehasonlítást futásidő-független módszerrel végezd (Node: crypto.timingSafeEqual).
A törzs mezői: id (a kézbesítés azonosítója), event (a típus), created_at (mikor keletkezett az esemény), tenant_id (melyik cég), aggregate (az érintett rekord típusa és azonosítója), idempotency_key, attempt (hányadik próbálkozás), és data.
A data mező NEM az entitás adata
Erre a pontra érdemes figyelni, mert a legtöbb webhook-rendszer másképp csinálja: a data ma NÉGY mezőt tartalmaz — id, tenant_id, operation (insert vagy update), occurred_at. A munkalap száma, státusza, ügyfele NINCS benne. Az értesítés tehát jelzés, nem adatszállítás: a részletekért az aggregate.id alapján kell visszakérdezned az API-n. Így a webhook nem szivárogtat adatot olyan végpontra, ami esetleg már nem a tiéd.
Idempotencia — ezt kérjük
Ugyanaz az esemény újrapróbálkozásnál újra megérkezhet, azonos X-Terepbazis-Delivery értékkel. A fogadó oldalon ezt az azonosítót tárold, és a másodszor érkezőt dobd el. Ez nem a mi hibánk esete, hanem a hálózaté: egy időtúllépés után nem tudjuk, hogy a kérés megérkezett-e.
Ha a te végpontod nem válaszol
Sikeresnek a 2xx választ tekintjük. Minden más (4xx, 5xx, időtúllépés, hálózati hiba) újrapróbálkozást vált ki, növekvő várakozással.
| Próbálkozás | Mikor |
|---|---|
| 1. | azonnal (a legközelebbi perces körben) |
| 2. | 2 perc múlva |
| 3. | 4 perc múlva |
| 4. | 8 perc múlva |
| 5. | 16 perc múlva |
| 6. | 32 perc múlva |
| utána | a kézbesítés dead letter állapotba kerül, és nem próbálkozunk tovább |
A dead letter nem eltűnés: a kézbesítés ott marad a nyilvántartásban a hibaüzenettel és a HTTP-státusszal együtt. Az Integrációs központ Outbox blokkjában maga az ESEMÉNY küldhető újra — ilyenkor a rendszer újra szétosztja minden illeszkedő endpointra, tehát a többi címzetted is megkapja még egyszer. Az endpointnál külön látod, hány hiba futott egymás után; ez a szám sikeres kézbesítéskor nullázódik.
Egy eset kimarad az újrapróbálkozásból: ha a cél-URL a küldés pillanatában megbukik a biztonsági ellenőrzésen (nem HTTPS, vagy belső cím), a kézbesítés azonnal dead letter lesz. Ez nem átmeneti hiba, tehát a várakozásnak nincs értelme.
Több endpoint, külön sorsok
Ha ugyanarra az eseményre két endpointod is illeszkedik, mindkettő külön kézbesítést kap, külön újrapróbálkozás-számlálóval. Az egyik végpont kiesése nem okoz duplikált küldést a másiknál — ez a leggyakoribb hiba az ilyen rendszerekben, és nálunk szerkezetileg ki van zárva.
IoT adatbeküldés
Mérési adatot HTTPS POST-tal küldhetsz be. Az eszközt előbb fel kell venni a Cégem → IoT oldalon, ahol beküldési titkot kap; a titkot a rendszer csak hasítva tárolja, ezért a generáláskor mentsd el.
- Vedd fel az eszközt a Cégem → IoT felületen, adj neki külső azonosítót (ez lesz a device_external_id) és szolgáltató-nevet (provider).
- Mentsd el a kapott beküldési titkot, mert később nem kérhető le újra.
- A gateway-ed POST kérést küld a Terepbázis iot-ingest végpontjára, az x-device-secret fejlécben a titokkal.
- A törzsben add meg a device_external_id, provider mezőket és a readings tömböt.
- Minden mérés vagy numeric_value, vagy text_value értéket tartalmaz — pontosan az egyiket —, plusz a recorded_at ISO időbélyeget.
- A válasz accepted mezője megmondja, hány mérés került be.
| Korlát | Érték |
|---|---|
| Mérések egy kérésben | legfeljebb 200 |
| Kérés mérete | legfeljebb 256 kB |
| Kérések percenként | 60, IP-címenként |
| Időbélyeg-ablak | legfeljebb 7 nap múlt, 1 óra jövő |
| Minőség-jelzés | good, uncertain vagy bad (alapértelmezés: good) |
Az időbélyeg-ablak szándékos: a visszamenőleg vagy előre dátumozott telemetria elrontaná a riasztásokat, ezért az ablakon kívüli mérést elutasítjuk. A hibák beszédesek — invalid_metric, exactly_one_reading_value_required, batch_too_large, rate_limited —, tehát a gateway naplójából eldönthető, mi történt.
Kész prompt fejlesztő-ügynöknek
Ha AI-ügynökkel (Claude Code, Cursor, Copilot) építed a fogadó oldalt, ezt a leírást másold be neki. Mindent tartalmaz, amit a fogadó végponthoz tudni kell, és megmondja, mit NE tegyen.
A prompt
Építs egy HTTPS webhook-fogadó végpontot a Terepbázis eseményeihez. A kérés POST, JSON törzzsel. Fejlécek: X-Terepbazis-Event (típus), X-Terepbazis-Delivery (kézbesítés-azonosító), X-Terepbazis-Timestamp (Unix másodperc), X-Terepbazis-Signature (sha256=hex). Az aláírás HMAC-SHA256 a megosztott titokkal, a `timestamp + '.' + nyers_body` string felett. Az esemény neve tábla.művelet alakú: work_orders.insert, work_orders.update, warehouse_tasks.insert, warehouse_tasks.update, iot_alerts.insert, iot_alerts.update, quotes.insert, quotes.update, invoices.insert, invoices.update, projects.insert, projects.update, integration.test. A törzs data mezője CSAK az id, tenant_id, operation és occurred_at mezőket tartalmazza — az entitás adatait az aggregate.id alapján külön kell visszakérdezni. Követelmények: (1) a NYERS törzset használd az ellenőrzéshez, ne az újraszerializáltat; (2) az aláírást futásidő-független összehasonlítással vesd össze; (3) utasítsd el a 5 percnél régebbi időbélyeget; (4) a feldolgozás ELŐTT válaszolj 2xx-szel, a munkát tedd sorba, mert 1-60 másodperc az időkorlát; (5) az X-Terepbazis-Delivery értékét tárold, és a másodszor érkező azonos azonosítót dobd el — az újrapróbálkozás ugyanazt az azonosítót hozza; (6) a nem 2xx válasz újrapróbálkozást vált ki 2, 4, 8, 16, 32 perces várakozással, hat próba után dead letter; (7) az aláíró fejléc HIÁNYOZHAT, ha az endpointhoz nincs titok — ilyenkor ne üres aláírásra számíts, hanem a fejléc hiányára. NE használj sorrend-feltételezést az események között, NE tételezd fel, hogy minden esemény pontosan egyszer érkezik, és NE következtess az esemény nevéből üzleti tényre — az update bármely mezőmódosulást jelenthet.
Ugyanez az elv a beküldés irányában: ha az ügynököd IoT-gateway-t ír, add meg neki a fenti korlát-táblát, és kérd, hogy a 429 (rate_limited) válasz retry_after_seconds mezőjét vegye figyelembe, ne fix várakozással próbálkozzon újra.
Mi jön még
- Szemantikus események (például külön jelzés a munkalap lezárására vagy az ajánlat elfogadására) a mai tábla.művelet alak mellé — ma az update nem mondja meg, mi változott.
- Aláíró titok generálása a felületről (a háttér már kész, a gomb még nincs kint).
- MCP-kiszolgáló: gépi olvasás és írás minden modulhoz, ugyanazokkal a jogosultsági szabályokkal, amiket a felület használ.
Ha integrációt tervezel és hiányzik egy esemény vagy egy mező, írj az info@terepbazis.net címre. A konkrét kérés gyorsabban bekerül, mint egy általános igény.