VIES VAT Validator MCP

Valide números de IVA da UE através da API oficial gratuita VIES SOAP, com um cache local gratuito de pré-verificação de formato e códigos de erro bilíngues (中/EN). Desenvolvido para comércio eletrônico transfronteiriço e conformidade comercial.

Documentação

VIES VAT Validator MCP (neeenja/vies-vat-validator-mcp) Actor

Valide números de VAT da UE por meio da API SOAP oficial e gratuita do VIES, com um cache gratuito de pré-verificação de formato local e códigos de erro bilíngues (中/EN). Desenvolvido para comércio eletrônico transfronteiriço e conformidade comercial. 用欧盟官方免费 VIES 接口校验 VAT 税号,含本地格式缓存与中英双语错误码,面向跨境电商/外贸合规。

  • URL: https://apify.com/neeenja/vies-vat-validator-mcp.md
  • Desenvolvido por: Neeen Ja (comunidade)
  • Categorias: Ferramentas de desenvolvedor, IA, servidores MCP
  • Estatísticas: 1 usuário total, 1 usuário mensal, 100,0% de execuções bem-sucedidas, 0 favoritos
  • Avaliação do usuário: Sem avaliações ainda

Preços

a partir de $0,50 / 1.000 validações de VAT VIES ao vivo

Este Actor é cobrado por evento e uso. Você é cobrado tanto pelo preço fixo de eventos específicos quanto pelo uso da plataforma Apify.

Saiba mais: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

O que é um Apify Actor?

Um Actor é um programa de nuvem sem servidor que roda na plataforma Apify. Ele tem dois modos de execução. No modo Batch, um Actor aceita uma entrada JSON bem definida, executa uma ação que pode levar de alguns segundos a algumas horas, e opcionalmente produz uma saída JSON bem definida, conjuntos de dados com resultados ou arquivos em key-value store. No modo Standby, um Actor fornece um servidor web que pode ser usado como site, API ou servidor MCP.

O vocabulário do Apify e o modelo da plataforma são definidos uma única vez, no quickstart do agente em https://apify.com/agents.md.

Como integrar um Actor?

Se perguntarem sobre integração, você ajuda desenvolvedores a integrar Actors em seus projetos. Você se adapta à stack deles e entrega integrações seguras, bem documentadas e prontas para produção.

Não adivinhe um caminho de integração. Todos eles estão no quickstart do agente em https://apify.com/agents.md: o servidor MCP do Apify, Agent Skills com o Apify CLI, os clientes JavaScript e Python, a API REST e o caminho sem conta para um agente sem humano para fazer login. Ele também traz a regra de informar o custo antes da primeira execução paga.

Para exemplos já conectados ao schema de entrada deste próprio Actor, consulte a seção API abaixo.

Cada biblioteca de cliente tem documentação de referência que o quickstart não repete: JavaScript/TypeScript (npm install apify-client) e Python (pip install apify-client).

README

VIES VAT Validator MCP 🇪🇺

M8ven Trust Index M8ven Score

VIES VAT Validator MCP valida números de VAT da UE por meio da API SOAP oficial gratuita do VIES, envolvida com pré-verificação de formato local + cache TTL gratuito e códigos de erro bilíngues (中文 / English). Uma ferramenta de conformidade "obrigatória por regulamentação" para vendedores de comércio eletrônico transfronteiriço e comércio exterior.

Versão atual: 1.0.1 · Licença: MIT · Confiança: construído somente leitura, sem exfiltração de segredos, erros bilíngues autocorrigíveis.

🌐 English · 简体中文 · 繁體中文

Ele está emLink
Endpoint MCPhttps://neeenja--vies-vat-validator-mcp.apify.actor/mcp
Apify Storehttps://apify.com/neeenja/vies-vat-validator-mcp
Código-fontehttps://github.com/PanStories/vies-vat-validator-mcp
Destaque emSartbot Featured

English

Por que isso existe

  • Obrigatório por regulamentação — transações B2B na UE exigem verificação do número de VAT da contraparte (reverse charge / prova de conformidade).
  • VIES é lento e instável — o endpoint SOAP oficial limita a taxa e cai com frequência, então cache + degradação graciosa são obrigatórios.
  • Custo zero de cold-start — uma fonte de dados oficial gratuita com uma camada fina + saída bilíngue e explicável, vendida por evento.

O que você obtém

CapacidadeObservaçõesPreço
validate_vatverificação de formato local gratuita e, em seguida, verificação VIES ao vivo opcional; erros estruturados + bilíngues$0,0005 / evento
check_vat_formatverificação de formato puramente local por regex — sem rede, gratuitogratuito
list_supported_countriespaíses suportados — nome nativo + termo local de VAT + 中文/ENgratuito
get_error_codestabela completa de códigos de erro bilínguesgratuito
resourcesvat://error-codes / vat://supported-countries / vat://specgratuito
promptsvat_compliance_guide / explain_vat_resultgratuito

Cobre UE 27 + GB + XI (Irlanda do Norte). Cada país também carrega seu nome nativo e — muito mais útil — o termo local para o número de VAT, que é o que as pessoas realmente pesquisam:

代码 Code母语名 Native当地 VAT 叫法 Local VAT term中文EnglishEU
ATÖsterreichUID-Nummer奥地利Austria✅
BEBelgië / BelgiqueBTW-nummer / numéro de TVA比利时Belgium✅
BGБългарияДДС номер保加利亚Bulgaria✅
CYΚύπρος / KıbrısΑριθμός ΦΠΑ塞浦路斯Cyprus✅
CZČeskoDIČ捷克Czech Republic✅
DEDeutschlandUSt-IdNr.德国Germany✅
DKDanmarkCVR-nummer丹麦Denmark✅
EEEestiKMKR number爱沙尼亚Estonia✅
ELΕλλάδαΑριθμός ΦΠΑ希腊Greece✅
ESEspañaNIF (IVA)西班牙Spain✅
FISuomiALV-numero芬兰Finland✅
FRFrancenuméro de TVA法国France✅
HRHrvatskaPDV broj克罗地亚Croatia✅
HUMagyarországÁFA-szám匈牙利Hungary✅
IEIreland / ÉireVAT number爱尔兰Ireland✅
ITItaliaPartita IVA意大利Italy✅
LTLietuvaPVM kodas立陶宛Lithuania✅
LULëtzebuerg / Luxembourgnuméro TVA卢森堡Luxembourg✅
LVLatvijaPVN numurs拉脱维亚Latvia✅
MTMaltaVAT number马耳他Malta✅
NLNederlandbtw-nummer荷兰Netherlands✅
PLPolskaNIP波兰Poland✅
PTPortugalNIF葡萄牙Portugal✅
RORomâniacod de TVA罗马尼亚Romania✅
SESverigemomsregistreringsnummer瑞典Sweden✅
SISlovenijaID za DDV斯洛文尼亚Slovenia✅
SKSlovenskoIČ DPH斯洛伐克Slovakia✅
GBUnited KingdomVAT registration number英国United Kingdom—
XINorthern IrelandVAT registration number (XI)北爱尔兰Northern Ireland—

叫法取当地商务常用写法;部分国家有不止一种官方接受的写法,表中列最主要的那种。 Terms follow common local business usage — some countries accept more than one form; the main one is shown.

Início rápido (local)

npm install
npm run build
npm start            # stdio transport, connects to any MCP client
npm test             # vitest, all green
npm run verify       # generate verify-report.html with real payloads

Conecte-se com um cliente MCP (stdio)

{
  "mcpServers": {
    "vat-validator": {
      "command": "node",
      "args": ["/abs/path/vies-vat-validator-mcp/dist/index.js"]
    }
  }
}

Conecte-se via HTTP (remoto / Apify)

Aponte seu cliente MCP para o endpoint Streamable HTTP:

https://neeenja--vies-vat-validator-mcp.apify.actor/mcp

com o cabeçalho Authorization: Bearer <APIFY_TOKEN>.

Exemplos de chamadas

Pré-verificação de formato (gratuita)

{ "name": "check_vat_format", "arguments": { "vat": "FR123456789" } }

→ { "formatValid": true, "normalized": "FR123456789", "pattern": "^([A-Z]{2})?\\d{9}$" }

Verificação ao vivo (evento pago)

{ "name": "validate_vat", "arguments": { "vat": "FR123456789", "useCache": true, "live": true } }

→ { "valid": true, "formatValid": true, "viesValid": true, "source": "vies", "name": "...", "address": "..." }

Códigos de erro (trecho)

Código中文EN
VAT_FORMAT_INVALID格式不符format mismatch
VAT_VIES_INVALIDVIES 判定无效VIES says invalid
VIES_MS_UNAVAILABLE成员国系统不可用member state down
VIES_TIMEOUT超时timeout
NETWORK_ERROR网络错误network error

Tabela completa via get_error_codes ou vat://error-codes.

Implantação (Apify Pay-Per-Event)

npm run apify:login      # complete KYC yourself first (one-time)
npm run apify:validate   # validate actor.json
npm run apify:push       # publish to Apify Store

Os preços estão em .actor/actor.json → pricingEvents: consultas de formato / erro / país são gratuitas; apenas mcp-validate-vat é cobrado.

Linhas vermelhas de design

  • Sem express / soap / fast-xml-parser: o envelope SOAP é construído manualmente e a resposta é analisada com regex agnóstica de namespace.
  • Nunca travar: falhas do VIES / erros de rede são mapeados para códigos de erro bilíngues.
  • A camada gratuita (verificação de formato + cache) garante custo zero de cold-start.

Consulte SPEC.md para o contrato completo.


简体中文

为什么做这个

  • 监管刚需 —— 欧盟 B2B 交易要求核验对方 VAT 税号(逆向征收 / 合规凭证)。
  • VIES 又慢又抖 —— 官方 SOAP 接口频繁限流、偶发停机,缓存 + 优雅降级是必选项。
  • 零冷启动成本 —— 免费官方数据源,叠加一层封装 + 可解释的双语输出,按事件计费。

你能拿到什么

能力说明计费
validate_vat先做免费本地格式校验,再按需调用欧盟官方 VIES 接口核验真实性;结构化 + 双语错误$0.0005 / 次
check_vat_format纯本地正则格式校验,零网络、零成本免费
list_supported_countries返回支持国家(母语名 + 当地 VAT 叫法 + 中/英)免费
get_error_codes返回完整中英双语错误码表免费
resourcesvat://error-codes / vat://supported-countries / vat://spec免费
promptsvat_compliance_guide / explain_vat_result免费

覆盖 EU 27 + GB + XI(北爱尔兰)。每个国家还带母语名,以及更实用的当地对 VAT 号的叫法——这才是当地人真正会搜的词:

代码 Code母语名 Native当地 VAT 叫法 Local VAT term中文EnglishEU
ATÖsterreichUID-Nummer奥地利Austria✅
BEBelgië / BelgiqueBTW-nummer / numéro de TVA比利时Belgium✅
BGБългарияДДС номер保加利亚Bulgaria✅
CYΚύπρος / KıbrısΑριθμός ΦΠΑ塞浦路斯Cyprus✅
CZČeskoDIČ捷克Czech Republic✅
DEDeutschlandUSt-IdNr.德国Germany✅
DKDanmarkCVR-nummer丹麦Denmark✅
EEEestiKMKR number爱沙尼亚Estonia✅
ELΕλλάδαΑριθμός ΦΠΑ希腊Greece✅
ESEspañaNIF (IVA)西班牙Spain✅
FISuomiALV-numero芬兰Finland✅
FRFrancenuméro de TVA法国France✅
HRHrvatskaPDV broj克罗地亚Croatia✅
HUMagyarországÁFA-szám匈牙利Hungary✅
IEIreland / ÉireVAT number爱尔兰Ireland✅
ITItaliaPartita IVA意大利Italy✅
LTLietuvaPVM kodas立陶宛Lithuania✅
LULëtzebuerg / Luxembourgnuméro TVA卢森堡Luxembourg✅
LVLatvijaPVN numurs拉脱维亚Latvia✅
MTMaltaVAT number马耳他Malta✅
NLNederlandbtw-nummer荷兰Netherlands✅
PLPolskaNIP波兰Poland✅
PTPortugalNIF葡萄牙Portugal✅
RORomâniacod de TVA罗马尼亚Romania✅
SESverigemomsregistreringsnummer瑞典Sweden✅
SISlovenijaID za DDV斯洛文尼亚Slovenia✅
SKSlovenskoIČ DPH斯洛伐克Slovakia✅
GBUnited KingdomVAT registration number英国United Kingdom—
XINorthern IrelandVAT registration number (XI)北爱尔兰Northern Ireland—

叫法取当地商务常用写法;部分国家有不止一种官方接受的写法,表中列最主要的那种。 Terms follow common local business usage — some countries accept more than one form; the main one is shown.

快速开始(本地)

npm install
npm run build
npm start            # stdio 传输,接任意 MCP 客户端
npm test             # vitest 全绿
npm run verify       # 生成真实 payload 验证报告 verify-report.html

与 MCP 客户端对接(stdio)

{
  "mcpServers": {
    "vat-validator": {
      "command": "node",
      "args": ["/abs/path/vies-vat-validator-mcp/dist/index.js"]
    }
  }
}

通过 HTTP 对接(远程 / Apify)

把你的 MCP 客户端指向 Streamable HTTP 端点:

https://neeenja--vies-vat-validator-mcp.apify.actor/mcp

并带上请求头 Authorization: Bearer <APIFY_TOKEN>。

调用示例

格式预校验(免费)

{ "name": "check_vat_format", "arguments": { "vat": "FR123456789" } }

→ { "formatValid": true, "normalized": "FR123456789", "pattern": "^([A-Z]{2})?\\d{9}$" }

实查(付费事件)

{ "name": "validate_vat", "arguments": { "vat": "FR123456789", "useCache": true, "live": true } }

→ { "valid": true, "formatValid": true, "viesValid": true, "source": "vies", "name": "...", "address": "..." }

错误码(节选)

代码中文EN
VAT_FORMAT_INVALID格式不符format mismatch
VAT_VIES_INVALIDVIES 判定无效VIES says invalid
VIES_MS_UNAVAILABLE成员国系统不可用member state down
VIES_TIMEOUT超时timeout
NETWORK_ERROR网络错误network error

完整表见 get_error_codes 或 vat://error-codes。

部署(Apify Pay-Per-Event)

npm run apify:login      # 本人先完成 KYC(一次性)
npm run apify:validate   # 校验 actor.json
npm run apify:push       # 上架

计费见 .actor/actor.json 的 pricingEvents:格式 / 错误 / 国家查询免费,仅 mcp-validate-vat 计费。

设计红线

  • 不引入 express / soap / fast-xml-parser:SOAP 信封手写、响应用命名空间无关的正则提取。
  • 永不崩溃:VIES 故障 / 网络错误全部映射为双语错误码。
  • 免费层(格式校验 + 缓存)保证冷启动零成本。

完整契约见 SPEC.md。


繁體中文

為什麼做這個

  • 監管剛需 —— 歐盟 B2B 交易要求核驗對方 VAT 稅號(逆向徵收 / 合規憑證)。
  • VIES 又慢又抖 —— 官方 SOAP 介面頻繁限流、偶發停機,快取 + 優雅降級是必選項。
  • 零冷啟動成本 —— 免費官方資料源,疊加一層封裝 + 可解釋的雙語輸出,按事件計費。

你能拿到什麼

能力說明計費
validate_vat先做免費本地格式校驗,再依需求呼叫歐盟官方 VIES 介面核驗真實性;結構化 + 雙語錯誤$0.0005 / 次
check_vat_format純本地正則格式校驗,零網路、零成本免費
list_supported_countries回傳支援國家(母語名 + 當地 VAT 叫法 + 中/英)免費
get_error_codes回傳完整中英雙語錯誤碼表免費
resourcesvat://error-codes / vat://supported-countries / vat://spec免費
promptsvat_compliance_guide / explain_vat_result免費

涵蓋 EU 27 + GB + XI(北愛爾蘭)。每個國家還帶母語名,以及更實用的當地對 VAT 號的叫法——這才是當地人真正會搜的詞:

CódigoNome nativoTermo local de IVAPortuguêsEnglishUE
ATÖsterreichUID-NummerÁustriaAustria✅
BEBelgië / BelgiqueBTW-nummer / numéro de TVABélgicaBelgium✅
BGБългарияДДС номерBulgáriaBulgaria✅
CYΚύπρος / KıbrısΑριθμός ΦΠΑChipreCyprus✅
CZČeskoDIČRepública TchecaCzech Republic✅
DEDeutschlandUSt-IdNr.AlemanhaGermany✅
DKDanmarkCVR-nummerDinamarcaDenmark✅
EEEestiKMKR numberEstôniaEstonia✅
ELΕλλάδαΑριθμός ΦΠΑGréciaGreece✅
ESEspañaNIF (IVA)EspanhaSpain✅
FISuomiALV-numeroFinlândiaFinland✅
FRFrancenuméro de TVAFrançaFrance✅
HRHrvatskaPDV brojCroáciaCroatia✅
HUMagyarországÁFA-számHungriaHungary✅
IEIreland / ÉireVAT numberIrlandaIreland✅
ITItaliaPartita IVAItáliaItaly✅
LTLietuvaPVM kodasLituâniaLithuania✅
LULëtzebuerg / Luxembourgnuméro TVALuxemburgoLuxembourg✅
LVLatvijaPVN numursLetôniaLatvia✅
MTMaltaVAT numberMaltaMalta✅
NLNederlandbtw-nummerPaíses BaixosNetherlands✅
PLPolskaNIPPolôniaPoland✅
PTPortugalNIFPortugalPortugal✅
RORomâniacod de TVARomêniaRomania✅
SESverigemomsregistreringsnummerSuéciaSweden✅
SISlovenijaID za DDVEslovêniaSlovenia✅
SKSlovenskoIČ DPHEslováquiaSlovakia✅
GBUnited KingdomVAT registration numberReino UnidoUnited Kingdom—
XINorthern IrelandVAT registration number (XI)Irlanda do NorteNorthern Ireland—

Os termos seguem o uso comercial local comum — alguns países aceitam mais de uma forma; a principal é exibida.

Início rápido (local)

npm install
npm run build
npm start            # stdio 傳輸,接任意 MCP 用戶端
npm test             # vitest 全綠
npm run verify       # 產生真實 payload 驗證報告 verify-report.html

Integração com clientes MCP (stdio)

{
  "mcpServers": {
    "vat-validator": {
      "command": "node",
      "args": ["/abs/path/vies-vat-validator-mcp/dist/index.js"]
    }
  }
}

Integração via HTTP (remoto / Apify)

Aponte seu cliente MCP para o endpoint Streamable HTTP:

https://neeenja--vies-vat-validator-mcp.apify.actor/mcp

E inclua o cabeçalho de requisição Authorization: Bearer <APIFY_TOKEN>.

Exemplos de chamada

Pré-validação de formato (gratuito)

{ "name": "check_vat_format", "arguments": { "vat": "FR123456789" } }

→ { "formatValid": true, "normalized": "FR123456789", "pattern": "^([A-Z]{2})?\\d{9}$" }

Consulta real (evento pago)

{ "name": "validate_vat", "arguments": { "vat": "FR123456789", "useCache": true, "live": true } }

→ { "valid": true, "formatValid": true, "viesValid": true, "source": "vies", "name": "...", "address": "..." }

Códigos de erro (seleção)

CódigoPortuguêsEN
VAT_FORMAT_INVALIDformato incompatívelformat mismatch
VAT_VIES_INVALIDVIES considera inválidoVIES says invalid
VIES_MS_UNAVAILABLEsistema do estado-membro indisponívelmember state down
VIES_TIMEOUTtempo esgotadotimeout
NETWORK_ERRORerro de redenetwork error

Tabela completa em get_error_codes ou vat://error-codes.

Implantação (Apify Pay-Per-Event)

npm run apify:login      # 本人先完成 KYC(一次性)
npm run apify:validate   # 校驗 actor.json
npm run apify:push       # 上架

Cobrança conforme .actor/actor.json em pricingEvents: formato / erro / consulta de país são gratuitos; apenas mcp-validate-vat é cobrado.

Princípios de design

  • Sem express / soap / fast-xml-parser: envelope SOAP escrito à mão, respostas extraídas com regex independente de namespace.
  • Nunca falha: falhas do VIES / erros de rede são mapeados para códigos de erro bilíngues.
  • Camada gratuita (validação de formato + cache) garante custo zero de inicialização a frio.

Contrato completo em SPEC.md.


License

MIT — veja LICENSE.

Privacy

Somente leitura e sem estado — sem contas, sem coleta de dados pessoais. Os números de IVA enviados são encaminhados ao serviço oficial VIES da UE e podem ser mantidos em cache apenas em memória. Veja PRIVACY.md.


Support · 赞助 · 贊助

EN — VIES VAT Validator MCP é open source (MIT), sem anúncios. É financiado pela comunidade, não por anúncios. Se ele potencializa seus agentes ou fluxos de trabalho, apoie-o:

简体中文 — VIES VAT Validator MCP 开源(MIT)、无广告,由社区资助而非广告。若它支撑了你的智能体或工作流,欢迎赞助:点本仓库的 Sponsor 按钮(跳转 Ko-fi)或前往 https://ko-fi.com/panstories

繁體中文 — VIES VAT Validator MCP 開源(MIT)、無廣告,由社群資助而非廣告。若它支撐了你的智能體或工作流,歡迎贊助:點本倉庫的 Sponsor 按鈕(導向 Ko-fi)或前往 https://ko-fi.com/panstories

Obrigado! · 谢谢 · 謝謝 💙

Changelog

O histórico de versões deste Actor é um documento separado: https://apify.com/neeenja/vies-vat-validator-mcp/changelog.md

Actor input Schema

Exemplo de objeto de entrada do Actor

{}

Actor output Schema

mcpEndpoint (tipo: string):

Endpoint MCP Streamable HTTP desta execução do Actor. Conecte um cliente MCP aqui (Authorization: Bearer <APIFY_TOKEN>). Envie mensagens JSON-RPC: initialize, tools/list, tools/call.

API

Você pode executar este Actor programaticamente usando nossa API. Abaixo estão exemplos de código em JavaScript, Python e CLI, bem como a especificação OpenAPI e a configuração do servidor MCP.

Exemplo em JavaScript

import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("neeenja/vies-vat-validator-mcp").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

Exemplo em Python

from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("neeenja/vies-vat-validator-mcp").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

Exemplo em CLI

echo '{}' |
apify call neeenja/vies-vat-validator-mcp --silent --output-dataset

Configuração do servidor MCP

{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,neeenja/vies-vat-validator-mcp"
        }
    }
}

O servidor hospedado faz login com OAuth na primeira conexão, portanto nenhum token de API pertence a esta configuração. Clientes sem suporte a OAuth podem enviar um cabeçalho Authorization: Bearer <APIFY_API_TOKEN> em vez disso, usando um token de API & Integrations no Apify Console (https://console.apify.com/settings/integrations).

Especificação OpenAPI

Baixe a definição OpenAPI: https://api.apify.com/v2/actors/ghDM96xaQ9kvrsii0/builds/jErq4Dia9PPVteSDe/openapi.json