ELBA API — ERP-kapcsolat

Áttekintés

Az ELBA nem ERP-nként épít csatlakozót, hanem egy nyitott API-t ad, amire bármelyik ERP vagy integrátor rá tud kötni. A fő irány az ELBA → ERP: az ERP lekéri a projekteket és az ajánlatok tételeit (mennyiség, végső ajánlati egységár, áfa), és az ELBA webhookkal szól, ha új ajánlat-verzió készült, ha egy ajánlat elnyert lett, vagy ha a projekt fázisa változott. A másik irányban (ERP → ELBA) az ERP a saját beszerzési árait töltheti fel, amelyekből az ELBA a következő árazásnál dolgozik.

Az API címe:

https://…/functions/v1/api/v1

Minden válasz JSON (UTF-8). Az összegek nettó forintban értendők, ha a mező neve mást nem mond. Az időpontok ISO 8601 formátumúak, UTC-ben.

Hitelesítés

Az API-kulcsot az ELBA-ban a Beállítások → ERP / API-kapcsolat résznél hozza létre a fiók (cégnél a cég fő felhasználója). A kulcs elba_ előtagú, 45 karakter hosszú, és csak létrehozáskor látható — az ELBA csak a lenyomatát tárolja. Minden kéréshez kell:

Authorization: Bearer elba_…vagy: X-Api-Key: elba_…

A kulcs a létrehozó fiók projektjeit látja, cég esetén a cég összes projektjét is. Kétféle jog van: olvasás (minden kulcsnak) és árak írása (külön bekapcsolandó). A kulcs bármikor visszavonható; utána minden hívás 401-et kap.

A kulcs titok

Szerveren tárold (környezeti változó, titoktár), ne böngészőben futó kódban. Ha kiszivárgott, vond vissza, és hozz létre újat.

Végpontok

Kérés	Mit ad
`GET /v1`	Él-e a kapcsolat, és milyen jogai vannak a kulcsnak.
`GET /v1/projektek`	A projektek listája, a legutóbb módosult elöl. Paraméterek: `modositva_utan` (időpont — növekményes szinkronhoz), `limit` (alap 100, legfeljebb 500), `offset`. Válasz: `{ osszes, adat: [...] }`, projektenként az ajánlat állapota (`sors`: kint / elnyert / elbukott / visszavont) és az utolsó rögzített verzió összegei.
`GET /v1/projektek/{id}`	A projekt adatai, az ajánlat fejléce (szorzók, fővállalkozói felár, kedvezmény, megrendelő és ajánlatadó adatai) és a rögzített verziók listája.
`GET /v1/projektek/{id}/tetelek`	Az ajánlat munkapéldánya: a tételek most érvényes mennyiséggel és végső ajánlati egységárral. Ez változhat — a megkötött állapothoz a verziót használd.
`GET /v1/verziok/{id}`	Egy rögzített ajánlat-verzió a tételeivel. Ez nem változik: erre érdemes rendelést, beszerzést, projekt-költségkeretet építeni.
`GET /v1/sajat-arak`	A fiók saját árai tételkulcsonként (a legfrissebb), `modositva_utan` szűréssel.
`PUT /v1/sajat-arak`	Saját árak feltöltése az ERP-ből (árak írása jog kell).

Példa: növekményes szinkron

GET /v1/projektek?modositva_utan=2026-10-01T00:00:00Z&limit=200

Az ERP eltárolja a legutóbbi futás idejét, és legközelebb csak az azóta módosult projekteket kéri le. A webhookkal együtt ez a legkevesebb hívással járó út: a webhook szól, a lista csak tartaléknak kell.

Tételek és árak

Minden tétel kulcsa a ck (az ELBA tételkulcsa) — ez a párosítás alapja a két rendszer között. A fontosabb mezők:

Mező	Jelentés
`ck`	Tételkulcs. Ezzel lehet saját árat visszaírni.
`szint`, `elem`, `alelem`	Hol van az épületben (pl. Földszint › Falak › Külső fal).
`munkanem`, `arazasi_egyseg`	Munkanem és az ELBA árazási egysége.
`megnevezes`, `jellemzo`, `termek`	A tétel szövege, a jellemzői és — ha van — a választott termék.
`mennyiseg`, `egyseg`	Mennyiség és mértékegység.
`onkoltseg_anyag_egysegar`, `onkoltseg_munka_egysegar`	Az önköltségi egységárak, módosítók nélkül.
`anyag_egysegar`, `munka_egysegar`	A végső ajánlati egységárak: a szorzók, a fővállalkozói felár és az egyösszegű kedvezmény után — ugyanaz, ami az ajánlaton áll.
`netto`, `afa_kulcs`, `afa`, `brutto`	Sorösszeg és áfa. Az `afa_kulcs` tört (0.27 = 27%); negatív érték fordított adózást jelent.

A rögzített verzió soraiban az egységárak úgy vannak arányosítva, hogy a sorok nettója pontosan a verzió nettó végösszegét adja.

Árak az ERP-ből

Az árak írása jogú kulccsal az ERP a fiók saját árai közé tölthet árat. A következő árazásnál az ELBA ezeket használja a rendszerárak helyett. Egy hívásban legfeljebb 1000 sor:

PUT /v1/sajat-arak
Content-Type: application/json

[
  { "ck": "falazoelem|anyag=b30", "anyag_egysegar": 9800, "munka_egysegar": 3900,
    "egyseg": "m2", "kulso_azon": "CIKK-10442", "megnevezes": "Falazóblokk 30 cm" }
]

A ck értékét a tételek végpontjából veszi az ERP; a kulso_azon az ERP saját cikkszáma, amit az ELBA eltárol és visszaad. A válasz soronként jelzi a hibát, a jó sorok mentésre kerülnek: { "ok": true, "mentve": 1, "hibas": 0, "hibak": [] }.

Webhook

A webhookot is a Beállításokban állítja be a fiók: egy https:// cím és a kért események. Beállításkor egy aláíró titkot kap (whsec_…), ezt is csak egyszer lát. Események:

Esemény	Mikor	Mezők
`ajanlat.verzio`	Új ajánlat-verziót rögzítettek.	`projekt_id, verzio_id, sorszam, nev, netto, afa, brutto`
`ajanlat.elnyert`	Az ajánlatot elnyertnek jelölték.	`projekt_id, verzio_id` (a legutóbbi), `sors_datum`
`projekt.fazis`	A projekt fázisa változott (pl. ajánlatból kivitelezés).	`projekt_id, regi, uj`
`ping`	Próbaüzenet a Beállításokból.	`uzenet`

A kérés egy POST, JSON törzzsel; mindig van benne id (egyedi, pl. evt_42), esemeny, idopont és kiserlet. Az üzenet szándékosan rövid: a részleteket az ERP az API-ból kéri le (pl. GET /v1/verziok/{verzio_id}).

POST https://erp.ceged.hu/elba-webhook
X-Elba-Esemeny: ajanlat.elnyert
X-Elba-Esemeny-Id: evt_42
X-Elba-Alairas: t=1791890000,v1=5f1c…

{"id":"evt_42","kiserlet":1,"esemeny":"ajanlat.elnyert","projekt_id":"…","verzio_id":"…","sors_datum":"2026-10-13","idopont":"…"}

Az aláírás ellenőrzése

Az X-Elba-Alairas fejlécben t a küldés ideje (Unix másodperc), v1 pedig a "<t>.<nyers törzs>" szöveg HMAC-SHA256 lenyomata (hex) a titokkal. Az ERP számolja ki ugyanezt, hasonlítsa össze, és dobja el az 5 percnél régebbi üzenetet:

// Node.js
const crypto = require('crypto');
function elbaHiteles(nyersTorzs, fejlec, titok) {
  const m = /t=(\d+),v1=([0-9a-f]+)/.exec(fejlec || '');
  if (!m || Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false;
  const vart = crypto.createHmac('sha256', titok).update(m[1] + '.' + nyersTorzs).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(vart), Buffer.from(m[2]));
}

Siker: bármely 2xx válasz, 10 másodpercen belül. Ha nem sikerül, az ELBA újrapróbálja (1 perc, 5 perc, 30 perc, 2, 6, 12, 24 óra), a 8. sikertelen kísérlet után feladja. Az átirányítást nem követi. Ugyanaz az esemény többször is megérkezhet, ezért az id alapján szűrd ki az ismétlést.

Hibák, korlátok

Hiba esetén a válasz { "hiba": "…", "kod": "…" } alakú, magyar szöveggel.

Kód	Jelentés
400	Hibás paraméter (pl. nem UUID az azonosító, rossz időpont-formátum, rossz törzs).
401	Hiányzó, hibás vagy visszavont kulcs.
403	A fiók csomagjában nincs API-kapcsolat, vagy a kulcsnak nincs árak írása joga.
404	Nincs ilyen projekt vagy verzió — vagy van, de ez a kulcs nem látja.
413	Túl nagy kérés (1000 sor vagy 2 MB felett).
500	Váratlan hiba az ELBA oldalán — érdemes később újrapróbálni.

Korlátok: fiókonként legfeljebb 5 élő kulcs és 3 webhook; listázásnál legfeljebb 500 projekt egy oldalon. Az API az ELBA Nagyvállalati csomagjának része.