Validátor doplnku VIES pre Tabuľky Google™

Doplnok Google Sheets™ vám umožňuje rýchlo a automaticky skontrolovať subjekty (dodávateľov) pomocou tabuľky Google Sheets™ z hľadiska ich aktuálneho stavu v systém VIES.

Táto dokumentácia obsahuje pokyny na integráciu aplikácie Tabuľky Google™ so systémom VIES API.

 

 

Inštalácia a konfigurácia

Inštalácia

Po vstupe na webovú stránku Google Workspace Marketplace https://workspace.google.com/marketplace/app/vies_api_eu_vat_validation/1043052728267, kliknite na Install tlačidlo.

Výber účtu Google, pre ktorý má byť nainštalovaný a dostupný doplnok VIES Validator pre Tabuľky Google:

Na ďalšej obrazovke si môžete prečítať Zásady ochrany osobných údajov a príslušné Podmienky služby, ako aj rozsah vašich údajov, ktoré budeme spracovávať. Ak chcete prejsť na ďalší krok inštalácie, stlačte tlačidlo Continue tlačidlo.

Potvrďte, že ste udelili potrebné povolenia pre správne fungovanie doplnku, a stlačte tlačidlo Allow tlačidlo:

Doplnok VIES Validation bol úspešne nainštalovaný do vášho účtu a bude k dispozícii po spustení Tabuliek Google na karte Rozšírenia. Ak chcete pokračovať, kliknite Next:

Na záverečnej obrazovke inštalátora sa zobrazí výzva na konfiguráciu doplnku. Kliknutím na tlačidlo „Complete additional setup now„“ otvorí nové okno prehliadača s aktuálnou stránkou dokumentácie. Kliknite na Done a začnite konfigurovať doplnok podľa popisu v časti Konfigurácia.

Konfigurácia

Po inštalácii je plugin štandardne nastavený na testovacie prostredie (viac podrobností o Test API stránka). Aby bolo možné volať funkcie v produkčnom prostredí, je potrebné jednorazovo nakonfigurovať prístup na webovú stránku viesapi.eu. Ak to chcete urobiť, prejdite do ľubovoľného tabuľkového procesora Google Sheets™ a vykonajte funkciu:

=VIESAPI_CONNECT_PRODUCTION("identifier";"key")

kde parametre funkcie sú:

• identifier – parameter by mal obsahovať identifikátor (ID) vygenerovaný na účte na stránke viesapi.eu,
• key – parameter by mal obsahovať Kľúč vygenerovaný na účte na stránke viesapi.eu.

Podrobnosti o generovaní identifikátora a kľúča sú popísané na Dokumentácia webovej stránky.

Na overenie správnosti spojenia s daným API (test alebo výroba) by sa mala vykonať nasledujúca funkcia:

=VIESAPI_CONNECT_STATUS()

Ktoré môžu vrátiť hodnoty:

• SUCCESS: Production – ak je doplnok správne nakonfigurovaný na prácu s produkčným prostredím,
• SUCCESS: Test – ak je doplnok správne nakonfigurovaný na prácu s testovacie prostredie,

• ERROR: Connection requires configuration – v prípade nesprávnej konfigurácie.

Ak uprednostňujete konfiguráciu bočného panela, kliknite na Extensions a potom vyberte VIES API - EU VAT Validation a nakoniec kliknite Show sidebar Ak chcete povoliť bočný panel:

Potom choďte na ID and Key pre vstup do ID a Key v príslušných textových poliach, ktoré sú k dispozícii po prihlásení do vášho účtu VIES API: https://viesapi.eu/sign-in/

Použitie

Pred použitím doplnku by ste sa mali oboznámiť so špecifikami jeho fungovania:

• Všetky volania funkcií sa vykonávajú v asynchrónnom režime, čo nespôsobuje zamrznutie (žiadnu odozvu) aplikácie Google Sheets™.
• Pridanie (vloženie) riadka alebo stĺpca neobnoví všetky definované volania funkcií.
• Kopírovanie alebo presúvanie buniek, ktoré obsahujú funkcie, neobnovuje definované volania funkcií.
• Odstránením riadka alebo stĺpca sa obnoví množstvo definovaných volaní funkcií a odošlú sa dotazy na viesApi.eu (iba v prípade predvolených nastavení Google Sheets™). Popis zmeny predvolených nastavení je uvedený v kapitole Konfigurácia.
• Pozor! Neodporúča sa spúšťať viac ako 500 paralelných dotazov, pretože Tabuľky Google™ majú problémy so spracovaním veľkého počtu asynchrónnych volaní.

Získajte firemné údaje z VIES

VIESAPI_VIES_DATA() – Funkcia získava všetky dostupné firemné dáta priamo zo systému VIES. Parametre by mali byť:

• európske daňové identifikačné číslo (VAT EU),
• (voliteľné) FORMAT vrátených údajov (pozri: Tagy, ktoré možno použiť ako FORMAT parameter).

=VIESAPI_VIES_DATA("PL7171642051")

Ak potrebujete iba štatút spoločnosti vo VIES, použite nasledujúci dotaz:

=VIESAPI_VIES_DATA("PL7171642051";"$(Valid)")

Ak je stav vrátenia Áno, znamená to, že spoločnosť má platné IČ DPH EÚ.

Značky dostupné v VIESAPI_VIES_DATA funkciu, ktorú možno použiť ako FORMAT parameter:

• $(UID) – jedinečný identifikátor vygenerovaný službou viesApi.eu
• $(CountryCode) – predvoľba krajiny
• $(VATNumber) – európske IČ DPH
• $(Valid) – odpoveď zo služby VIES s informáciou o aktuálnom statuse DPH v EÚ kontrolovanej spoločnosti (Yes/No)
• $(TraderName) – názov spoločnosti
• $(TraderCompanyType) – typ podnikania
• $(TraderAddress) – adresa obchodníka, kde je spoločnosť registrovaná
• $(ID) – jedinečný identifikátor vygenerovaný systémom VIES (konzultačné číslo)
• $(Date) – dátum vygenerovania odpovede
• $(Source) – zdroj údajov

Predvolený formát: "$(TraderName), $(TraderAddress)"

Ak reťazec "JSON" sa uvádza ako FORMAT parameter, funkcia vráti kompletný výsledok vo forme reťazca JSON, ktorý možno voľne analyzovať a ďalej spracovávať:

=VIESAPI_VIES_DATA("PL7171642051";"JSON")

Získajte analyzované firemné údaje z VIES

VIESAPI_VIES_DATA_PARSED() – Funkcia načíta všetky dostupné údaje o spoločnosti priamo zo systému VIES. Okrem toho sa názov a adresa spoločnosti vrátia ako analyzované údaje rozdelené do samostatných atribútov. Parametre by mali byť:

• európske daňové identifikačné číslo (VAT EU),
• (voliteľné) FORMAT vrátených údajov (pozri: Tagy, ktoré možno použiť ako FORMAT parameter).

=VIESAPI_VIES_DATA_PARSED("PL7171642051")

Ak potrebujete iba štatút spoločnosti vo VIES, použite nasledujúci dotaz:

=VIESAPI_VIES_DATA_PARSED("PL7171642051";"$(Valid)")

Ak je stav vrátenia Áno, znamená to, že spoločnosť má platné IČ DPH EÚ.

Značky dostupné v VIESAPI_VIES_DATA_PARSED funkciu, ktorú možno použiť ako FORMAT parameter:

• $(UID) – jedinečný identifikátor vygenerovaný službou viesApi.eu
• $(CountryCode) – predvoľba krajiny
• $(VATNumber) – európske IČ DPH
• $(Valid) – odpoveď zo služby VIES s informáciou o aktuálnom statuse DPH v EÚ kontrolovanej spoločnosti (Yes/No)
• $(TraderName) – názov spoločnosti
• $(TraderNameComponents.Name) – názov spoločnosti z traderName (bez právnej formy)
• $(TraderNameComponents.LegalForm) – názov právnej formy prevzatý z traderName (bez názvu spoločnosti)
• $(TraderNameComponents.LegalFormCanonicalId) – slovníkový identifikátor právnej formy
• $(TraderNameComponents.LegalFormCanonicalName) – slovníkový názov právnej formy
• $(TraderCompanyType) – typ podnikania
• $(TraderAddress) – adresa obchodníka, kde je spoločnosť registrovaná
• $(TraderAddressComponents.Country) – názov krajiny obchodníka v jej národnom jazyku
• $(TraderAddressComponents.PostalCode) – poštové smerovacie číslo adresy obchodníka
• $(TraderAddressComponents.City) – mesto adresy obchodníka
• $(TraderAddressComponents.Street) – ulica, kde sa nachádza adresa obchodníka
• $(TraderAddressComponents.StreetNumber) – číslo domu s adresou obchodníka
• $(TraderAddressComponents.HouseNumber) – číslo bytu/kancelárie podľa adresy obchodníka
• $(TraderAddressComponents.Other) – ďalšie údaje o adrese (názov oblasti, názov budovy, číslo poschodia atď.)
• $(ID) – jedinečný identifikátor vygenerovaný systémom VIES (konzultačné číslo)
• $(Date) – dátum vygenerovania odpovede
• $(Source) – zdroj údajov

Predvolený formát: "$(TraderName), $(TraderAddress)"

Ak reťazec "JSON" sa uvádza ako FORMAT parameter, funkcia vráti kompletný výsledok vo forme reťazca JSON, ktorý možno voľne analyzovať a ďalej spracovávať:

=VIESAPI_VIES_DATA_PARSED("PL7171642051";"JSON")

Kontrola stavu používateľského účtu (bezplatne)

VIESAPI_ACCOUNT_STATUS() – Funkcia vracia základné informácie o pláne aktuálne využívanom používateľom. Parametre by mali byť:

• (voliteľné) FORMAT vrátených údajov (pozri: Tagy, ktoré možno použiť ako FORMAT parameter)

=VIESAPI_ACCOUNT_STATUS()

Pozornosť! Volaním funkcie sa nezvýši počet uskutočnených dotazov.

Značky dostupné v VIESAPI_ACCOUNT_STATUS funkciu možno použiť ako FORMAT parameter:

• $(UID) – jedinečný identifikátor vygenerovaný službou viesApi.eu
• $(BillingPlanName) – názov aktuálneho plánu
• $(SubscriptionPrice) – mesačný poplatok za predplatné
• $(ItemPrice) – cena jedného dopytu mimo plánu
• $(ItemPriceStatus) – cena za dopyt – DPH/VIES/stav činnosti spoločnosti
• $(ItemPriceParsed) – cena za dopyt – DPH/VIES/stav činnosti spoločnosti s analyzovanými údajmi
• $(Limit) – maximálny počet dopytov v pláne
• $(RequestDelay) – minimálny časový interval medzi dopytmi
• $(DomainLimit) – maximálny počet domén (API kľúčov)
• $(OverPlanAllowed) – možnosť prekročiť maximálny počet dopytov v pláne
• $(ExcelAddIn) – prístup k doplnku Google Sheets™ a Microsoft Excel™
• $(Stats) – prístup k štatistikám dopytov
• $(NIPMonitor) – prístup k monitorovaniu statusu spoločností: DPH/VIES/status aktivity
• $(FuncGetVIESData) – prístup k funkciám, ktoré overujú stav spoločnosti v systéme VIES
• $(FuncGetVIESDataParsed) – prístup k funkciám, ktoré overujú status spoločnosti v systéme VIES a analyzujú meno a adresu obchodníka
• $(VIESDataCount) – počet dopytov VIES vykonaných v tomto mesiaci
• $(VIESDataParsedCount) – počet dopytov VIES s analyzovanými údajmi vykonaných v tomto mesiaci
• $(TotalCount) – celkový počet dopytov vykonaných v tomto mesiaci

Predvolený FORMÁT: "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)"

Ak reťazec "JSON" sa uvádza ako FORMAT parameter, funkcia vráti kompletný výsledok vo forme reťazca JSON, ktorý je možné voľne analyzovať a ďalej spracovávať.

Kontrola stavu systému VIES (bezplatne)

VIESAPI_VIES_STATUS() – Táto funkcia umožňuje overiť aktuálny stav systému VIES. Vracia celkový stav označujúci dostupnosť, ako aj zoznam jednotlivých členských krajín spolu s aktuálnym stavom dostupnosti ich národných systémov. Parametre by mali byť:

• (voliteľné) FORMAT vrátených údajov (pozri: Tagy, ktoré možno použiť ako FORMAT parameter)

=VIESAPI_VIES_STATUS()

Pozornosť! Volaním funkcie sa nezvýši počet uskutočnených dotazov.

Značky dostupné v VIESAPI_VIES_STATUS funkciu možno použiť ako FORMAT parameter:

• $(UID) – jedinečný identifikátor vygenerovaný službou viesApi.eu
• $(Available) – aktuálna dostupnosť systému VIES (Dostupný, Čiastočne dostupný, Nedostupný)
• $(Countries) – zoznam štátov jednotlivých členských krajín (Dostupné, Nedostupné)
• $(AT), $(FR), $(PL), etc. – stav dostupnosti konkrétnej členskej krajiny (ako hodnotu značky použite dvojpísmenný kód krajiny s veľkými písmenami)

Predvolený FORMÁT: "$(Available)"

Ak reťazec "JSON" sa uvádza ako FORMAT parameter, funkcia vráti kompletný výsledok vo forme reťazca JSON, ktorý je možné voľne analyzovať a ďalej spracovávať.

Ďalšie užitočné funkcie (zadarmo)

VIESAPI_ACCOUNT_STATUS_TOTAL() – Funkcia vracia informáciu o celkovom počte dopytov uskutočnených v aktuálnom fakturačnom mesiaci pre daný účet (všetky API kľúče). Vráti presne rovnaké číslo ako $(TotalCount) tag v VIESAPI_STATUS_ACCOUNT() funkciu.

VIESAPI_ACCOUNT_STATUS_LIMIT() – Funkcia vracia informácie o maximálnom počte dotazov dostupných v pláne zvolenom používateľom. Vráti presne rovnaké číslo ako $(Limit) označiť VIES.STATUS.ACCOUNT() funkciu

VIESAPI_EUVAT_NORM() – Táto funkcia opravuje a formátuje IČ DPH EÚ (odstraňuje medzery a spojovníky atď.) offline a nenačítava žiadne údaje z VIES:

=VIESAPI_EUVAT_NORM("PL 717-164-20-51")

VIESAPI_EUVAT_VALID() – Funkcia iba offline kontroluje správnosť (syntax, kontrolný súčet) IČ DPH EÚ a nenačítava žiadne údaje zo systému VIES. Návraty TRUE ak je číslo platné resp FALSE ak to nie je platné:

=VIESAPI_EUVAT_VALID("PL7171642051")

VIESAPI_CONNECTION_STATE() – Funkcia vráti aktuálny stav konfigurácie doplnku.

Ak funkcia vráti nasledujúcu hodnotu, okrem iného to znamená, že ID a API key neboli uložené:

ERROR: Connection requires configuration

Po uložení API ID a key, funkcia by mala vrátiť nasledujúcu správu:

SUCCESS: Production

Tabuľky Google™ sú ochrannou známkou spoločnosti Google LLC.