Az Excel bővítmény lehetővé teszi az entitások (vállalkozók) gyors és automatikus ellenőrzését az Excel-táblázat segítségével aktuális állapotuk tekintetében a VIES rendszer.

Ez a fejezet utasításokat tartalmaz a Microsoft Excel alkalmazás és a nip24.pl rendszer integrálásához. A mellékelt bővítményt sikeresen tesztelték az MS Excel következő verzióiban: 2007, 2010, 2013, 2016, 2019 (Windows és MacOS operációs rendszereken) és 2021 (Windows és MacOS operációs rendszereken), valamint a webes verzióban az Excel365-ből.

Az Excel 2007, 2010, 2013, 2016 és 2019 bővítményének legújabb verziója mindig letölthető a Letöltési oldal. A bővítmény az Excel 32 bites és 64 bites verziójába is telepíthető. Figyelem! Válassza ki azt a verziót (32 vagy 64 bites). megegyezik az Excel verziójával, nem az operációs rendszer.

A MacOS és Excel 2021 Windows és Excel365 rendszerhez készült bővítmény letöltéséhez és telepítéséhez keresse fel a hivatalos Microsoft áruházat: https://appsource.microsoft.com.

Az Excel bővítmény teljes funkcionalitása ellenőrizhető – fiók létrehozása nélkül – a biztosított felhasználásával Teszt API. Az oldal azt is leírja, hogyan konfigurálhat egy Excel-bővítményt a teszteléshez biztosított API-ban való használatra.

A bővítmény éles API-ban való használatához fiók létrehozása a viesapi.eu weboldalon, minimum Üzleti terv vásárlása, valamint kulcs és azonosítójának generálása szükséges. A fiók regisztrációjának és beállításának, valamint a kulcsok generálásának folyamatát a Dokumentáció weboldal.

MS Excel 2021 és Excel 365 telepítése és konfigurálása a Microsoft Store-ból (AppSource)

Telepítés

Miután belépett a Microsoft hivatalos áruház webhelyére https://appsource.microsoft.com, kattints a Get it now gomb.

Megjelenik egy bejelentkezési ablak, amelyben meg kell adnia azt az e-mail címet, amelyre a Microsoft fiókját (magán vagy vállalati) hozta létre. Ha nem rendelkezik ilyen fiókkal, létrehozhat egyet, és folytathatja a telepítési folyamatot, vagy leállíthatja a telepítést, és használhatja a bővítmény telepítésének lehetőségét a fent leírt módok egyikén.

A bővítmény Excel 2021 vagy Excel 365 (web) verzióból történő letöltéséhez és telepítéséhez lépjen a Insert [1] lapon keresse meg a Bővítmények részt, és kattintson a OfficeAdd-ins [2] gombot. Ezután a megnyíló ablakba írja be a következő szót:viesapi ′ [3] gombot a keresőmezőben, és nyomja meg a nagyító ikont. A „VIES API - EU VAT Validation” található, amelyet a gombra kattintva telepíteni kell Add gombot [4]. Az összes fenti lépést az alábbi képernyőkép illusztrálja:

Miután rákattintott a Add gombot, egy képernyőnek kell megjelennie, ahol elolvashatja a licencfeltételeket és az adatvédelmi szabályokat.

A bővítmény telepítésének elindításához nyomja meg a gombot Continue gomb.

Konfiguráció

A beépülő modul helyes telepítése után az alábbihoz hasonló képernyőt kell látnia. Ban,-ben Home menu [1], keresse meg a ikont, amely a VIES API Panel [2], és kattintson rá az oldalsó panel megjelenítéséhez. Közvetlenül a telepítés után a beépülő modul tesztkörnyezetben való működésre konfigurálódik – részletek a Teszt API oldal. A kiegészítő tesztelési módban történő használatához nincs szükség fiók létrehozására a viesapi.eu weboldal.

A bővítmény éles környezetre váltásához kattintson a gombra ID and key [3] fülre, és adja meg a Key és kulcs ID, amelyet a viesapi.eu weboldalon a fiókjába való bejelentkezés után talál meg a „API Keys” lapon. Mindkét érték megadása után nyomja meg a gombot Save gomb.

Ha még nem rendelkezik fiókkal a weboldalunkon, kattintson a linkre: viesapi.eu [4], és menjen végig a regisztrációs folyamaton, amelyet részletesen ismertet a Dokumentáció oldalon.

Telepítés és konfigurálás az Excelhez: 2007, 2010, 2013, 2016 és 2019

Telepítés

Töltse le az Excel 2007, 2010, 2013, 2016 és 2019 bővítmény legújabb verzióját a Letöltési oldal. Indítsa el az MS Excel programot, és lépjen a következőre File> Options, majd válassza ki Add-ins [1] a menüből.

A beállítások alján válassza ki a lehetőséget Excel Add-ins [2] és kattintson a gombra Go [3] gombot.

A haladó felhasználók hozzáadhatnak egy kiegészítőt a Developer fület [1], majd kattintson Excel Add-ins [2] és kattintson a gombra Browse [3] gomb:

Ban,-ben Add-ins ablakban kattintson a Browse gombot, lépjen abba a könyvtárba, ahol a viesapi-ms-excel-addin-version-number.zip a fájlt kicsomagolták, és válassza ki:

• viesapiExcel.xll – az Excel 32 bites verziója esetén,
• viesapiExcel64.xll – az Excel 64 bites verziójához.

A bővítmény helyes betöltése az alábbi ábrán látható [1].

Elég rákattintani a OK gomb [2], hogy a bővítményben megvalósított funkciók elérhetőek legyenek az Excelben.

Konfiguráció

A telepítés után a bővítmény alapértelmezés szerint tesztkörnyezetre van állítva (további részletek: Teszt API oldal). Ahhoz, hogy az éles környezetben funkciókat lehessen hívni, egyszer be kell állítani a viesapi.eu webhelyhez való hozzáférést. Ehhez nyissa meg bármelyik Excel-táblázatot, és hajtsa végre a következő funkciót:

=VIESAPI.CONNECT.PRODUCTION("identifier";"key")

ahol a függvény paraméterei:

• identifier – a paraméternek tartalmaznia kell a viesapi.eu weboldalon lévő fiókon generált azonosítót (ID),
• key – a paraméternek tartalmaznia kell a viesapi.eu weboldalon lévő fiókon generált Kulcsot.

Az azonosító és a kulcs létrehozásának részletei a következő oldalon találhatók: Dokumentáció weboldal.

Egy adott API-val (teszt vagy termelés) való kapcsolat helyességének ellenőrzéséhez a következő funkciót kell végrehajtani:

=VIESAPI.CONNECT.STATUS()

Ami értékeket adhat vissza:

• SUCCESS: Production – ha a bővítmény megfelelően van konfigurálva az éles környezettel való együttműködésre,
• SUCCESS: Test – ha a bővítmény megfelelően van beállítva, hogy működjön együtt a tesztkörnyezet,

• ERROR: Connection requires configuration – hibás konfiguráció esetén.

Alapértelmezés szerint minden Excel-dokumentum automatikusan kiszámítja a táblázatot. Ennek az opciónak a beállítása azt jelenti, hogy minden képlet meghívásra kerül, amikor olyan változtatásokat hajtanak végre, amelyek hatással vannak a képletre. Példa erre egy sor törlése a munkalapon.

Annak érdekében, hogy elkerülje az adott lapon definiált összes funkció automatikus meghívását, amely a veisapi.eu weboldal API-jába történő automatikus lekérdezésekhez kapcsolódik, állítsa a munkafüzet számítási beállítását Manuálisra:

1. Tól File menü, válassza ki Options
2. Jelölje ki a Formulas lapon
3. A Számítási beállítások részben válassza ki a beállítást: Manual és törölje a jelölést a kiegészítő opció: Recalculate the workbook before saving.
4. A lapon végrehajtott változtatásokat el kell menteni.

Ilyen módon konfigurált Excel-táblázat esetén az összes definiált képlet frissítésének kikényszerítéséhez nyomja meg a billentyűkombinációt:

CTRL + ALT + SHIFT + F9

Frissítse a bővítményt a legújabb verzióra

Figyelem!Az Excel bővítmény frissítésének alábbi eljárása megfelelően működik az MS Excel 2019, 2021 és Excel 365 verzióinál, ahol a bővítmény a Microsoft Store áruházból telepíthető.

Figyelem! A legújabb verzió telepítése után újra kell konfigurálni a bővítményt, azaz meg kell adni és menteni kell az azonosítót és a kulcsot.

Az Excel-bővítmény legújabb verziójának telepítéséhez kövesse az alábbi lépéseket:

1. Ellenőrizze a telepített bővítmény verzióját a képlet meghívásával =VIESAPI.VERSION(). A kiegészítő legújabb verziója az 1.2.8

2. Az MS Excel gyorsítótárának törlése a hivatalos dokumentációs oldalon leírt eljárás szerint: https://learn.microsoft.com/en-us/office/dev/add-ins/testing/clear-cache

3. A 2. ponttól kezdődő összes lépés végrehajtása után indítsa újra az MS Excel alkalmazást.

4. Az újraindítás során az MS Excel alkalmazás letölti a bővítmény legújabb verzióját a Microsoft Store áruházból.

5. Konfigurálja a bővítményt a fiókjába való bejelentkezés után letöltött azonosító és kulcs megadásával weboldal – „API kulcsok” fül.

Használat

Tekintse meg, hogyan ellenőrizheti automatikusan és tömegesen a VIES rendszerben lévő vállalatok EU-s áfa-státuszát Excel-bővítményünk segítségével:

A kiegészítő használata előtt meg kell ismerkednie a működésének sajátosságaival:

• Minden függvényhívás aszinkron módban fut, ami nem okozza az Excel alkalmazás lefagyó (nincs válasz) hatását.
• Egy sor vagy oszlop hozzáadása (beszúrása) nem frissíti az összes meghatározott függvényhívást.
• A függvényeket tartalmazó cellák másolása vagy áthelyezése nem frissíti a meghatározott függvényhívásokat.
• Egy sor vagy oszlop törlése frissíti az összes meghatározott függvényhívást, és lekérdezéseket küld a viesApi.eu-nak (csak alapértelmezett Excel-beállítások esetén). Az alapértelmezett beállítások módosításának leírását a Konfiguráció fejezet tartalmazza.
• Figyelem! Nem ajánlott 500-nál több párhuzamos lekérdezést futtatni, mert az Excel problémái vannak nagyszámú aszinkron hívás kezelésével.

Vállalati adatok lekérése a VIES-től

VIESAPI.VIES.DATA() – A funkció az összes elérhető cégadatot közvetlenül a VIES rendszerből kéri le. A paramétereknek a következőknek kell lenniük:

• európai adóazonosító szám (áfa EU),
• (választható) FORMAT a visszaadott adatok közül (lásd: Címkék, amelyek a FORMAT paraméter).

=VIESAPI.VIES.DATA("PL7171642051")

Ha csak vállalati státuszra van szüksége a VIES-ben, használja a következő lekérdezést:

=VIESAPI.VIES.DATA("PL7171642051";"$(Valid)")

Ha a visszaküldött státusz Igen, az azt jelenti, hogy a cég érvényes EU adószámmal rendelkezik.

Címkék elérhetők a VIESAPI.VIES.DATA funkcióként használható FORMAT paraméter:

• $(UID) – A viesApi.eu szolgáltatás által generált egyedi azonosító
• $(CountryCode) - Ország kód
• $(VATNumber) – európai adószám
• $(Valid) – Érvényes státuszú EU adószám (Yes/No)
  
• $(TraderName) – A vállalkozó/szállító neve
• $(TraderCompanyType) - Üzleti típus
• $(TraderAddress) – A szerződő fél címe
• $(ID) – A VIES rendszer által generált egyedi azonosító
• $(Date) – A válasz generálásának dátuma
• $(Source) – Az adatok forrása

Alapértelmezett formátum: "$(TraderName), $(TraderAddress)"

Ha a húr "JSON" mint a FORMAT paraméter, a függvény a teljes eredményt JSON karakterlánc formájában adja vissza, amely szabadon elemezhető és tovább feldolgozható:

=VIESAPI.VIES.DATA("PL7171642051";"JSON")

Felhasználói fiók állapotának ellenőrzése (ingyenes)

VIESAPI.STATUS.ACCOUNT() – A függvény alapvető információkat ad vissza a felhasználó által jelenleg használt tervről. A paramétereknek a következőknek kell lenniük:

• (választható) FORMAT a visszaadott adatok közül (lásd: Címkék, amelyek a FORMAT paraméter)

=VIESAPI.STATUS.ACCOUNT()

Figyelem! A függvény meghívása nem növeli a lekérdezések számát.

Az elérhető címkék a VIESAPI.STATUS.ACCOUNT funkció használható a FORMAT paraméter:

• $(BillingPlanName) – Az aktuális díjcsomag neve
• $(SubscriptionPrice) – A havi előfizetés nettó ára
• $(ItemPrice) – Egyetlen lekérdezés nettó költsége a tervből a normál tervben
• $(ItemPriceStatus) – Egyetlen lekérdezés nettó költsége – VIES / Az entitás üzleti státusza az egyedi tervben
• $(Limit) – A lekérdezések maximális száma a tervben
• $(RequestDelay) – A kérések közötti minimális időintervallum
• $(DomainLimit) – A tartományok maximális száma (API-kulcsok)
• $(OverPlanAllowed) – Lehetőség a tervben szereplő lekérdezések maximális számának túllépésére
• $(ExcelAddIn) – Hozzáférés az MS Excel bővítmény használatával
• $(Stats) – Hozzáférés a végrehajtott lekérdezések statisztikájához
• $(NIPMonitor) – Hozzáférés a VIES állapotának figyeléséhez
• $(SearchByNIP) – Keresés EU adóazonosító szám alapján
• $(FuncGetVIESData) – Hozzáférés azokhoz a funkciókhoz, amelyek ellenőrzik az entitás állapotát a VIES rendszerben
• $(VIESStatusCount) – Az entitás státuszára vonatkozó lekérdezések száma a VIES rendszerben
• $(TotalCount) – Az aktuális hónapban végrehajtott lekérdezések teljes száma

Alapértelmezett FORMÁTUM: "Name of the current tariff plan: $(BillingPlanName), Monthly subscription net price: $(SubscriptionPrice), Maximum number of inquiries in the plan: $(Limit), Total number of queries made in the current month: $(TotalCount)"

Ha a húr "JSON" mint a FORMAT paraméter, a függvény a teljes eredményt JSON karakterlánc formájában adja vissza, amely szabadon elemezhető és tovább feldolgozható.

Egyéb hasznos funkciók (ingyenes)

VIESAPI.ACCOUNT.STATUS.TOTAL() – A függvény információt ad vissza az aktuális számlázási hónapban egy adott fiókra vonatkozó lekérdezések teljes számáról (összes API-kulcs). Pontosan ugyanazt a számot adja vissza, mint a $(TotalCount) címke a VIESAPI.STATUS.ACCOUNT() funkció.

VIESAPI.ACCOUNT.STATUS.LIMIT() – A függvény információt ad vissza a felhasználó által kiválasztott tervben elérhető lekérdezések maximális számáról. Pontosan ugyanazt a számot adja vissza, mint a $(Limit) tag be VIES.STATUS.ACCOUNT() funkció

VIESAPI.EUVAT.NORM() – Ez a funkció offline módban javítja és formázza az EU adószámot (eltávolítja a szóközöket, kötőjeleket stb.), és nem kér le adatokat a VIES-ből:

=VIESAPI.EUVAT.NORM("PL 717-164-20-51")

VIESAPI.EUVAT.VALID() – A funkció csak offline ellenőrzi az EU ÁFA szám helyességét (szintaxis, ellenőrző összeg), és nem kér le adatokat a VIES rendszerből. Visszatér TRUE ha a szám érvényes ill FALSE ha nem érvényes:

=VIESAPI.EUVAT.VALID("PL7171642051")

VIESAPI.CONNECTION.STATE() – A függvény visszaadja a bővítmény konfigurációjának aktuális állapotát.

Ha a függvény a következő értéket adja vissza, az többek között azt jelenti, hogy a ID és API key nem lettek elmentve:

ERROR: Connection requires configuration

Mentés után a API ID és key, a függvénynek a következő üzenetet kell visszaadnia:

SUCCESS: Production