doc(update)
This commit is contained in:
27
README.md
27
README.md
@@ -1,8 +1,5 @@
|
||||
# Alfa Bank SDK (Unofficial)
|
||||
|
||||
[](https://github.com/apoloz/alfa-bank-sdk/actions)
|
||||
[](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');
|
||||
|
||||
Reference in New Issue
Block a user