README

该软件包提供了VIES增值税号验证PHP SDK接口。

用于检查增值税号有效性的VIES服务的PHP SDK接口。实现此接口的服务必须设计为发送请求并处理增值税验证服务的响应，具体取决于API（REST/SOAP等）。

此接口的实现由rocketfellows仓库提供（现在已经提供或将来提供）。

有关VIES增值税号验证服务的更多信息，请参阅https://ec.europa.eu/taxation_customs/vies/#/technical-information。

安装。

composer require rocketfellows/vies-vat-validation-php-sdk-interface

接口描述。

接口合约。

• VatNumberValidationServiceInterface - SDK接口，返回值类型 VatNumberValidationResult，输入参数 VatNumber;

• VatNumber - 验证的增值税号；

• VatNumberValidationResult - 验证结果；

接口异常。

InvalidInputServiceException - 对应API错误代码 INVALID_INPUT 的异常。
描述：提供的国家代码无效或增值税号为空。

ServiceUnavailableException - 对应API错误代码 SERVICE_UNAVAILABLE 的异常。
描述：在网络级别或Web应用级别遇到了错误，请稍后重试。

MSUnavailableServiceException - 对应API错误代码 MS_UNAVAILABLE 的异常。
描述：成员国中的应用程序没有回复或不可用。请参阅技术信息页面以检查请求的成员国的状态，稍后重试。

TimeoutServiceException - 对应API错误代码 TIMEOUT 的异常。
描述：应用程序在分配的时间段内没有收到回复，请稍后重试。

InvalidRequesterInfoServiceException - 对应API错误代码 INVALID_REQUESTER_INFO 的异常。

VatBlockedServiceException - 对应API错误代码 VAT_BLOCKED 的异常。

IPBlockedServiceException - 对应API错误代码 IP_BLOCKED 的异常。

GlobalMaxConcurrentReqServiceException - 对应API错误代码 GLOBAL_MAX_CONCURRENT_REQ 的异常。
描述：您的增值税验证请求尚未处理；已达到最大并发请求数。请稍后重新提交您的请求或联系 TAXUD-VIESWEB@ec.europa.eu 获取更多信息：由于Web应用程序流量过大，您的请求无法处理。请稍后重试。

GlobalMaxConcurrentReqTimeServiceException - 对应API错误代码 GLOBAL_MAX_CONCURRENT_REQ_TIME 的异常。

MSMaxConcurrentReqServiceException - 对应API错误代码 MS_MAX_CONCURRENT_REQ 的异常。
描述：您的增值税验证请求尚未处理；已达到此成员国的最大并发请求数。请稍后重新提交您的请求或联系 TAXUD-VIESWEB@ec.europa.eu 获取更多信息：由于您尝试联系的国家/地区流量过大，您的请求无法处理。请稍后重试。

MSMaxConcurrentReqTimeServiceException - 对应API错误代码 MS_MAX_CONCURRENT_REQ_TIME 的异常。

UnknownServiceErrorException - 如果无法理解服务返回的错误代码，则会抛出异常。

ServiceRequestException - 如果无法向服务发送请求（其他错误），则会抛出异常。

CountryCodeAttributeNotFoundException - 如果在创建 VatNumberValidationResult 实例时找不到国家代码属性，则会抛出异常。

RequestDateAttributeNotFoundException - 如果在创建 VatNumberValidationResult 实例时找不到请求日期属性，则会抛出异常。

ValidationFlagAttributeNotFoundException - 在创建 VatNumberValidationResult 实例时，如果找不到验证标志属性，则抛出此异常。

VatNumberAttributeNotFoundException - 在创建 VatNumberValidationResult 实例时，如果找不到增值税号属性，则抛出此异常。

VatOwnerAddressAttributeNotFoundException - 在创建 VatNumberValidationResult 实例时，如果找不到增值税所有者地址属性，则抛出此异常。

VatOwnerNameAttributeNotFoundException - 在创建 VatNumberValidationResult 实例时，如果找不到增值税所有者名称属性，则抛出此异常。

输入参数和返回值。

VatNumber 类型描述（已验证的增值税号）

• countryCode - 字符串 - 两位国家代码，根据 ISO 3166-1 标准；
• vatNumber - 字符串 - 已验证的增值税号。

VatNumberValidationResult 类型描述（验证结果）

• vatNumber - VatNumber - 已验证的增值税号；
• requestDate - 字符串 - 请求日期；
• isValid - 布尔值 - 有效性标志；
• name - null | 字符串 - 名称；
• address - null | 字符串 - 地址。

接口实现。

此接口的实现由 rocketfellows 存储库提供（要么已经提供，要么将来提供）。

迄今为止，VIES 提供了两种验证增值税号的服务

• 交互式网页界面；
• SOAP 网络服务 API；
• REST 网络服务 API。

增值税号验证结果工厂。

rocketfellows\ViesVatValidationInterface\VatNumberValidationResultFactory - 一个工厂，用于从给定的原始数据创建 rocketfellows\ViesVatValidationInterface\VatNumberValidationResult 实例，并检查所需属性是否存在。

工厂函数

• public function createFromObject(stdClass $rawData): VatNumberValidationResult - 从 stdClass 对象原始数据创建 VatNumberValidationResult；
• public function createFromArray(array $rawData): VatNumberValidationResult - 从数组原始数据创建 VatNumberValidationResult。

函数抛出以下异常

• CountryCodeAttributeNotFoundException - 如果在创建 VatNumberValidationResult 实例时找不到国家代码属性，则会抛出异常。

• RequestDateAttributeNotFoundException - 如果在创建 VatNumberValidationResult 实例时找不到请求日期属性，则会抛出异常。

• ValidationFlagAttributeNotFoundException - 在创建 VatNumberValidationResult 实例时，如果找不到验证标志属性，则抛出此异常。

• VatNumberAttributeNotFoundException - 在创建 VatNumberValidationResult 实例时，如果找不到增值税号属性，则抛出此异常。

• VatOwnerAddressAttributeNotFoundException - 在创建 VatNumberValidationResult 实例时，如果找不到增值税所有者地址属性，则抛出此异常。

• VatOwnerNameAttributeNotFoundException - 在创建 VatNumberValidationResult 实例时，如果找不到增值税所有者名称属性，则抛出此异常。

使用示例。

从具有 camel case 命名空间属性的 stdClass 对象原始数据创建 VatNumberValidationResult；

$factory = new VatNumberValidationResultFactory();

$vatNumberValidationResult = $factory->createFromObject(
    (object) [
        'countryCode' => 'DE',
        'vatNumber' => '12312312',
        'requestDate' => '2023-12-12 20:20:20',
        'valid' => true,
        'name' => 'fooBar',
        'address' => 'barFoo',
    ]
);

var_dump(sprintf('VAT country code: %s', $vatNumberValidationResult->getCountryCode()));
var_dump(sprintf('VAT number: %s', $vatNumberValidationResult->getVatNumber()));
var_dump(sprintf('Request date: %s', $vatNumberValidationResult->getRequestDateString()));
var_dump(sprintf('Is VAT valid: %s', $vatNumberValidationResult->isValid() ? 'true' : 'false'));
var_dump(sprintf('VAT holder name: %s', $vatNumberValidationResult->getName()));
var_dump(sprintf('VAT holder address: %s', $vatNumberValidationResult->getAddress()));

VAT country code: DE
VAT number: 12312312
Request date: 2023-12-12 20:20:20
Is VAT valid: true
VAT holder name: fooBar
VAT holder address: barFoo

从具有 snake case 命名空间属性的 stdClass 对象原始数据创建 VatNumberValidationResult；

$factory = new VatNumberValidationResultFactory();

$vatNumberValidationResult = $factory->createFromObject(
    (object) [
        'country_code' => 'DE',
        'vat_number' => '12312312',
        'request_date' => '2023-12-12 20:20:20',
        'valid' => true,
        'name' => 'fooBar',
        'address' => 'barFoo',
    ]
);

var_dump(sprintf('VAT country code: %s', $vatNumberValidationResult->getCountryCode()));
var_dump(sprintf('VAT number: %s', $vatNumberValidationResult->getVatNumber()));
var_dump(sprintf('Request date: %s', $vatNumberValidationResult->getRequestDateString()));
var_dump(sprintf('Is VAT valid: %s', $vatNumberValidationResult->isValid() ? 'true' : 'false'));
var_dump(sprintf('VAT holder name: %s', $vatNumberValidationResult->getName()));
var_dump(sprintf('VAT holder address: %s', $vatNumberValidationResult->getAddress()));

VAT country code: DE
VAT number: 12312312
Request date: 2023-12-12 20:20:20
Is VAT valid: true
VAT holder name: fooBar
VAT holder address: barFoo

从具有 camel case 命名空间属性的数组原始数据创建 VatNumberValidationResult；

$factory = new VatNumberValidationResultFactory();

$vatNumberValidationResult = $factory->createFromArray(
    [
        'countryCode' => 'DE',
        'vatNumber' => '12312312',
        'requestDate' => '2023-12-12 20:20:20',
        'valid' => true,
        'name' => 'fooBar',
        'address' => 'barFoo',
    ]
);

var_dump(sprintf('VAT country code: %s', $vatNumberValidationResult->getCountryCode()));
var_dump(sprintf('VAT number: %s', $vatNumberValidationResult->getVatNumber()));
var_dump(sprintf('Request date: %s', $vatNumberValidationResult->getRequestDateString()));
var_dump(sprintf('Is VAT valid: %s', $vatNumberValidationResult->isValid() ? 'true' : 'false'));
var_dump(sprintf('VAT holder name: %s', $vatNumberValidationResult->getName()));
var_dump(sprintf('VAT holder address: %s', $vatNumberValidationResult->getAddress()));

VAT country code: DE
VAT number: 12312312
Request date: 2023-12-12 20:20:20
Is VAT valid: true
VAT holder name: fooBar
VAT holder address: barFoo

从具有 snake case 命名空间属性的数组原始数据创建 VatNumberValidationResult；

$factory = new VatNumberValidationResultFactory();

$vatNumberValidationResult = $factory->createFromArray(
    [
        'country_code' => 'DE',
        'vat_number' => '12312312',
        'request_date' => '2023-12-12 20:20:20',
        'valid' => true,
        'name' => 'fooBar',
        'address' => 'barFoo',
    ]
);

var_dump(sprintf('VAT country code: %s', $vatNumberValidationResult->getCountryCode()));
var_dump(sprintf('VAT number: %s', $vatNumberValidationResult->getVatNumber()));
var_dump(sprintf('Request date: %s', $vatNumberValidationResult->getRequestDateString()));
var_dump(sprintf('Is VAT valid: %s', $vatNumberValidationResult->isValid() ? 'true' : 'false'));
var_dump(sprintf('VAT holder name: %s', $vatNumberValidationResult->getName()));
var_dump(sprintf('VAT holder address: %s', $vatNumberValidationResult->getAddress()));

VAT country code: DE
VAT number: 12312312
Request date: 2023-12-12 20:20:20
Is VAT valid: true
VAT holder name: fooBar
VAT holder address: barFoo

故障代码异常工厂。

rocketfellows\ViesVatValidationInterface\FaultCodeExceptionFactory - 一个工厂，用于根据增值税号验证服务可以返回的错误代码创建异常。错误代码检测不区分大小写。

输入参数

• $faultCode - 增值税号验证服务可以返回的错误代码；
• $message - 可选 - 增值税号验证服务可以返回的错误消息。

根据错误代码映射创建异常

InvalidInputServiceException - 对应API错误代码 INVALID_INPUT 的异常。
描述：提供的国家代码无效或增值税号为空。

ServiceUnavailableException - 对应API错误代码 SERVICE_UNAVAILABLE 的异常。
描述：在网络级别或Web应用级别遇到了错误，请稍后重试。

MSUnavailableServiceException - 对应API错误代码 MS_UNAVAILABLE 的异常。
描述：成员国中的应用程序没有回复或不可用。请参阅技术信息页面以检查请求的成员国的状态，稍后重试。

TimeoutServiceException - 对应API错误代码 TIMEOUT 的异常。
描述：应用程序在分配的时间段内没有收到回复，请稍后重试。

InvalidRequesterInfoServiceException - 对应API错误代码 INVALID_REQUESTER_INFO 的异常。

VatBlockedServiceException - 对应API错误代码 VAT_BLOCKED 的异常。

IPBlockedServiceException - 对应API错误代码 IP_BLOCKED 的异常。

GlobalMaxConcurrentReqServiceException - 对应API错误代码 GLOBAL_MAX_CONCURRENT_REQ 的异常。
描述：您的增值税验证请求尚未处理；已达到最大并发请求数。请稍后重新提交您的请求或联系 TAXUD-VIESWEB@ec.europa.eu 获取更多信息：由于Web应用程序流量过大，您的请求无法处理。请稍后重试。

GlobalMaxConcurrentReqTimeServiceException - 对应API错误代码 GLOBAL_MAX_CONCURRENT_REQ_TIME 的异常。

MSMaxConcurrentReqServiceException - 对应API错误代码 MS_MAX_CONCURRENT_REQ 的异常。
描述：您的增值税验证请求尚未处理；已达到此成员国的最大并发请求数。请稍后重新提交您的请求或联系 TAXUD-VIESWEB@ec.europa.eu 获取更多信息：由于您尝试联系的国家/地区流量过大，您的请求无法处理。请稍后重试。

MSMaxConcurrentReqTimeServiceException - 对应API错误代码 MS_MAX_CONCURRENT_REQ_TIME 的异常。

UnknownServiceErrorException - 如果无法理解服务返回的错误代码，则会抛出异常。

使用示例

大写错误代码

$factory = new FaultCodeExceptionFactory();

$exception = $factory->create('INVALID_REQUESTER_INFO');

var_dump(get_class($exception));

rocketfellows\ViesVatValidationInterface\exceptions\service\InvalidRequesterInfoServiceException

大小写混合的错误代码

$factory = new FaultCodeExceptionFactory();

$exception = $factory->create('invalid_requester_info');

var_dump(get_class($exception));

rocketfellows\ViesVatValidationInterface\exceptions\service\InvalidRequesterInfoServiceException

贡献。

欢迎提交拉取请求。如果有重大更改，请首先打开一个 issue 进行讨论。

请确保根据需要更新测试。