Excel dodatak vam omogućuje brzu i automatsku provjeru subjekata (izvođača) pomoću proračunske tablice programa Excel u smislu njihovog trenutnog statusa u VIES sustav.

Ovo poglavlje sadrži upute o integraciji aplikacije Microsoft Excel s VIES API sustavom. Dodatak je uspješno testiran u sljedećim verzijama MS Excela: 2007, 2010, 2013, 2016, 2019 (na operativnim sustavima Windows i MacOS) i 2021 (na operativnim sustavima Windows i MacOS) te web verziji Excela365.

Najnovija verzija dodatka za Excel 2007, 2010, 2013, 2016 i 2019 uvijek je dostupna za preuzimanje s Stranica za preuzimanje. Dodatak se može instalirati u 32-bitnu i 64-bitnu verziju programa Excel. Pažnja! Odaberite verziju (32 ili 64 bitnu) koja odgovara verziji programa Excel, a ne operativni sustav.

Za preuzimanje i instaliranje dodatka za MacOS i Excel 2021 za Windows i Excel365 posjetite službenu Microsoftovu trgovinu: https://appsource.microsoft.com.

Punu funkcionalnost Excel dodatka možete provjeriti – bez potrebe za kreiranjem računa – korištenjem predviđenog Test API. Stranica također opisuje kako konfigurirati Excel dodatak za korištenje u API-ju predviđenom za testiranje.

Korištenje dodatka u proizvodnom API-ju zahtijeva postavljanje računa na web stranici viesapi.eu, kupnju minimalnog poslovnog plana i generiranje ključa i njegovog identifikatora. Proces registracije i postavljanja računa kao i generiranja ključeva opisan je na Dokumentacija web stranica.

Instalacija i konfiguracija za MS Excel 2021 i Excel 365 iz Microsoft Store (AppSource)

Montaža

Nakon ulaska na web mjesto Microsoft Official Store https://appsource.microsoft.com, kliknite na Get it now dugme.

Prikazat će se prozor za prijavu u koji morate unijeti adresu e-pošte za koju ste kreirali račun kod Microsofta (privatni ili korporativni). Ukoliko nemate takav račun, možete ga kreirati i nastaviti proces instalacije ili zaustaviti instalaciju i koristiti opciju instaliranja dodatka na jedan od gore opisanih načina.

Da biste preuzeli i instalirali dodatak iz programa Excel 2021 ili Excel 365 (web), idite na Insert [1], pronađite odjeljak Dodaci i kliknite OfficeAdd-ins [2] gumb. Zatim u otvoreni prozor upišite riječ 'viesapi ′ [3] u polje za pretraživanje i pritisnite ikonu povećala. Dodatak pod nazivom "VIES API - EU VAT Validation” treba pronaći koju treba instalirati klikom na Add gumb [4]. Svi gornji koraci ilustrirani su na snimci zaslona u nastavku:

Nakon klika na Add gumb, trebao bi se pojaviti zaslon na kojem možete pročitati licencne uvjete i pravila zaštite privatnosti.

Za početak instalacije dodatka pritisnite Continue dugme.

Konfiguracija

Nakon što ispravno instalirate dodatak, trebali biste vidjeti ekran sličan onom prikazanom u nastavku. u Home menu [1], pronađite ikonu koja predstavlja VIES API Panel [2] i kliknite na njega za prikaz bočne ploče. Odmah nakon instalacije, dodatak je konfiguriran za rad u testnom okruženju – pojedinosti na Testirajte API stranicu. Korištenje dodatka u testnom načinu ne zahtijeva stvaranje računa na viesapi.eu web stranica.

Kako biste prebacili dodatak u produkcijsko okruženje, kliknite na ID and key [3] karticu i unesite Key i ključ ID, koje možete pronaći nakon što se prijavite na svoj račun na web stranici viesapi.eu u rubrici “API Keys” kartica. Nakon unosa obje vrijednosti, pritisnite Save dugme.

Ako još nemate račun na našoj web stranici, kliknite na poveznicu na viesapi.eu [4] i proći kroz postupak registracije, koji je detaljno opisan na Dokumentacija stranica.

Instalacija i konfiguracija za Excel: 2007, 2010, 2013, 2016 i 2019

Montaža

Nabavite najnoviju verziju dodatka za Excel 2007, 2010, 2013, 2016 i 2019 od Stranica za preuzimanje. Pokrenite MS Excel i idite na File> Options, zatim odaberite Add-ins [1] iz izbornika.

Na dnu postavki odaberite Excel Add-ins [2] i kliknite na Go [3] gumb.

Napredni korisnici mogu dodati dodatak iz Developer karticu [1], zatim kliknite Excel Add-ins [2] i kliknite na Browse [3] gumb:

u Add-ins prozor, kliknite na Browse gumb, idite u imenik u kojem je viesapi-ms-excel-addin-version-number.zip datoteka je raspakirana i odaberite:

• viesapiExcel.xll – za 32-bitnu verziju programa Excel,
• viesapiExcel64.xll – za 64-bitnu verziju programa Excel.

Ispravno učitavanje dodatka prikazano je na donjoj slici [1].

Dovoljno je kliknuti na OK gumb [2] kako bi funkcije implementirane u dodatku bile dostupne u Excelu.

Konfiguracija

Nakon instalacije, dodatak je prema zadanim postavkama postavljen na testno okruženje (više detalja na Test API stranica). Kako biste mogli pozivati funkcije u produkcijskom okruženju, potrebno je jednom konfigurirati pristup web stranici viesapi.eu. Da biste to učinili, idite na bilo koju Excel proračunsku tablicu i izvršite funkciju:

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

gdje su parametri funkcije:

• identifier – parametar treba sadržavati identifikator (ID) generiran na računu na web stranici viesapi.eu,
• key – parametar treba sadržavati Ključ generiran na računu na web stranici viesapi.eu.

Pojedinosti o generiranju identifikatora i ključa opisane su na Dokumentacija web stranica.

Kako bi se provjerila ispravnost veze s određenim API-jem (testnim ili proizvodnim), treba izvršiti sljedeću funkciju:

=VIESAPI.CONNECT.STATUS()

Koji može vratiti vrijednosti:

• SUCCESS: Production – ako je dodatak ispravno konfiguriran za rad s proizvodnim okruženjem,
• SUCCESS: Test – ako je dodatak ispravno konfiguriran za rad s testno okruženje,

• ERROR: Connection requires configuration – u slučaju pogrešne konfiguracije.

Prema zadanim postavkama, svaki Excel dokument postavljen je za automatski izračun proračunske tablice. Postavljanje ove opcije podrazumijeva da se sve formule pozivaju kada se naprave promjene koje utječu na formulu. Primjer za to je brisanje retka na radnom listu.

Kako biste izbjegli automatsko pozivanje svih funkcija definiranih u određenom listu, a koje se odnosi na automatsko slanje upita API-ju web stranice veisapi.eu, promijenite opciju izračuna radne knjige na Ručno:

1. Od File izbornik, Odaberi Options
2. Istaknite Formulas tab
3. U odjeljku Mogućnosti izračuna odaberite postavku: Manual i odznačiti dodatna opcija: Recalculate the workbook before saving.
4. Potrebno je pohraniti promjene napravljene u listu.

S tako konfiguriranom Excel proračunskom tablicom, za prisilno osvježavanje svih definiranih formula pritisnite kombinaciju tipki:

CTRL + ALT + SHIFT + F9

Ažurirajte dodatak na najnoviju verziju

Pažnja!Sljedeći postupak za ažuriranje dodatka Excel radi ispravno za verzije MS Excel 2019, 2021 i Excel 365, gdje se dodatak može instalirati iz Microsoft Storea.

Pažnja! Nakon instalacije zadnje verzije potrebno je rekonfigurirati dodatak, odnosno unijeti i spremiti ID i ključ.

Da biste instalirali najnoviju verziju dodatka za Excel, slijedite ove korake:

1. Provjerite verziju instaliranog dodatka pozivanjem formule =VIESAPI.VERSION(). Najnovija verzija dodatka je 1.2.8

2. Brisanje MS Excel predmemorije, prema postupku opisanom na stranici službene dokumentacije: https://learn.microsoft.com/en-us/office/dev/add-ins/testing/clear-cache

3. Nakon završetka svih koraka iz točke 2. ponovno pokrenite MS Excel aplikaciju.

4. Tijekom ponovnog pokretanja, aplikacija MS Excel će preuzeti najnoviju verziju dodatka iz Microsoft Storea.

5. Konfigurirajte dodatak unosom ID-a i ključa preuzetog nakon prijave na svoj račun na našem web stranica – Kartica „Ključevi API-ja”.

Korištenje

Pogledajte kako automatski i masovno provjeriti EU PDV status tvrtki u VIES sustavu pomoću našeg Excel dodatka:

Prije korištenja dodatka, trebali biste se upoznati sa specifičnostima njegovog rada:

• Svi pozivi funkcija izvršavaju se u asinkronom načinu, koji ne uzrokuje efekt zamrzavanja (bez odgovora) Excel aplikacije.
• Dodavanje (umetanje) retka ili stupca ne osvježava sve definirane pozive funkcija.
• Kopiranje ili premještanje ćelija koje sadrže funkcije ne osvježavaju definirane pozive funkcija.
• Brisanje retka ili stupca osvježit će sve definirane pozive funkcija i poslati upite na viesApi.eu (samo u slučaju zadanih postavki programa Excel). Opis promjene zadanih postavki nalazi se u poglavlju Konfiguracija.
• Pažnja! Ne preporučuje se pokretanje više od 500 paralelnih upita jer Excel ima problema s rukovanjem velikim brojem asinkronih poziva.

Dobijte podatke o tvrtki iz VIES-a

VIESAPI.VIES.DATA() – Funkcija dohvaća sve dostupne podatke tvrtke izravno iz VIES sustava. Parametri bi trebali biti:

• Europski porezni identifikacijski broj (PDV EU),
• (neobavezno) FORMAT vraćenih podataka (pogledajte: Oznake koje se mogu koristiti kao FORMAT parametar).

=VIESAPI.VIES.DATA("PL7171642051")

Ako trebate samo status tvrtke u VIES-u, koristite sljedeći upit:

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

Ako je vraćeni status Da, to znači da tvrtka ima važeći EU PDV broj.

Oznake dostupne u VIESAPI.VIES.DATA funkcija koja se može koristiti kao FORMAT parametar:

• $(UID) – jedinstveni identifikator koji generira usluga viesApi.eu
• $(CountryCode) – pozivni broj države
• $(VATNumber) – europski PDV broj
• $(Valid) – odgovor VIES servisa s obavijesti o trenutnom statusu PDV-a provjerene tvrtke u EU (Yes/No)
• $(TraderName) – naziv tvrtke za registraciju
• $(TraderCompanyType) – vrsta poslovanja
• $(TraderAddress) – adresu trgovca na kojoj je tvrtka registrirana
• $(ID) – jedinstveni identifikator koji generira VIES sustav (konzultacijski broj)
• $(Date) – datum kada je odgovor generiran
• $(Source) – izvor podataka

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

Ako niz "JSON" daje se kao FORMAT parametar, funkcija će vratiti potpuni rezultat u obliku JSON niza, koji se može slobodno analizirati i dalje obrađivati:

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

Dobijte parsirane podatke tvrtke iz VIES-a

VIESAPI.VIES.DATA.PARSED() – Funkcija dohvaća sve dostupne podatke o tvrtki izravno iz VIES sustava. Osim toga, naziv i adresa tvrtke vraćaju se kao raščlanjeni podaci podijeljeni u zasebne atribute. Parametri bi trebali biti:

• Europski porezni identifikacijski broj (PDV EU),
• (neobavezno) FORMAT vraćenih podataka (pogledajte: Oznake koje se mogu koristiti kao FORMAT parametar).

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

Ako trebate samo status tvrtke u VIES-u, koristite sljedeći upit:

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

Ako je vraćeni status Da, to znači da tvrtka ima važeći EU PDV broj.

Oznake dostupne u VIESAPI.VIES.DATA.PARSED funkcija koja se može koristiti kao FORMAT parametar:

• $(UID) – jedinstveni identifikator koji generira usluga viesApi.eu
• $(CountryCode) – pozivni broj države
• $(VATNumber) – europski PDV broj
• $(Valid) – odgovor VIES servisa s obavijesti o trenutnom statusu PDV-a provjerene tvrtke u EU (Yes/No)
• $(TraderName) – naziv tvrtke za registraciju
• $(TraderNameComponents.Name) – naziv tvrtke iz traderName (bez pravnog oblika)
• $(TraderNameComponents.LegalForm) – naziv pravnog oblika preuzet iz naziva trgovca (bez naziva tvrtke)
• $(TraderNameComponents.LegalFormCanonicalId) – rječnički identifikator pravnog oblika
• $(TraderNameComponents.LegalFormCanonicalName) – rječnički naziv pravnog oblika
• $(TraderCompanyType) – vrsta poslovanja
• $(TraderAddress) – adresu trgovca na kojoj je tvrtka registrirana
• $(TraderAddressComponents.Country) – naziv zemlje trgovca na njenom nacionalnom jeziku
• $(TraderAddressComponents.PostalCode) – poštanski broj adrese trgovca
• $(TraderAddressComponents.City) – grad u kojem se nalazi adresa trgovca
• $(TraderAddressComponents.Street) – ulica na kojoj se nalazi adresa trgovca
• $(TraderAddressComponents.StreetNumber) – broj zgrade na kojoj se nalazi adresa trgovca
• $(TraderAddressComponents.HouseNumber) – broj stana/ureda na adresi trgovca
• $(TraderAddressComponents.Other) – ostali podaci o adresi (naziv područja, naziv zgrade, broj kata itd.)
• $(ID) – jedinstveni identifikator koji generira VIES sustav (konzultacijski broj)
• $(Date) – datum kada je odgovor generiran
• $(Source) – izvor podataka

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

Ako niz "JSON" daje se kao FORMAT parametar, funkcija će vratiti potpuni rezultat u obliku JSON niza, koji se može slobodno analizirati i dalje obrađivati:

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

Provjera statusa korisničkog računa (besplatno)

VIESAPI.ACCOUNT.STATUS() – Funkcija vraća osnovne informacije o planu koji korisnik trenutno koristi. Parametri bi trebali biti:

• (neobavezno) FORMAT vraćenih podataka (pogledajte: Oznake koje se mogu koristiti kao FORMAT parametar)

=VIESAPI.ACCOUNT.STATUS()

Pažnja! Pozivanje funkcije ne povećava broj postavljenih upita.

Oznake dostupne u VIESAPI.ACCOUNT.STATUS funkcija se može koristiti kao FORMAT parametar:

• $(UID) – jedinstveni identifikator koji generira usluga viesApi.eu
• $(BillingPlanName) – naziv trenutnog plana
• $(SubscriptionPrice) – mjesečna pretplata
• $(ItemPrice) – cijena jednog upita izvan plana
• $(ItemPriceStatus) – cijena po upitu – PDV/VIES/Status aktivnosti tvrtke
• $(ItemPriceParsed) – cijena po upitu – PDV/VIES/Status aktivnosti tvrtke s parsiranim podacima
• $(Limit) – maksimalan broj upita u planu
• $(RequestDelay) – minimalni vremenski interval između upita
• $(DomainLimit) – maksimalan broj domena (API ključeva)
• $(OverPlanAllowed) – mogućnost prekoračenja maksimalnog broja upita u planu
• $(ExcelAddIn) – pristup dodatku za MS Excel
• $(Stats) – pristup statistikama upita
• $(NIPMonitor) – pristup praćenju statusa tvrtki: PDV/VIES/Status aktivnosti
• $(FuncGetVIESData) – pristup funkcijama koje provjeravaju status tvrtke u VIES sustavu
• $(FuncGetVIESDataParsed) – pristup funkcijama koje provjeravaju status tvrtke u VIES sustavu i analiziraju ime i adresu trgovca
• $(VIESDataCount) – broj VIES upita izvršenih ovog mjeseca
• $(VIESDataParsedCount) – broj VIES upita s parsiranim podacima izvršenih ovog mjeseca
• $(TotalCount) – ukupan broj upita izvršenih ovog mjeseca

Zadani 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)"

Ako niz "JSON" daje se kao FORMAT parametar, funkcija će vratiti potpuni rezultat u obliku JSON niza, koji se može slobodno analizirati i dalje obrađivati.

Provjera statusa VIES sustava (besplatno)

VIESAPI.VIES.STATUS() – Ova funkcija vam omogućuje provjeru trenutnog statusa VIES sustava. Vraća opći status koji pokazuje dostupnost, kao i popis pojedinačnih zemalja članica zajedno s trenutnim statusom dostupnosti njihovih nacionalnih sustava. Parametri bi trebali biti:

• (neobavezno) FORMAT vraćenih podataka (pogledajte: Oznake koje se mogu koristiti kao FORMAT parametar)

=VIESAPI.VIES.STATUS()

Pažnja! Pozivanje funkcije ne povećava broj postavljenih upita.

Oznake dostupne u VIESAPI.VIES.STATUS funkcija se može koristiti kao FORMAT parametar:

• $(UID) – jedinstveni identifikator koji generira usluga viesApi.eu
• $(Available) – trenutna dostupnost VIES sustava (Dostupno, Djelomično dostupno, Nedostupno)
• $(Countries) – popis država pojedinih zemalja članica (Dostupno, Nedostupno)
• $(AT), $(FR), $(PL), etc. – status dostupnosti određene zemlje članice (kao vrijednost oznake koristite dvoslovni veliki kod zemlje)

Zadani FORMAT: "$(Available)"

Ako niz "JSON" daje se kao FORMAT parametar, funkcija će vratiti potpuni rezultat u obliku JSON niza, koji se može slobodno analizirati i dalje obrađivati.

Ostale korisne funkcije (besplatno)

VIESAPI.ACCOUNT.STATUS.TOTAL() – Funkcija vraća podatke o ukupnom broju upita napravljenih u tekućem obračunskom mjesecu za određeni račun (svi API ključevi). Vraća potpuno isti broj kao $(TotalCount) oznaka u VIESAPI.STATUS.ACCOUNT() funkcija.

VIESAPI.ACCOUNT.STATUS.LIMIT() – Funkcija vraća informacije o maksimalnom broju dostupnih upita u planu koji je odabrao korisnik. Vraća potpuno isti broj kao $(Limit) označiti VIES.STATUS.ACCOUNT() funkcija

VIESAPI.EUVAT.NORM() – Ova značajka ispravlja i formatira EU PDV broj (uklanja razmake i crtice itd.) izvan mreže i ne dohvaća nikakve podatke iz VIES-a:

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

VIESAPI.EUVAT.VALID() – Funkcija samo provjerava ispravnost (sintaksu, kontrolni zbroj) EU PDV broja offline i ne dohvaća nikakve podatke iz VIES sustava. Povratak TRUE ako broj vrijedi ili FALSE ako ne vrijedi:

=VIESAPI.EUVAT.VALID("PL7171642051")

VIESAPI.CONNECTION.STATE() – Funkcija vraća trenutni status konfiguracije dodatka.

Ako funkcija vrati sljedeću vrijednost, to između ostalog znači da je ID i API key nisu spremljeni:

ERROR: Connection requires configuration

Nakon spremanja API ID i key, funkcija bi trebala vratiti sljedeću poruku:

SUCCESS: Production