rocketfellows / vies-vat-validation-php-sdk-soap
Requires
- php: >=7.4
- rocketfellows/soap-client-factory: 1.0.0
- rocketfellows/vies-vat-validation-php-sdk-interface: ~1.2.0
Requires (Dev)
- phpstan/phpstan: ^1.10
- phpunit/phpunit: ^8.5
- roave/security-advisories: dev-latest
- squizlabs/php_codesniffer: 3.6.2
README
An implementation of interface https://github.com/rocketfellows/vies-vat-validation-php-sdk-interface for the VIES service for checking the validity of the VAT number via the SOAP protocol. The implementation is designed to send a request and process a response from the VAT validation service via the SOAP protocol.
For more information about VIES VAT number validation services via the SOAP protocol see https://ec.europa.eu/taxation_customs/vies/#/technical-information.
Installation.
composer require rocketfellows/vies-vat-validation-php-sdk-soap
Dependencies.
Current implementation dependencies:
- https://github.com/rocketfellows/soap-client-factory v1.0.0;
- https://github.com/rocketfellows/vies-vat-validation-php-sdk-interface.
VIES VAT number validation SOAP service description.
For more information about VIES VAT number validation SOAP service see: https://ec.europa.eu/taxation_customs/vies/#/technical-information.
For the SOAP service, three WSDLs are available:
- https://ec.europa.eu/taxation_customs/vies/services/checkVatService.wsdl to verify the validity of a VAT number;
- https://ec.europa.eu/taxation_customs/vies/checkVatTestService.wsdl to verify the integration with the original service by using the below values (common for all Member States / CountryCodes) for each required result:
vatNumber
value=100, response= VALID;vatNumber
value=200, response = INVALID.
VIES VAT number validation PHP sdk SOAP component description.
AbstractVatNumberValidationSoapService
- is an abstract class that implements the interface https://github.com/rocketfellows/vies-vat-validation-php-sdk-interface and is intended for sending a request for VAT validation using the SOAP protocol, processing response/faults and returning an object of type validation result.
VatNumberValidationSoapService
- is an inheritor of the AbstractVatNumberValidationSoapService
class, configured to send a request to the sales service according to wsdl https://ec.europa.eu/taxation_customs/vies/services/checkVatService.wsdl.
VatNumberValidationSoapTestService
- is an inheritor of the AbstractVatNumberValidationSoapService
class, configured to send a request to the test service according to wsdl https://ec.europa.eu/taxation_customs/vies/checkVatTestService.wsdl.
VatNumberValidationSoapExpansibleService
- is an inheritor of the AbstractVatNumberValidationSoapService
class, configured to send a request to the service according to wsdl, passed through the class constructor (customizable service).
For creating vat number validation result this component is using factory rocketfellows\ViesVatValidationInterface\VatNumberValidationResultFactory
from interface package https://github.com/rocketfellows/vies-vat-validation-php-sdk-interface.
According to factory, if any of required response attributes is missing, then validation process will throw special exceptions:
CountryCodeAttributeNotFoundException
- exception thrown if while creating instance ofVatNumberValidationResult
country code attribute not found.RequestDateAttributeNotFoundException
- exception thrown if while creating instance ofVatNumberValidationResult
request date attribute not found.ValidationFlagAttributeNotFoundException
- exception thrown if while creating instance ofVatNumberValidationResult
validation flag attribute not found.VatNumberAttributeNotFoundException
- exception thrown if while creating instance ofVatNumberValidationResult
vat number attribute not found.VatOwnerAddressAttributeNotFoundException
- exception thrown if while creating instance ofVatNumberValidationResult
vat owner address attribute not found.VatOwnerNameAttributeNotFoundException
- exception thrown if while creating instance ofVatNumberValidationResult
vat owner name attribute not found.
Usage examples.
VatNumberValidationSoapService usage.
VAT number validation result (VAT is valid):
use rocketfellows\ViesVatValidationInterface\FaultCodeExceptionFactory; use rocketfellows\SoapClientFactory\SoapClientFactory; use rocketfellows\ViesVatValidationInterface\VatNumber; use rocketfellows\ViesVatValidationInterface\VatNumberValidationResultFactory; use rocketfellows\ViesVatValidationSoap\services\VatNumberValidationSoapService; require_once __DIR__ . '/vendor/autoload.php'; // Service initialization $service = new VatNumberValidationSoapService( (new FaultCodeExceptionFactory()), (new SoapClientFactory()), (new VatNumberValidationResultFactory()) ); $validationResult = $service->validateVat(VatNumber::create('DE', '206223519')); var_dump(sprintf('VAT country code: %s', $validationResult->getCountryCode())); var_dump(sprintf('VAT number: %s', $validationResult->getVatNumber())); var_dump(sprintf('Request date: %s', $validationResult->getRequestDateString())); var_dump(sprintf('Is VAT valid: %s', $validationResult->isValid() ? 'true' : 'false')); var_dump(sprintf('VAT holder name: %s', $validationResult->getName())); var_dump(sprintf('VAT holder address: %s', $validationResult->getAddress()));
VAT country code: DE
VAT number: 206223519
Request date: 2023-12-31+01:00
Is VAT valid: true
VAT holder name: ---
VAT holder address: ---
VAT number validation result (VAT is not valid):
use rocketfellows\ViesVatValidationInterface\FaultCodeExceptionFactory; use rocketfellows\SoapClientFactory\SoapClientFactory; use rocketfellows\ViesVatValidationInterface\VatNumber; use rocketfellows\ViesVatValidationInterface\VatNumberValidationResultFactory; use rocketfellows\ViesVatValidationSoap\services\VatNumberValidationSoapService; require_once __DIR__ . '/vendor/autoload.php'; // Service initialization $service = new VatNumberValidationSoapService( (new FaultCodeExceptionFactory()), (new SoapClientFactory()), (new VatNumberValidationResultFactory()) ); $validationResult = $service->validateVat(VatNumber::create('DE', '206223511')); var_dump(sprintf('VAT country code: %s', $validationResult->getCountryCode())); var_dump(sprintf('VAT number: %s', $validationResult->getVatNumber())); var_dump(sprintf('Request date: %s', $validationResult->getRequestDateString())); var_dump(sprintf('Is VAT valid: %s', $validationResult->isValid() ? 'true' : 'false')); var_dump(sprintf('VAT holder name: %s', $validationResult->getName())); var_dump(sprintf('VAT holder address: %s', $validationResult->getAddress()));
VAT country code: DE
VAT number: 206223511
Request date: 2023-12-31+01:00
Is VAT valid: false
VAT holder name: ---
VAT holder address: ---
VatNumberValidationSoapTestService usage.
According to https://ec.europa.eu/taxation_customs/vies/checkVatTestService.wsdl here is the list of VAT Number to use to receive each kind of answer:
- 100 = Valid request with Valid VAT Number
- 200 = Valid request with an Invalid VAT Number
- 201 = Error : INVALID_INPUT
- 202 = Error : INVALID_REQUESTER_INFO
- 300 = Error : SERVICE_UNAVAILABLE
- 301 = Error : MS_UNAVAILABLE
- 302 = Error : TIMEOUT
- 400 = Error : VAT_BLOCKED
- 401 = Error : IP_BLOCKED
- 500 = Error : GLOBAL_MAX_CONCURRENT_REQ
- 501 = Error : GLOBAL_MAX_CONCURRENT_REQ_TIME
- 600 = Error : MS_MAX_CONCURRENT_REQ
- 601 = Error : MS_MAX_CONCURRENT_REQ_TIME
For all the other cases, The web service will responds with a "SERVICE_UNAVAILABLE" error.
Some usage examples below.
VAT number validation result (VAT is valid):
use rocketfellows\ViesVatValidationInterface\FaultCodeExceptionFactory; use rocketfellows\SoapClientFactory\SoapClientFactory; use rocketfellows\ViesVatValidationInterface\VatNumber; use rocketfellows\ViesVatValidationInterface\VatNumberValidationResultFactory; use rocketfellows\ViesVatValidationSoap\services\VatNumberValidationSoapTestService; require_once __DIR__ . '/vendor/autoload.php'; // Service initialization $service = new VatNumberValidationSoapTestService( (new FaultCodeExceptionFactory()), (new SoapClientFactory()), (new VatNumberValidationResultFactory()) ); $validationResult = $service->validateVat(VatNumber::create('DE', '100')); var_dump(sprintf('VAT country code: %s', $validationResult->getCountryCode())); var_dump(sprintf('VAT number: %s', $validationResult->getVatNumber())); var_dump(sprintf('Request date: %s', $validationResult->getRequestDateString())); var_dump(sprintf('Is VAT valid: %s', $validationResult->isValid() ? 'true' : 'false')); var_dump(sprintf('VAT holder name: %s', $validationResult->getName())); var_dump(sprintf('VAT holder address: %s', $validationResult->getAddress()));
VAT country code: DE VAT number: 100 Request date: 2023-12-31+01:00 Is VAT valid: true VAT holder name: John Doe VAT holder address: 123 Main St, Anytown, UK
VAT number validation result (VAT is not valid):
use rocketfellows\ViesVatValidationInterface\FaultCodeExceptionFactory; use rocketfellows\SoapClientFactory\SoapClientFactory; use rocketfellows\ViesVatValidationInterface\VatNumber; use rocketfellows\ViesVatValidationInterface\VatNumberValidationResultFactory; use rocketfellows\ViesVatValidationSoap\services\VatNumberValidationSoapTestService; require_once __DIR__ . '/vendor/autoload.php'; // Service initialization $service = new VatNumberValidationSoapTestService( (new FaultCodeExceptionFactory()), (new SoapClientFactory()), (new VatNumberValidationResultFactory()) ); $validationResult = $service->validateVat(VatNumber::create('DE', '200')); var_dump(sprintf('VAT country code: %s', $validationResult->getCountryCode())); var_dump(sprintf('VAT number: %s', $validationResult->getVatNumber())); var_dump(sprintf('Request date: %s', $validationResult->getRequestDateString())); var_dump(sprintf('Is VAT valid: %s', $validationResult->isValid() ? 'true' : 'false')); var_dump(sprintf('VAT holder name: %s', $validationResult->getName())); var_dump(sprintf('VAT holder address: %s', $validationResult->getAddress()));
VAT country code: DE VAT number: 200 Request date: 2023-12-31+01:00 Is VAT valid: false VAT holder name: --- VAT holder address: ---
VAT number validation resulted with INVALID_INPUT fault:
use rocketfellows\ViesVatValidationInterface\FaultCodeExceptionFactory; use rocketfellows\SoapClientFactory\SoapClientFactory; use rocketfellows\ViesVatValidationInterface\VatNumber; use rocketfellows\ViesVatValidationInterface\VatNumberValidationResultFactory; use rocketfellows\ViesVatValidationSoap\services\VatNumberValidationSoapTestService; require_once __DIR__ . '/vendor/autoload.php'; // Service initialization $service = new VatNumberValidationSoapTestService( (new FaultCodeExceptionFactory()), (new SoapClientFactory()), (new VatNumberValidationResultFactory()) ); try { $validationResult = $service->validateVat(VatNumber::create('DE', '201')); } catch (Exception $exception) { var_dump(get_class($exception)); var_dump($exception->getMessage()); }
rocketfellows\ViesVatValidationInterface\exceptions\service\InvalidInputServiceException INVALID_INPUT
VAT number validation resulted with IP_BLOCKED fault:
use rocketfellows\ViesVatValidationInterface\FaultCodeExceptionFactory; use rocketfellows\SoapClientFactory\SoapClientFactory; use rocketfellows\ViesVatValidationInterface\VatNumber; use rocketfellows\ViesVatValidationInterface\VatNumberValidationResultFactory; use rocketfellows\ViesVatValidationSoap\services\VatNumberValidationSoapTestService; require_once __DIR__ . '/vendor/autoload.php'; // Service initialization $service = new VatNumberValidationSoapTestService( (new FaultCodeExceptionFactory()), (new SoapClientFactory()), (new VatNumberValidationResultFactory()) ); try { $validationResult = $service->validateVat(VatNumber::create('DE', '401')); } catch (Exception $exception) { var_dump(get_class($exception)); var_dump($exception->getMessage()); }
rocketfellows\ViesVatValidationInterface\exceptions\service\IPBlockedServiceException IP_BLOCKED
VatNumberValidationSoapExpansibleService usage.
VatNumberValidationSoapExpansibleService
- is an inheritor of the AbstractVatNumberValidationSoapService
class, configured to send a request to the service according to wsdl, passed through the class constructor (customizable service).
For example init service with wsdl - https://ec.europa.eu/taxation_customs/vies/services/checkVatService.wsdl.
VAT number validation result (VAT is valid):
use rocketfellows\ViesVatValidationInterface\FaultCodeExceptionFactory; use rocketfellows\SoapClientFactory\SoapClientFactory; use rocketfellows\ViesVatValidationInterface\VatNumber; use rocketfellows\ViesVatValidationInterface\VatNumberValidationResultFactory; use rocketfellows\ViesVatValidationSoap\services\VatNumberValidationSoapExpansibleService; require_once __DIR__ . '/vendor/autoload.php'; // Service initialization $service = new VatNumberValidationSoapExpansibleService( 'https://ec.europa.eu/taxation_customs/vies/services/checkVatService.wsdl', (new FaultCodeExceptionFactory()), (new SoapClientFactory()), (new VatNumberValidationResultFactory()) ); $validationResult = $service->validateVat(VatNumber::create('DE', '206223519')); var_dump(sprintf('VAT country code: %s', $validationResult->getCountryCode())); var_dump(sprintf('VAT number: %s', $validationResult->getVatNumber())); var_dump(sprintf('Request date: %s', $validationResult->getRequestDateString())); var_dump(sprintf('Is VAT valid: %s', $validationResult->isValid() ? 'true' : 'false')); var_dump(sprintf('VAT holder name: %s', $validationResult->getName())); var_dump(sprintf('VAT holder address: %s', $validationResult->getAddress()));
VAT country code: DE VAT number: 206223519 Request date: 2023-12-11+01:00 Is VAT valid: true VAT holder name: --- VAT holder address: ---
VAT number validation result (VAT is not valid):
use rocketfellows\ViesVatValidationInterface\FaultCodeExceptionFactory; use rocketfellows\SoapClientFactory\SoapClientFactory; use rocketfellows\ViesVatValidationInterface\VatNumber; use rocketfellows\ViesVatValidationInterface\VatNumberValidationResultFactory; use rocketfellows\ViesVatValidationSoap\services\VatNumberValidationSoapExpansibleService; require_once __DIR__ . '/vendor/autoload.php'; // Service initialization $service = new VatNumberValidationSoapExpansibleService( 'https://ec.europa.eu/taxation_customs/vies/services/checkVatService.wsdl', (new FaultCodeExceptionFactory()), (new SoapClientFactory()), (new VatNumberValidationResultFactory()) ); $validationResult = $service->validateVat(VatNumber::create('DE', '206223511')); var_dump(sprintf('VAT country code: %s', $validationResult->getCountryCode())); var_dump(sprintf('VAT number: %s', $validationResult->getVatNumber())); var_dump(sprintf('Request date: %s', $validationResult->getRequestDateString())); var_dump(sprintf('Is VAT valid: %s', $validationResult->isValid() ? 'true' : 'false')); var_dump(sprintf('VAT holder name: %s', $validationResult->getName())); var_dump(sprintf('VAT holder address: %s', $validationResult->getAddress()));
VAT country code: DE VAT number: 206223511 Request date: 2023-12-11+01:00 Is VAT valid: false VAT holder name: --- VAT holder address: ---
Contributing.
Welcome to pull requests. If there is a major changes, first please open an issue for discussion.
Please make sure to update tests as appropriate.