From e83bb5e7e744a5702c09d2e5a697f9afe52d6c00 Mon Sep 17 00:00:00 2001 From: Anatoliy Poloz Date: Mon, 26 Jan 2026 12:59:26 +0300 Subject: [PATCH] docs(readme): updated --- README.md | 44 ++++++++++---------------------------------- 1 file changed, 10 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index 66f97de..72e93d2 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,6 @@ composer require apoloz/alfa-bank-sdk **1. Генерация закрытого ключа и запроса (CSR):** Используйте OpenSSL для создания ключа и файла запроса. Создайте файл `openssl.cnf`: - ```ini [req] distinguished_name = req_distinguished_name @@ -35,7 +34,6 @@ emailAddress = your_email@company.com ``` Выполните команды в терминале: - ```bash # Генерация закрытого ключа (храните его в секрете!) openssl genrsa -out private.key 2048 @@ -53,7 +51,6 @@ openssl req -new -key private.key -out request.csr -config openssl.cnf -utf8 ## Конфигурация (Laravel) Опубликуйте файл конфигурации: - ```bash php artisan vendor:publish --tag=alfa-bank-config ``` @@ -123,19 +120,16 @@ SDK поддерживает две разные модели безопасно ### 1. Подключение к СБП (Pay-in) **Шаги для получения доступа:** - 1. Генерируете пару ключей: `openssl req -x509 -newkey rsa:2048 -keyout client.key -out client.crt -nodes -days 3650`. 2. Отправляете `client.crt` менеджеру банка (acquiring@alfabank.ru). 3. Получаете от банка `alias` (key-name) и `TermNo`. **Поток данных и подпись:** - -- **Transport**: Обязательный **MTLS**. Вы должны передать `client.crt` и `client.key` в конфигурацию Guzzle/Saloon. -- **Payload**: Тело запроса канонизируется по алгоритму **JCS**. -- **Signature**: SHA256withRSA подпись JCS-строки помещается в заголовок `Authorization`. +* **Transport**: Обязательный **MTLS**. Вы должны передать `client.crt` и `client.key` в конфигурацию Guzzle/Saloon. +* **Payload**: Тело запроса канонизируется по алгоритму **JCS**. +* **Signature**: SHA256withRSA подпись JCS-строки помещается в заголовок `Authorization`. **SDK делает это автоматически**: - ```php // В config/alfa-bank.php 'sbp' => [ @@ -150,18 +144,15 @@ SDK поддерживает две разные модели безопасно ### 2. Подключение к BaaS (Номинальные счета) **Шаги для получения доступа:** - 1. Регистрация в личном кабинете партнера. 2. Получение `client_id` и `client_secret` для OAuth2. 3. Регистрация публичного ключа для проверки подписей выплат. **Поток данных и подпись:** - -- **Auth**: Стандартный OAuth2 Bearer Token. -- **Payload Signature**: Для критических операций (выплаты, идентификация) требуется `digestSignatures`. Это массив CMS-подписей (PKCS7) в формате Base64, которыми подписываются финансовые поля. +* **Auth**: Стандартный OAuth2 Bearer Token. +* **Payload Signature**: Для критических операций (выплаты, идентификация) требуется `digestSignatures`. Это массив CMS-подписей (PKCS7) в формате Base64, которыми подписываются финансовые поля. **Пример формирования CMS в SDK:** - ```php use Apoloz\AlfaBank\Utils\CmsSigner; @@ -176,7 +167,6 @@ $signature = CmsSigner::sign($payload, $privateKey, $certificate); SDK использует нативный функционал Saloon для OAuth2. **1. Инициализация:** - ```php $baas = AlfaBank::baas( clientId: '...', clientSecret: '...', redirectUri: '...', @@ -185,14 +175,12 @@ $baas = AlfaBank::baas( ``` **2. Получение ссылки на вход:** - ```php $url = $baas->getAuthorizationUrl(['beneficiaries']); // Перенаправьте пользователя на $url ``` **3. Обмен кода на токен:** - ```php $authenticator = $baas->getAccessToken($code); $baas->authenticate($authenticator); // Применить токен @@ -200,7 +188,6 @@ $baas->authenticate($authenticator); // Применить токен ``` **4. Обновление токена:** - ```php $newAuth = $baas->refreshAccessToken($savedRefreshToken); $baas->authenticate($newAuth); @@ -209,9 +196,7 @@ $baas->authenticate($newAuth); Полный пример: [examples/13_h2h_auth_service.php](examples/13_h2h_auth_service.php) ### 4. Генерация Client Secret (Утилита) - Если банк выдал только сертификаты, вы можете сгенерировать `client_secret` самостоятельно: - ```php // См. examples/14_generate_client_secret.php $baas->send(new RefreshClientSecretRequest($clientId)); @@ -227,7 +212,6 @@ $baas->send(new RefreshClientSecretRequest($clientId)); ## Архитектура и Потоки данных ### Гибридный поток: СБП -> Номинальный счет - ```mermaid sequenceDiagram participant Client as Покупатель @@ -242,7 +226,7 @@ sequenceDiagram Note over API, BaaS: Webhook with Signature API->>BaaS: 4. Webhook (Входящий платеж) - + Note over BaaS, API: OAuth2 + CMS Signature BaaS->>API: 5. IdentifyTransactionRequest(beneficiaryId) API-->>BaaS: 6. 200 OK (Зачислено) @@ -253,7 +237,6 @@ sequenceDiagram ## Примеры использования ### 1. СБП: Прием платежа на номинальный счет - ```php use Apoloz\AlfaBank\Laravel\Facades\Sbp; use Apoloz\AlfaBank\Sbp\Requests\GetQrCodeRequest; @@ -271,7 +254,6 @@ echo "QR URL: " . $response->dto()->payload; ``` ### 2. Идентификация платежа (BaaS) - Когда платеж пришел на номинальный счет, его нужно привязать к бенефициару: ```php @@ -294,11 +276,9 @@ AlfaBank::send(new IdentifyTransactionRequest($data)); ``` ### 3. Работа с номинальными счетами (Бенефициары) - ... (existing content) ... ### 4. Самозанятые (Регистрация доходов) - ```php use Apoloz\AlfaBank\Requests\SelfEmployed\RegisterIncomeRequest; use Apoloz\AlfaBank\Data\SelfEmployed\CreateIncomeRequestData; @@ -314,9 +294,7 @@ $response = AlfaBank::send(new RegisterIncomeRequest($data)); ``` ### 5. Файловый обмен (KYC) - Загрузка сканов документов бенефициаров через pre-signed ссылки: - ```php use Apoloz\AlfaBank\Requests\Files\UploadFileRequest; @@ -330,18 +308,16 @@ AlfaBank::send(new UploadFileRequest($uploadUrl, $file)); Эти примеры разработаны специально для быстрого запуска и тестирования в консоли `php artisan tinker`. Они содержат полные цепочки бизнес-логики. -- [17_laravel_tinker_scoring_creation.php](examples/17_laravel_tinker_scoring_creation.php) — **Скоринг и Создание Бенефициара**: Полный цикл проверки и регистрации контрагента с автоматической подписью данных. -- [18_laravel_tinker_identification_payout.php](examples/18_laravel_tinker_identification_payout.php) — **Идентификация и Выплата**: Привязка входящих денег к бенефициару и последующий вывод на карту (с шифрованием PAN). -- [19_laravel_tinker_card_registration_payout.php](examples/19_laravel_tinker_card_registration_payout.php) — **Безопасная регистрация карт**: Токенизация карты (создание Реквизита) и выплата по ID (PCI DSS Friendly). +* [17_laravel_tinker_scoring_creation.php](examples/17_laravel_tinker_scoring_creation.php) — **Скоринг и Создание Бенефициара**: Полный цикл проверки и регистрации контрагента с автоматической подписью данных. +* [18_laravel_tinker_identification_payout.php](examples/18_laravel_tinker_identification_payout.php) — **Идентификация и Выплата**: Привязка входящих денег к бенефициару и последующий вывод на карту (с шифрованием PAN). +* [19_laravel_tinker_card_registration_payout.php](examples/19_laravel_tinker_card_registration_payout.php) — **Безопасная регистрация карт**: Токенизация карты (создание Реквизита) и выплата по ID (PCI DSS Friendly). --- ## Продвинутые возможности ### Управление возвратами СБП - Просмотр всей истории попыток возврата по транзакции: - ```php $response = Sbp::send(new GetQrcReversalHistoryRequest($payrrn, $termNo)); foreach ($response->dto()->refunds as $refund) { @@ -350,7 +326,6 @@ foreach ($response->dto()->refunds as $refund) { ``` ### Webhook Handling (Laravel) - ```php // Обработка СБП уведомлений в Listener public function handle(AlfaWebhookReceived $event) { @@ -360,3 +335,4 @@ public function handle(AlfaWebhookReceived $event) { } } ``` +