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 Office
Add-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:
- De
File
cardápio, selecionarOptions
- Destaque o
Formulas
aba - Na seção Opções de cálculo, selecione a configuração:
Manual
e desmarque a opção adicional:Recalculate the workbook before saving
. - É 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 comoFORMAT
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 comoFORMAT
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 comoFORMAT
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 comoFORMAT
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