# Alfa Bank SDK (Unofficial)

[![Tests](https://github.com/apoloz/alfa-bank-sdk/actions/workflows/tests.yml/badge.svg)](https://github.com/apoloz/alfa-bank-sdk/actions)
[![Static Analysis](https://img.shields.io/badge/phpstan-level%205-brightgreen.svg)](https://phpstan.org/)

Профессиональная PHP-библиотека для интеграции с API Альфа-Банка (BaaS и СБП). Построена на базе [Saloon v3](https://docs.saloon.dev) и [Spatie Laravel Data](https://spatie.be/docs/laravel-data).

## Требования

- PHP 8.2+
- Расширение OpenSSL
- [Saloon](https://docs.saloon.dev) v3.0+
- [Spatie Laravel Data](https://spatie.be/docs/laravel-data)

## Установка

```bash
composer require apoloz/alfa-bank-sdk
```

---

## Архитектура и потоки данных

Библиотека обеспечивает строгую типизацию на всех этапах. Вы работаете только с объектами (DTO), а SDK берет на себя всю сложность протоколов банка.

### 1. Жизненный цикл запроса (BaaS)
```mermaid
sequenceDiagram
    participant App as Приложение
    participant DTO as Request DTO
    participant SDK as Connector
    participant API as Alfa Bank

    App->>DTO: 1. Создание данных
    App->>SDK: 2. send(Request)
    SDK->>SDK: 3. Маппинг полей (PascalCase)
    SDK->>SDK: 4. Подпись/Шифрование
    SDK->>API: 5. HTTPS + mTLS
    API-->>SDK: 6. JSON Ответ
    SDK->>SDK: 7. Валидация ошибок
    SDK->>App: 8. Возврат Response DTO
```

### 2. Безопасность СБП (Body Signing)
Для СБП реализована автоматическая каноникализация JSON (JCS) с рекурсивной сортировкой ключей перед подписью RSA-SHA256.

---

## Настройка и Безопасность

Альфа-Банк требует **два набора ключей**:
1.  **Транспортные (mTLS):** Для установки защищенного соединения.
2.  **Прикладные (Signing):** Для цифровой подписи реестров и платежей.

### Быстрый старт (Laravel)

1. Опубликуйте конфиг:
```bash
php artisan vendor:publish --tag=alfa-bank-config
```

2. Настройте `.env`:
```env
ALFA_BAAS_CERT_PATH=/path/to/transport.crt
ALFA_BAAS_KEY_PATH=/path/to/transport.key
ALFA_BAAS_CLIENT_ID=your_id
ALFA_BAAS_CLIENT_SECRET=your_secret
```

3. Проверьте соединение:
```bash
php artisan alfa:check
```

---

## Примеры использования

### 1. Авторизация и получение счетов
```php
use Apoloz\AlfaBank\Laravel\Facades\AlfaBank;
use Apoloz\AlfaBank\Requests\Accounts\GetAccountsRequest;

// SDK сам получит токен и применит его
$accounts = AlfaBank::send(new GetAccountsRequest());

foreach ($accounts as $account) {
    echo $account->number . ": " . $account->openDate;
}
```

### 2. Стандартный платеж (BaaS)
```php
use Apoloz\AlfaBank\Requests\Payments\CreatePaymentRequest;
use Apoloz\AlfaBank\Data\Payments\PaymentData;

$data = new PaymentData(
    amount: 1500.00,
    date: date('Y-m-d'),
    externalId: 'INV-2026-001',
    operationCode: '01',
    payeeAccount: '40702...',
    payeeBankBic: '044525593',
    payeeName: 'ООО Партнер',
    payerAccount: '40702...',
    payerBankBic: '044525593',
    payerBankCorrAccount: '30101...',
    payerInn: '7700000000',
    payerName: 'Моя Компания',
    priority: '5',
    purpose: 'Оплата по счету №1'
);

$response = AlfaBank::send(new CreatePaymentRequest($data));
echo "Платеж создан: " . $response->id;
```

### 3. СБП: Генерация QR-кода
```php
use Apoloz\AlfaBank\Laravel\Facades\Sbp;
use Apoloz\AlfaBank\Sbp\Requests\GetQrCodeRequest;
use Apoloz\AlfaBank\Sbp\Data\QrCodeRequestData;

$payload = new QrCodeRequestData(
    termNo: '90080567',
    amount: '10000', // 100.00 руб
    paymentPurpose: 'Заказ №5'
);

$response = Sbp::send(new GetQrCodeRequest($payload));
echo "Отсканируйте код: " . $response->payload;
```

### 4. Работа с выписками (Пагинация)
```php
use Apoloz\AlfaBank\Requests\Statement\GetTransactionsRequest;

// Автоматическая итерация через все страницы
$paginator = AlfaBank::paginate(new GetTransactionsRequest(
    accountNumber: '40702...',
    executeDateFrom: '2026-01-01',
    executeDateTo: '2026-01-18'
));

foreach ($paginator->items() as $transaction) {
    echo "Транзакция {" . $transaction->uuid . ": " . $transaction->amount['amount'] . " RUB\n";
}
```

### 5. Самозанятые (Справочники и выплаты)
```php
use Apoloz\AlfaBank\Requests\SelfEmployed\GetActivitiesRequest;

// Получение списка разрешенных видов деятельности
$activities = AlfaBank::send(new GetActivitiesRequest());

foreach ($activities as $activity) {
    echo "{$activity->code}: {$activity->name}\n";
}
```

### 6. Номинальные счета (Полный цикл)
Сценарий создания бенефициара и выплаты с подписью:

```php
use Apoloz\AlfaBank\Requests\NominalAccounts\Beneficiaries\CreateBeneficiaryRequest;
use Apoloz\AlfaBank\Requests\NominalAccounts\Payouts\CreatePayoffRequest;

// 1. Создание бенефициара с CMS подписью
$response = $baas->send(new CreateBeneficiaryRequest($beneficiaryData));

// 2. Инициирование выплаты
$payoff = $baas->send(new CreatePayoffRequest($payoffData));
echo "Статус выплаты: " . $payoff->dto()->status;
```

---

## Продвинутые возможности

### Диагностика без Laravel
```php
use Apoloz\AlfaBank\AlfaBank;

$ok = AlfaBank::check(
    certificatePath: 'cert.pem',
    privateKeyPath: 'key.pem',
    clientId: '...',
    clientSecret: '...'
);
```

### Логирование с маскировкой данных
SDK автоматически скрывает номера карт, токены и подписи в логах.
```php
$connector = AlfaBank::getFacadeRoot();
$connector->withLogging(Log::channel('daily')->getLogger());
```

### Обработка Webhooks (Laravel)
```php
// routes/api.php
Route::alfaWebhooks('/webhooks/alfa');

// Listener
public function handle(AlfaWebhookReceived $event) {
    $data = $event->webhook->data; 
    // $data будет объектом TransactionWebhookData или SbpPaymentWebhookData
}
```

---

## Лицензия

MIT. Автор: Anatoliy Poloz.