egorsergeychik/youscore-laravel

YouScore API SDK for Laravel

v0.4.0 2026-02-20 11:11 UTC

Requires

• php: ^8.1
• illuminate/http: ^11.0|^12.0
• illuminate/support: ^11.0|^12.0

Requires (Dev)

• orchestra/testbench: ^10.8

MIT

• Egor Sergeychik

README

An unofficial Laravel SDK for YouScore.com.ua - a comprehensive business intelligence platform providing detailed company information, risk analysis, and financial monitoring for Ukrainian businesses.

Features

• 🔄 Automatic Polling: Built-in retry mechanism for pending API responses
• 🎭 Laravel Integration: Seamless integration with Laravel's service container and facades
• ⚡ Type Safety: Full PHP 8.1+ type hints and return types

Requirements

• PHP 8.1 or higher
• Laravel 11.0 or higher
• YouScore API key from youscore.com.ua

Installation

Install the package via Composer:

composer require egorsergeychik/youscore-laravel

Configuration

Publish the configuration file:

php artisan vendor:publish --tag=youscore-config

Add your YouScore API credentials to your .env file:

YOUSCORE_API_KEY=your_api_key_here
YOUSCORE_BASE_URL=https://api.youscore.com.ua
YOUSCORE_TIMEOUT=30

# Polling configuration (optional)
YOUSCORE_POLLING_ENABLED=true
YOUSCORE_POLLING_MAX_ATTEMPTS=2
YOUSCORE_POLLING_DELAY=2500

Usage

Using the Facade

The easiest way to use the SDK is through the YouScore facade:

use EgorSergeychik\YouScore\Facades\YouScore;

// Get company registration data
$response = YouScore::registrationData()->getUnitedStateRegisterData('39404434');

// Access response data
$companyName = $response->json('name.fullName');
$status = $response->json('status');

Using Dependency Injection

You can also inject the Client class directly:

use EgorSergeychik\YouScore\Client;

class CompanyService
{
    public function __construct(private Client $youScore)
    {
    }

    public function getCompanyData(string $code): array
    {
        $response = $this->youScore->registrationData()
            ->getUnitedStateRegisterData($code);
            
        return $response->json();
    }
}

Response Handling

All methods return Laravel's Illuminate\Http\Client\Response object:

$response = YouScore::registrationData()->getUnitedStateRegisterData('39404434');

// Check if request was successful
if ($response->successful()) {
    // Get JSON data
    $data = $response->json();
    
    // Access specific fields
    $companyName = $response->json('name.fullName');
    $status = $response->json('status');
    
    // Get raw response body
    $body = $response->body();
    
    // Get status code
    $statusCode = $response->status();
}

// Handle errors
if ($response->failed()) {
    $errorMessage = $response->json('message', 'Unknown error occurred');
    // Handle error appropriately
}

Automatic Polling

The SDK includes automatic polling for handling pending API responses (HTTP 202):

// The SDK will automatically retry requests that return 202 status
$response = YouScore::registrationData()->getUnitedStateRegisterData('39404434');
// Will retry up to max_attempts times with specified delay

Configure polling behavior in your config/youscore.php:

'polling' => [
    'enabled' => true,        // Enable/disable polling
    'max_attempts' => 2,      // Maximum retry attempts
    'delay' => 2500,          // Delay between attempts (milliseconds)
],

Error Handling

The SDK automatically throws exceptions for HTTP errors. You can catch and handle them:

use Illuminate\Http\Client\RequestException;

try {
    $response = YouScore::registrationData()->getUnitedStateRegisterData('invalid_code');
} catch (RequestException $e) {
    // Handle HTTP errors (4xx, 5xx)
    $statusCode = $e->response->status();
    $errorBody = $e->response->body();
    
    Log::error('YouScore API error', [
        'status' => $statusCode,
        'response' => $errorBody,
    ]);
}

Configuration Options

The package supports various configuration options in config/youscore.php:

return [
    // API endpoint (usually doesn't need to be changed)
    'base_url' => env('YOUSCORE_BASE_URL', 'https://api.youscore.com.ua'),
    
    // Your YouScore API key
    'api_key' => env('YOUSCORE_API_KEY', ''),
    
    // Request timeout in seconds
    'timeout' => env('YOUSCORE_TIMEOUT', 30),

    // Polling configuration for handling 202 responses
    'polling' => [
        'enabled' => env('YOUSCORE_POLLING_ENABLED', true),
        'max_attempts' => env('YOUSCORE_POLLING_MAX_ATTEMPTS', 2),
        'delay' => env('YOUSCORE_POLLING_DELAY', 2500), // milliseconds
    ],
];

Testing

Run the package tests:

composer test

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Security

If you discover any security-related issues, please email [e-mail] instead of using the issue tracker.

Disclaimer

This is an unofficial SDK for YouScore.com.ua. It is not affiliated with, endorsed by, or sponsored by YouScore. Use at your own risk.