Excelov dodatek vam omogoča hitro in samodejno preverjanje subjektov (pogodbenikov) s pomočjo Excelove preglednice glede na njihov trenutni status v sistem VIES.

To poglavje vsebuje navodila za integracijo aplikacije Microsoft Excel s sistemom VIES API. Dodatek je bil uspešno preizkušen v naslednjih različicah programa MS Excel: 2007, 2010, 2013, 2016, 2019 (v operacijskih sistemih Windows in MacOS) in 2021 (v operacijskih sistemih Windows in MacOS) ter spletni različici programa Excel365.

Najnovejša različica dodatka za Excel 2007, 2010, 2013, 2016 in 2019 je vedno na voljo za prenos iz Stran za prenos. Dodatek je mogoče namestiti v 32-bitno in 64-bitno različico Excela. Pozor! Izberite različico (32- ali 64-bitno), ki jo ustreza različici Excela, ne operacijski sistem.

Če želite prenesti in namestiti dodatek za MacOS in Excel 2021 za Windows in Excel365, obiščite uradno Microsoftovo trgovino: https://appsource.microsoft.com.

Celotno delovanje dodatka Excel lahko preverite – brez potrebe po ustvarjanju računa – z uporabo priloženega Test API. Na strani je tudi opisano, kako konfigurirati dodatek Excel za uporabo v API-ju, ki je na voljo za testiranje.

Uporaba dodatka v proizvodnem API-ju zahteva nastavitev računa na spletni strani viesapi.eu, nakup minimalnega poslovnega načrta ter generiranje ključa in njegovega identifikatorja. Postopek registracije in nastavitve računa ter generiranja ključev je opisan na Dokumentacija Spletna stran.

Namestitev in konfiguracija za MS Excel 2021 in Excel 365 iz trgovine Microsoft Store (AppSource)

Namestitev

Po vstopu na spletno mesto Microsoftove uradne trgovine https://appsource.microsoft.com, kliknite na Get it now gumb.

Prikaže se okno za prijavo, v katerega morate vnesti e-poštni naslov, za katerega ste ustvarili račun pri Microsoftu (zasebni ali poslovni). Če takega računa nimate, ga lahko ustvarite in nadaljujete postopek namestitve ali pa zaustavite namestitev in uporabite možnost namestitve dodatka na enega od zgoraj opisanih načinov.

Če želite prenesti in namestiti dodatek iz programa Excel 2021 ali Excel 365 (splet), pojdite na Insert [1], poiščite razdelek Dodatki in kliknite OfficeAdd-ins [2] gumb. Nato v odprto okno vnesite besedo 'viesapi ′ [3] v iskalno polje in pritisnite ikono povečevalnega stekla. Dodatek, imenovan "VIES API - EU VAT Validation”, ki ga je treba namestiti s klikom na Add gumb [4]. Vsi zgornji koraki so prikazani na spodnjem posnetku zaslona:

Po kliku na Add gumb, se mora pojaviti zaslon, kjer lahko preberete licenčne pogoje in pravila o varovanju zasebnosti.

Za začetek namestitve dodatka pritisnite Continue gumb.

Konfiguracija

Po pravilni namestitvi vtičnika bi morali videti zaslon, podoben spodnjemu. V Home menu [1], poiščite ikono, ki predstavlja VIES API Panel [2] in kliknite nanj, da prikažete stransko ploščo. Takoj po namestitvi je dodatek konfiguriran za delo v testnem okolju – podrobnosti na Testna stran API. Uporaba dodatka v testnem načinu ne zahteva ustvarjanja računa na viesapi.eu Spletna stran.

Če želite preklopiti dodatek v produkcijsko okolje, kliknite na ID and key [3] in vnesite Key in ključ ID, ki ga najdete po prijavi v svoj račun na spletni strani viesapi.eu v razdelku »API Keys” zavihek. Po vnosu obeh vrednosti pritisnite Save gumb.

Če še nimate računa na naši spletni strani, kliknite povezavo na viesapi.eu [4] in pojdite skozi postopek registracije, ki je podrobno opisan na Dokumentacija strani.

Namestitev in konfiguracija za Excel: 2007, 2010, 2013, 2016 in 2019

Namestitev

Pridobite najnovejšo različico dodatka za Excel 2007, 2010, 2013, 2016 in 2019 iz Stran za prenos. Zaženite MS Excel in pojdite na File> Options, nato izberite Add-ins [1] iz menija.

Na dnu nastavitev izberite Excel Add-ins [2] in kliknite Go [3] gumb.

Napredni uporabniki lahko dodajo dodatek iz Developer zavihek [1], nato kliknite Excel Add-ins [2] in kliknite Browse [3] gumb:

V Add-ins oknu kliknite Browse gumb, pojdite v imenik, kjer je viesapi-ms-excel-addin-version-number.zip datoteka je bila razpakirana in izberite:

• viesapiExcel.xll – za 32-bitno različico Excela,
• viesapiExcel64.xll – za 64-bitno različico Excela.

Pravilno nalaganje dodatka je prikazano na spodnji sliki [1].

Dovolj je klikniti na OK gumb [2], da omogočite funkcije, implementirane v dodatku, na voljo v Excelu.

Konfiguracija

Po namestitvi je vtičnik privzeto nastavljen na testno okolje (več podrobnosti na Test API stran). Za možnost priklica funkcij v produkcijskem okolju je potrebno enkrat konfigurirati dostop do spletne strani viesapi.eu. Če želite to narediti, pojdite na katero koli Excelovo preglednico in izvedite funkcijo:

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

kjer so parametri funkcije:

• identifier – parameter naj vsebuje identifikator (ID), generiran na računu na spletni strani viesapi.eu,
• key – parameter naj vsebuje Ključ, ustvarjen na računu na spletni strani viesapi.eu.

Podrobnosti o generiranju identifikatorja in ključa so opisane na Dokumentacija Spletna stran.

Za preverjanje pravilnosti povezave z danim API (testnim ali produkcijskim) je treba izvesti naslednjo funkcijo:

=VIESAPI.CONNECT.STATUS()

Ki lahko vrne vrednosti:

• SUCCESS: Production – če je dodatek pravilno konfiguriran za delo s produkcijskim okoljem,
• SUCCESS: Test – če je dodatek pravilno konfiguriran za delo z testno okolje,

• ERROR: Connection requires configuration – v primeru napačne konfiguracije.

Privzeto je vsak Excelov dokument nastavljen tako, da samodejno izračuna preglednico. Nastavitev te možnosti pomeni, da se vse formule kličejo, ko se izvedejo spremembe, ki vplivajo na formulo. Primer tega je brisanje vrstice na delovnem listu.

Da bi se izognili samodejnemu priklicu vseh funkcij, definiranih v danem listu, ki je povezan s samodejnim pošiljanjem poizvedb v API spletnega mesta veisapi.eu, spremenite možnost izračuna delovnega zvezka na Ročno:

1. Iz File meni, izberite Options
2. Označite Formulas zavihek
3. V razdelku Možnosti izračuna izberite nastavitev: Manual in odkljukajte dodatna možnost: Recalculate the workbook before saving.
4. Spremembe, narejene na listu, je treba shraniti.

Pri tako nastavljeni Excelovi preglednici za prisilno osvežitev vseh definiranih formul pritisnite kombinacijo tipk:

CTRL + ALT + SHIFT + F9

Posodobite vtičnik na najnovejšo različico

Pozor!Naslednji postopek za posodobitev dodatka Excel deluje pravilno za različice MS Excel 2019, 2021 in Excel 365, kjer lahko dodatek namestite iz trgovine Microsoft Store.

Pozor! Po namestitvi zadnje različice morate dodatek na novo konfigurirati, torej vnesti in shraniti ID in ključ.

Če želite namestiti najnovejšo različico dodatka Excel, sledite tem korakom:

1. Preverite različico nameščenega dodatka s klicem formule =VIESAPI.VERSION(). Najnovejša različica dodatka je 1.2.8

2. Čiščenje predpomnilnika MS Excel po postopku, opisanem na uradni dokumentacijski strani: https://learn.microsoft.com/en-us/office/dev/add-ins/testing/clear-cache

3. Po zaključku vseh korakov iz točke 2 ponovno zaženite aplikacijo MS Excel.

4. Med ponovnim zagonom bo aplikacija MS Excel prenesla najnovejšo različico dodatka iz trgovine Microsoft Store.

5. Konfigurirajte dodatek tako, da vnesete ID in ključ, ki ste ga prenesli po prijavi v svoj račun na našem Spletna stran – zavihek »Ključi API«.

Uporaba

Oglejte si, kako samodejno in množično preverite EU DDV status podjetij v sistemu VIES z uporabo našega dodatka za Excel:

Pred uporabo dodatka se morate seznaniti s posebnostmi njegovega delovanja:

• Vsi klici funkcij se izvajajo v asinhronem načinu, ki ne povzroča učinka zamrznitve (brez odziva) aplikacije Excel.
• Dodajanje (vstavljanje) vrstice ali stolpca ne osveži vseh definiranih klicev funkcij.
• Kopiranje ali premikanje celic, ki vsebujejo funkcije, ne osveži definiranih klicev funkcij.
• Če izbrišete vrstico ali stolpec, se osvežijo vsi definirani klici funkcij in pošljejo poizvedbe na viesApi.eu (samo v primeru privzetih nastavitev Excela). Opis spreminjanja privzetih nastavitev je vključen v poglavju Konfiguracija.
• Pozor! Ni priporočljivo izvajati več kot 500 vzporednih poizvedb, ker ima Excel težave z obravnavanjem velikega števila asinhronih klicev.

Pridobite podatke o podjetju iz VIES

VIESAPI.VIES.DATA() – Funkcija pridobi vse razpoložljive podatke podjetja neposredno iz sistema VIES. Parametri bi morali biti:

• evropska davčna številka (VAT EU),
• (neobvezno) FORMAT vrnjenih podatkov (glejte: Oznake, ki jih je mogoče uporabiti kot FORMAT parameter).

=VIESAPI.VIES.DATA("PL7171642051")

Če potrebujete le status podjetja v VIES, uporabite naslednjo poizvedbo:

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

Če je vrnjeni status Da, to pomeni, da ima podjetje veljavno EU številko za DDV.

Oznake, ki so na voljo v VIESAPI.VIES.DATA funkcijo, ki se lahko uporablja kot FORMAT parameter:

• $(UID) – enolični identifikator, ki ga ustvari storitev viesApi.eu
• $(CountryCode) – koda države
• $(VATNumber) – evropska številka za DDV
• $(Valid) – odgovor storitve VIES, ki obvešča o trenutnem statusu DDV v EU preverjenega podjetja (Yes/No)
• $(TraderName) – ime podjetja v registraciji
• $(TraderCompanyType) – vrsta poslovanja
• $(TraderAddress) – naslov trgovca, kjer je podjetje registrirano
• $(ID) – edinstveni identifikator, ki ga ustvari sistem VIES (posvetovalna številka)
• $(Date) – datum, ko je bil odgovor ustvarjen
• $(Source) – vir podatkov

Privzeti format: "$(TraderName), $(TraderAddress)"

Če niz "JSON" je podan kot FORMAT bo funkcija vrnila celoten rezultat v obliki niza JSON, ki ga je mogoče prosto razčleniti in nadalje obdelati:

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

Pridobite razčlenjene podatke podjetja iz VIES

VIESAPI.VIES.DATA.PARSED() – Funkcija pridobi vse razpoložljive podatke o podjetju neposredno iz sistema VIES. Poleg tega se ime in naslov podjetja vrneta kot razčlenjeni podatki, razdeljeni v ločene atribute. Parametri naj bodo:

• evropska davčna številka (VAT EU),
• (neobvezno) FORMAT vrnjenih podatkov (glejte: Oznake, ki jih je mogoče uporabiti kot FORMAT parameter).

=VIESAPI.VIES.DATA.PARSED("PL7171642051")

Če potrebujete le status podjetja v VIES, uporabite naslednjo poizvedbo:

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

Če je vrnjeni status Da, to pomeni, da ima podjetje veljavno EU številko za DDV.

Oznake, ki so na voljo v VIESAPI.VIES.DATA.PARSED funkcijo, ki se lahko uporablja kot FORMAT parameter:

• $(UID) – enolični identifikator, ki ga ustvari storitev viesApi.eu
• $(CountryCode) – koda države
• $(VATNumber) – evropska številka za DDV
• $(Valid) – odgovor storitve VIES, ki obvešča o trenutnem statusu DDV v EU preverjenega podjetja (Yes/No)
• $(TraderName) – ime podjetja v registraciji
• $(TraderNameComponents.Name) – ime podjetja iz traderName (brez pravne oblike)
• $(TraderNameComponents.LegalForm) – ime pravne oblike, pridobljeno iz traderName (brez imena podjetja)
• $(TraderNameComponents.LegalFormCanonicalId) – slovarski identifikator pravne oblike
• $(TraderNameComponents.LegalFormCanonicalName) – slovarsko ime pravne oblike
• $(TraderCompanyType) – vrsta poslovanja
• $(TraderAddress) – naslov trgovca, kjer je podjetje registrirano
• $(TraderAddressComponents.Country) – ime države trgovca v njenem nacionalnem jeziku
• $(TraderAddressComponents.PostalCode) – poštna številka naslova trgovca
• $(TraderAddressComponents.City) – mesto, kjer je trgovec naveden
• $(TraderAddressComponents.Street) – ulica, kjer je trgovec na naslovu
• $(TraderAddressComponents.StreetNumber) – hišna številka ulice, na kateri je trgovec naveden
• $(TraderAddressComponents.HouseNumber) – številka stanovanja/pisarne na naslovu trgovca
• $(TraderAddressComponents.Other) – drugi podatki o naslovu (ime območja, ime stavbe, številka nadstropja itd.)
• $(ID) – edinstveni identifikator, ki ga ustvari sistem VIES (posvetovalna številka)
• $(Date) – datum, ko je bil odgovor ustvarjen
• $(Source) – vir podatkov

Privzeti format: "$(TraderName), $(TraderAddress)"

Če niz "JSON" je podan kot FORMAT bo funkcija vrnila celoten rezultat v obliki niza JSON, ki ga je mogoče prosto razčleniti in nadalje obdelati:

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

Preverjanje stanja uporabniškega računa (brezplačno)

VIESAPI.ACCOUNT.STATUS() – Funkcija vrne osnovne informacije o načrtu, ki ga trenutno uporablja uporabnik. Parametri bi morali biti:

• (neobvezno) FORMAT vrnjenih podatkov (glejte: Oznake, ki jih je mogoče uporabiti kot FORMAT parameter)

=VIESAPI.ACCOUNT.STATUS()

Pozor! Klic funkcije ne poveča števila izvedenih poizvedb.

Oznake, ki so na voljo v VIESAPI.ACCOUNT.STATUS funkcijo lahko uporabite kot FORMAT parameter:

• $(UID) – enolični identifikator, ki ga ustvari storitev viesApi.eu
• $(BillingPlanName) – ime trenutnega načrta
• $(SubscriptionPrice) – mesečna naročnina
• $(ItemPrice) – stroški posameznega povpraševanja zunaj paketa
• $(ItemPriceStatus) – cena na poizvedbo – DDV/VIES/status dejavnosti podjetja
• $(ItemPriceParsed) – cena na poizvedbo – DDV/VIES/status dejavnosti podjetja z razčlenjenimi podatki
• $(Limit) – največje število poizvedb v načrtu
• $(RequestDelay) – minimalni časovni interval med poizvedbami
• $(DomainLimit) – največje število domen (API ključev)
• $(OverPlanAllowed) – možnost prekoračitve največjega števila poizvedb v načrtu
• $(ExcelAddIn) – dostop do dodatka za MS Excel
• $(Stats) – dostop do statistike poizvedb
• $(NIPMonitor) – dostop do spremljanja statusa podjetij: DDV/VIES/status dejavnosti
• $(FuncGetVIESData) – dostop do funkcij, ki preverjajo status podjetja v sistemu VIES
• $(FuncGetVIESDataParsed) – dostop do funkcij, ki preverjajo status podjetja v sistemu VIES in analizirajo ime in naslov trgovca
• $(VIESDataCount) – število poizvedb VIES, opravljenih ta mesec
• $(VIESDataParsedCount) – število poizvedb VIES z razčlenjenimi podatki, opravljenih ta mesec
• $(TotalCount) – skupno število poizvedb, opravljenih ta mesec

Privzeti FORMAT: "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)"

Če niz "JSON" je podan kot FORMAT bo funkcija vrnila celoten rezultat v obliki niza JSON, ki ga je mogoče prosto razčleniti in nadalje obdelati.

Preverjanje stanja sistema VIES (brezplačno)

VIESAPI.VIES.STATUS() – Ta funkcija vam omogoča preverjanje trenutnega stanja sistema VIES. Vrne splošno stanje, ki označuje razpoložljivost, ter seznam posameznih držav članic skupaj s trenutnim stanjem razpoložljivosti njihovih nacionalnih sistemov. Parametri morajo biti:

• (neobvezno) FORMAT vrnjenih podatkov (glejte: Oznake, ki jih je mogoče uporabiti kot FORMAT parameter)

=VIESAPI.VIES.STATUS()

Pozor! Klic funkcije ne poveča števila izvedenih poizvedb.

Oznake, ki so na voljo v VIESAPI.VIES.STATUS funkcijo lahko uporabite kot FORMAT parameter:

• $(UID) – enolični identifikator, ki ga ustvari storitev viesApi.eu
• $(Available) – trenutna razpoložljivost sistema VIES (Na voljo, Delno na voljo, Ni na voljo)
• $(Countries) – seznam posameznih držav članic (Na voljo, Ni na voljo)
• $(AT), $(FR), $(PL), etc. – status razpoložljivosti določene države članice (kot vrednost oznake uporabite dvočrkovno kodo države z velikimi črkami)

Privzeti FORMAT: "$(Available)"

Če niz "JSON" je podan kot FORMAT bo funkcija vrnila celoten rezultat v obliki niza JSON, ki ga je mogoče prosto razčleniti in nadalje obdelati.

Druge uporabne funkcije (brezplačno)

VIESAPI.ACCOUNT.STATUS.TOTAL() – Funkcija vrne podatke o skupnem številu poizvedb v tekočem obračunskem mesecu za dani račun (vsi API ključi). Vrne popolnoma enako število kot $(TotalCount) oznako v VIESAPI.STATUS.ACCOUNT() funkcijo.

VIESAPI.ACCOUNT.STATUS.LIMIT() – Funkcija vrne informacije o največjem številu poizvedb, ki so na voljo v načrtu, ki ga izbere uporabnik. Vrne popolnoma enako število kot $(Limit) označite VIES.STATUS.ACCOUNT() funkcijo

VIESAPI.EUVAT.NORM() – Ta funkcija popravi in oblikuje EU številko DDV (odstrani presledke in vezaje itd.) brez povezave in ne pridobi nobenih podatkov iz VIES:

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

VIESAPI.EUVAT.VALID() – Funkcija samo preveri pravilnost (sintakso, kontrolno vsoto) številke EU za DDV brez povezave in ne pridobi nobenih podatkov iz sistema VIES. Vračila TRUE če je številka veljavna oz FALSE če ne velja:

=VIESAPI.EUVAT.VALID("PL7171642051")

VIESAPI.CONNECTION.STATE() – Funkcija vrne trenutno stanje konfiguracije dodatka.

Če funkcija vrne naslednjo vrednost, to med drugim pomeni, da je ID in API key niso bili shranjeni:

ERROR: Connection requires configuration

Po shranjevanju API ID in key, mora funkcija vrniti naslednje sporočilo:

SUCCESS: Production