Como integrar a consulta de IVA do VIES ao cadastro de empresas

Na sexta-feira, você está analisando recusas na sua financeira para pequenas empresas quando várias solicitações da Alemanha aparecem em sequência, todas com o motivo “número de IVA não registrado”. Uma das empresas já entrou em contato. A pessoa responsável diz que o número aparece em todas as notas fiscais que emite e quer saber por que a solicitação foi interrompida. Você adicionou a consulta de IVA no mês passado, depois que um corretor enviou uma solicitação com o número de outra empresa. Agora, o mesmo motivo aparece em empresas com histórias bem diferentes, e as solicitações de segunda-feira estão chegando. O que essa resposta deve significar antes de virar uma decisão?

O VIES retorna mais do que válido ou inválido

Uma resposta do VIES pode informar o status do registro, o nome registrado ou um erro no cadastro. O serviço VIES da Comissão Europeia confirma se um número de IVA está registrado, e a resposta pode incluir o nome registrado. Nas consultas que fizemos em nossa máquina em 30 de outubro de 2026, vimos números registrados com nomes informados, números registrados com nomes ocultos, números não registrados e erros no cadastro.

Um número alemão apareceu como válido, com o nome exibido como “---”, e dois minutos depois retornou MS_UNAVAILABLE. Uma regra que considera apenas valid aprovaria a primeira resposta sem ter um nome para comparar. Tratar a ausência do valor valid como se fosse um número inválido pode transformar um problema temporário no cadastro em uma recusa.

respostaexemplostatus HTTPvalidnome registradoregra que considera apenas valid
registrado, com nome informadoIE6388047V200trueGOOGLE IRELAND LIMITEDaprova
registrado, com nome ocultoDE811569869, ESB82846825200true---aprova, sem nada para comparar
não registradoIE1234567X200false---recusa
cadastro sem resposta, RESTDE811569869200ausenteausente, erro MS_UNAVAILABLEnão encontra valid
cadastro sem resposta, SOAPDE811569869200ausentefalha MS_UNAVAILABLEnão encontra valid
cadastro ocupado, endpoint do navegadorLV40003009497200false---, erro MS_MAX_CONCURRENT_REQrecusa

O tipo de resposta faz diferença: o status do registro indica se o número consta no cadastro nacional, e o nome pode ajudar a verificar se a empresa solicitante é a empresa registrada.

A página de status não classifica cada resposta

Classifique cada chamada pela resposta que ela retorna. Use a página de status apenas como contexto. Em nossas consultas, o endpoint do navegador retornou isValid como false junto com MS_MAX_CONCURRENT_REQ quando o cadastro estava ocupado. Considerado isoladamente, esse valor false faz um problema no cadastro parecer um número não registrado.

O endpoint acessado pelo navegador atende à página web do VIES. O contrato REST publicado documenta uma interface separada. O endpoint de status também divergiu das respostas das nossas chamadas nos dois sentidos: indicava que a Alemanha estava disponível enquanto as chamadas alemãs retornavam MS_UNAVAILABLE, e que a Letônia estava indisponível enquanto números letões retornavam respostas válidas com nomes.

A Comissão informa que o VIES obtém dados de cadastros dos Estados-Membros sobre os quais não tem controle. A disponibilidade pode variar de um cadastro para outro e de uma chamada para outra.

Trate erros do serviço antes de decidir o status do registro

Conecte o código do país e o número de IVA da solicitação a um serviço VIES publicado e defina um resultado próprio para erros do serviço. As interfaces publicadas são REST e SOAP. A REST oferece POST /check-vat-number, e a SOAP oferece checkVat. As duas interfaces podem ser usadas sem chave nem conta.

Em uma fonte de dados, envie o código do país e o número da solicitação pelo fluxo de decisão. A fonte de dados adiciona a resposta aos dados da decisão, onde as regras podem classificá-la. Verifique se há um erro antes de ler valid: nas nossas consultas à Alemanha, a REST retornou HTTP 200 com MS_UNAVAILABLE e sem o campo valid. A opção de nova tentativa documentada para REST cobre problemas de conexão e determinados status HTTP. Respostas HTTP 200 com MS_UNAVAILABLE ficam para o fluxo de decisão tratar.

Por exemplo, uma resposta de erro deve levar a um resultado de indisponibilidade, como encaminhamento para análise ou uma nova tentativa posterior. Uma resposta com valid false indica um número não registrado, e uma resposta com valid true indica um número registrado. Teste se cada caminho chega à decisão esperada antes de colocar a integração em produção.

Leve essas verificações para um fluxo de decisão

Crie regras para crédito, fraude ou cobrança e aplique-as a decisões em produção.

Confira o nome registrado separadamente

Um número válido pode pertencer a outra empresa. Compare o nome registrado com o nome empresarial informado na solicitação e mantenha o status do registro e a verificação do nome em valores separados na tabela de decisão.

Nas nossas consultas à Alemanha e à Espanha, os números válidos retornaram o nome e o endereço como “---”. Os valores de correspondência do comerciante foram NOT_PROCESSED, então não havia nome para comparar. Classifique “---” como nome não informado.

Como exemplo de regra, defina a verificação do nome como correspondente quando o nome retornado contiver o nome empresarial da pessoa solicitante, como não informado quando o nome estiver vazio ou for “---”, e como divergente quando não corresponder ao nome empresarial informado. Uma divergência deve ser encaminhada para análise de uma pessoa. Se o VIES não informar o nome, consulte o nome empresarial registrado no registro de empresas correspondente. Para uma solicitação do Reino Unido, a consulta à Companies House é um exemplo de verificação em um registro de empresas.

status do IVAverificação do nomeresultadomotivo
unavailableanyreferVAT_CHECK_UNAVAILABLE
invalidanydeclineVAT_NOT_REGISTERED
validmismatchreferVAT_NAME_MISMATCH
validnot disclosedreferVAT_NAME_NOT_DISCLOSED
validmatchpassOK

Encaminhe uma divergência para análise de uma pessoa e, se o nome não tiver sido informado, consulte o registro de empresas correspondente. O VIES é uma das verificações usadas em conjunto com outras no crédito para pequenas e médias empresas.

Revise os termos antes de armazenar uma resposta em cache

Peça à equipe jurídica que revise os termos do VIES para o uso pretendido antes de ativar o cache. Os termos restringem a retransmissão e outros usos, e proíbem expressamente copiar ou reproduzir o conteúdo. Peça à equipe jurídica que confirme se a integração e as opções de armazenamento pretendidas são permitidas.

Há também um risco técnico. A documentação de cache da fonte de dados descreve o armazenamento em cache de uma resposta que possa ser interpretada e tenha status HTTP abaixo de 400. Assim, uma resposta REST com HTTP 200 e um corpo que possa ser interpretado pode armazenar um erro como MS_UNAVAILABLE da mesma forma que uma resposta comum.

Defina os resultados antes das solicitações de segunda-feira

Antes da chegada das solicitações de segunda-feira, defina os resultados da consulta:

  1. Chame o contrato REST publicado ou o serviço SOAP com o código do país e o número de IVA informados na solicitação. A página do VIES usa um endpoint de navegador separado.
  2. Verifique se há um erro antes de ler valid. Encaminhe o erro para um resultado próprio, como análise ou nova tentativa posterior. Reserve a recusa para um número confirmado como não registrado.
  3. Faça a chamada e leia a resposta. Use a resposta de cada chamada para verificar se ela funcionou. A página de status dá contexto sobre o serviço.
  4. Compare o nome registrado com o nome empresarial informado na solicitação. Defina um resultado próprio para encaminhar à análise de uma pessoa quando um número válido estiver registrado em nome de outra empresa.
  5. Classifique “---” como nome não informado. Consulte o nome no registro de empresas correspondente.
  6. Peça à equipe jurídica que revise os termos e aprove o uso pretendido antes de armazenar respostas do VIES via REST em cache. Considere que respostas de erro HTTP 200 podem ser armazenadas pelo cache como se fossem respostas comuns.
  7. Mantenha a resposta da validação junto à decisão, no formato aprovado pela equipe jurídica, seguindo a recomendação da Comissão para uma fiscalização tributária.

Perguntas frequentes sobre a consulta de IVA do VIES

Existe uma API gratuita para validar números de IVA da União Europeia?

Nossas consultas não precisaram de chave nem de conta. A Comissão não informa um preço para o serviço. Confira nos termos quais usos são permitidos.

O que significa MS_UNAVAILABLE e como a decisão deve tratá-lo?

MS_UNAVAILABLE significa que o serviço do Estado-Membro não está respondendo ou está indisponível. Nas nossas consultas à Alemanha, o erro veio com HTTP 200. Encaminhe-o para um resultado separado, como análise ou nova tentativa posterior, em vez de recusar a solicitação.

Um resultado válido do VIES comprova que a empresa é quem diz ser?

Não. Um número válido pode pertencer a outra empresa. Compare o nome registrado com o nome empresarial informado na solicitação e encaminhe uma divergência para análise de uma pessoa.

O VIES usa REST ou SOAP? Qual devo escolher?

O VIES publica interfaces REST e SOAP. Use o contrato publicado compatível com sua integração e teste como os erros chegam ao fluxo de decisão.

Posso armazenar respostas do VIES e reutilizá-las?

Somente depois que a equipe jurídica revisar os termos e aprovar o uso pretendido. Os termos restringem a retransmissão e outros usos, além de proibirem copiar ou reproduzir o conteúdo. Defina com a equipe jurídica qual registro de validação o uso pretendido permite armazenar antes de guardar ou reutilizar uma resposta.

Quanto tempo leva uma chamada ao VIES?

Nas nossas consultas de 30 de outubro de 2026, a maioria das respostas levou de 0,4 a 0,8 segundos, e algumas demoraram mais. Essas medições foram feitas em uma tarde e não são uma garantia de serviço. Defina um resultado próprio para chamadas lentas ou com falha.

Leve essas verificações para um fluxo de decisão

Crie regras para crédito, fraude ou cobrança e aplique-as a decisões em produção.