PHPackages                             wearesho-team/risktools-blacklist - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Validation & Sanitization](/categories/validation)
4. /
5. wearesho-team/risktools-blacklist

ActiveLibrary[Validation & Sanitization](/categories/validation)

wearesho-team/risktools-blacklist
=================================

RiskTools Blacklist Integration

1.0.1(1y ago)01MITPHPPHP >=8.1CI passing

Since Feb 24Pushed 1y ago1 watchersCompare

[ Source](https://github.com/wearesho-team/risktools-blacklist)[ Packagist](https://packagist.org/packages/wearesho-team/risktools-blacklist)[ RSS](/packages/wearesho-team-risktools-blacklist/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (6)Versions (3)Used By (0)

RiskTools Blacklist SDK
=======================

[](#risktools-blacklist-sdk)

[![Latest Stable Version](https://camo.githubusercontent.com/0ae5c212163452f8067764a0a80fe6434db0301fc7734e356063f5d3e0412f5e/68747470733a2f2f706f7365722e707567782e6f72672f776561726573686f2d7465616d2f7269736b746f6f6c732d626c61636b6c6973742f762f737461626c65)](https://packagist.org/packages/wearesho-team/risktools-blacklist)[![Total Downloads](https://camo.githubusercontent.com/e904f4115f2c45cea9240e16ff81a83c42c7600059aefa36399cab3d589b55b6/68747470733a2f2f706f7365722e707567782e6f72672f776561726573686f2d7465616d2f7269736b746f6f6c732d626c61636b6c6973742f646f776e6c6f616473)](https://packagist.org/packages/wearesho-team/risktools-blacklist)[![License](https://camo.githubusercontent.com/868e13e444f8f4063b86942aeac9debaf06cfe26e621d794cb387fafeded18ac/68747470733a2f2f706f7365722e707567782e6f72672f776561726573686f2d7465616d2f7269736b746f6f6c732d626c61636b6c6973742f6c6963656e7365)](https://packagist.org/packages/wearesho-team/risktools-blacklist)[![PHP Tests & Linting](https://github.com/wearesho-team/risktools-blacklist/actions/workflows/php.yml/badge.svg)](https://github.com/wearesho-team/risktools-blacklist/actions/workflows/php.yml)[![codecov](https://camo.githubusercontent.com/ad530f567999a81ca0f7abb1e10386dbb9b5d18464ef356be15fe23e8be3a976/68747470733a2f2f636f6465636f762e696f2f67682f776561726573686f2d7465616d2f7269736b746f6f6c732d626c61636b6c6973742f67726170682f62616467652e7376673f746f6b656e3d4d4d6f54653963533941)](https://codecov.io/gh/wearesho-team/risktools-blacklist)

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

Сервіс дозволяє перевіряти позичальників на наявність у чорних списках за допомогою [API](https://doc.blacklist.risktools.pro). Чорні списки передаються кредиторами. Кожен запис містить категорію (причину), за якою клієнт доданий до чорного списку.

Зміст
-----

[](#зміст)

1. [Встановлення](#%D0%B2%D1%81%D1%82%D0%B0%D0%BD%D0%BE%D0%B2%D0%BB%D0%B5%D0%BD%D0%BD%D1%8F)
2. [Конфігурація](#%D0%BA%D0%BE%D0%BD%D1%84%D1%96%D0%B3%D1%83%D1%80%D0%B0%D1%86%D1%96%D1%8F)
    - [Базова конфігурація](#%D0%B1%D0%B0%D0%B7%D0%BE%D0%B2%D0%B0-%D0%BA%D0%BE%D0%BD%D1%84%D1%96%D0%B3%D1%83%D1%80%D0%B0%D1%86%D1%96%D1%8F)
    - [Конфігурація через змінні оточення](#%D0%BA%D0%BE%D0%BD%D1%84%D1%96%D0%B3%D1%83%D1%80%D0%B0%D1%86%D1%96%D1%8F-%D1%87%D0%B5%D1%80%D0%B5%D0%B7-%D0%B7%D0%BC%D1%96%D0%BD%D0%BD%D1%96-%D0%BE%D1%82%D0%BE%D1%87%D0%B5%D0%BD%D0%BD%D1%8F)
3. [Ініціалізація сервісу](#%D1%96%D0%BD%D1%96%D1%86%D1%96%D0%B0%D0%BB%D1%96%D0%B7%D0%B0%D1%86%D1%96%D1%8F-%D1%81%D0%B5%D1%80%D0%B2%D1%96%D1%81%D1%83)
    - [Використання Builder](#%D0%B2%D0%B8%D0%BA%D0%BE%D1%80%D0%B8%D1%81%D1%82%D0%B0%D0%BD%D0%BD%D1%8F-builder)
    - [Використання Dependency Injection](#%D0%B2%D0%B8%D0%BA%D0%BE%D1%80%D0%B8%D1%81%D1%82%D0%B0%D0%BD%D0%BD%D1%8F-dependency-injection)
4. [Пошук](#%D0%BF%D0%BE%D1%88%D1%83%D0%BA)
    - [Формування запиту](#%D1%84%D0%BE%D1%80%D0%BC%D1%83%D0%B2%D0%B0%D0%BD%D0%BD%D1%8F-%D0%B7%D0%B0%D0%BF%D0%B8%D1%82%D1%83)
    - [Доступні категорії](#%D0%B4%D0%BE%D1%81%D1%82%D1%83%D0%BF%D0%BD%D1%96-%D0%BA%D0%B0%D1%82%D0%B5%D0%B3%D0%BE%D1%80%D1%96%D1%97)
    - [Отримання результатів](#%D0%BE%D1%82%D1%80%D0%B8%D0%BC%D0%B0%D0%BD%D0%BD%D1%8F-%D1%80%D0%B5%D0%B7%D1%83%D0%BB%D1%8C%D1%82%D0%B0%D1%82%D1%96%D0%B2)
5. [Оновлення (додавання) даних](#%D0%BE%D0%BD%D0%BE%D0%B2%D0%BB%D0%B5%D0%BD%D0%BD%D1%8F-%D0%B4%D0%BE%D0%B4%D0%B0%D0%B2%D0%B0%D0%BD%D0%BD%D1%8F-%D0%B4%D0%B0%D0%BD%D0%B8%D1%85)
    - [Формування записів](#%D1%84%D0%BE%D1%80%D0%BC%D1%83%D0%B2%D0%B0%D0%BD%D0%BD%D1%8F-%D0%B7%D0%B0%D0%BF%D0%B8%D1%81%D1%96%D0%B2)
    - [Відправка даних](#%D0%B2%D1%96%D0%B4%D0%BF%D1%80%D0%B0%D0%B2%D0%BA%D0%B0-%D0%B4%D0%B0%D0%BD%D0%B8%D1%85)
    - [Обробка відповіді](#%D0%BE%D0%B1%D1%80%D0%BE%D0%B1%D0%BA%D0%B0-%D0%B2%D1%96%D0%B4%D0%BF%D0%BE%D0%B2%D1%96%D0%B4%D1%96)
6. [Обробка винятків](#%D0%BE%D0%B1%D1%80%D0%BE%D0%B1%D0%BA%D0%B0-%D0%B2%D0%B8%D0%BD%D1%8F%D1%82%D0%BA%D1%96%D0%B2)
    - [Exception](#exception)
    - [RequestException](#requestexception)
    - [ResponseException](#responseexception)
7. [CLI Утиліта](#cli-%D1%83%D1%82%D0%B8%D0%BB%D1%96%D1%82%D0%B0)
    - [Встановлення](#%D0%B2%D1%81%D1%82%D0%B0%D0%BD%D0%BE%D0%B2%D0%BB%D0%B5%D0%BD%D0%BD%D1%8F-1)
    - [Використання](#%D0%B2%D0%B8%D0%BA%D0%BE%D1%80%D0%B8%D1%81%D1%82%D0%B0%D0%BD%D0%BD%D1%8F)
    - [Опції команди](#%D0%BE%D0%BF%D1%86%D1%96%D1%97-%D0%BA%D0%BE%D0%BC%D0%B0%D0%BD%D0%B4%D0%B8)
    - [Приклад виводу](#%D0%BF%D1%80%D0%B8%D0%BA%D0%BB%D0%B0%D0%B4-%D0%B2%D0%B8%D0%B2%D0%BE%D0%B4%D1%83)
8. [Ліцензія](#%D0%BB%D1%96%D1%86%D0%B5%D0%BD%D0%B7%D1%96%D1%8F)

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

[](#встановлення)

```
composer require wearesho-team/risktools-blacklist
```

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

[](#конфігурація)

Для налаштування пакету доступні два варіанти конфігурації, які реалізують інтерфейс [ConfigInterface](./src/ConfigInterface.php):

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

[](#базова-конфігурація)

Використовуйте клас [Config](./src/Config.php) для прямого налаштування через конструктор:

```
use Wearesho\RiskTools\Blacklist\Config;

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

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

[](#конфігурація-через-змінні-оточення)

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

Змінна оточенняОписRISK\_TOOLS\_BLACKLIST\_AUTH\_KEYКлюч авторизації для доступу до APIRISK\_TOOLS\_BLACKLIST\_API\_URLURL-адреса API сервісуПриклад використання:

```
use Wearesho\RiskTools\Blacklist\EnvironmentConfig;

$config = new EnvironmentConfig();
```

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

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

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

[](#ініціалізація-сервісу)

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

[](#використання-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)

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

- [ConfigInterface](./src/ConfigInterface.php)
- \\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](./src/Category.php)):

- `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

[](#exception)

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

```
use Wearesho\RiskTools\Blacklist\Exception;

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

### RequestException

[](#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

[](#responseexception)

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

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

```
use Wearesho\RiskTools\Blacklist\ResponseException;

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

CLI Утиліта
-----------

[](#cli-утиліта)

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

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

[](#встановлення-1)

Після встановлення пакету через 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](./LICENSE)

###  Health Score

26

—

LowBetter than 43% of packages

Maintenance44

Moderate activity, may be stable

Popularity1

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity47

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~1 days

Total

2

Last Release

439d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/e9694cebbc0ae729ff03618cd3338bc1c7d4efbf34522f1b916cadc965988fa9?d=identicon)[Horat1us](/maintainers/Horat1us)

---

Top Contributors

[![Horat1us](https://avatars.githubusercontent.com/u/2751367?v=4)](https://github.com/Horat1us "Horat1us (1 commits)")

###  Code Quality

TestsPHPUnit

Code StylePHP\_CodeSniffer

### Embed Badge

![Health badge](/badges/wearesho-team-risktools-blacklist/health.svg)

```
[![Health](https://phpackages.com/badges/wearesho-team-risktools-blacklist/health.svg)](https://phpackages.com/packages/wearesho-team-risktools-blacklist)
```

###  Alternatives

[aporat/store-receipt-validator

PHP receipt validator for Apple App Store and Amazon Appstore

6503.9M9](/packages/aporat-store-receipt-validator)[robertogallea/laravel-codicefiscale

Codice fiscale validation for php/laravel

58151.6k1](/packages/robertogallea-laravel-codicefiscale)[deligoez/tckimlikno

Turkish Identification Number Verification & Validation Package for Laravel

2917.4k](/packages/deligoez-tckimlikno)[speelpenning/laravel-postcode-nl

A Laravel client using the Postcode.eu REST API for Dutch address verification.

1221.1k](/packages/speelpenning-laravel-postcode-nl)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)