Complemento do Planilhas Google™ Validador VIES

Complemento do Planilhas Google™ Validador VIES

API de visualizações do Google SheetsO complemento Google Sheets™ permite verificar de forma rápida e automática o status atual de entidades (contratados) usando a planilha Google Sheets™. Sistema VIES.

Esta documentação contém instruções sobre como integrar o aplicativo Google Sheets™ com o sistema VIES API.

 

 

Instalação e configuração

Instalação

Após acessar o site do Google Workspace Marketplace https://workspace.google.com/marketplace/app/vies_api_eu_vat_validation/1043052728267, Clique no Install botão.

instalar o complemento da API do Google Sheets

Selecionando a conta do Google na qual o complemento VIES Validator para Planilhas Google deve ser instalado e estar disponível:

instalar conta do complemento do Google Sheets da API do Vies

Na próxima tela, você poderá ler o Política de Privacidade e o aplicável Termos de serviço, bem como o escopo dos seus dados que processaremos. Para prosseguir para a próxima etapa da instalação, pressione o Continue botão.

permissões de instalação do complemento do Google Sheets da API do Vies

Confirme que concedeu as permissões necessárias para que o complemento funcione corretamente e pressione o botão. Allow botão:

permissões de instalação do complemento do Google Sheets da API do Vies

O complemento de Validação VIES foi instalado com sucesso em sua conta e estará disponível na guia Extensões após a abertura do Google Sheets. Para continuar, clique aqui. Next:

instalar extensão do complemento do Google Sheets da API do Vies

A tela final do instalador solicitará que você configure o complemento. Clique em “Complete additional setup nowO link abrirá uma nova janela do navegador com a página de documentação atual. Clique no Done Clique no botão e comece a configurar o complemento conforme descrito na seção Configuração.

complemento da API do Google Sheets instalado

Configuração

Após a instalação, o plugin é configurado para o ambiente de teste por padrão (mais detalhes em API de teste página). Para poder chamar funções no ambiente de produção, é necessário configurar o acesso ao site viesapi.eu uma vez. Para isso, acesse qualquer planilha do Google Sheets™ e execute a função:

=VIESAPI_CONNECT_PRODUCTION("identifier";"key")

onde os parâmetros da função são:

  • identifier – o parâmetro deve conter o identificador (ID) gerado na conta no site viesapi.eu,
  • key – o parâmetro deve conter a Chave gerada na conta no site viesapi.eu.

Os detalhes sobre como gerar o identificador e a chave estão descritos no Documentação local na rede Internet.

Para verificar a exatidão da conexão com uma determinada API (teste ou produção), a seguinte função deve ser executada:

=VIESAPI_CONNECT_STATUS()

Que pode retornar valores:

  • SUCCESS: Production – se o suplemento estiver configurado corretamente para funcionar com o ambiente de produção,
  • SUCCESS: Test – se o suplemento estiver configurado corretamente para funcionar com o ambiente de teste,
  • ERROR: Connection requires configuration – em caso de configuração errada.

Se preferir uma configuração com barra lateral, clique em Extensions guia, depois selecione VIES API - EU VAT Validation e finalmente clique Show sidebar Para ativar a barra lateral:

barra lateral de configuração do complemento do Google Sheets da API do Vies

Em seguida, vá para o ID and Key guia para entrar no ID e Key nos campos de texto apropriados, que ficam disponíveis após o login na sua conta da API VIES: https://viesapi.eu/sign-in/

ID e chave de configuração do complemento do Google Sheets da API Vies

Uso

Antes de usar o add-on, você deve se familiarizar com as especificidades de sua operação:

  • Todas as chamadas de função são executadas no modo assíncrono, o que não causa o efeito de congelamento (sem resposta) do aplicativo Planilhas Google™.
  • Adicionar (inserir) uma linha ou coluna não atualiza todas as chamadas de função definidas.
  • Copiar ou mover células que contêm funções não atualiza as chamadas de função definidas.
  • A exclusão de uma linha ou coluna atualizará todas as chamadas de função definidas e enviará consultas para viesApi.eu (somente no caso das configurações padrão do Planilhas Google™). A descrição da alteração das configurações padrão está incluída no capítulo Configuração.
  • Atenção! Não é recomendável executar mais de 500 consultas paralelas, pois o Planilhas Google™ está com dificuldades para lidar com um grande número de chamadas assíncronas.

Obtenha dados da empresa do VIES

VIESAPI_VIES_DATA() – A função recupera todos os dados disponíveis da empresa diretamente do sistema VIES. Os parâmetros devem ser:

  • Número de identificação fiscal europeu (IVA UE),
  • (opcional) FORMAT dos dados retornados (veja: Tags que podem ser usadas como FORMAT parâmetro).

=VIESAPI_VIES_DATA("PL7171642051")

Se você precisar apenas do status da empresa no VIES, use a seguinte consulta:

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

Se o status devolvido for Sim, significa que a empresa possui um número de IVA da UE válido.

Marcas disponíveis no VIESAPI_VIES_DATA função que pode ser usada como FORMAT parâmetro:

  • $(UID) – identificador único gerado pelo serviço viesApi.eu
  • $(CountryCode) – código do país
  • $(VATNumber) – número de IVA europeu
  • $(Valid) – resposta do serviço VIES, informando sobre o status atual do IVA da UE da empresa verificada (Yes/No)
  • $(TraderName) – nome de registro da empresa
  • $(TraderCompanyType) – tipo de negócio
  • $(TraderAddress) – endereço comercial onde a empresa está registrada
  • $(ID) – identificador único gerado pelo sistema VIES (número de consulta)
  • $(Date) – a data em que a resposta foi gerada
  • $(Source) – a fonte dos dados

Formato padrão: "$(TraderName), $(TraderAddress)"

Se a corda "JSON" é dado como o FORMAT parâmetro, a função retornará o resultado completo na forma de uma string JSON, que pode ser analisada livremente e processada posteriormente:

=VIESAPI_VIES_DATA("PL7171642051";"JSON")

Obtenha dados analisados da empresa do VIES

VIESAPI_VIES_DATA_PARSED() – A função recupera todos os dados disponíveis da empresa diretamente do sistema VIES. Além disso, o nome e o endereço da empresa são retornados como dados analisados, divididos em atributos separados. Os parâmetros devem ser:

  • Número de identificação fiscal europeu (IVA UE),
  • (opcional) FORMAT dos dados retornados (veja: Tags que podem ser usadas como FORMAT parâmetro).

=VIESAPI_VIES_DATA_PARSED("PL7171642051")

Se você precisar apenas do status da empresa no VIES, use a seguinte consulta:

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

Se o status devolvido for Sim, significa que a empresa possui um número de IVA da UE válido.

Marcas disponíveis no VIESAPI_VIES_DATA_PARSED função que pode ser usada como FORMAT parâmetro:

  • $(UID) – identificador único gerado pelo serviço viesApi.eu
  • $(CountryCode) – código do país
  • $(VATNumber) – número de IVA europeu
  • $(Valid) – resposta do serviço VIES, informando sobre o status atual do IVA da UE da empresa verificada (Yes/No)
  • $(TraderName) – nome de registro da empresa
  • $(TraderNameComponents.Name) – nome da empresa de traderName (sem forma jurídica)
  • $(TraderNameComponents.LegalForm) – nome da forma jurídica extraído de traderName (sem nome da empresa)
  • $(TraderNameComponents.LegalFormCanonicalId) – identificador de dicionário de forma jurídica
  • $(TraderNameComponents.LegalFormCanonicalName) – nome do dicionário da forma jurídica
  • $(TraderCompanyType) – tipo de negócio
  • $(TraderAddress) – endereço comercial onde a empresa está registrada
  • $(TraderAddressComponents.Country) – nome do país do comerciante na sua língua nacional
  • $(TraderAddressComponents.PostalCode) – código postal do endereço do comerciante
  • $(TraderAddressComponents.City) – cidade do endereço do comerciante
  • $(TraderAddressComponents.Street) – rua do endereço do comerciante
  • $(TraderAddressComponents.StreetNumber) – número do prédio da rua do endereço do comerciante
  • $(TraderAddressComponents.HouseNumber) – número do apartamento/escritório do endereço do comerciante
  • $(TraderAddressComponents.Other) – outros detalhes do endereço (nome da área, nome do prédio, número do andar, etc.)
  • $(ID) – identificador único gerado pelo sistema VIES (número de consulta)
  • $(Date) – a data em que a resposta foi gerada
  • $(Source) – a fonte dos dados

Formato padrão: "$(TraderName), $(TraderAddress)"

Se a corda "JSON" é dado como o FORMAT parâmetro, a função retornará o resultado completo na forma de uma string JSON, que pode ser analisada livremente e processada posteriormente:

=VIESAPI_VIES_DATA_PARSED("PL7171642051";"JSON")

Verificação do status da conta do usuário (gratuita)

VIESAPI_ACCOUNT_STATUS() – A função retorna informações básicas sobre o plano atualmente utilizado pelo usuário. Os parâmetros devem ser:

  • (opcional) FORMAT dos dados retornados (veja: Tags que podem ser usadas como FORMAT parâmetro)

=VIESAPI_ACCOUNT_STATUS()

Atenção! Chamar a função não aumenta o número de consultas feitas.

As etiquetas disponíveis no VIESAPI_ACCOUNT_STATUS função pode ser usada como FORMAT parâmetro:

  • $(UID) – identificador único gerado pelo serviço viesApi.eu
  • $(BillingPlanName) – nome do plano atual
  • $(SubscriptionPrice) – taxa de assinatura mensal
  • $(ItemPrice) – custo de uma única consulta fora do plano
  • $(ItemPriceStatus) – custo por consulta – IVA/VIES/status de atividade da empresa
  • $(ItemPriceParsed) – custo por consulta – IVA/VIES/status de atividade da empresa com dados analisados
  • $(Limit) – número máximo de consultas no plano
  • $(RequestDelay) – intervalo mínimo de tempo entre consultas
  • $(DomainLimit) – número máximo de domínios (chaves de API)
  • $(OverPlanAllowed) – capacidade de exceder o número máximo de consultas do plano
  • $(ExcelAddIn) – acesso ao suplemento Google Sheets™ e Microsoft Excel™
  • $(Stats) – acesso às estatísticas de consulta
  • $(NIPMonitor) – acesso ao monitoramento do status das empresas: IVA/VIES/status de atividade
  • $(FuncGetVIESData) – acesso a funções que verificam o status da empresa no sistema VIES
  • $(FuncGetVIESDataParsed) – acesso a funções que verificam o status da empresa no sistema VIES e analisam o nome e endereço do comerciante
  • $(VIESDataCount) – número de consultas VIES realizadas neste mês
  • $(VIESDataParsedCount) – número de consultas VIES com dados analisados realizadas neste mês
  • $(TotalCount) – número total de consultas realizadas neste mês

FORMATO padrão: "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)"

Se a corda "JSON" é dado como o FORMAT parâmetro, a função retornará o resultado completo na forma de uma string JSON, que pode ser analisada livremente e processada posteriormente.

Verificação de status do sistema VIES (gratuita)

VIESAPI_VIES_STATUS() – Esta função permite verificar o status atual do sistema VIES. Ela retorna um status geral indicando a disponibilidade, bem como uma lista de países membros individuais, juntamente com o status atual de disponibilidade de seus sistemas nacionais. Os parâmetros devem ser:

  • (opcional) FORMAT dos dados retornados (veja: Tags que podem ser usadas como FORMAT parâmetro)

=VIESAPI_VIES_STATUS()

Atenção! Chamar a função não aumenta o número de consultas feitas.

As etiquetas disponíveis no VIESAPI_VIES_STATUS função pode ser usada como FORMAT parâmetro:

  • $(UID) – identificador único gerado pelo serviço viesApi.eu
  • $(Available) – disponibilidade atual do sistema VIES (Disponível, Parcialmente disponível, Indisponível)
  • $(Countries) – lista de estados de países membros individuais (Disponível, Indisponível)
  • $(AT), $(FR), $(PL), etc. – status de disponibilidade de um país membro específico (use o código do país com 2 letras maiúsculas como valor da tag)

FORMATO padrão: "$(Available)"

Se a corda "JSON" é dado como o FORMAT parâmetro, a função retornará o resultado completo na forma de uma string JSON, que pode ser analisada livremente e processada posteriormente.

Outras funções úteis (gratuitas)

VIESAPI_ACCOUNT_STATUS_TOTAL() – A função retorna informações sobre o número total de consultas feitas no mês de cobrança atual para uma determinada conta (todas as chaves de API). Retorna exatamente o mesmo número que o $(TotalCount) etiqueta no VIESAPI_STATUS_ACCOUNT() função.

VIESAPI_ACCOUNT_STATUS_LIMIT() – A função retorna informações sobre o número máximo de consultas disponíveis no plano selecionado pelo usuário. Retorna exatamente o mesmo número que o $(Limit) marcar em VIES.STATUS.ACCOUNT() função

VIESAPI_EUVAT_NORM() – Este recurso corrige e formata o número de IVA da UE (remove espaços e hífens etc.) offline e não recupera nenhum dado do VIES:

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

VIESAPI_EUVAT_VALID() – A função apenas verifica a exatidão (sintaxe, soma de verificação) do número de IVA da UE offline e não recupera nenhum dado do sistema VIES. Devoluções TRUE se o número é válido ou FALSE se não for válido:

=VIESAPI_EUVAT_VALID("PL7171642051")

VIESAPI_CONNECTION_STATE() – A função retorna o status atual da configuração do suplemento.

Se a função retornar o valor a seguir, significa, entre outros, que o ID e API key não foram salvos:

ERROR: Connection requires configuration

Depois de salvar o API ID e key, a função deve retornar a seguinte mensagem:

SUCCESS: Production

Google Sheets™ é uma marca registrada da Google LLC.