Google Sheets™-add-on VIES Validator

Google Sheets™-add-on VIES Validator

vies api google sheetsMet de Google Sheets™-invoegtoepassing kunt u snel en automatisch entiteiten (contractanten) controleren met behulp van het Google Sheets™-spreadsheet op basis van hun huidige status in de VIES-systeem.

Deze documentatie bevat instructies voor het integreren van de Google Sheets™-applicatie met het VIES API-systeem.

 

 

Installatie en configuratie

Installatie

Nadat u de Google Workspace Marketplace-website hebt geopend https://workspace.google.com/marketplace/app/vies_api_eu_vat_validation/1043052728267, Klik op de Install knop.

Vies API Google Sheets add-on installeren

Selecteer het Google-account waarvoor de VIES Validator Google Sheets Add-on moet worden geïnstalleerd en beschikbaar moet zijn:

Vies API Google Sheets add-on account installeren

Op het volgende scherm kunt u de Privacybeleid en de toepasselijke Servicevoorwaarden, evenals de omvang van uw gegevens die wij zullen verwerken. Om door te gaan naar de volgende stap van de installatie, drukt u op de Continue knop.

Vies API Google Sheets add-on installatierechten

Bevestig dat u de benodigde machtigingen hebt verleend zodat de add-on goed functioneert en druk op de knop Allow knop:

Vies API Google Sheets-invoegtoepassing installatiemachtigingen toestaan

De VIES-validatie-add-on is succesvol geïnstalleerd op uw account en is beschikbaar nadat u Google Sheets start op het tabblad Extensies. Om verder te gaan, klik Next:

Vies API Google Sheets add-on installatie-extensie

Het laatste scherm van het installatieprogramma vraagt u om de add-on te configureren. Klik op de knop "Complete additional setup now" opent een nieuw browservenster met de huidige documentatiepagina. Klik op de Done en begin met het configureren van de add-on zoals beschreven in het gedeelte Configuratie.

Vies API Google Sheets-add-on geïnstalleerd

Configuratie

Na installatie wordt de plug-in standaard ingesteld op de testomgeving (meer details op Test-API Om functies in de productieomgeving te kunnen aanroepen, is het noodzakelijk om eenmalig toegang tot de website viesapi.eu te configureren. Ga hiervoor naar een willekeurige Google Sheets™-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.

Als u de voorkeur geeft aan een zijbalkconfiguratie, klikt u op Extensions tabblad en selecteer vervolgens VIES API - EU VAT Validation en klik ten slotte Show sidebar om de zijbalk in te schakelen:

Vies API Google Sheets add-on configuratie zijbalk

Ga dan naar de ID and Key tabblad om de ID en Key in de daarvoor bestemde tekstvelden, die beschikbaar zijn nadat u bent ingelogd op uw VIES API-account: https://viesapi.eu/sign-in/

Vies API Google Sheets add-on configuratie-id en sleutel

Gebruik

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

  • Alle functieaanroepen worden uitgevoerd in de asynchrone modus, waardoor de Google Sheets™-toepassing niet vastloopt (geen reactie).
  • 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.
  • Door een rij of kolom te verwijderen, worden alle gedefinieerde functieaanroepen vernieuwd en worden query's naar viesApi.eu gestuurd (alleen in het geval van de standaardinstellingen van Google Sheets™). De beschrijving van het wijzigen van de standaardinstellingen vindt u in het hoofdstuk Configuratie.
  • Let op! Het is niet aan te raden om meer dan 500 parallelle query's uit te voeren, omdat Google Sheets™ moeite heeft met het verwerken van een groot aantal asynchrone aanroepen.

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) – reactie van de VIES-dienst, met informatie over de huidige EU-btw-status van het gecontroleerde bedrijf (Yes/No)
  • $(TraderName) – bedrijfsregistratienaam
  • $(TraderCompanyType) – bedrijfstype
  • $(TraderAddress) – handelsadres waar het bedrijf is geregistreerd
  • $(ID) – unieke identificatie gegenereerd door het VIES-systeem (consultatienummer)
  • $(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")

Ontvang geparseerde bedrijfsgegevens van VIES

VIESAPI_VIES_DATA_PARSED() – De functie haalt alle beschikbare bedrijfsgegevens rechtstreeks op uit het VIES-systeem. Bovendien worden de naam en het adres van het bedrijf geretourneerd als geparseerde gegevens, opgesplitst in afzonderlijke kenmerken. 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_PARSED("PL7171642051")

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

=VIESAPI_VIES_DATA_PARSED("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_PARSED 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) – reactie van de VIES-dienst, met informatie over de huidige EU-btw-status van het gecontroleerde bedrijf (Yes/No)
  • $(TraderName) – bedrijfsregistratienaam
  • $(TraderNameComponents.Name) – bedrijfsnaam van traderName (zonder rechtsvorm)
  • $(TraderNameComponents.LegalForm) – naam van de rechtsvorm ontleend aan traderName (zonder bedrijfsnaam)
  • $(TraderNameComponents.LegalFormCanonicalId) – woordenboekidentificatie van rechtsvorm
  • $(TraderNameComponents.LegalFormCanonicalName) – woordenboeknaam van rechtsvorm
  • $(TraderCompanyType) – bedrijfstype
  • $(TraderAddress) – handelsadres waar het bedrijf is geregistreerd
  • $(TraderAddressComponents.Country) – naam van het handelsland in zijn nationale taal
  • $(TraderAddressComponents.PostalCode) – postcode van het adres van de handelaar
  • $(TraderAddressComponents.City) – stad van het adres van de handelaar
  • $(TraderAddressComponents.Street) – straat van het adres van de handelaar
  • $(TraderAddressComponents.StreetNumber) – straatnummer van het adres van de handelaar
  • $(TraderAddressComponents.HouseNumber) – appartement-/kantoornummer van het adres van de handelaar
  • $(TraderAddressComponents.Other) – overige adresgegevens (gebiedsnaam, gebouwnaam, verdieping, etc.)
  • $(ID) – unieke identificatie gegenereerd door het VIES-systeem (consultatienummer)
  • $(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_PARSED("PL7171642051";"JSON")

Statuscontrole gebruikersaccount (gratis)

VIESAPI_ACCOUNT_STATUS() – 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_ACCOUNT_STATUS()

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

De tags die beschikbaar zijn in de VIESAPI_ACCOUNT_STATUS functie kan worden gebruikt als de FORMAT parameter:

  • $(UID) – unieke identificatie gegenereerd door de viesApi.eu-service
  • $(BillingPlanName) – naam van het huidige plan
  • $(SubscriptionPrice) – maandelijkse abonnementskosten
  • $(ItemPrice) – kosten van een enkele query buiten het plan
  • $(ItemPriceStatus) – kosten per query – BTW/VIES/bedrijfsactiviteitsstatus
  • $(ItemPriceParsed) – kosten per query – BTW/VIES/bedrijfsactiviteitenstatus met geparseerde gegevens
  • $(Limit) – maximaal aantal zoekopdrachten in het plan
  • $(RequestDelay) – minimale tijdsinterval tussen query's
  • $(DomainLimit) – maximaal aantal domeinen (API-sleutels)
  • $(OverPlanAllowed) – mogelijkheid om het maximale aantal zoekopdrachten in het plan te overschrijden
  • $(ExcelAddIn) – toegang tot de Google Sheets™ en Microsoft Excel™ add-in
  • $(Stats) – toegang tot querystatistieken
  • $(NIPMonitor) – toegang tot het toezicht op de status van bedrijven: BTW/VIES/Activiteitenstatus
  • $(FuncGetVIESData) – toegang tot functies die de bedrijfsstatus in het VIES-systeem verifiëren
  • $(FuncGetVIESDataParsed) – toegang tot functies die de bedrijfsstatus in het VIES-systeem verifiëren en de naam en het adres van de handelaar analyseren
  • $(VIESDataCount) – aantal VIES-query’s dat deze maand is uitgevoerd
  • $(VIESDataParsedCount) – aantal VIES-query’s met geparseerde gegevens die deze maand zijn uitgevoerd
  • $(TotalCount) – totaal aantal zoekopdrachten deze maand uitgevoerd

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.

VIES-systeemstatuscontrole (gratis)

VIESAPI_VIES_STATUS() – Met deze functie kunt u de huidige status van het VIES-systeem controleren. Het retourneert een algemene status die de beschikbaarheid aangeeft, evenals een lijst van individuele lidstaten, samen met de huidige beschikbaarheidsstatus van hun nationale systemen. De parameters moeten zijn:

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

=VIESAPI_VIES_STATUS()

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

De tags die beschikbaar zijn in de VIESAPI_VIES_STATUS functie kan worden gebruikt als de FORMAT parameter:

  • $(UID) – unieke identificatie gegenereerd door de viesApi.eu-service
  • $(Available) – huidige beschikbaarheid van het VIES-systeem (beschikbaar, gedeeltelijk beschikbaar, niet beschikbaar)
  • $(Countries) – lijst van individuele lidstaten (beschikbaar, niet beschikbaar)
  • $(AT), $(FR), $(PL), etc. – beschikbaarheidsstatus van een specifiek lidstaatland (gebruik een landcode van 2 hoofdletters als tagwaarde)

Standaard FORMAAT: "$(Available)"

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

Google Sheets™ is een handelsmerk van Google LLC.