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.
| resposta | exemplo | status HTTP | valid | nome registrado | regra que considera apenas valid |
|---|---|---|---|---|---|
| registrado, com nome informado | IE6388047V | 200 | true | GOOGLE IRELAND LIMITED | aprova |
| registrado, com nome oculto | DE811569869, ESB82846825 | 200 | true | --- | aprova, sem nada para comparar |
| não registrado | IE1234567X | 200 | false | --- | recusa |
| cadastro sem resposta, REST | DE811569869 | 200 | ausente | ausente, erro MS_UNAVAILABLE | não encontra valid |
| cadastro sem resposta, SOAP | DE811569869 | 200 | ausente | falha MS_UNAVAILABLE | não encontra valid |
| cadastro ocupado, endpoint do navegador | LV40003009497 | 200 | false | ---, erro MS_MAX_CONCURRENT_REQ | recusa |
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.
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 IVA | verificação do nome | resultado | motivo |
|---|---|---|---|
| unavailable | any | refer | VAT_CHECK_UNAVAILABLE |
| invalid | any | decline | VAT_NOT_REGISTERED |
| valid | mismatch | refer | VAT_NAME_MISMATCH |
| valid | not disclosed | refer | VAT_NAME_NOT_DISCLOSED |
| valid | match | pass | OK |
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:
- 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.
- 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. - 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.
- 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.
- Classifique “---” como nome não informado. Consulte o nome no registro de empresas correspondente.
- 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.
- 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.