README

PHP bindings for the BIR1 (Baza Internetowa REGON 1) API (https://wyszukiwarkaregon.stat.gov.pl/appBIR/index.aspx).

API Documentation

Installation

The API client can be installed via Composer.

In your composer.json file:

{
    "require": {
        "freshmindpl/wyszukiwarkaregon": "~3.0"
    }
}

Once the composer.json file is created you can run composer install for the initial package install and composer update to update to the latest version of the API client.

Basic Usage

Remember to include the Composer autoloader in your application:

<?php
require_once 'vendor/autoload.php';

// Application code...
?>

Configure your access credentials when creating a client:

<?php
use WyszukiwarkaRegon\Client;
use WyszukiwarkaRegon\Exception\RegonException;
use WyszukiwarkaRegon\Exception\SearchException;

$client = new Client([
   'key' => 'aaaabbbbccccdddd' //Optional api key - required for full reports,
   'session' => 'abcdefghijklmnopqrstuvwxyz' //Session id if already logged in
]);
?>

Local Testing

Run phpunit from the project root to start all tests.

Examples

Login

<?php
// Login and obtain session id (sid)
try {
    $session_id = $client->login();
} catch (RegonException $e) {
    echo "There was an error.\n";
}

if(empty($session_id)) {
    // Empty session means that api key is invalid
    
    throw new \Exception('Invalid api key');
}

Logout

<?php
// Login and obtain session id (sid)
try {
    $client->login();
} catch (RegonException $e) {
    echo "There was an error.\n";
}

....

// Invalidate current session
$client->logout();

GetValue

See API Documentation for list of available params (section 2.5)

<?php

try {
    $value = $client->getValue('StatusSesji');
} catch (RegonException $e) {
    echo "There was an error.\n";
}

?>

Search

<?php

$params = [
    'Regon' => 142396858, // 9 or 14 digits
    'Krs' => null, // 10 digits
    'Nip' => null, // 10 digits
    'Regony9zn' => null, // Multiple 9 digits Regon's seperated by any non digit char (max 100)
    'Regony14zn' => null, // Multiple 14 digits Regon's seperated by any non digit char (max 100)
    'Krsy' => null, // Multiple 10 digits Krs seperated by any non digit char (max 100)
    'Nipy' => null, // Multiple 10 digits Nip seperated by any non digit char (max 100)
];

try {
    $data = $client->search($params);
    
} catch (SearchException $e) {
    switch($e->getCode()) {
        case GetValue::SEARCH_ERROR_CAPTCHA: //Captcha resolve needed
            // Some code
            break;
        case GetValue::SEARCH_ERROR_INVALIDARGUMENT: //Wrong search params
            // Some code
            break;
        case GetValue::SEARCH_ERROR_NOTFOUND: //Empty result - no data found matching search params
            // Some code
            break;
        case GetValue::SEARCH_ERROR_SESSION: //Wrong session id or expired session
            // Some code
            break;
    }
} catch (RegonException $e) {
    echo "There was an error.\n";
}

Reports

See API Documentation for list of available reports (section 2.6)

<?php

$regon = '1234567890';

try {
    $report = $client->report($regon, 'PublDaneRaportFizycznaOsoba'); 
    
} catch (SearchException $e) {
    switch($e->getCode()) {
        case GetValue::SEARCH_ERROR_CAPTCHA: //Captcha resolve needed
            // Some code
            break;
        case GetValue::SEARCH_ERROR_INVALIDARGUMENT: //Wrong search params
            // Some code
            break;
        case GetValue::SEARCH_ERROR_NOTFOUND: //Empty result - no data found matching search params
            // Some code
            break;
        case GetValue::SEARCH_ERROR_NOTAUTHORIZED: //Not authorized for this raport
            // Some code
            break;
        case GetValue::SEARCH_ERROR_SESSION: //Wrong session id or expired session
            // Some code
            break;
    }
} catch (RegonException $e) {
    echo "There was an error.\n";
}

Full example

This is a working example on how to use GUS client to query for data

<?php

$client = new Client([
    'key' => YOUR_API_KEY
]);

//Enable sandbox mode for development environment
if (defined('DEVELOPMENT') && DEVELOPMENT) {
    $client->sandbox();
}

//Check if we have saved session id
$session_id = $memcache->get('gus_session_id');

if (!$session_id) {
    try {
        $session_id = $client->login();
    } catch (RegonException $e) {
        echo "There was an error.\n";
        exit;
    }
    
    //Save session_id for later use
    $memcache->save('gus_session_id', $session_id); 
} else {

    //Set current session
    $client->setSession($session_id);
}

//Try to get data
try {
    
    //Get basic data
    $data = $client->search(['Nip' => '1234567890']);
    
    //Get full comapny report
    switch($data[0]['Typ']) {
        case 'P':
        case 'LP':
            $full = $client->report($data[0]['Regon'], 'PublDaneRaportPrawna');
        break;
    
        case 'F':
        case 'LF':
            $full = $client->report($data[0]['Regon'], 'PublDaneRaportDzialalnoscFizycznejCeidg');
        break;
    }
} catch (SearchException $e) {
    switch($e->getCode()) {
        case GetValue::SEARCH_ERROR_CAPTCHA: //Captcha resolve needed
            // You need to get catpcha and show it to the user
            break;
        case GetValue::SEARCH_ERROR_INVALIDARGUMENT: //Wrong search params
            // Invalid argument passed to search/report method
            break;
        case GetValue::SEARCH_ERROR_NOTFOUND: //Empty result - no data found matching search params
            // No records where found
            $data = null;
            $full = null;
            break;
        case GetValue::SEARCH_ERROR_NOTAUTHORIZED: //Not authorized for this raport
            // You are not authorized to generate this report
            break;
        case GetValue::SEARCH_ERROR_SESSION: //Wrong session id or expired session
            // Your session has expired - You need to login again
            break;
    }
} catch (RegonException $e) {
    echo "There was an error.\n";
    exit;
}

License

MIT license. See the LICENSE file for more details.