API de validação do número de IVA: verifique os IDs fiscais da UE em um POST
Valide os números de IVA de todos os 27 estados membros da UE com uma chamada de API. Retorna validade, código do país e número formatado. Nível gratuito, sem XML SOAP.
Você vende software para empresas na Europa. A legislação fiscal da UE exige que você valide o IVA do comprador ID antes de aplicar a autoliquidação (0% de IVA). O serviço oficial VIES não tem tempo de atividade confiável e retorna XML SOAP. Você precisa de uma alternativa RESTful mais rápida.
O botoi /v1/validate/vat endpoint valida números de IVA para todos os 27 membros da UE
estados e o Reino Unido. Envie um POST, obtenha uma resposta JSON com validade, código do país e o
número formatado. Sem análise XML. Nenhum arquivo WSDL. Sem intervalos devido ao governo sobrecarregado
servidores.
A chamada da API
Envie um número de IVA com o prefixo do país de duas letras:
Resposta:
O valid campo é true quando o número corresponde ao formato esperado
para o seu país. O country_code e country campos dizem a você
a qual jurisdição o número pertence.
Quando um número falha na validação
Se o número não corresponder ao padrão esperado, valid volta
false. A resposta ainda inclui o país detectado:
Os números de IVA alemães exigem exatamente 9 dígitos após o DE prefixo. Este tem 5.
Seu frontend pode exibir o nome do país e o formato esperado para ajudar o usuário a corrigir seu
entrada.
Integração de checkout Stripe
Antes de criar uma sessão de checkout Stripe, valide o ID de IVA do comprador. Se for válido, defina
o cliente para tax_exempt: "reverse" então Stripe cobra 0% de IVA. Se for
inválido, rejeite o formulário e peça ao comprador para corrigi-lo.
Isto evita dois problemas comuns: cobrar IVA a uma empresa que deveria estar isenta (criando uma dor de cabeça no reembolso) e concedendo uma isenção fiscal a alguém com um número de IVA falso (criando um problema de auditoria).
Geração de fatura com IVA condicional
Ao gerar uma fatura, você precisa decidir a taxa de IVA. As regras:
- Venda B2B no mesmo país: cobre a sua taxa de IVA nacional.
- Venda B2B transfronteiriça com um ID de IVA válido: aplicar autoliquidação (0%).
- ID de IVA inválido ou ausente: cobrar a taxa local do comprador.
O country_code da resposta da API aciona esta lógica:
Validação do formulário de inscrição SaaS B2B
Adicione um campo de número de IVA ao seu formulário de inscrição e valide-o ao enviar. Se for válido, preencha automaticamente o menu suspenso do país. Se for inválido, mostre um erro antes que o formulário chegue ao seu backend.
Isso mantém dados incorretos fora do seu sistema de faturamento. Ele também evita que sua equipe financeira precise manualmente verificar os números de IVA depois que o cliente já se inscreveu e começou a usar o produto.
Formato do IVA por país
Cada país da UE tem um formato diferente para números de identificação de IVA. A API valida contra todos esses padrões:
A lista completa abrange todos os 27 estados membros da UE mais o Reino Unido. Os formatos variam de 8 dígitos (Dinamarca, Luxemburgo) para 12 dígitos (Suécia). Alguns países incluem letras no corpo do número (França, Espanha, Irlanda).
Validação de formato vs pesquisa VIES
Esta API valida o estrutura de um número de IVA. Confirma o prefixo, comprimento, e o padrão de caracteres correspondem às regras desse país. Não questiona a opinião da Comissão Europeia Banco de dados VIES para confirmar se o número está registrado ativamente.
Para a maioria dos fluxos de checkout, a validação do formato é o primeiro passo correto. Ele detecta erros de digitação, falta prefixos e números inventados instantaneamente, sem depender de um serviço externo que seja frequentemente para baixo. Se você também precisar do status do registro, ligue para o VIES após a verificação do formato ser aprovada. Esta abordagem em duas etapas reduz as chamadas VIES em 15-30% (todos os formatos inválidos nunca atingem o serviço lento).
Pontos-chave
O nível gratuito cobre o desenvolvimento e o uso de produção de baixo volume. Para checkout de alto tráfego
fluxos, adicione sua chave de API no Authorization: Bearer cabeçalho. Verifique o
Documentos da API
para a referência completa do endpoint e o
playground interativo para testar os números de IVA no seu navegador.
FAQ
- Quais países são suportados pela API de validação de IVA?
- Todos os 27 estados membros da UE, mais o Reino Unido (prefixo GB). Cada país tem seu próprio padrão de formato. A API detecta o país a partir do prefixo de duas letras e valida com base no regex correto para essa jurisdição.
- Isso substitui o serviço VIES SOAP?
- Ele substitui a parte de validação de formato. O VIES confirma se um número específico está registado junto de uma autoridade fiscal nacional. Esta API valida estrutura e formato instantaneamente, sem depender do tempo de atividade do VIES. Use os dois juntos: primeiro verifique o formato e depois procure no VIES o status registrado.
- O número de IVA é armazenado após validação?
- Não. O número é processado na memória e descartado após a resposta. Nada é gravado no disco ou em qualquer sistema externo.
- Posso validar os números de IVA do Reino Unido após o Brexit?
- Os números de IVA do Reino Unido (prefixo GB) seguem um padrão conhecido e podem ser validados estruturalmente. Já não fazem parte do sistema VIES da UE, mas a verificação do formato ainda funciona.
- O que acontece se eu omitir o prefixo do país?
- A API exige o prefixo do país com duas letras (por exemplo, "DE", "FR", "NL"). Sem ele, o endpoint retorna um erro explicando que o código do país está ausente ou não é compatível.
Comece a construir com botoi
150+ endpoints de API para consultas, processamento de texto, geração de imagens e utilitários para desenvolvedores. Plano gratuito, sem cartão de crédito.