Excel-apuohjelman avulla voit nopeasti ja automaattisesti tarkistaa entiteetit (urakoitsijat) Excel-laskentataulukon avulla niiden nykyisen tilan suhteen VIES-järjestelmä.

Tämä luku sisältää ohjeet Microsoft Excel -sovelluksen integroimiseksi nip24.pl-järjestelmään. Mukana toimitettu apuohjelma on testattu onnistuneesti seuraavissa MS Excelin versioissa: 2007, 2010, 2013, 2016, 2019 (Windows- ja MacOS-käyttöjärjestelmissä) ja 2021 (Windows- ja MacOS-käyttöjärjestelmissä) sekä verkkoversio Excel365:stä.

Excel 2007, 2010, 2013, 2016 ja 2019 lisäosan uusin versio on aina ladattavissa osoitteesta Lataa sivu. Lisäosa voidaan asentaa sekä 32- että 64-bittisiin Excelin versioihin. Huomio! Valitse versio (32- tai 64-bittinen). vastaa Excelin versiota, ei käyttöjärjestelmää.

Voit ladata ja asentaa lisäosan MacOS:lle ja Excel 2021:lle Windowsille ja Excel365:lle käymällä virallisessa Microsoft Storessa: https://appsource.microsoft.com.

Excel-apuohjelman koko toiminnallisuus voidaan tarkistaa – ilman tarvetta luoda tiliä – käyttämällä tarjottua Testaa API. Sivulla kuvataan myös, kuinka Excel-apuohjelma määritetään käytettäväksi testausta varten tarkoitetussa API:ssa.

Apuohjelman käyttö tuotantosovellusliittymässä edellyttää tilin luomista viesapi.eu-verkkosivustolle, vähintään Liiketoimintasuunnitelman ostamista sekä avaimen ja sen tunnuksen generoimista. Tilin rekisteröinti- ja perustamisprosessi sekä avainten luonti on kuvattu sivulla Dokumentointi verkkosivusto.

Asennus ja konfigurointi MS Excel 2021:lle ja Excel 365:lle Microsoft Storesta (AppSource)

Asennus

Kun olet siirtynyt Microsoftin viralliselle verkkosivustolle https://appsource.microsoft.com, Klikkaa Get it now -painiketta.

Näyttöön tulee kirjautumisikkuna, jossa sinun on annettava sähköpostiosoite, jolle olet luonut tilin Microsoftissa (yksityinen tai yritys). Jos sinulla ei ole tällaista tiliä, voit luoda sellaisen ja jatkaa asennusta tai lopettaa asennuksen ja käyttää vaihtoehtoa asentaa lisäosa jollakin yllä kuvatuista tavoista.

Lataa ja asenna apuohjelma Excel 2021:stä tai Excel 365:stä (web) siirtymällä Insert [1]-välilehti, etsi Apuohjelmat-osio ja napsauta OfficeAdd-ins [2]-painiketta. Kirjoita sitten avautuvaan ikkunaan sana "viesapi ′ [3] hakukentässä ja paina suurennuslasikuvaketta. Lisäosa nimeltä "VIES API - EU VAT Validation" pitäisi löytyä, joka tulee asentaa napsauttamalla Add painiketta [4]. Kaikki yllä olevat vaiheet on kuvattu alla olevassa kuvakaappauksessa:

Kun olet napsauttanut Add -painiketta, näyttöön tulee näyttö, josta voit lukea lisenssiehdot ja tietosuojasäännöt.

Aloita lisäosan asennus painamalla Continue -painiketta.

Kokoonpano

Kun olet asentanut laajennuksen oikein, sinun pitäisi nähdä alla olevan kaltainen näyttö. Vuonna Home menu [1], etsi kuvake, joka edustaa VIES API Panel [2] ja napsauta sitä avataksesi sivupaneelin. Välittömästi asennuksen jälkeen apuohjelma konfiguroidaan toimimaan testiympäristössä – lisätietoja Testaa API-sivua. Lisäosan käyttäminen testitilassa ei edellytä tilin luomista viesapi.eu verkkosivusto.

Voit vaihtaa lisäosan tuotantoympäristöön napsauttamalla ID and key [3]-välilehti ja kirjoita Key ja avain ID, jonka löydät kirjautumalla sisään tilillesi viesapi.eu-sivuston "API Keys”-välilehti. Kun olet syöttänyt molemmat arvot, paina Save -painiketta.

Jos sinulla ei vielä ole tiliä verkkosivuillamme, napsauta linkkiä osoitteessa viesapi.eu [4] ja käydä läpi rekisteröintiprosessi, joka on kuvattu yksityiskohtaisesti osoitteessa Dokumentointi sivu.

Excelin asennus ja konfigurointi: 2007, 2010, 2013, 2016 ja 2019

Asennus

Hanki uusin versio Excel 2007, 2010, 2013, 2016 ja 2019 apuohjelmasta Lataa sivu. Käynnistä MS Excel ja siirry kohtaan File> Optionsja valitse sitten Add-ins [1] valikosta.

Valitse asetusten alareunasta Excel Add-ins [2] ja napsauta Go [3]-painiketta.

Edistyneet käyttäjät voivat lisätä lisäosan osoitteesta Developer välilehti [1] ja napsauta sitten Excel Add-ins [2] ja napsauta Browse [3]-painike:

Vuonna Add-ins ikkunassa, napsauta Browse -painiketta, siirry hakemistoon, jossa viesapi-ms-excel-addin-version-number.zip tiedosto purettiin ja valitse:

• viesapiExcel.xll – Excelin 32-bittiselle versiolle,
• viesapiExcel64.xll – Excelin 64-bittiselle versiolle.

Lisäosan oikea lataus näkyy alla olevassa kuvassa [1].

Riittää, kun napsautat OK painiketta [2] saadaksesi apuohjelmassa toteutetut toiminnot saataville Excelissä.

Kokoonpano

Asennuksen jälkeen laajennus asetetaan oletusarvoisesti testiympäristöön (lisätietoja Testaa API sivu). Jotta tuotantoympäristön toimintoja voidaan kutsua esiin, pääsy viesapi.eu-verkkosivustolle on määritettävä kerran. Voit tehdä tämän siirtymällä mihin tahansa Excel-laskentataulukkoon ja suorittamalla toiminnon:

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

jossa funktion parametrit ovat:

• identifier – parametrin tulee sisältää tunniste (ID), joka on luotu tilille viesapi.eu-sivustolla,
• key – parametrin tulee sisältää viesapi.eu-sivustolla olevalle tilille luotu avain.

Yksityiskohdat tunnisteen ja avaimen luomisesta on kuvattu Dokumentointi verkkosivusto.

Jotta voidaan varmistaa yhteyden oikeellisuus tietyn API:n kanssa (testi tai tuotanto), on suoritettava seuraava toiminto:

=VIESAPI.CONNECT.STATUS()

Mikä voi palauttaa arvoja:

• SUCCESS: Production – jos apuohjelma on määritetty oikein toimimaan tuotantoympäristön kanssa,
• SUCCESS: Test – jos apuohjelma on määritetty toimimaan oikein testiympäristössä,

• ERROR: Connection requires configuration – jos kokoonpano on väärä.

Oletusarvoisesti jokainen Excel-asiakirja on asetettu laskemaan laskentataulukko automaattisesti. Tämän vaihtoehdon asettaminen tarkoittaa, että kaikkia kaavoja kutsutaan, kun tehdään muutoksia, jotka vaikuttavat kaavaan. Esimerkki tästä on rivin poistaminen laskentataulukosta.

Jotta vältetään kaikkien tietyssä taulukossa määritettyjen toimintojen automaattinen kutsuminen, joka liittyy kyselyjen automaattiseen lähettämiseen veisapi.eu-sivuston API:lle, vaihda työkirjan laskentavaihtoehdoksi Manuaalinen:

1. alkaen File valikosta, valitse Options
2. Korosta Formulas -välilehti
3. Valitse Laskentavaihtoehdot-osiossa asetus: Manual ja poista valinta lisävaihtoehto: Recalculate the workbook before saving.
4. Arkkiin tehdyt muutokset on tallennettava.

Kun Excel-laskentataulukko on määritetty tällä tavalla, paina näppäinyhdistelmää pakottaaksesi kaikkien määritettyjen kaavojen päivittämisen:

CTRL + ALT + SHIFT + F9

Päivitä laajennus uusimpaan versioon

Huomio!Seuraava Excel-apuohjelman päivittäminen toimii oikein MS Excel 2019-, 2021- ja Excel 365 -versioissa, joissa apuohjelma voidaan asentaa Microsoft Storesta.

Huomio! Kun olet asentanut uusimman version, sinun on määritettävä lisäosa uudelleen, eli syötettävä ja tallennettava tunnus ja avain.

Voit asentaa Excel-apuohjelman uusimman version seuraavasti:

1. Tarkista asennetun apuohjelman versio kutsumalla kaava =VIESAPI.VERSION(). Lisäosan uusin versio on 1.2.8

2. Tyhjennä MS Excelin välimuisti virallisella dokumentaatiosivulla kuvatulla tavalla: https://learn.microsoft.com/en-us/office/dev/add-ins/testing/clear-cache

3. Kun olet suorittanut kaikki vaiheet kohdasta 2, käynnistä MS Excel -sovellus uudelleen.

4. Uudelleenkäynnistyksen aikana MS Excel -sovellus lataa apuohjelman uusimman version Microsoft Storesta.

5. Määritä lisäosa syöttämällä tunnus ja avain, joka on ladattu kirjautuessasi sisään tiliisi verkkosivusto – "API-avaimet" -välilehti.

Käyttö

Katso, kuinka VIES-järjestelmässä olevien yritysten EU-arvonlisäveroasema tarkistetaan automaattisesti ja massiivisesti Excel-apuohjelman avulla:

Ennen kuin käytät lisäosaa, sinun tulee tutustua sen toiminnan erityispiirteisiin:

• Kaikki funktiokutsut suoritetaan asynkronisessa tilassa, mikä ei aiheuta Excel-sovelluksen jäädyttämistä (ei vastausta).
• Rivin tai sarakkeen lisääminen (lisääminen) ei päivitä kaikkia määritettyjä funktiokutsuja.
• Funktioita sisältävien solujen kopioiminen tai siirtäminen ei päivitä määritettyjä funktiokutsuja.
• Rivin tai sarakkeen poistaminen päivittää kaikki määritetyt funktiokutsut ja lähettää kyselyt viesApi.eu:lle (vain Excelin oletusasetusten tapauksessa). Kuvaus oletusasetusten muuttamisesta on Asetukset-luvussa.
• Huomio! Ei ole suositeltavaa suorittaa yli 500 rinnakkaista kyselyä, koska Excelillä on vaikeuksia käsitellä suurta määrää asynkronisia puheluita.

Hanki yritystiedot VIES:stä

VIESAPI.VIES.DATA() – Toiminto hakee kaikki saatavilla olevat yritystiedot suoraan VIES-järjestelmästä. Parametrien tulee olla:

• eurooppalainen verotunnistenumero (ALV EU),
• (valinnainen) FORMAT palautetuista tiedoista (katso: Tunnisteet, joita voidaan käyttää FORMAT parametri).

=VIESAPI.VIES.DATA("PL7171642051")

Jos tarvitset vain yrityksen aseman VIES:ssä, käytä seuraavaa kyselyä:

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

Jos palautettu tila on Kyllä, se tarkoittaa, että yrityksellä on voimassa oleva EU:n ALV-numero.

Tunnisteet saatavilla osoitteessa VIESAPI.VIES.DATA toimintoa, jota voidaan käyttää FORMAT parametri:

• $(UID) – ViesApi.eu-palvelun luoma yksilöllinen tunniste
• $(CountryCode) - Maatunnus
• $(VATNumber) – eurooppalainen ALV-numero
• $(Valid) – Voimassa oleva EU-alv-numero (Yes/No)
  
• $(TraderName) – Urakoitsijan/toimittajan nimi
• $(TraderCompanyType) - Yritystyyppi
• $(TraderAddress) – Vastapuolen osoite
• $(ID) – VIES-järjestelmän luoma yksilöllinen tunniste
• $(Date) – Vastauksen luomispäivämäärä
• $(Source) – Tietojen lähde

Oletusmuoto: "$(TraderName), $(TraderAddress)"

Jos merkkijono "JSON" annetaan muodossa FORMAT parametri, funktio palauttaa täydellisen tuloksen JSON-merkkijonon muodossa, jota voidaan vapaasti jäsentää ja käsitellä edelleen:

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

Käyttäjätilin tilan tarkistus (ilmainen)

VIESAPI.STATUS.ACCOUNT() – Toiminto palauttaa perustiedot käyttäjän tällä hetkellä käyttämästä suunnitelmasta. Parametrien tulee olla:

• (valinnainen) FORMAT palautetuista tiedoista (katso: Tunnisteet, joita voidaan käyttää FORMAT parametri)

=VIESAPI.STATUS.ACCOUNT()

Huomio! Funktion kutsuminen ei lisää tehtyjen kyselyjen määrää.

Tunnisteet, jotka ovat saatavilla osoitteessa VIESAPI.STATUS.ACCOUNT toimintoa voidaan käyttää FORMAT parametri:

• $(BillingPlanName) – Nykyisen tariffisuunnitelman nimi
• $(SubscriptionPrice) – Kuukausitilauksen nettohinta
• $(ItemPrice) – Yksittäisen kyselyn nettokustannus suunnitelman ulkopuolelta vakiosuunnitelmassa
• $(ItemPriceStatus) – Yksittäisen tiedustelun nettokustannus – VIES / Yksittäisen suunnitelman kokonaisuuden liiketoimintatila
• $(Limit) – Suunnitelman kyselyiden enimmäismäärä
• $(RequestDelay) – Pyyntöjen välinen vähimmäisaika
• $(DomainLimit) – Verkkotunnusten enimmäismäärä (API-avaimet)
• $(OverPlanAllowed) – Kyky ylittää suunnitelman kyselyiden enimmäismäärä
• $(ExcelAddIn) – Pääsy MS Excelin apuohjelmalla
• $(Stats) – Pääsy suoritettujen kyselyiden tilastoihin
• $(NIPMonitor) – Pääsy VIES-tilan seurantaan
• $(SearchByNIP) – Haku EU:n ALV-tunnistenumerolla
• $(FuncGetVIESData) – Pääsy toimintoihin, jotka tarkistavat kokonaisuuden tilan VIES-järjestelmässä
• $(VIESStatusCount) – VIES-järjestelmän kokonaisuuden tilaa koskevien tiedustelujen määrä
• $(TotalCount) – Kuluvan kuukauden aikana suoritettujen kyselyjen kokonaismäärä

Oletusmuoto: "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)"

Jos merkkijono "JSON" annetaan muodossa FORMAT parametri, funktio palauttaa täydellisen tuloksen JSON-merkkijonon muodossa, jota voidaan vapaasti jäsentää ja käsitellä edelleen.

Muita hyödyllisiä toimintoja (ilmainen)

VIESAPI.ACCOUNT.STATUS.TOTAL() – Toiminto palauttaa tiedot kuluvan laskutuskuukauden aikana tehtyjen kyselyjen kokonaismäärästä tietylle tilille (kaikki API-avaimet). Palauttaa täsmälleen saman numeron kuin $(TotalCount) -tunnisteen VIESAPI.STATUS.ACCOUNT() toiminto.

VIESAPI.ACCOUNT.STATUS.LIMIT() – Funktio palauttaa tiedon käyttäjän valitsemassa suunnitelmassa käytettävissä olevien kyselyjen enimmäismäärästä. Palauttaa täsmälleen saman numeron kuin $(Limit) merkitse sisään VIES.STATUS.ACCOUNT() toiminto

VIESAPI.EUVAT.NORM() – Tämä ominaisuus korjaa ja muotoilee EU:n ALV-numeron (poistaa välilyönnit ja yhdysmerkit jne.) offline-tilassa eikä nouta tietoja VIES:stä:

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

VIESAPI.EUVAT.VALID() – Toiminto tarkistaa vain EU:n ALV-numeron oikeellisuuden (syntaksi, tarkistussumma) offline-tilassa eikä nouta tietoja VIES-järjestelmästä. Palauttaa TRUE jos numero on kelvollinen tai FALSE jos se ei ole voimassa:

=VIESAPI.EUVAT.VALID("PL7171642051")

VIESAPI.CONNECTION.STATE() – Funktio palauttaa apuohjelman kokoonpanon nykyisen tilan.

Jos funktio palauttaa seuraavan arvon, se tarkoittaa muun muassa, että ID ja API key ei tallennettu:

ERROR: Connection requires configuration

Tallennuksen jälkeen API ID ja key, funktion pitäisi palauttaa seuraava viesti:

SUCCESS: Production