O suplemento do Excel permite verificar de forma rápida e automática as entidades (contratantes) usando a planilha do Excel em termos de seu status atual no Sistema VIES.

Este capítulo contém instruções sobre como integrar o aplicativo Microsoft Excel ao sistema VIES API. O complemento fornecido foi testado com sucesso nas seguintes versões do MS Excel: 2007, 2010, 2013, 2016, 2019 (nos sistemas operacionais Windows e macOS) e 2021 (nos sistemas operacionais Windows e macOS) e na versão web do Excel 365.

A versão mais recente do complemento para Excel 2007, 2010, 2013, 2016 e 2019 está sempre disponível para download no Baixar página. O complemento pode ser instalado nas versões de 32 e 64 bits do Excel. Atenção! Selecione a versão (32 ou 64 bits) que corresponde à versão do Excel, não o sistema operacional.

Para baixar e instalar o complemento para MacOS e Excel 2021 para Windows e Excel365, visite a loja oficial da Microsoft: https://appsource.microsoft.com.

A funcionalidade completa do suplemento do Excel pode ser verificada – sem a necessidade de criar uma conta - usando o fornecido API de teste. A página também descreve como configurar um suplemento do Excel para uso na API fornecida para teste.

O uso do add-in na API de produção requer a criação de uma conta no site viesapi.eu, a compra de um mínimo do plano de negócios e a geração de uma chave e seu identificador. O processo de registro e criação de uma conta, bem como geração de chaves, foi descrito no Documentação local na rede Internet.

Instalação e configuração para MS Excel 2021 e Excel 365 da Microsoft Store (AppSource)

Instalação

Depois de entrar no site da Microsoft Official Store https://appsource.microsoft.com, Clique no Get it now botão.

Será exibida uma janela de login na qual você deve inserir o endereço de e-mail para o qual criou uma conta na Microsoft (privada ou corporativa). Se você não tiver essa conta, poderá criar uma e continuar o processo de instalação ou interromper a instalação e usar a opção de instalar o complemento de uma das maneiras descritas acima.

Para baixar e instalar o suplemento do Excel 2021 ou Excel 365 (web), vá para o Insert [1], encontre a seção Add-ins e clique no botão OfficeAdd-ins botão [2]. Em seguida, na janela aberta, digite a palavra 'viesapi ′ [3] no campo de pesquisa e pressione o ícone da lupa. Um complemento chamado “VIES API - EU VAT Validation” deve ser encontrado, que deve ser instalado clicando no botão Add botão [4]. Todas as etapas acima estão ilustradas na captura de tela abaixo:

Após clicar no Add botão, uma tela deve aparecer onde você pode ler os termos da licença e as regras de proteção de privacidade.

Para iniciar a instalação do suplemento, pressione Continue botão.

Configuração

Após instalar corretamente o plugin, você deverá ver uma tela semelhante à apresentada abaixo. No Home menu [1], encontre o ícone que representa o VIES API Panel [2] e clique nele para exibir o painel lateral. Imediatamente após a instalação, o add-in é configurado para funcionar em um ambiente de teste – detalhes sobre o Página de teste da API. Usar o add-on no modo de teste não requer a criação de uma conta no viesapi.eu local na rede Internet.

Para mudar o add-on para o ambiente de produção, clique no botão ID and key guia [3] e digite a Key e chave ID, que você pode encontrar depois de fazer login na sua conta no site viesapi.eu na seção “API Keys" aba. Após inserir os dois valores, pressione o botão Save botão.

Se você ainda não possui uma conta em nosso site, clique no link em viesapi.eu [4] e passar pelo processo de registro, que está descrito detalhadamente no Documentação página.

Instalação e configuração para Excel: 2007, 2010, 2013, 2016 e 2019

Instalação

Obtenha a versão mais recente do suplemento para Excel 2007, 2010, 2013, 2016 e 2019 do Baixar página. Inicie o MS Excel e vá para File> Options, em seguida, selecione Add-ins [1] no menu.

Na parte inferior das configurações, selecione Excel Add-ins [2] e clique no botão Go botão [3].

Usuários avançados podem adicionar um complemento do Developer guia [1], depois clique Excel Add-ins [2] e clique no botão Browse botão [3]:

No Add-ins janela, clique no Browse botão, vá para o diretório onde o viesapi-ms-excel-addin-version-number.zip arquivo foi descompactado e selecione:

• viesapiExcel.xll – para a versão de 32 bits do Excel,
• viesapiExcel64.xll – para a versão de 64 bits do Excel.

O carregamento correto do add-in é mostrado na figura abaixo [1].

Basta clicar no OK botão [2] para disponibilizar no Excel as funções implementadas no add-in.

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 Excel 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.

Por padrão, todos os documentos do Excel são configurados para calcular automaticamente a planilha. Definir esta opção implica que todas as fórmulas são chamadas quando são feitas alterações que afetam a fórmula. Um exemplo disso é excluir uma linha em uma planilha.

Para evitar a chamada automática de todas as funções definidas em uma determinada planilha, que está relacionada ao envio automático de consultas para a API do site veisapi.eu, altere a opção de cálculo da pasta de trabalho para Manual:

1. De File cardápio, selecionar Options
2. Destaque o Formulas aba
3. Na seção Opções de cálculo, selecione a configuração: Manual e desmarque a opção adicional: Recalculate the workbook before saving.
4. É necessário salvar as alterações feitas na planilha.

Com a planilha Excel configurada desta forma, para forçar a atualização de todas as fórmulas definidas, pressione a combinação de teclas:

CTRL + ALT + SHIFT + F9

Atualize o plugin para a versão mais recente

Atenção!O procedimento a seguir para atualizar o suplemento do Excel funciona corretamente nas versões do MS Excel 2019, 2021 e Excel 365, onde o suplemento pode ser instalado na Microsoft Store.

Atenção! Após instalar a versão mais recente, você deve reconfigurar o add-on, ou seja, inserir e salvar o ID e a chave.

Para instalar a versão mais recente do suplemento do Excel, siga estas etapas:

1. Verifique a versão do add-in instalado chamando a fórmula =VIESAPI.VERSION(). A versão mais recente do complemento é 1.2.8

2. Limpando o cache do MS Excel, conforme procedimento descrito na página de documentação oficial: https://learn.microsoft.com/en-us/office/dev/add-ins/testing/clear-cache

3. Após concluir todos os passos do ponto 2, reinicie o aplicativo MS Excel.

4. Durante a reinicialização, o aplicativo MS Excel baixará a versão mais recente do suplemento da Microsoft Store.

5. Configure o add-on inserindo o ID e a chave baixados após o login em sua conta em nosso local na rede Internet – Aba “Chaves de API”.

Uso

Veja como verificar de forma automática e massiva o status de IVA da UE de empresas no sistema VIES usando nosso suplemento do Excel:

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 Excel.
• 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 de configurações padrão do Excel). A descrição da alteração das configurações padrão está incluída no capítulo Configuração.
• Atenção! Não é recomendado executar mais de 500 consultas paralelas porque o Excel está tendo problemas 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 do MS 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