Doplněk Google Sheets™ – validátor VIES

Doplněk Google Sheets™ – validátor VIES

API pro Google TabulkyDoplněk Google Sheets™ vám umožňuje rychle a automaticky kontrolovat entity (dodavatele) pomocí tabulky Google Sheets™ z hlediska jejich aktuálního stavu v systém VIES.

Tato dokumentace obsahuje pokyny k integraci aplikace Google Sheets™ se systémem VIES API.

 

 

Instalace a konfigurace

Instalace

Po vstupu na web Google Workspace Marketplace https://workspace.google.com/marketplace/app/vies_api_eu_vat_validation/1043052728267, klikněte na Install knoflík.

Instalace doplňku VIE API pro Google Tabulky

Výběr účtu Google, pro který má být nainstalován a dostupný doplněk VIES Validator pro Google Sheets:

Instalace doplňku Google Sheets pro VIE API v účtu

Na další obrazovce si můžete přečíst Zásady ochrany osobních údajů a příslušné Podmínky služby, a také rozsah vašich údajů, které budeme zpracovávat. Chcete-li pokračovat k dalšímu kroku instalace, stiskněte tlačítko Continue knoflík.

oprávnění k instalaci doplňku VIE API Google Sheets

Potvrďte, že jste udělili potřebná oprávnění pro správné fungování doplňku, a stiskněte tlačítko Allow tlačítko:

Jak povolit instalaci doplňku VIE API pro Google Sheets?

Doplněk VIES Validation byl úspěšně nainstalován na váš účet a bude k dispozici po spuštění Tabulek Google na kartě Rozšíření. Chcete-li pokračovat, klikněte prosím Next:

Instalace rozšíření doplňku Google Sheets pro VIE API

Na poslední obrazovce instalačního programu se zobrazí výzva k nastavení doplňku. Kliknutím na tlačítko „Complete additional setup now„odkaz“ otevře nové okno prohlížeče s aktuální stránkou dokumentace. Klikněte na Done a začněte konfigurovat doplněk, jak je popsáno v části Konfigurace.

Nainstalován doplněk Google Tabulek pro rozhraní API Vies

Konfigurace

Po instalaci je plugin standardně nastaven do testovacího prostředí (více podrobností na Test API stránka). Aby bylo možné volat funkce v produkčním prostředí, je nutné jednou nakonfigurovat přístup k webovým stránkám viesapi.eu. Chcete-li to provést, přejděte do libovolné tabulky Google Sheets™ a proveďte funkci:

=VIESAPI_CONNECT_PRODUCTION("identifier";"key")

kde parametry funkce jsou:

  • identifier – parametr by měl obsahovat identifikátor (ID) vygenerovaný na účtu na webu viesapi.eu,
  • key – parametr by měl obsahovat Klíč vygenerovaný na účtu na webu viesapi.eu.

Podrobnosti o generování identifikátoru a klíče jsou popsány na Dokumentace webová stránka.

Aby bylo možné ověřit správnost spojení s daným API (test nebo výroba), měla by být provedena následující funkce:

=VIESAPI_CONNECT_STATUS()

Které mohou vrátit hodnoty:

  • SUCCESS: Production – pokud je doplněk správně nakonfigurován pro práci s produkčním prostředím,
  • SUCCESS: Test – pokud je doplněk správně nakonfigurován pro práci s testovací prostředí,
  • ERROR: Connection requires configuration – v případě špatné konfigurace.

Pokud dáváte přednost konfiguraci s bočním panelem, klikněte na Extensions a poté vyberte VIES API - EU VAT Validation a nakonec klikněte Show sidebar Chcete-li povolit postranní panel:

Konfigurace doplňku Google Sheets v API pro Vies, postranní panel

Pak jděte do ID and Key záložkou pro vstup do ID a Key do příslušných textových polí, která jsou k dispozici po přihlášení k vašemu účtu VIES API: https://viesapi.eu/sign-in/

Konfigurační ID a klíč doplňku VIE API Google Sheets

Používání

Před použitím doplňku byste se měli seznámit se specifiky jeho fungování:

  • Všechna volání funkcí jsou prováděna v asynchronním režimu, což nezpůsobuje zamrznutí (žádnou odezvu) aplikace Google Sheets™.
  • Přidáním (vložením) řádku nebo sloupce se neobnoví všechna definovaná volání funkcí.
  • Kopírování nebo přesouvání buněk obsahujících funkce neobnovuje volání definovaných funkcí.
  • Smazání řádku nebo sloupce obnoví všechna definovaná volání funkcí a odešlou dotazy na viesApi.eu (pouze v případě výchozího nastavení Tabulek Google™). Popis změny výchozího nastavení je uveden v kapitole Konfigurace.
  • Pozor! Nedoporučuje se spouštět více než 500 paralelních dotazů, protože Google Sheets™ má potíže se zpracováním velkého počtu asynchronních volání.

Získejte firemní data z VIES

VIESAPI_VIES_DATA() – Funkce načítá všechna dostupná firemní data přímo ze systému VIES. Parametry by měly být:

  • evropské daňové identifikační číslo (VAT EU),
  • (volitelný) FORMAT vrácených dat (viz: Tagy, které lze použít jako FORMAT parametr).

=VIESAPI_VIES_DATA("PL7171642051")

Pokud potřebujete pouze status společnosti ve VIES, použijte prosím následující dotaz:

=VIESAPI_VIES_DATA("PL7171642051";"$(Valid)")

Pokud je vrácený stav Ano, znamená to, že společnost má platné EU DIČ.

Štítky dostupné v VIESAPI_VIES_DATA funkce, kterou lze použít jako FORMAT parametr:

  • $(UID) – unikátní identifikátor generovaný službou viesApi.eu
  • $(CountryCode) – předvolba země
  • $(VATNumber) – evropské DIČ
  • $(Valid) – odpověď ze služby VIES s informací o aktuálním statusu DPH v EU u kontrolované společnosti (Yes/No)
  • $(TraderName) – název společnosti
  • $(TraderCompanyType) – typ podnikání
  • $(TraderAddress) – adresa obchodníka, kde je společnost registrována
  • $(ID) – jedinečný identifikátor generovaný systémem VIES (konzultační číslo)
  • $(Date) – datum, kdy byla odpověď vygenerována
  • $(Source) – zdroj dat

Výchozí formát: "$(TraderName), $(TraderAddress)"

Pokud řetězec "JSON" se uvádí jako FORMAT parametr, funkce vrátí kompletní výsledek ve formě řetězce JSON, který lze libovolně analyzovat a dále zpracovávat:

=VIESAPI_VIES_DATA("PL7171642051";"JSON")

Získejte analyzovaná firemní data z VIES

VIESAPI_VIES_DATA_PARSED() – Funkce načítá všechna dostupná data o společnosti přímo ze systému VIES. Název a adresa společnosti jsou navíc vráceny jako analyzovaná data rozdělená do samostatných atributů. Parametry by měly být:

  • evropské daňové identifikační číslo (VAT EU),
  • (volitelný) FORMAT vrácených dat (viz: Tagy, které lze použít jako FORMAT parametr).

=VIESAPI_VIES_DATA_PARSED("PL7171642051")

Pokud potřebujete pouze status společnosti ve VIES, použijte prosím následující dotaz:

=VIESAPI_VIES_DATA_PARSED("PL7171642051";"$(Valid)")

Pokud je vrácený stav Ano, znamená to, že společnost má platné EU DIČ.

Štítky dostupné v VIESAPI_VIES_DATA_PARSED funkce, kterou lze použít jako FORMAT parametr:

  • $(UID) – unikátní identifikátor generovaný službou viesApi.eu
  • $(CountryCode) – předvolba země
  • $(VATNumber) – evropské DIČ
  • $(Valid) – odpověď ze služby VIES s informací o aktuálním statusu DPH v EU u kontrolované společnosti (Yes/No)
  • $(TraderName) – název společnosti
  • $(TraderNameComponents.Name) – název společnosti z traderName (bez právní formy)
  • $(TraderNameComponents.LegalForm) – název právní formy převzatý z traderName (bez názvu společnosti)
  • $(TraderNameComponents.LegalFormCanonicalId) – slovníkový identifikátor právní formy
  • $(TraderNameComponents.LegalFormCanonicalName) – slovníkový název právní formy
  • $(TraderCompanyType) – typ podnikání
  • $(TraderAddress) – adresa obchodníka, kde je společnost registrována
  • $(TraderAddressComponents.Country) – název země obchodníka v jejím národním jazyce
  • $(TraderAddressComponents.PostalCode) – poštovní směrovací číslo adresy obchodníka
  • $(TraderAddressComponents.City) – město, kde má obchodník adresu
  • $(TraderAddressComponents.Street) – ulice, kde se nachází adresa obchodníka
  • $(TraderAddressComponents.StreetNumber) – číslo popisné, kde se nachází adresa obchodníka
  • $(TraderAddressComponents.HouseNumber) – číslo bytu/kanceláře dle adresy obchodníka
  • $(TraderAddressComponents.Other) – další údaje o adrese (název oblasti, název budovy, číslo patra atd.)
  • $(ID) – jedinečný identifikátor generovaný systémem VIES (konzultační číslo)
  • $(Date) – datum, kdy byla odpověď vygenerována
  • $(Source) – zdroj dat

Výchozí formát: "$(TraderName), $(TraderAddress)"

Pokud řetězec "JSON" se uvádí jako FORMAT parametr, funkce vrátí kompletní výsledek ve formě řetězce JSON, který lze libovolně analyzovat a dále zpracovávat:

=VIESAPI_VIES_DATA_PARSED("PL7171642051";"JSON")

Kontrola stavu uživatelského účtu (zdarma)

VIESAPI_ACCOUNT_STATUS() – Funkce vrací základní informace o plánu aktuálně používaném uživatelem. Parametry by měly být:

  • (volitelný) FORMAT vrácených dat (viz: Tagy, které lze použít jako FORMAT parametr)

=VIESAPI_ACCOUNT_STATUS()

Pozornost! Volání funkce nezvýší počet provedených dotazů.

Značky dostupné v VIESAPI_ACCOUNT_STATUS funkci lze použít jako FORMAT parametr:

  • $(UID) – unikátní identifikátor generovaný službou viesApi.eu
  • $(BillingPlanName) – název aktuálního plánu
  • $(SubscriptionPrice) – měsíční poplatek za předplatné
  • $(ItemPrice) – cena jednoho dotazu mimo tarif
  • $(ItemPriceStatus) – cena za dotaz – DPH/VIES/status činnosti společnosti
  • $(ItemPriceParsed) – cena za dotaz – DPH/VIES/stav činnosti společnosti s analyzovanými daty
  • $(Limit) – maximální počet dotazů v plánu
  • $(RequestDelay) – minimální časový interval mezi dotazy
  • $(DomainLimit) – maximální počet domén (API klíčů)
  • $(OverPlanAllowed) – možnost překročit maximální počet dotazů v plánu
  • $(ExcelAddIn) – přístup k doplňkům Google Sheets™ a Microsoft Excel™
  • $(Stats) – přístup ke statistikám dotazů
  • $(NIPMonitor) – přístup ke sledování statusu společností: DPH/VIES/status aktivity
  • $(FuncGetVIESData) – přístup k funkcím, které ověřují status společnosti v systému VIES
  • $(FuncGetVIESDataParsed) – přístup k funkcím, které ověřují status společnosti v systému VIES a analyzují jméno a adresu obchodníka
  • $(VIESDataCount) – počet dotazů VIES provedených v tomto měsíci
  • $(VIESDataParsedCount) – počet dotazů VIES s analyzovanými daty provedených v tomto měsíci
  • $(TotalCount) – celkový počet dotazů provedených v tomto měsíci

Výchozí FORMÁT: "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)"

Pokud řetězec "JSON" se uvádí jako FORMAT parametr, funkce vrátí kompletní výsledek ve formě řetězce JSON, který lze libovolně analyzovat a dále zpracovávat.

Kontrola stavu systému VIES (zdarma)

VIESAPI_VIES_STATUS() – Tato funkce umožňuje ověřit aktuální stav systému VIES. Vrací celkový stav indikující dostupnost a také seznam jednotlivých členských zemí spolu s aktuálním stavem dostupnosti jejich národních systémů. Parametry by měly být:

  • (volitelný) FORMAT vrácených dat (viz: Tagy, které lze použít jako FORMAT parametr)

=VIESAPI_VIES_STATUS()

Pozornost! Volání funkce nezvýší počet provedených dotazů.

Značky dostupné v VIESAPI_VIES_STATUS funkci lze použít jako FORMAT parametr:

  • $(UID) – unikátní identifikátor generovaný službou viesApi.eu
  • $(Available) – aktuální dostupnost systému VIES (Dostupný, Částečně dostupný, Nedostupný)
  • $(Countries) – seznam států jednotlivých členských zemí (Dostupné, Nedostupné)
  • $(AT), $(FR), $(PL), etc. – stav dostupnosti konkrétní členské země (jako hodnotu tagu použijte dvoupísmenný kód země velkými písmeny)

Výchozí FORMÁT: "$(Available)"

Pokud řetězec "JSON" se uvádí jako FORMAT parametr, funkce vrátí kompletní výsledek ve formě řetězce JSON, který lze libovolně analyzovat a dále zpracovávat.

Další užitečné funkce (zdarma)

VIESAPI_ACCOUNT_STATUS_TOTAL() – Funkce vrací informaci o celkovém počtu dotazů uskutečněných v aktuálním zúčtovacím měsíci pro daný účet (všechny API klíče). Vrátí přesně stejné číslo jako $(TotalCount) značka v VIESAPI_STATUS_ACCOUNT() funkce.

VIESAPI_ACCOUNT_STATUS_LIMIT() – Funkce vrací informaci o maximálním počtu dotazů dostupných v plánu zvoleném uživatelem. Vrátí přesně stejné číslo jako $(Limit) označit VIES.STATUS.ACCOUNT() funkce

VIESAPI_EUVAT_NORM() – Tato funkce opravuje a formátuje DIČ EU (odstraňuje mezery a spojovníky atd.) offline a nenačítá žádná data z VIES:

=VIESAPI_EUVAT_NORM("PL 717-164-20-51")

VIESAPI_EUVAT_VALID() – Funkce pouze offline kontroluje správnost (syntaxe, kontrolní součet) DIČ EU a nenačítá žádná data ze systému VIES. Návraty TRUE pokud je číslo platné popř FALSE pokud není platný:

=VIESAPI_EUVAT_VALID("PL7171642051")

VIESAPI_CONNECTION_STATE() – Funkce vrací aktuální stav konfigurace doplňku.

Pokud funkce vrátí následující hodnotu, znamená to mimo jiné, že ID a API key nebyly uloženy:

ERROR: Connection requires configuration

Po uložení API ID a key, funkce by měla vrátit následující zprávu:

SUCCESS: Production

Google Sheets™ je ochranná známka společnosti Google LLC.