KönyvelőHíd API: hozzáférés könyvelőprogramnak és fejlesztőknek

MindenkinekÚj

Hogyan éri el a könyvelőprogramod a számlákat, a számlaképeket és a bankkivonatokat, és mit írhat vissza.

A KönyvelőHíd API-t kínál, amellyel a könyvelőprogramod vagy egy saját rendszered (például egy szkript) közvetlenül éri el a KönyvelőHíd adatait. Letöltheti az iktatott bejövő és kimenő számlákat a számlaképekkel, a bankkivonatokat és a kiegyenlítéseket, majd visszajelzi, mit vett át és mit könyvelt le. Számlaképet és dokumentumot fel is tölthet.

Ehhez nem kell külön előfizetés vagy Számlázó API-kulcs: a KönyvelőHíd-előfizetés elég, és a Számlázó Demo vagy Free csomagja mellett is működik. A kapcsolat a fiók egészére szól: a kapott kulcs a fiók összes cégét eléri, ezért a fiók tulajdonosa állítja be, és bizalmasan kell kezelni.

Hozzáférés: API-kulcs, Cég azonosító

A kulcsot a Beállítások oldal „KönyvelőHíd API” szekciójában kapod meg (ha a cégnél a Számlázó is megvan, a KönyvelőHíd modulban). A szekció kulcs-részét az iroda és a főkönyvelő, illetve a vállalkozói fiók tulajdonosa kezeli.

Az API-kulcs részben minden megnyitott könyvelt évnek saját sora van. Az év sorában kattints az „API-kulcs megjelenítése” gombra, és add meg a saját jelszavadat: megjelenik a teljes kulcs (az iroda-kulcs) egy „Másol” gombbal, alatta pedig a cégeid Cég azonosítója.
A könyvelőprogramba írd be a kulcsot és a cégek Cég azonosítóját. A program ezt a kulcsot küldi minden hívásban, a céget pedig a Cég azonosító választja ki.

A kulcs könyvelt évenként más. Évnyitás után az új év sora magától megjelenik, és a könyvelőprogramba az új év kulcsát kell beírni. Ha a program még a korábbi év kulcsát használja, a szekció figyelmeztet.
A táblázat azt is mutatja, mikor használták utoljára a kulcsot, és mikor, ki generált újat.
A Cég azonosító legfeljebb 8 karakteres kód. A vállalkozói fiókban felvett új cég automatikusan megkapja: az adószám első 8 számjegyét, vagy ha az a fiókban már foglalt, az első 7 számjegyet és egy betűt. A FiókCégek oldalon, a cég Módosítás ablakában átírhatod (A cégadatok mezői). A cegek művelet a fiók összes cégazonosítóját visszaadja.

Figyelem

Az iroda-kulcs a fiók összes cégét eléri, ezért kezeld bizalmasan. Ha illetéktelen kézbe került, az év sorában kattints az „Új kulcs generálása” gombra: a régi kulcs azonnal érvénytelen lesz, és a vele bekötött könyvelőprogram addig nem ér el adatot, amíg az újat be nem írod.

Tipp

Ha egy cégnél a Cég azonosító mező üres, a szekció jelzi: töltsd ki, mielőtt a könyvelőprogrammal lekérdezed, mert a program ezzel a kóddal hivatkozik a cégre. Ha Google-, Microsoft- vagy Facebook-fiókkal lépsz be, és még nincs jelszavad, a kulcs megjelenítéséhez a belépő oldalon az „Elfelejtett jelszó” linkkel állíts be egyet.

Mit lehet lekérdezni?

a fiók cégeinek azonosítóit;
az iktatott bejövő és kimenő számlákat: a még át nem vett tételek listáját (hónapra is szűrve), vagy az összes tételt; egy számla teljes adatait (partner, dátumok, összegek áfakulcsonként) a számlaképpel együtt, PDF-ben;
a feltöltött kimenő számla XML-fájlokat;
a bankkivonatokat (banki import) a PDF-fel együtt;
egy számla kiegyenlítési adatait: a bruttó összeget és a már kiegyenlített részt;
a számlaképet iktatószám alapján;
az új egyéb iratokat.

Hogy a könyvelőprogram mely állapotú bizonylatokat veheti át — csak az „Ellenőrizve”, vagy az „Iktatva” állapotúakat is —, azt a cég „Átadott adatok” beállítása dönti el.

Figyelem

A letöltés átadásnak számít. Amikor a program letölt egy számlát (vagy egy új egyéb iratot), az a KönyvelőHídban „Átadva” állapotba kerül, és a még át nem vett tételek között többé nem szerepel — a csak megtekintésre megosztott cégnél is. Ha egy számlát újra át kell adni, a programban állítsd vissza az állapotát „Ellenőrizve”-re.

Mit lehet írni?

Az írható kör azt fedi le, amit egy könyvelőprogram a munka végén visszajelez, és amit egy beküldő rendszer bejuttat:

visszaszinkron (átvétel): a tételek állapota (például Könyvelve, Függő, Nem könyvelhető) és a könyvelés adatai, egy kérésben több tételre is;
kiegyenlítés: egy számla kiegyenlítése dátummal és összeggel, vagy több számláé egyszerre. Ez a számla teljes kiegyenlítési állapotát állítja be: a programban korábban rögzített részletek helyére egyetlen tétel kerül;
számlakép feltöltése: PDF-ből, JPG-ből vagy PNG-ből új, „Iktatva” állapotú tétel lesz (a képből a program A4-es PDF-et készít). A feltöltött kép a képlimitbe beszámít;
dokumentum feltöltése (egyéb irat);
partnerek felvétele és frissítése.

Amit nem lehet: törölni semmit nem lehet az API-n. Passzív cégre új adat (feltöltés) nem küldhető, olvasni viszont lehet. Ugyanígy csak olvasni lehet, amíg egy cég törlése folyamatban van, és ha a fiók KönyvelőHíd-előfizetése lejárt.

Technikai alapok

Az API SOAP-alapú (nem REST): minden műveletnek saját címe és WSDL-leírása van, például https://ugyfelkapu.qs.hu/docs_back/soap/iktatottBejovo.php és …/iktatottBejovo.wsdl. A kérés text/xml POST.
A dátumok ÉÉÉÉ-HH-NN alakúak, a fájlok (PDF, XML) base64-kódolva utaznak.
Minden hívásban az iroda-kulcs és a Cég azonosító szerepel (a cegek kivételével, ahhoz csak a kulcs kell).

Dokumentáció

A részletes, műveletenkénti leírás bejelentkezés nélkül elérhető: https://ugyfelkapu.qs.hu/api/docs/. Megtalálod benne az összes műveletet, a paramétereket és a válaszok felépítését példa-kérésekkel, és ki is próbálhatod a hívásokat (Kipróbálás). A kulcsról a bevezető „Hitelesítés” része szól, a KönyvelőHíd-műveletek az „Iktató” csoportokban vannak.

Ha a könyvelőprogramod fejlesztőivel készítteted el az integrációt, nekik ezt a linket küldd el. A kulcsot és a Cég azonosítókat lehetőleg te magad írd be a programba.

Gyakori kérdések

Kell hozzá Számlázó-előfizetés vagy Számlázó API-kulcs? Nem. A Számlázó API-kulcsai a számlakiállításra valók (webshop, saját rendszer); a KönyvelőHíd API-nak saját kulcsa van, amelyet a Beállítások „KönyvelőHíd API” szekciójában kapsz. A Számlázó API-ról a Számlázó tudásbázisában olvashatsz.

Ki jelenítheti meg a kulcsot? Az iroda és a főkönyvelő, illetve a vállalkozói fiók tulajdonosa, mindig a saját jelszavával. Minden megjelenítést és új kulcs generálását naplózunk.

Mit ér el az iroda-kulcs? A fiók összes cégét, a megosztott cégeket is: ezeket az iroda a saját Cég azonosítójával kéri le. Ahol az irodának csak megtekintési joga van, ott a feltöltés, a kiegyenlítés és a visszaszinkron nem megy.

Megváltozik a kulcs, ha jelszót cserélek? Nem: az iroda-kulcs a fiókhoz és az évhez tartozik, nem a jelszóhoz. Ha attól tartasz, hogy illetéktelen kézbe került, generálj újat a Beállítások „KönyvelőHíd API” szekciójában az „Új kulcs generálása” gombbal: a régi kulcs azonnal érvénytelen lesz, az újat pedig be kell írnod a könyvelőprogramba.

Mi történik, ha egy kérés időtúllépés miatt megismétlődik? A visszaszinkron és a kiegyenlítés ismételhető: ugyanaz kétszer beküldve ugyanaz az eredmény. A feltöltésnél a program ugyanazt a fájlnevet egy cégnél nem fogadja el kétszer, így nem lesz dupla tétel. A letöltés viszont egyszeri (lásd fent: Átadva), ezért a program a kapott adatot rögtön mentse el.

Mi a különbség az API és az AI-asszisztens között? Az API programok közti kapcsolat: a könyvelőprogram rendszeresen, automatikusan veszi át az adatokat. Az AI-asszisztens beszélgetésben válaszol a kérdéseidre, a te jogaiddal, és nem jelöli átadottnak a számlákat.