wearesho-team/risktools-blacklist

RiskTools Blacklist Integration

1.0.1 2025-02-26 09:14 UTC

Requires

• php: >=8.1
• guzzlehttp/guzzle: ^7.5
• horat1us/environment-config: ^1.5

Requires (Dev)

• phpunit/phpunit: ^10.5
• squizlabs/php_codesniffer: ^3.11
• symfony/console: ^6.4
• vlucas/phpdotenv: ^5.6

MIT

• horat1us

README

Реалізація SDK для API RiskTools Blacklist.

Сервіс дозволяє перевіряти позичальників на наявність у чорних списках за допомогою API. Чорні списки передаються кредиторами. Кожен запис містить категорію (причину), за якою клієнт доданий до чорного списку.

Зміст

1. Встановлення
2. Конфігурація
   • Базова конфігурація
   • Конфігурація через змінні оточення
3. Ініціалізація сервісу
   • Використання Builder
   • Використання Dependency Injection
4. Пошук
   • Формування запиту
   • Доступні категорії
   • Отримання результатів
5. Оновлення (додавання) даних
   • Формування записів
   • Відправка даних
   • Обробка відповіді
6. Обробка винятків
   • Exception
   • RequestException
   • ResponseException
7. CLI Утиліта
   • Встановлення
   • Використання
   • Опції команди
   • Приклад виводу
8. Ліцензія

Встановлення

composer require wearesho-team/risktools-blacklist

Конфігурація

Для налаштування пакету доступні два варіанти конфігурації, які реалізують інтерфейс ConfigInterface:

Базова конфігурація

Використовуйте клас Config для прямого налаштування через конструктор:

use Wearesho\RiskTools\Blacklist\Config;

$config = new Config(
    authKey: 'ваш-ключ-авторизації',
    apiUrl: 'url-api-сервісу'
);

Конфігурація через змінні оточення

Клас EnvironmentConfig дозволяє налаштувати пакет використовуючи змінні оточення:

Змінна оточення	Опис
RISK_TOOLS_BLACKLIST_AUTH_KEY	Ключ авторизації для доступу до API
RISK_TOOLS_BLACKLIST_API_URL	URL-адреса API сервісу

Приклад використання:

use Wearesho\RiskTools\Blacklist\EnvironmentConfig;

$config = new EnvironmentConfig();

Для цього варіанту необхідно попередньо налаштувати відповідні змінні оточення у вашому середовищі або .env файлі:

RISK_TOOLS_BLACKLIST_AUTH_KEY=ваш-ключ-авторизації
RISK_TOOLS_BLACKLIST_API_KEY=url-api-сервісу

Ініціалізація сервісу

Використання Builder

Для створення екземпляра сервісу використовуйте Builder:

use Wearesho\RiskTools\Blacklist\Service\Builder;

// Базова ініціалізація з налаштуваннями за замовчуванням
$service = Builder::create()->getService();

// Ініціалізація з власним конфігом
$service = Builder::create()
    ->withConfig(new CustomConfig())
    ->getService();

// Ініціалізація з власним HTTP-клієнтом
$service = Builder::create()
    ->withHttpClient(new CustomHttpClient())
    ->getService();

// Ініціалізація з усіма залежностями
$service = Builder::create()
    ->withConfig(new CustomConfig())
    ->withHttpClient(new CustomHttpClient())
    ->getService();

Налаштування за замовчуванням

За замовчуванням Builder використовує:

• EnvironmentConfig - конфігурація з змінних оточення
• GuzzleHttp\Client - стандартний HTTP-клієнт

Використання Dependency Injection

Для використання сервісу з Dependency Injection вам необхідно налаштувати DI Container для реалізації двох інтерфейсів:

• ConfigInterface
• \GuzzleHttp\ClientInterface

use Wearesho\RiskTools\Blacklist;

$service = new Blacklist\Service(
    client: new Blacklist\Client(
        config: new Blacklist\Config(), // налаштувати в DI Container
        httpClient: new \GuzzleHttp\Client(), // налаштувати в DI Container
    ),
    searchFactory: new Blacklist\Search\Factory(),
    updateFactory: new Blacklist\Update\Factory(), 
);

Пошук

Для виконання пошуку у чорному списку використовуйте метод search() сервісу. Пошук можливий за номером телефону та/або ІПН. Якщо в параметрах пошуку задані одночасно і ІПН та номер телефону, пошук виконуйтеся за логікою АБО, тобто будуть знайдені записи, у яких збігається ІПН або номер телефону.

Доступні категорії

Для фільтрації записів доступні наступні категорії (Category enum):

• MILITARY - військовий
• CLAIM - скарга НБУ
• FRAUD - шахрайство
• CIRCLE - на прохання близьких осіб (батьки тощо)
• DEAD - помер
• GAMING - лудоман
• INCAPABLE - недієздатний
• WRITEOFF - списання
• INADEQUATE - неадекватна поведінка
• ADDICT - залежність (алгоголізм, наркоманія тощо)
• LOST_DOCS - втрачені документи
• SELF - за власним бажанням
• OTHER - інше

Формування запиту

use Wearesho\RiskTools\Blacklist\Search\Request;
use Wearesho\RiskTools\Blacklist\Category;

// Пошук за номером телефону
$request = Request::byPhone('380501234567');

// Пошук за ІПН
$request = Request::byIpn('1234567890');

// Пошук за номером телефону та ІПН одночасно
$request = Request::byPhoneOrIpn('380501234567', '1234567890');

// Пошук з фільтрацією за категоріями
$request = Request::byPhone(
    '380501234567',
    Category::MILITARY,
    Category::FRAUD
);

Отримання результатів

use Wearesho\RiskTools\Blacklist\Service;

/** @var Service $service */
$response = $service->search($request);

// Отримання кількості знайдених записів
$total = $response->found();

// Отримання списку партнерів, які додали записи
$partners = $response->partners(); // ['87613', '01933']

// Отримання статистики за категоріями
$categories = $response->categories(); // ['military' => 2, 'fraud' => 1]

// Обробка знайдених записів
foreach ($response->records() as $record) {
    // Отримання даних запису
    $phone = $record->phone(); // ?string
    $ipn = $record->ipn(); // ?string
    $category = $record->category(); // Category enum
    $partnerId = $record->partnerId(); // string
    $addedAt = $record->addedAt(); // DateTimeImmutable

    // Приклад використання
    echo sprintf(
        "Запис %s додано %s партнером %s в категорії %s\n",
        $phone ?? $ipn,
        $addedAt->format('Y-m-d'),
        $partnerId,
        $category->value
    );
}

Оновлення (додавання) даних

Формування записів

use Wearesho\RiskTools\Blacklist\Update\Record;
use Wearesho\RiskTools\Blacklist\Category;
use DateTimeImmutable;

// Створення запису за номером телефону
$record = Record::withPhone(
    "380501234567",
    Category::MILITARY,
    new DateTimeImmutable() // опціонально
);

// Створення запису за ІПН
$record = Record::withIpn(
    "1234567890",
    Category::FRAUD,
    new DateTimeImmutable("2023-08-01T12:00:00+03:00") // опціонально
);

// Створення запису з телефоном та ІПН
$record = Record::withPhoneAndIpn(
    "380501234567",
    "1234567890",
    Category::CIRCLE,
    new DateTimeImmutable() // опціонально
);

Відправка даних

use Wearesho\RiskTools\Blacklist\Exception;
use Wearesho\RiskTools\Blacklist\Update\Record;

// Формування масиву записів
$records = [
    Record::withPhone("380501234567", Category::MILITARY),
    Record::withIpn("1234567890", Category::FRAUD),
    Record::withPhoneAndIpn(
        "380507654321",
        "0987654321",
        Category::CIRCLE,
        new DateTimeImmutable()
    ),
];

// Відправка даних
try {
    $response = $service->update($records);
} catch (Exception $e) {
    // Обробка помилок запиту
    echo "Помилка запиту: " . $e->getMessage() . PHP_EOL;
}

Обробка відповіді

use Wearesho\RiskTools\Blacklist\Update\Response;
/** @var Response $response */

if ($response->isSuccessful()) {
    echo "Всі записи успішно оновлено" . PHP_EOL;
    exit;
}

echo "Кількість записів з помилками: " . $response->countErrors() . PHP_EOL;

foreach ($response->errors() as $error) {
    $record = $error->record();

    // Виведення інформації про запис з помилкою
    echo sprintf(
        "Помилка для запису %s / %s:" . PHP_EOL,
        $record->phone() ?? '-',
        $record->ipn() ?? '-'
    );

    // Виведення помилок валідації
    foreach ($error->errors() as $field => $messages) {
        echo "- $field: " . implode(', ', $messages) . PHP_EOL;
    }
}

Обробка винятків

SDK використовує три типи винятків для різних ситуацій:

Exception

Базовий інтерфейс для всіх винятків SDK. Рекомендується використовувати його для відлову будь-яких помилок SDK:

use Wearesho\RiskTools\Blacklist\Exception;

try {
    $response = $service->update($records);
} catch (Exception $e) {
    // Обробка будь-якої помилки SDK
    echo "Помилка SDK: " . $e->getMessage();
}

RequestException

Виникає у випадках:

• Мережевих помилок
• Невірного формату відповіді API
• Помилок автентифікації
• Інших помилок HTTP-запитів

use Wearesho\RiskTools\Blacklist\RequestException;

try {
    $response = $service->search($request);
} catch (RequestException $e) {
    echo "Помилка запиту: " . $e->getMessage();
    echo "Код помилки: " . $e->getCode();

    // Доступ до оригінального винятку Guzzle (якщо є)
    if ($e->getPrevious() instanceof \GuzzleHttp\Exception\GuzzleException) {
        // Обробка специфічної помилки Guzzle
    }
    
    // Доступ до оригінального винятку JSON (якщо є)
    if ($e->getPrevious() instanceof \JsonException) {
        // Обробка специфічної помилки JSON
    }
}

ResponseException

Виникає при некоректному форматі даних у відповіді API:

• Відсутні обов'язкові поля
• Неправильні типи даних
• Неможливість обробки відповіді

use Wearesho\RiskTools\Blacklist\ResponseException;

try {
    $response = $service->update($records);
} catch (ResponseException $e) {
    echo "Помилка обробки відповіді: " . $e->getMessage();
}

CLI Утиліта

SDK містить консольну утиліту для пошуку даних в чорному списку.

Встановлення

Після встановлення пакету через composer, утиліта буде доступна як vendor/bin/blacklist.

Використання

# Пошук за номером телефону
vendor/bin/blacklist search --phone=380501234567

# Пошук за ІПН
vendor/bin/blacklist search --ipn=1234567890

# Пошук за телефоном та ІПН
vendor/bin/blacklist search --phone=380501234567 --ipn=1234567890

# Пошук з фільтром по категорії
vendor/bin/blacklist search --phone=380501234567 --category=military

# Детальний вивід помилок
vendor/bin/blacklist search --phone=380501234567 -v

Опції команди

• -phone, -p: Номер телефону для пошуку
• -ipn, -i: ІПН для пошуку
• -category, -c: Категорія для фільтрації (за замовчуванням: other)
• -v, -vv, -vvv: Рівень детальності виводу

Приклад виводу

Список

+-------------+------------+----------+------------+---------------------+
| Phone       | IPN        | Category | Partner ID | Added At           |
+-------------+------------+----------+------------+---------------------+
| 380501234567| 1234567890 | military | 42         | 2023-08-01 12:00:00|
+-------------+------------+----------+------------+---------------------+

У випадку помилки

[ERROR] Search failed
        Invalid phone format

Записи не знайдені

[INFO] No records found

Ліцензія

MIT