# Cégjelző Figyelő API leírás (v2)

Utolsó módosítás dátuma: 2025-11-19

# API elérési címek

Teszt API endpoint: https://watch-dev.api.cegjelzo.com/v2 (opens new window)

Swagger dokumentáció: https://watch-dev.api.cegjelzo.com/v2/docs (opens new window)

Itt megtekinthetők a request és response modellek.

# Általános információk

A Figyelő API gazdasági társaságok (cégek: kft, bt, nyrt stb.), egyéni vállalkozók, civil szervezetek és őstermelők nyilvántartási adataiban történő változások figyelésére szolgál. A szolgáltatás segítségével első kézből értesülhetnek a partner cégekben bekövetkezett adatváltozásokról.

# FONTOS

A Cégjelző API nem szerződésszerű használata esetén a rendszer automatikusan korlátozza az adott ügyféltől érkező összes hívást, ezért javasoljuk, hogy élesítés előtt fokozott figyelemmel nézzék át a beépített terméket.

Korlátozások

Rate limit - A Figyelő API rate limitált. Maximum 30 kérés indítható másodpercenként. Figyelt tételek - A felhasználó összes listáján összesen a szerződésben meghatározott figyelt tétel szerepelhet.
Lista méret - A listák mérete maximum 2000 figyelt tétel lehet.
Lista szám - A létrehozható listák száma korlátlan. Változás intervallum - A változásokat időintervallumra adja vissza az api, ez maximum egy hét lehet.
Figyelés kezdete - A rögzített tételek rögzítést követő adatbetöltésnél aktiválódnak.

Változások lekérdezésének ideje

Az előző nap beszerzett adatokat reggel 6 órakor kezdjük el betölteni.

Ezért az előző nap figyelési találatait célszerű reggel 7 óra után lekérdezni, ellenkező esetben nem fognak látszani az előző napi változások.

# Segítség a teszteléshez

# Bevezetés

Ezen tesztelési segédlet célja, hogy megkönnyítse a Cégjelző Figyelő API integrálását és tesztelését a fejlesztőknek szánt teszt környezetben.

# A teszt rendszer

Az API teszt végpontja https://watch-dev.api.cegjelzo.com/v2 (opens new window) címen érhető el, melyhez tartozik egy swagger (openapi) dokumentáció is, mely ezen a címen (opens new window) érhető el. A swagger dokumentáció elolvasása, és áttanulmányozása erősen ajánlott, hiszen a kérések és a válaszok struktúrájának pontos modellje megtalálható benne.

Fontos információ a teszt rendszerrel kapcsolatban, hogy az ott megtalálható adatok nem pontosak, nem kerülnek frissítésre, és ezáltal valós változások sem kerülnek be, kizárólag fejlesztésre használhatóak.

# Hogyan lehet tesztelni?

Mint ahogy az feljebb ki lett emelve a teszt végponton nem történik valós változás, emiatt felmerülhet a kérdés, hogy akkor hogyan lehet tesztelni? - Röviden, tömören "időutazással".

Bár új változások nem kerülnek be, a régiek rögzítve lettek az adatbázisba, és ezt ki lehet használni a teszteléshez. Ezen dokumentációhoz mellékelve megtalálható egy excel lista a teszt rendszeren megtalálható változásokról.

A lista letölthető innen.

# Partnertörzs frissítése

Amennyiben partnertörzsünket szeretnénk karbantartani a Figyelő API segítségével, akkor a folyamat két lépésből áll a legtöbb esetben:

1. A figyelt vállalkozások változásainak ellenőrzése.
2. Változás esetén a hatályos adatok frissítése a saját rendszerben.

Ennek tesztelése nehéz, hiszen nem tudhatjuk előre, hogy milyen változások fognak érkezni, és hogy a listánkon szereplő vállalkozások között szerepel-e olyan, ahova érkezni fog változás - nem beszélve arról, hogy ha érkezett is változás, azt figyelembe kell-e vennünk vagy sem.

# Teszt lista előállítása

  • Először (integrációtól függő dolog) el kell döntenünk, hogy milyen változásokra, változás típusokra és mely rovatok változásaira figyelünk.

A vállalkozások összes rovata figyelve van. A változás lekérdezésekor a heading_types mező segítségével megállapítható, hogy mely rovatban történt változás, és hogy az az integráció szempontjából fontos-e.

FONTOS, hogy a heading_types mező csak és kizárólag társas vállakozások esetén tartalmaz adatot, minden más esetben, pl egyéni vállalkozóknál üres lista fog szerepelni változástól függetlenül. Ezen esetek megkülönböztetésére használható a change_type mező, mely társas vállalkozások esetén mklk, minden más esetben pedig az adott entitás típusát tartalmazza, pl egyéni vállalkozó esetében ez self_employed.

  • Amennyiben az integráció figyelmen kívül hagyja a heading_types mezőt, akkor ebben az esetben a következő lépésnél nem kell a változások között keresni, szimplán csak elég a nekünk szimpatikus vállalkozásokat felvenni a listánkra, és a listán szereplő dátumokkal tesztelni.
  • Ha összegyűjtöttük a szükséges változás típusokat (vagy nem vettük őket figyelembe), akkor a mellékelt excel alapján ki kell választani pár vállalkozást, ami a kritériumnak megfelel, pl amennyiben a név változásokat figyeljük akkor a listából olyan vállalkozásokat kell kiválasztani ahol a long_name vagy short_name oszlopban szerepel egy X. Emellé érdemes kiválasztani pár nem céget is, amennyiben az éles környezetben szeretnénk majd nem csak társas vállalkozásokat figyelni. Fontos, hogy ezen esetekben nem fog X szerepelni semelyik oszlopban sem, hiszen ezek esetében a heading_types mező is üres lesz a változás lekérdezésekor.
  • Következő lépésben vegyük fel a listánkra a kiválasztott, és nekünk szükséges változásokat tartalmazó vállalkozásokat, illetve melléjük 1-2 olyat, amiben nem szerepel az a változás amire figyelünk.

# Frissítés tesztelése

  • Miután elkészítettük a listánkat az excel alapján, következhet az integráció tesztelése.

  • Módosítsuk a belső teszt környezetben a törzsadatokat: Ezzel azt szimulálva, hogy az adott vállalkozásnak eddig pl más neve volt.

    FONTOS, ezt így, ilyen formában ne teszteljük éles környezetben, csak olyan adatbázisban, amit szabadon módosíthatunk, és tesztelésre használunk!

  • Az excel alapján keressük ki a kiválasztott vállalkozás változásának időpontjait, majd az integrációban ezeket kezdjük el lekérdezni: úgy, mintha épp aznap/azon hét lenne (ha ez nehéz feladatnak bizonyul, például nagyon mélyen van integrálva a dátum kezelésére használt logika, abban az esetben érdemes az adott kódrészt mockolni a teszteléshez - így, amennyiben a frissítést és lekérdezést sikeresen implementáltuk, akkor a partnertörzsbe a tesztrendszerben megtalálható jó adat fog kerülni (amennyiben az az elvárt működés)

    Ez természetesen csak egy példa, viszont az elv az másfajta integrációk esetén is ugyan az marad: Készítsünk egy listát a megadott excel alapján, majd azon lista változásait kérdezzük le az adott idő "változás" intervallumokban.

# Egyszerű változások tesztelése

  • A mellékelt excel alapján ki kell választani pár vállalkozást, ami a kritériumnak megfelel, pl amennyiben az eljárásokat szeretnénk figyelni akkor a listából olyan vállalkozásokat kell kiválasztani ahol a megfelelő oszlopban szerepel egy X. Emellé érdemes kiválasztani pár nem céget is, amennyiben az éles környezetben szeretnénk majd nem csak társas vállalkozásokat is figyelni.

  • Következő lépésben vegyük fel a listánkra a kiválasztott, és nekünk szükséges változásokat tartalmazó vállalkozásokat, illetve melléjük 1-2 olyat, amiben nem szerepel az a változás amire figyelünk.

  • Az excel alapján keressük ki a kiválasztott vállalkozás változásának időpontjait, majd az integrációban ezeket kezdjük el lekérdezni: úgy, mintha épp aznap/azon hét lenne - így, amennyiben sikeresen integráltuk az API-t, akkor a válaszban szerepelni fognak a kívánt változások.

    Amennyiben szeretnénk, hogy sok változás jelenjen meg a listánkon, érdemes az excelben a 2025-08-07, 2025-08-08, 2025-08-09 re szűrni (vagy majdnem bármelyik napra 2025 augusztusából), mint változás időpontja. Ebben az időszakban történt a 25-ös teáor-ok kihírdetése a magyar cégközlöny által, azaz majdnem az összes az excelben szereplő céghez történt ebben a hónapban változás.

# Műveletek figyelési listákkal

# 1. Az összes lista metaadatainak lekérdezése

HTTP Method: GET

Végpont: /v2/lists

Headers (Fejléc):

  • X-Api-Key: Kötelező. Kapott Api key.

Minta lekérdezés: GET https://watch-dev.api.cegjelzo.com/v2/lists

Minta válasz:

Status code: 200 OK

{
  "watch_lists": [
    {
      "list_key": "132135",
      // a lista azonosítója
      "list_name": "Teszt Lista",
      // a lista neve
      "created_at": "2022-01-23",
      // a létrehozás dátuma
      "watch_count": 13
      // a listára rögzített figyelt tételek száma
    },
    {
      "list_key": "102030",
      "list_name": "Teszt Lista 2",
      "created_at": "2022-01-23",
      "watch_count": 130
    }
  ],
  "total_watch_count": 143
  // az összes figyelt tétel száma
}

# 2. Új figyelési lista létrehozása

HTTP Method: POST

Végpont: /v2/lists

Headers (Fejléc):

  • X-Api-Key: Kötelező. Kapott Api key.

Minta lekérdezés: POST https://watch-dev.api.cegjelzo.com/v2/lists

Body (tartalom JSON formátumban):

{
  "list_name": "Teszt Lista"
  // a lista neve
}

Minta válasz:

Status code: 201 Created

{
  "list_key": "132639",
  "list_name": "Teszt Lista",
  "created_at": "2022-01-23",
  // lista létrehozásának dátuma 
  "watch_count": 0
}

# 3. Lista metaadatok lekérdezése azonosító alapján

HTTP Method: GET

Végpont: /v2/lists/<list_key>

Headers (Fejléc):

  • X-Api-Key: Kötelező. Kapott Api key.

Minta hívás: GET https://watch-dev.api.cegjelzo.com/v2/lists/1a2b3c

Minta válasz:

Status code: 200 OK

{
  "list_key": "1a2b3c",
  "list_name": "Teszt Lista",
  "created_at": "2022-01-23",
  "watch_count": 132
}

# 4. Lista törlése lista azonosító alapján, az összes figyelt tételével együtt

HTTP Method: DELETE

Végpont: /v2/lists/<list_key>

Headers (Fejléc):

  • X-Api-Key: Kötelező. Kapott Api key.

Minta hívás: DELETE https://watch-dev.api.cegjelzo.com/v2/lists/1a2b3c

Body (tartalom JSON formátumban):

{
  "list_name": "Teszt Lista"
  // a lista neve
}

Minta válasz:

Status code: 204 No content

# Műveletek figyelési tételekkel

# 1. Lista figyelt tételeinek lekérdezése

HTTP Method: GET

Végpont: v2/lists/<list_key>/items

Headers (Fejléc):

  • X-Api-Key: Kötelező. Kapott Api key.

Minta hívás: GET https://watch-dev.api.cegjelzo.com/v2/lists/1a2b3c/items

Minta válasz:

Status code: 200 OK

{
  "watched_items": [
    // a listára rögzített figyelési tételek listája
    {
      "added_at": "2022-01-04",
      // a figyelés kezdete
      "tax_id": "10625790"
      // a vállalkozás adótörzsszáma
    },
    {
      "added_at": "2022-03-12",
      // a figyelés kezdete
      "tax_id": "10101234"
      // a vállalkozás adótörzsszáma
    }
  ]
}

# 2. Figyelt tétel(ek) felvétele a listára

HTTP Method: POST

Végpont: v2/lists/<list_key>/items

Headers (Fejléc):

  • X-Api-Key: Kötelező. Kapott Api key.

Minta hívás: POST https://watch-dev.api.cegjelzo.com/v2/lists/1a2b3c/items

{
  "tax_ids": [
    "10000000",
    // hibás adótörzs
    "13800000",
    // formailag helyes adótörzs, de nem létezik a cég
    "invalid_tétel",
    // hibás adótörzs
    "10625790",
    // létező adótörzs - még nincs figyeltetve
    "23412341"
    // létező adótörzs - előzőleg már rögzítve lett a listára
  ]
}

Minta válasz:

Status code: 200 OK

{
  "success": [
    "10625790"
  ],
  "failed": [
    {
      "tax_id": "10000000",
      "code": 422
      // mert ilyen adótörzs nem lehetséges
    },
    {
      "tax_id": "13800000",
      "code": 404
      // mert ilyen adótörzs nem található az adatbázisban
    },
    {
      "tax_id": "invalid_tétel",
      "code": 422
      // mert formailag hibás az adótörzs
    },
    {
      "tax_id": "23412341",
      "code": 409
      // mert már szerepel a listán
    }
  ]
}

Ezen végpont válasza speciális a tömeges rögzítés lehetősége miatt.

A fenti működés miatt, fontos, hogy a válasznál ne csak a státusz kódot ellenőrizzék, hanem magát a válasz json-t is.

A válasz success kulcsa alatt található azon adótörzsek listája amit sikeresen rögzített a hívás.
A failed kulcs alatt olyan objektumok találhatók, melyek megmutatják, hogy melyik adótörzs (tax_id) rögzítése nem sikerült, valamint a code mező tájékoztat arról, hogy miért nem.

Ezek a következők lehetnek:

  • 404 - Az adótörzs nem található az adatbázisban.
  • 409 - Az adótörzs már szerepel a figyelési listán
  • 422 - Az adótörzs formátuma nem megfelelő
  • 429 - Nem adható a listához, mert
    • a lista hossza a elérte a maximális lista méretet (2000)
    • a figyelt tételek száma elérte a szerződésben foglalt maximális figyelési számot

# 3. Figyelt tétel(ek) eltávolítás a listáról

HTTP Method: DELETE

Végpont: v2/lists/<list_key>/items

Headers (Fejléc):

  • X-Api-Key: Kötelező. Kapott Api key.

Minta hívás: DELETE https://watch-dev.api.cegjelzo.com/v2/lists/1a2b3c/items

{
  "tax_ids": [
    "10000000",
    // hibás adótörzs
    "13800000",
    // formailag helyes adótörzs, de nem létezik a cég
    "invalid_tétel",
    // hibás adótörzs
    "10625790",
    // létező adótörzs - még nincs figyeltetve
    "23412341"
    // létező adótörzs - előzőleg már rögzítve lett a listára
  ]
}

Minta válasz:

Status code: 200 OK

{
  "success": [
    "10625790"
  ],
  "failed": [
    {
      "tax_id": "10000000",
      "code": 422
      // mert ilyen adótörzs nem lehetséges
    },
    {
      "tax_id": "13800000",
      "code": 404
      // mert ilyen adótörzs nem található az adatbázisban
    },
    {
      "tax_id": "invalid_tétel",
      "code": 422
      // mert formailag hibás az adótörzs
    },
    {
      "tax_id": "23412341",
      "code": 409
      // mert már szerepel a listán
    }
  ]
}

Ezen végpont válasza speciális a tömeges eltávolítás lehetősége miatt.

A fenti működés miatt, fontos, hogy a válasznál ne csak a státusz kódot ellenőrizzék, hanem magát a válasz json-t is.

A válasz success kulcsa alatt található azon adótörzsek listája amit sikeresen eltávolított a hívás.
A failed kulcs alatt olyan objektumok találhatók, melyek megmutatják, hogy melyik adótörzs (tax_id) eltávolítása nem sikerült, a code mező tájékoztat ennek okáról.

# 4. Válozások lekérdezése a listáról

HTTP Method: GET

Végpont: v2/lists/<list_key>/changes

Headers (Fejléc):

  • X-Api-Key: Kötelező. Kapott Api key.

Minta hívás: GET https://watch-dev.api.cegjelzo.com/v2/lists/1a2b3c/changes

Minta válasz:

{
  "start_date": "2022-01-10",
  "end_date": "2022-01-10",
  "changed_items": [
    {
      "change": "2022-01-10",
      "tax_id": "10625790",
      "chapter": "changes",
      "changed_headings": [
        "long_name",
        "bank_accounts"
      ],
      "path": "https://s3.eu-central-1.amazonaws.com/cegjelzo-watch-changes-test/{dátum}/{cégforma}/{filenév}"
    }
  ]
}

Status code: 200 OK

# Kapcsolat

Bármilyen felmerülő kérdés, vagy pontosítás esetén az alábbi e-mail címen elérhetőek vagyunk: support@cegjelzo.hu