codedge/laravel-bzst-evatr

A library for validating value added tax identification numbers (VAT ID) using the German Federal Ministry of Finance EVATR interface.

1.0.1 2016-06-19 08:54 UTC

This package is auto-updated.

Last update: 2022-06-13 17:49:18 UTC


README

Latest Stable Version Build Status StyleCI codecov License

This library is a wrapper for the XmlRPC interface to validate European VAT IDs.
See https://evatr.bff-online.de/eVatR/xmlrpc/ (German version).

With this library you can check an European VAT ID if it is valid. Additionally you can pass in and address of this European VAT ID and do an address check.

The library supports the simple and the qualified request.

  • Simple request:
    • Checks if a certain foreign VAT ID is valid at the time the request is made.
  • Qualified request:
    • Additionally checks if the address (company name, street, city and zip code) connected to the VAT ID matches with registered data in the foreign country.

All error messages are available in English or German - of course you can modify those as you like.

Install with Composer

To install the library using Composer:

$ composer require codedge/laravel-bzst-evatr

This adds the codedge/laravel-bzst-evatr package to your composer.json and downloads the project.

Next run: php artisan vendor:publish to publish the translation files of the library to resources/lang/vendor/evatr/<locale>/messages.php.

Don't forget to add the Service Provider to your config/app.php [1] and optionally the facade [2]:

// config/app.php

return [

    //...
    
    'providers' => [
        // ...
        
        /*
         * Application Service Providers...
         */
        App\Providers\AppServiceProvider::class,
        App\Providers\AuthServiceProvider::class,
        App\Providers\EventServiceProvider::class,
        App\Providers\RouteServiceProvider::class,
        Codedge\Evatr\EvatrServiceProvider::class, // [1]
    ],
    
    // ...
    
    'aliases' => [
        'App' => Illuminate\Support\Facades\App::class,
        'Artisan' => Illuminate\Support\Facades\Artisan::class,
        
        // ...
        
        'View' => Illuminate\Support\Facades\View::class,
        'Evatr' => Codedge\Evatr\Facades\Evatr::class, // [2]

]

Usage

If using the facade, just do:

// app/Http/routes.php

Route::get('/', function () {

    Evatr::setOwnUstId('123');      // Or use an alias: Evatr::setUstId1('123');
    Evatr::setForeignUstId('123');  // Or use an alias: Evatr::setUstId2('123');
    
    Evatr::query(); // Fires the XmlRpc call

    echo 'Error code: ' . Evatr::getResponse()->getErrorCode();
    echo 'Error message: ' . Evatr::getResponse()->getErrorMessage();

    echo 'Date: ' . Evatr::getResponse()->getDate();
    echo 'Time: ' . Evatr::getResponse()->getTime();

});

Alternatively you can use the dependency injection of the singleton instance like so:

// app/Http/routes.php

Route::get('/', function (Codedge\Evatr\Evatr $evatr) {

    $evatr->setOwnUstId('123')
          ->setForeignUstId('123')
          ->query(); // Fires the XmlRpc call

    echo 'Error code: ' . $evatr->getResponse()->getErrorCode();     // Get the interface error code
    echo 'Error message: ' . $evatr->getResponse()->getErrorMessage();  // Get the interface error message
    
    echo 'Date: ' . $evatr->getResponse()->getDate();
    echo 'Time: ' . $evatr->getResponse()->getTime();

});

All date and time methods return a Carbon instance for better and further handling.

Request - Available methods and fields

Depending if you want to send a simple or qualified request please see what parameters need to be set:

Field name Description Simple request Qualified request Method name
Own VAT ID Your German VAT ID x x setOwnUstId, alias: setUstId1
Foreign VAT ID The requested VAT ID x x setForeignUstId, alias: setUstId2
Company name Name of the requested company x setCompanyName
City City of the requested company x setCityName
Zip code Zip code of the req. company optional setZipCode
Street Street of the req. company optional setStreet
Print conf. Official confirmation msg optional setPrintConfirmation

Response - Available methods and fields

Additionally to the response field the response returns the following fields:

Field name Description Method name
Error Code See avail. error codes getErrorCode
Error Message See avail. error messages getErrorMessage
Date Date of the request getDate
Time Time of the request getTime
Valid from Start date of validity of the foreign VAT ID. Only filled with error code 203 and 204. getValidFrom
Valid until End date of validity of the foreign VAT ID. Only filled with error code 204. getValidUntil
Erg_Name Result for the requested company name getResponseCompany
Erg_City Result for the requested company city getResponseCity
Erg_Street Result for the requested company street getResponseStreet
Erg_PLZ Result for the requested company zip code getResponseZipCode

Each of these result fields can have one of the following results:

Result Description
A Matches the requested value
B Does not match the requested value
C Not requested
D Not provided by EU member state