EORI Validator Pro
收藏EORI Validator Pro 数据集概述
数据集名称
EORI Validator Pro
数据集描述
EORI Validator Pro 是一个用于验证经济运营商注册和识别（EORI）号码的专用API。该API可针对欧盟海关和英国税务海关总署（HMRC）的官方数据库，验证任何欧盟或英国的EORI号码。一个端点覆盖所有27个欧盟成员国和英国。当信息被披露时，会返回贸易商的名称和地址。24小时缓存机制可在上游服务中断时确保您的应用程序正常工作。批处理端点支持并行验证最多50个号码。
主要功能
- 单一端点覆盖欧盟与英国：一个端点处理所有27个欧盟成员国及英国的EORI号码验证。
- 返回贸易商详情：当公司选择公开披露时，返回从欧盟海关数据库获取的注册名称和完整地址。
- 格式预检：对明显格式错误的号码，在20毫秒内返回
INVALID_FORMAT，无需查询海关数据库，节省配额并降低延迟。 - 24小时缓存：对有效的验证结果进行24小时缓存，以应对上游服务可能出现的停机情况。
- 批处理验证：支持批量验证最多50个EORI号码（数量上限因订阅计划而异），结果保持输入顺序。
- 明确的错误代码：提供如
INVALID_FORMAT、NOT_FOUND、COUNTRY_NOT_SUPPORTED、SERVICE_UNAVAILABLE等可预测的错误代码。
支持的国家/地区 (28个)
- 欧盟 (27国)：AT, BE, BG, CY, CZ, DE, DK, EE, ES, FI, FR, GR, HR, HU, IE, IT, LT, LU, LV, MT, NL, PL, PT, RO, SE, SI, SK。
- 英国：GB (United Kingdom)。
- 同时接受：XI (Northern Ireland — 格式与欧盟相同)。
端点详情
1. 验证单个EORI号码
-
端点：
POST /api/v1/validate -
请求体示例：
{ "eori": "DE123456789012345" } -
成功响应示例： json { "valid": true, "eori": "DE123456789012345", "country": "DE", "country_name": "Germany", "trader_name": "Example GmbH", "trader_address": "Musterstraße 1, 10115 Berlin, DE", "source": "EU_CUSTOMS", "cached": false, "verified_at": "2026-04-18T10:00:00Z" }
-
无效响应示例： json { "valid": false, "eori": "DE000000000000000", "error_code": "NOT_FOUND", "error": "EORI number not found in EU Customs database" }
2. 批量验证EORI号码（最多50个）
- 端点：
POST /api/v1/validate/batch - 请求体示例：
{ "eoris": ["DE123456789012345", "GB123456789012", "INVALID"] } - 说明：返回按输入顺序排列的
results以及聚合计数。批量大小上限因计划而异：基础版10个，专业版/商业版50个。
3. 健康检查
- 端点：
GET /api/health - 响应示例：
{ "status": "ok", "eu_reachable": true, "gb_reachable": true, "timestamp": "..." }
使用场景
- 海关软件与货运代理：在客户提交给海关经纪人之前，阻止其使用无效的EORI号码申报。
- B2B客户入驻：在了解你的业务（KYB）过程中，验证新客户提供的EORI号码是否真实存在于欧盟海关数据库中，而不仅仅是格式正确。
- 发票与ERP系统：根据单个EORI字段自动填充商业发票上的贸易商名称和地址。
- 市场平台合规：夜间批量检查每个卖家的EORI号码，每次请求最多可处理50个号码。
数据来源与处理
- 验证源：验证实时针对欧盟委员会DG TAXUD EORI验证服务和英国税务海关总署（HMRC）检查EORI API进行，这些是海关当局使用的相同数据库。
- 缓存策略：有效结果缓存24小时；无效结果缓存1小时。
- 数据披露：仅当运营商选择公开披露时，才会返回贸易商名称和地址。并非每个有效的EORI都会包含这些信息。
错误代码
| 代码 | HTTP状态码 | 含义 |
|---|---|---|
INVALID_FORMAT |
400 | EORI号码不符合其所在国家/地区的预期格式模式 |
COUNTRY_NOT_SUPPORTED |
400 | 2字母前缀不是欧盟成员国、XI或GB |
NOT_FOUND |
200 (valid=false) | 格式正确，但该号码未在欧盟海关或HMRC注册 |
SERVICE_UNAVAILABLE |
503 | 上游欧盟海关或HMRC暂时无法访问——请使用退避策略重试 |
BATCH_LIMIT_EXCEEDED |
422 | 批量大小超过您计划的上限 |
BATCH_NOT_ALLOWED |
422 | 免费计划：需升级至基础版或更高版本以使用批处理端点 |
RATE_LIMIT_EXCEEDED |
429 | 您计划的月度配额已用尽 |
FORBIDDEN |
403 | 请求未通过RapidAPI代理发送 |
响应头信息
每个请求都包含以下响应头：
X-RateLimit-Limit— 您计划的月度配额。X-RateLimit-Remaining— 当前周期内剩余的请求次数。X-Cache: HIT | MISS— 指示结果是否来自24小时缓存。
快速开始示例
提供了使用JavaScript、Python和cURL调用单个验证端点的代码示例。请求需包含Content-Type、X-RapidAPI-Key和X-RapidAPI-Host头部。
