Met de Excel-add-in kunt u via de Excel-spreadsheet snel en automatisch entiteiten (aannemers) controleren op hun huidige status in de VIES-systeem.

Dit hoofdstuk bevat instructies voor het integreren van de Microsoft Excel-toepassing met het nip24.pl-systeem. De meegeleverde add-in is met succes getest in de volgende versies van MS Excel: 2007, 2010, 2013, 2016, 2019 (op de Windows- en MacOS-besturingssystemen) en 2021 (op de Windows- en MacOS-besturingssystemen) en de webversie van Excel365.

De nieuwste versie van de add-on voor Excel 2007, 2010, 2013, 2016 en 2019 is altijd beschikbaar om te downloaden van de Download pagina. De add-on kan worden geïnstalleerd in zowel 32-bits als 64-bits versies van Excel. Aandacht! Selecteer de versie (32 of 64 bit) die komt overeen met de versie van Excel, niet het besturingssysteem.

Ga naar de officiële Microsoft Store om de add-on voor MacOS en Excel 2021 voor Windows en Excel365 te downloaden en te installeren: https://appsource.microsoft.com.

De volledige functionaliteit van de Excel-invoegtoepassing kan worden gecontroleerd - zonder dat je een account hoeft aan te maken - met behulp van de verstrekte Test-API. Op de pagina wordt ook beschreven hoe u een Excel-invoegtoepassing configureert voor gebruik in de API die voor testen wordt geleverd.

Het gebruik van de add-in in de productie-API vereist het opzetten van een account op de website viesapi.eu, het kopen van een minimum van het Business-plan en het genereren van een sleutel en zijn identificatie. Het proces van het registreren en opzetten van een account en het genereren van sleutels is beschreven op de Documentatie website.

Installatie en configuratie voor MS Excel 2021 en Excel 365 vanuit Microsoft Store (AppSource)

Installatie

Na het betreden van de Microsoft Official Store-website https://appsource.microsoft.com, Klik op de Get it now knop.

Er verschijnt een inlogvenster waarin u het e-mailadres moet invullen waarvoor u een account bij Microsoft heeft aangemaakt (privé of zakelijk). Als u niet over een dergelijk account beschikt, kunt u er een aanmaken en doorgaan met het installatieproces of de installatie stoppen en de optie gebruiken om de add-on op een van de hierboven beschreven manieren te installeren.

Om de invoegtoepassing vanuit Excel 2021 of Excel 365 (web) te downloaden en te installeren, gaat u naar de Insert Ga op het tabblad [1] naar het gedeelte Add-ins en klik op het OfficeAdd-ins [2] knop. Typ vervolgens in het geopende venster het woord 'viesapi ′ [3] in het zoekveld en druk op het vergrootglaspictogram. Een add-on genaamd "VIES API - EU VAT Validation" moet worden gevonden, die moet worden geïnstalleerd door op de Add knop [4]. Alle bovenstaande stappen worden geïllustreerd in de onderstaande schermafbeelding:

Na het klikken op de Add knop, zou er een scherm moeten verschijnen waar u de licentievoorwaarden en regels voor privacybescherming kunt lezen.

Druk op om de invoegtoepassing te installeren Continue knop.

Configuratie

Nadat u de plug-in correct hebt geïnstalleerd, zou u een scherm moeten zien dat lijkt op het onderstaande scherm. In de Home menu [1], zoek het pictogram dat de VIES API Panel [2] en klik erop om het zijpaneel weer te geven. Onmiddellijk na installatie is de invoegtoepassing geconfigureerd om in een testomgeving te werken – details op de Test API-pagina. Als u de add-on in de testmodus gebruikt, hoeft u geen account aan te maken op de viesapi.eu website.

Om de add-on naar de productieomgeving te schakelen, klikt u op de ID and key tabblad [3] en voer het Key en sleutel ID, die u kunt vinden nadat u bent ingelogd op uw account op de website viesapi.eu in de rubriek “API Keys" tabblad. Nadat u beide waarden hebt ingevoerd, drukt u op de Save knop.

Heeft u nog geen account op onze website, klik dan op de link op viesapi.eu [4] en doorloop het registratieproces, dat in detail wordt beschreven op de Documentatie bladzijde.

Installatie en configuratie voor Excel: 2007, 2010, 2013, 2016 en 2019

Installatie

Download de nieuwste versie van de invoegtoepassing voor Excel 2007, 2010, 2013, 2016 en 2019 van de Download pagina. Start MS Excel en ga naar File> Optionsen selecteer vervolgens Add-ins [1] uit het menu.

Selecteer onderaan de instellingen Excel Add-ins [2] en klik op de Go [3] knop.

Gevorderde gebruikers kunnen een add-on toevoegen vanuit de Developer tabblad [1] en klik vervolgens op Excel Add-ins [2] en klik op de Browse [3] knop:

In de Add-ins venster, klik op de Browse knop, ga naar de map waar de viesapi-ms-excel-addin-version-number.zip bestand is uitgepakt en selecteer:

• viesapiExcel.xll – voor de 32-bits versie van Excel,
• viesapiExcel64.xll – voor de 64-bits versie van Excel.

Het correct laden van de add-in wordt weergegeven in onderstaande figuur [1].

Het volstaat om op de te klikken OK knop [2] om de in de add-in geïmplementeerde functies beschikbaar te maken in Excel.

Configuratie

Na installatie wordt de plug-in standaard ingesteld op de testomgeving (meer details op Test-API bladzijde). Om functies in de productieomgeving te kunnen oproepen, is het noodzakelijk om eenmalig de toegang tot de website viesapi.eu te configureren. Ga hiervoor naar een Excel-spreadsheet en voer de volgende functie uit:

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

waarbij de functieparameters zijn:

• identifier – de parameter moet de identifier (ID) bevatten die is gegenereerd op het account op de website viesapi.eu,
• key – de parameter moet de sleutel bevatten die is gegenereerd op het account op de website viesapi.eu.

Details over het genereren van de identifier en sleutel worden beschreven op de Documentatie website.

Om de juistheid van de verbinding met een bepaalde API (test of productie) te verifiëren, moet de volgende functie worden uitgevoerd:

=VIESAPI.CONNECT.STATUS()

Welke waarden kunnen retourneren:

• SUCCESS: Production – als de invoegtoepassing correct is geconfigureerd om te werken met de productieomgeving,
• SUCCESS: Test – als de invoegtoepassing correct is geconfigureerd om te werken met de test omgeving,

• ERROR: Connection requires configuration – bij een verkeerde configuratie.

Elk Excel-document is standaard ingesteld om de spreadsheet automatisch te berekenen. Als u deze optie instelt, worden alle formules aangeroepen wanneer er wijzigingen worden aangebracht die van invloed zijn op de formule. Een voorbeeld hiervan is het verwijderen van een rij op een werkblad.

Om te voorkomen dat alle functies die in een bepaald blad zijn gedefinieerd automatisch worden aangeroepen, wat verband houdt met het automatisch verzenden van query's naar de API van de veisapi.eu-website, wijzigt u de optie voor het berekenen van de werkmap in Handmatig:

1. Van de File menu, selecteren Options
2. Markeer de Formulas tabblad
3. Selecteer de instelling in het gedeelte Berekeningsopties: Manual en uitvinken de extra optie: Recalculate the workbook before saving.
4. Het is noodzakelijk om de aangebrachte wijzigingen in het blad op te slaan.

Met het Excel-spreadsheet zo geconfigureerd, drukt u op de toetsencombinatie om het vernieuwen van alle gedefinieerde formules te forceren:

CTRL + ALT + SHIFT + F9

Gebruik

Bekijk hoe u automatisch en massaal de EU-btw-status van bedrijven in het VIES-systeem kunt verifiëren met behulp van onze Excel-add-in:

Voordat u de add-on gebruikt, moet u zich vertrouwd maken met de specifieke kenmerken van de werking ervan:

• Alle functieaanroepen worden uitgevoerd in asynchrone modus, wat niet het bevriezingseffect (geen reactie) van de Excel-toepassing veroorzaakt.
• Het toevoegen (invoegen) van een rij of kolom vernieuwt niet alle gedefinieerde functieaanroepen.
• Het kopiëren of verplaatsen van cellen die functies bevatten, ververst gedefinieerde functieaanroepen niet.
• Als u een rij of kolom verwijdert, worden alle gedefinieerde functieaanroepen vernieuwd en worden query's naar viesApi.eu verzonden (alleen in het geval van standaard Excel-instellingen). De beschrijving van het wijzigen van de standaardinstellingen is opgenomen in het hoofdstuk Configuratie.
• Aandacht! Het wordt niet aanbevolen om meer dan 500 parallelle query's uit te voeren, omdat Excel problemen heeft met het afhandelen van een groot aantal asynchrone oproepen.

Haal bedrijfsgegevens op uit VIES

VIESAPI.VIES.DATA() – De functie haalt alle beschikbare bedrijfsgegevens direct uit het VIES-systeem. De parameters moeten zijn:

• Europees fiscaal identificatienummer (BTW EU),
• (optioneel) FORMAT van de geretourneerde gegevens (zie: Tags die kunnen worden gebruikt als de FORMAT parameter).

=VIESAPI.VIES.DATA("PL7171642051")

Als u alleen de bedrijfsstatus in VIES nodig heeft, gebruik dan de volgende query:

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

Als de geretourneerde status Ja is, betekent dit dat het bedrijf een geldig EU BTW-nummer heeft.

Labels beschikbaar in de VIESAPI.VIES.DATA functie die kan worden gebruikt als de FORMAT parameter:

• $(UID) – Unieke identificatie gegenereerd door de viesApi.eu-service
• $(CountryCode) - Landcode
• $(VATNumber) – Europees btw-nummer
• $(Valid) – Geldige status EU BTW-nummer (Yes/No)
  
• $(TraderName) – Naam van de aannemer/leverancier
• $(TraderCompanyType) - Soort bedrijf
• $(TraderAddress) – Adres wederpartij
• $(ID) – Unieke identificatie gegenereerd door het VIES-systeem
• $(Date) – De datum waarop het antwoord is gegenereerd
• $(Source) – De bron van de gegevens

Standaard formaat: "$(TraderName), $(TraderAddress)"

Als de tekenreeks "JSON" wordt gegeven als de FORMAT parameter, retourneert de functie het volledige resultaat in de vorm van een JSON-tekenreeks, die vrij kan worden geparseerd en verder kan worden verwerkt:

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

Statuscontrole gebruikersaccount (gratis)

VIESAPI.STATUS.ACCOUNT() – De functie retourneert basisinformatie over het abonnement dat momenteel door de gebruiker wordt gebruikt. De parameters moeten zijn:

• (optioneel) FORMAT van de geretourneerde gegevens (zie: Tags die kunnen worden gebruikt als de FORMAT parameter)

=VIESAPI.STATUS.ACCOUNT()

Aandacht! Het aanroepen van de functie verhoogt niet het aantal uitgevoerde query's.

De tags die beschikbaar zijn in de VIESAPI.STATUS.ACCOUNT functie kan worden gebruikt als de FORMAT parameter:

• $(BillingPlanName) – Naam van het huidige tariefplan
• $(SubscriptionPrice) – Nettoprijs van het maandabonnement
• $(ItemPrice) – Nettokosten voor eenmalig onderzoek buiten het plan in het standaardplan
• $(ItemPriceStatus) – Nettokosten van een enkel onderzoek – VIES / Bedrijfsstatus van de entiteit in een individueel plan
• $(Limit) – Het maximum aantal queries in het plan
• $(RequestDelay) – Het minimale tijdsinterval tussen verzoeken
• $(DomainLimit) – Maximaal aantal domeinen (API-sleutels)
• $(OverPlanAllowed) - Mogelijkheid om het maximale aantal vragen in het plan te overschrijden
• $(ExcelAddIn) – Toegang via de MS Excel-invoegtoepassing
• $(Stats) – Toegang tot statistieken van uitgevoerde zoekopdrachten
• $(NIPMonitor) – Toegang tot monitoring van de VIES-status
• $(SearchByNIP) – Zoeken op EU-btw-identificatienummer
• $(FuncGetVIESData) – Toegang tot functies die de status van de entiteit in het VIES-systeem controleren
• $(VIESStatusCount) – Aantal navraag gedaan over de status van de entiteit in het VIES-systeem
• $(TotalCount) – Totaal aantal zoekopdrachten uitgevoerd in de huidige maand

Standaard FORMAAT: "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)"

Als de tekenreeks "JSON" wordt gegeven als de FORMAT parameter, retourneert de functie het volledige resultaat in de vorm van een JSON-tekenreeks, die vrij kan worden geparseerd en verder kan worden verwerkt.

Andere handige functies (gratis)

VIESAPI.ACCOUNT.STATUS.TOTAL() – De functie retourneert informatie over het totale aantal vragen dat in de huidige factureringsmaand is gedaan voor een bepaald account (alle API-sleutels). Retourneert exact hetzelfde getal als de $(TotalCount) label in de VIESAPI.STATUS.ACCOUNT() functie.

VIESAPI.ACCOUNT.STATUS.LIMIT() – De functie retourneert informatie over het maximale aantal query's dat beschikbaar is in het plan dat door de gebruiker is geselecteerd. Retourneert exact hetzelfde getal als de $(Limit) tag in VIES.STATUS.ACCOUNT() functie

VIESAPI.EUVAT.NORM() – Deze functie corrigeert en formatteert het EU-btw-nummer (verwijdert spaties en koppeltekens etc.) offline en haalt geen gegevens op uit VIES:

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

VIESAPI.EUVAT.VALID() – De functie controleert alleen offline de juistheid (syntaxis, checksum) van het EU-btw-nummer en haalt geen gegevens op uit het VIES-systeem. Geeft terug TRUE of het nummer geldig is of FALSE als het niet geldig is:

=VIESAPI.EUVAT.VALID("PL7171642051")

VIESAPI.CONNECTION.STATE() – De functie retourneert de huidige status van de configuratie van de invoegtoepassing.

Als de functie de volgende waarde retourneert, betekent dit onder andere dat de ID en API key werden niet gered:

ERROR: Connection requires configuration

Na het opslaan van de API ID en key, zou de functie het volgende bericht moeten retourneren:

SUCCESS: Production