Hivatalos API

Az AtlasSystem hivatalos API-ján keresztül külső program is le tudja kérdezni a cég adatainak egy részét: például a saját másik rendszere, egy partner szoftvere vagy egy riportkészítő eszköz.

Az oldal két részből áll:

• az első rész a főfelhasználónak szól: hogyan ad ki és von vissza hozzáférési kulcsot;
• a második rész annak, aki a kapcsolódó programot írja: milyen adatok kérdezhetők le és hogyan.

Amit az API nem tud

Az API kizárólag olvas. Adatot létrehozni, módosítani vagy törölni egyetlen kulccsal sem lehet. Egy kulcs mindig csak a saját cég adatait éri el, és csak azokat az adatköröket, amelyeket a kiadásakor engedélyeztek neki.

Kulcs kiadása és visszavonása

A kulcsokat a főfelhasználó kezeli a Beállítások API fülén.

Új kulcs kiadása

Mező	Mit ad meg
Név (kinek adjuk ki)	Saját azonosításra, hogy később tudja, melyik kulcsot kinek adta ki. Kötelező.
Hatókör	Melyik adatkört érheti el a kulcs. Egyszerre több is választható, de legalább egy kötelező.
Lejárat (üres = nincs)	Ettől a naptól a kulcs nem használható. Üresen hagyva visszavonásig érvényes.
IP-korlát (vesszővel, üres = nincs)	Mely IP-címekről fogadja el a rendszer a kulcsot. Üresen hagyva bármelyikről.

A négy választható hatókör: mozgasok, kartonok, termekek, raktarak. Mindegyik egy-egy adatkört nyit meg; a részleteket lentebb, az egyes adatkörök leírásában találja.

A Kulcs kiadása gomb csak akkor aktív, ha a nevet kitöltötte és legalább egy hatókört választott.

A kulcs csak egyszer látszik

A kiadás után a rendszer egyetlen alkalommal mutatja meg a kulcs teljes alakját, a Másol gombbal együtt. Ha elhagyja ezt a képernyőt, a kulcs többé nem kérhető vissza - sem Ön, sem a rendszergazda nem tudja újra megjeleníteni. Ilyenkor a régit vonja vissza, és adjon ki újat.

Mentse el a kulcsot biztonságos helyre, mielőtt továbbadja. A kulcs jelszó értékű: aki birtokolja, a hatókörébe eső adatokat le tudja kérdezni.

A kiadott kulcsok listája

Oszlop	Jelentése
Név	Amit a kiadáskor megadott.
Prefix	A kulcs felismerhető eleje. A teljes kulcsot a rendszer nem tárolja, csak ezt - ezért tudja a listában is azonosítani, melyik kulcsról van szó.
Hatókör, Lejárat, IP-korlát	A kiadáskor megadott értékek.
Utolsó használat	Mikor hívták a kulccsal a rendszert utoljára. Ebből látszik, ha egy kulcsot már senki nem használ.
Állapot	aktív, lejárt (a lejárati napja elmúlt) vagy visszavonva.

Visszavonás

Az aktív kulcsok sorában a Visszavon gomb azonnal érvényteleníti a kulcsot; a rendszer megerősítést kér. A visszavonás után a kulccsal futó lekérdezések azonnal leállnak, és a kulcs nem hozható vissza: ha a hozzáférésre újra szükség van, új kulcsot kell kiadni.

A visszavont kulcs sora a listában marad, hogy később is visszakereshető legyen, ki és mit ért el vele.

Amit a kiadás előtt érdemes átgondolni

A kulcs a hatókörébe eső adatokat úgy adja át, ahogy az AtlasSystemben vannak. A terméktörzsnél ez a termékek árait is jelenti, a raktáraknál pedig a rögzített telefonszámot és e-mail címet. Csak olyan hatókört adjon egy kulcsnak, amire a fogadó félnek valóban szüksége van.

Kapcsolódás

Ez a rész annak szól, aki a kapcsolódó programot írja.

Cím

Minden lekérdezés a cég saját AtlasSystem-címén érhető el, az /api/publikus/v1/ útvonal alatt. A rendszer a címből ismeri fel, melyik cégről van szó, ezért egy kulcs más cég címén akkor sem működik, ha egyébként érvényes.

https://<a cég saját AtlasSystem-címe>/api/publikus/v1/<adatkör>

Minden lekérdezés GET. Más HTTP-metódus (POST, PUT, PATCH, DELETE) hibát ad.

Hitelesítés

A kulcsot minden híváshoz az Authorization fejlécben kell elküldeni, Bearer előtaggal:

Authorization: Bearer atlas_<prefix>_<titok>

Példahívás

curl -H "Authorization: Bearer atlas_abc123def456_..." \
     "https://<a cég saját AtlasSystem-címe>/api/publikus/v1/termekek?per_page=50&sort=nev"

Lapozás

Paraméter	Jelentése
page	Hányadik oldal. Alapértelmezés: 1.
per_page	Hány sor legyen egy oldalon. Alapértelmezés: 100, felső határ: 500.

A felső határnál nagyobb kért érték nem hiba: a rendszer 500-ra vágja, és adatot ad vissza.

A válasz a sorokat a data kulcs alatt adja, mellette meta (current_page, last_page, per_page, total) és links szerepel.

Rendezés

A sort paraméterrel, mezőnév szerint. Mínuszjel az elején csökkenő sorrendet jelent:

?sort=nev      -> növekvő
?sort=-nev     -> csökkenő

Rendezni csak a felsorolt mezőkre lehet, adatkörönként; ismeretlen mezőnév hibát ad. Ha nem ad meg rendezést, a rendszer az id szerint csökkenő sorrendben válaszol.

Szűrés

A szűrők a szuro tömbben mennek:

?szuro[cikkszam]=40306896&szuro[torolt]=1

Szűrni csak a felsorolt kulcsokra lehet; ismeretlen szűrőnév hibát ad.

A dátumot váró szűrőknél a 2026-08-19 alak is megadható. A záró dátumot a rendszer a nap végéig értelmezi, tehát az aznapi sorok is beleesnek a tartományba.

Korlátozás

Egy kulcs percenként 120 hívást indíthat. A határ átlépésekor a rendszer tul_sok_keres hibát ad. Ugyanez a percenkénti korlát él a hitelesítés előtt, a hívó IP-címére is.

A lekérdezhető adatkörök

Készlet-mozgások

GET /api/publikus/v1/mozgasok

Egy sor egy szállítólevél-tétel, mert a mozgás adatai részben tétel-szintűek (azonosító, mennyiség, cikkszám).

A mozgás forrás- és célraktára a raktarbol és a raktarba mezőben, a raktár nevével szerepel. Raktárra szűrni a raktar_id szűrővel lehet, amely a forrásra és a célra egyaránt illeszkedik.

Mezők: id, termek_cikkszam, termek_nev, termek_tipus, termek_tipus_nev, azonosito, mennyiseg, raktarbol, raktarba, bizszam, ref, irany, irany_nev, besorolas, besorolas_nev, szabad_besorolas, datum, lezaras, nyitott.

Az irany a mozgás típusa. A nyers érték mellett mindig megy olvasható név is (irany_nev): 1 - Kimenő szállítólevél, 2 - Kiadás, 3 - Bejövő szállítólevél, 4 - Bevétel, 5 - Átadás. Ugyanez a párosítás áll a termék típusánál és besorolásánál is.

Illesszen az értékre, ne a szövegre

Ahol a válasz nyers értéket és olvasható nevet is ad (irany / irany_nev, tipus / tipus_nev, besorolas / besorolas_nev, kategoria / kategoria_nev), ott a programja a nyers értékre illesszen. A magyar megnevezés a felület szövegét követi, és változhat; az érték nem.

Szűrők: nyitott (1 = csak nyitott, 0 = csak lezárt), irany, raktar_id (forrás vagy cél raktár), refszam, bizszam, azonosito, datum_tol, datum_ig, lezaras_tol, lezaras_ig.

A két dátum-tartomány független: a datum_tol / datum_ig a szállítólevél keltére szűr ("mikor történt"), a lezaras_tol / lezaras_ig a lezárás időpontjára ("mikor zárták le"). Egyszerre is használhatók.

Rendezhető: id, azonosito, mennyiseg, letrehozva.

Két tudnivaló a lezárásról

A lezaras mező a lezárás pontos időpontja. A rendszerben szereplő lezárási dátum külön oszlop, és azt az API szándékosan nem adja ki - a lezárás idejét az időbélyegből olvassa ki.

A nyitott mező és a nyitott szűrő ettől függetlenül a lezárási dátumra épül, mert az minden soron kitöltött. Néhány régi, még a pontos időbélyeg bevezetése előtt lezárt szállítólevélnél ezért előfordulhat, hogy a nyitott értéke false, a lezaras viszont üres.

Dolgozói kartonok

GET /api/publikus/v1/kartonok

Mezők: nev, fajta, fajta_nev, csoport.

A fajta értéke 1 = alkalmazott, 2 = alvállalkozó; az olvasható változat a fajta_nev.

Szűrők: fajta, csoport_id. Rendezhető: id, fajta.

Ez az adatkör szándékosan szűk

A dolgozói karton a rendszerben sok személyes adatot tárol (személyi igazolvány szám, születési adatok, anyja neve, TAJ-szám, adóazonosító, lakcím, telefonszám, e-mail cím, bankszámlaszám, baleset esetén értesítendő személy). Ezek közül az API egyet sem ad ki: kizárólag a név, a fajta és a csoport kérdezhető le (a fajta a nyers érték és az olvasható név alakjában is). Ez nem hiány, hanem szándék.

Termékek

GET /api/publikus/v1/termekek

A termekek törzs saját adatai. Mezők: id, nev, tipus, tipus_nev, egyediazonosito, cikkszam, vonalkod, egysegar, kiegar, bruttoar, kategoria, kategoria_nev, feltetel, wantphoto, besorolas, besorolas_nev, elszamolas, pontertek, eszkoztarkell, szereloar, szerelokiegar, munkatetel_tipus, munkatetel_tipus_nev, min_menny, dobkezeles, szabad_besorolas, megjegyzes, leiras, vallalkozoar, vallalkozokiegar, mertekegyseg, foanyag_kategoria, egyebar, arszazalekol, szereloarszazalekol, vallalkozoarszazalekol, muszer, osszetett, torolt, letrehozva, modositva.

Szűrők: nev (részletre is illeszkedik), cikkszam, vonalkod, tipus, besorolas, szabad_besorolas, kategoria, torolt. Rendezhető: id, nev, cikkszam, tipus, besorolas, modositva.

A törölt termékek alapból nem szerepelnek a válaszban; a szuro[torolt]=1 kéri őket is.

Az árak kimennek

A termékek árai szerepelnek a válaszban (egységár, kiegészítő ár, bruttó ár, szerelői és vállalkozói árak, pontérték). Ez tudatos döntés, nem kifelejtett szűrés. Ezt vegye figyelembe, mielőtt termekek hatókörű kulcsot ad ki külső félnek.

Amit a válasz nem tartalmaz: a számított exportár, a felhasználói egyedi árak, a készletadatok és a kapcsolt eszköztár - ezek nem a terméktörzs saját adatai.

Raktárak

GET /api/publikus/v1/raktarak

Mezők: id, nev, tipus, tipus_nev, cim, telefon, email, csoport, ceg, torolt, letrehozva, modositva.

Szűrők: nev (részletre is illeszkedik), tipus, csoport, torolt. Rendezhető: id, nev, tipus, csoport.

A törölt raktárak alapból nem szerepelnek a válaszban; a szuro[torolt]=1 kéri őket is.

A raktárhoz rögzített telefonszám és e-mail cím szerepel a válaszban. Ha ezek személyes elérhetőségek, ezt vegye figyelembe a kulcs kiadásakor.

Hibaüzenetek

Hiba esetén a válasz mindig ugyanilyen alakú:

{
  "error": {
    "code": "hatokoron_kivul",
    "message": "Az API kulcs nem éri el ezt az erőforrást."
  }
}

A programja a code értékére illesszen, ne a message szövegére: a szöveg változhat, a kód nem.

Kód	HTTP	Mikor
ervenytelen_kulcs	401	Hiányzó, hibás vagy ismeretlen kulcs.
lejart_kulcs	401	A kulcs lejárati napja elmúlt.
letiltott_kulcs	401	A kulcsot visszavonták.
nem_engedett_ip	403	A hívás olyan IP-címről jött, amely nincs a kulcs IP-korlátjában.
hatokoron_kivul	403	A kulcs érvényes, de ezt az adatkört nem éri el.
ervenytelen_parameter	422	Ismeretlen szűrő- vagy rendezési mező, vagy értelmezhetetlen dátum.
tul_sok_keres	429	Túllépte a percenkénti hívásszámot.
nem_talalhato	404	A kért adat nem található.
ismeretlen_szolgaltatas	404	Nem létező útvonal vagy ismeretlen cím.
nem_engedett_muvelet	405	Az API kizárólag olvasható, más művelet nem indítható.

A hiányzó, a hibás és az ismeretlen kulcs szándékosan ugyanazt a ervenytelen_kulcs kódot kapja: a három megkülönböztetéséből ki lehetne találni, hogy egy adott kulcs létezik-e. A lejárt és a visszavont kulcs viszont külön kódot kap, mert ott a hívó már bizonyította, hogy birtokolja a kulcsot.

Naplózás

A rendszer minden hívást naplóz: melyik kulccsal (a kulcs felismerhető elejével, sosem a teljes kulccsal), melyik adatkörre, milyen eredménnyel, melyik IP-címről érkezett, hány sort adott vissza és mennyi ideig futott. A sikeres lekérdezések is bekerülnek a naplóba, nem csak az elutasítottak.