diff --git a/README.md b/README.md index 6b68ed0..ddf3020 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,5 @@ # 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). ## Требования @@ -18,16 +15,19 @@ 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' => [ @@ -42,15 +42,18 @@ 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; @@ -65,6 +68,7 @@ $signature = CmsSigner::sign($payload, $privateKey, $certificate); ## Архитектура и Потоки данных ### Гибридный поток: СБП -> Номинальный счет + ```mermaid sequenceDiagram participant Client as Покупатель @@ -79,7 +83,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 (Зачислено) @@ -90,6 +94,7 @@ sequenceDiagram ## Примеры использования ### 1. СБП: Прием платежа на номинальный счет + ```php use Apoloz\AlfaBank\Laravel\Facades\Sbp; use Apoloz\AlfaBank\Sbp\Requests\GetQrCodeRequest; @@ -107,6 +112,7 @@ echo "QR URL: " . $response->dto()->payload; ``` ### 2. Идентификация платежа (BaaS) + Когда платеж пришел на номинальный счет, его нужно привязать к бенефициару: ```php @@ -127,6 +133,7 @@ AlfaBank::send(new IdentifyTransactionRequest($data)); ``` ### 3. Работа с номинальными счетами (Бенефициары) + ```php use Apoloz\AlfaBank\Requests\NominalAccounts\Beneficiaries\CreateBeneficiaryRequest; @@ -143,6 +150,7 @@ AlfaBank::send(new ScoreBeneficiaryRequest($id)); ## Продвинутые возможности ### Автоматическая пагинация + ```php $paginator = AlfaBank::paginate(new GetTransactionsRequest(...)); @@ -152,6 +160,7 @@ foreach ($paginator->items() as $transaction) { ``` ### Webhook Handling (Laravel) + ```php // Регистрация роута Route::alfaWebhooks('/api/alfa/webhooks');