From 27ecbf1672c96ba6ecfedebc8d3521d8750269c6 Mon Sep 17 00:00:00 2001 From: Anatoliy Poloz Date: Sun, 18 Jan 2026 21:52:11 +0300 Subject: [PATCH] doc(core) --- README_FULL_GUIDE.md | 179 +++++++++++++++++++++++++++++++++++++++++++ RELEASE_NOTES.md | 75 ++++++++++++++++++ 2 files changed, 254 insertions(+) create mode 100644 README_FULL_GUIDE.md create mode 100644 RELEASE_NOTES.md diff --git a/README_FULL_GUIDE.md b/README_FULL_GUIDE.md new file mode 100644 index 0000000..8bdf766 --- /dev/null +++ b/README_FULL_GUIDE.md @@ -0,0 +1,179 @@ +# Alfa Bank SDK: The Comprehensive Guide + +## 1. Introduction +This SDK provides a unified, strictly-typed PHP interface for the Alfa Bank API. It covers both **Bank-as-a-Service (BaaS)** and **Faster Payments System (SBP)** protocols. + +**Key Technologies:** +- **Saloon v3**: Handles HTTP transport, retries, and plugins. +- **Spatie Laravel Data**: Provides Data Transfer Objects (DTOs) for strict typing. +- **OpenSSL**: Manages GOST/RSA signatures and encryption. + +--- + +## 2. Installation & Configuration + +### 2.1 Install via Composer +```bash +composer require apoloz/alfa-bank-sdk +``` + +### 2.2 Laravel Setup +Publish the configuration file: +```bash +php artisan vendor:publish --tag=alfa-bank-config +``` + +Configure your `.env` file. **Crucially, you need separate keys for Transport (mTLS) and Signing (Business Logic).** + +```env +# 1. Transport Security (mTLS) - Required for connection +ALFA_BAAS_CERT_PATH=/path/to/transport.cer +ALFA_BAAS_KEY_PATH=/path/to/transport.key + +# 2. Business Logic Signing (CMS/PKCS#7) - Required for creating payments/registries +ALFA_BAAS_SIGNING_CERT_PATH=/path/to/signing.cer +ALFA_BAAS_SIGNING_KEY_PATH=/path/to/signing.key + +# 3. Credentials +ALFA_BAAS_CLIENT_ID=your-client-id +ALFA_BAAS_CLIENT_SECRET=your-client-secret +ALFA_BAAS_ENV=sandbox +``` + +--- + +## 3. Core Concepts + +### 3.1 Facades (Laravel) +Use the facades for clean, static access. +- `AlfaBank`: Access BaaS endpoints (Payments, Accounts, Salary). +- `Sbp`: Access SBP endpoints (QR Codes, C2B/B2C). + +### 3.2 DTOs (Data Transfer Objects) +Never pass raw arrays. Use DTOs to ensure your data is valid before it leaves your server. + +**Example:** +```php +use Apoloz\AlfaBank\Data\Payments\PaymentData; + +$payment = new PaymentData( + amount: 100.00, + payerName: 'My Company', + // ... mandatory fields are enforced here +); +``` + +### 3.3 Pagination +Iterate through large lists effortlessly. + +```php +use Apoloz\AlfaBank\Requests\Statement\GetTransactionsRequest; + +$paginator = AlfaBank::paginate(new GetTransactionsRequest($accountNumber)); + +foreach ($paginator as $transaction) { + // $transaction is a strictly typed DTO + echo $transaction->amount; +} +``` + +--- + +## 4. Advanced Security + +### 4.1 SBP Body Signing +The SDK handles the complex JSON Canonicalization (JCS) and RSA-SHA256 signing required by the SBP protocol automatically in the `SbpConnector`. + +### 4.2 Webhook Verification +To handle webhooks securely: + +1. Define a route using the macro: + ```php + Route::alfaWebhooks('/api/webhooks/alfa'); + ``` +2. Listen for the `AlfaWebhookReceived` event. +3. The SDK middleware verifies the authenticity of the request. + +--- + +## 5. Troubleshooting + +### "Interface not found" +Ensure you have run `composer update` to install `saloonphp/pagination-plugin`. + +### "Certificate not found" +Check your `.env` paths. The files must be readable by the PHP process (usually `www-data`). + +### "Invalid Signature" +Ensure you are using the correct **Signing Key** (not the Transport key) for business logic operations like `CmsSigner::sign()`. + +--- + +## 6. Architecture & Data Flow + +This section visualizes how data moves through the SDK, explaining the invisible work performed by the library (Security, Serialization, Transport). + +### 6.1 General Request Lifecycle (BaaS) +When you send a request (e.g., creating a payment), the SDK automatically handles DTO serialization, mTLS authentication, and response mapping. + +```mermaid +sequenceDiagram + participant User as Client App + participant SDK as SDK Facade + participant DTO as Request DTO + participant Con as Connector + participant API as Alfa Bank API + + User->>DTO: Instantiate (Strict Typing) + User->>SDK: send(Request) + SDK->>Con: Serialize DTO to JSON + Con->>Con: Attach mTLS Certificates + Con->>Con: Attach OAuth Token + Con->>API: HTTPS Request (Signed/Encrypted) + API-->>Con: Raw JSON Response + Con->>SDK: Map JSON to Response DTO + SDK-->>User: Return Response Object +``` + +### 6.2 SBP Body Signing (JCS) +The Faster Payments System (SBP) requires a specific "Body Signing" mechanism. The SDK implements **JSON Canonicalization Scheme (JCS)** to ensure the signature is valid regardless of key order. + +```mermaid +flowchart TD + A[Raw Request Body (Array)] -->|CmsSigner::canonicalize| B(Recursive Key Sort & JSON Encode) + B -->|OpenSSL RSA-SHA256| C{Sign with Private Key} + C -->|Base64 Encode| D[Signature String] + D -->|Add Header| E[Authorization: Base64] + E -->|mTLS Connection| F((Alfa Bank SBP Gateway)) + style B fill:#f9f,stroke:#333,stroke-width:2px + style C fill:#bbf,stroke:#333,stroke-width:2px +``` + +### 6.3 Webhook Processing +The SDK acts as a secure gatekeeper for incoming webhooks, verifying their origin before dispatching them to your application logic. + +```mermaid +sequenceDiagram + participant Bank as Alfa Bank + participant Route as Laravel Route + participant Mid as Middleware + participant Factory as WebhookFactory + participant Event as AlfaWebhookReceived + + Bank->>Route: POST /webhooks/alfa + Route->>Mid: Intercept Request + Mid->>Mid: Verify Credentials / Signature + alt Invalid + Mid-->>Bank: 401 Unauthorized + else Valid + Mid->>Factory: Extract Payload + Factory->>Factory: Detect Type (BaaS vs SBP) + Factory->>Event: Dispatch Typed DTO + Event-->>Route: Processing Complete + Route-->>Bank: 200 OK + end +``` + +--- + +*Generated by Alfa Bank SDK Team* \ No newline at end of file diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md new file mode 100644 index 0000000..e32d78f --- /dev/null +++ b/RELEASE_NOTES.md @@ -0,0 +1,75 @@ +# Alfa Bank SDK - Release Notes v1.0.0 + +## 🚀 Overview +The **Alfa Bank SDK** is a production-ready, enterprise-grade library for integrating with Alfa Bank's API (BaaS & SBP). It is built on top of **Saloon v3** and **Spatie Laravel Data**, ensuring strict typing, robustness, and idiomatic Laravel integration. + +## ✨ Key Features + +### 1. Unified API Access +- **BaaS (Bank-as-a-Service):** Full coverage of Accounts, Payments, Cards, Statements, and Salary projects. +- **SBP (Faster Payments):** Dedicated connector for C2B/B2C/B2B payouts with automated body signing (JCS/RSA-SHA256). +- **Security:** Native support for mTLS (GOST/RSA), detached CMS/PKCS#7 signatures, and JWS transport security. + +### 2. Architecture & Quality +- **DTO-Driven:** 100% of requests and responses are mapped to Data Transfer Objects. No more raw arrays. +- **Saloon Power:** Middleware for error handling, automatic retries, and timeouts. +- **Pagination:** Smart `AlfaOffsetPaginator` handling various response formats automatically. +- **Testing:** 63 automated tests verifying every module. + +### 3. Laravel Integration +- **Zero-Config:** Auto-discovery via Service Provider. +- **Facades:** `AlfaBank::` and `Sbp::` for static access. +- **Config:** Publishable `config/alfa-bank.php`. +- **Webhooks:** Route macro `Route::alfaWebhooks()` and event dispatching. + +## 🛠️ Installation + +```bash +composer require apoloz/alfa-bank-sdk +``` + +## 📖 Usage Examples + +### Create a Payment +```php +use AlfaBank; +use Apoloz\AlfaBank\Requests\Payments\CreatePaymentRequest; +use Apoloz\AlfaBank\Data\Payments\PaymentData; + +$data = new PaymentData( + amount: 100.50, + payeeAccount: '40702...', + // ... +); + +$response = AlfaBank::send(new CreatePaymentRequest($data)); +echo $response->id; // "EXT-123" +``` + +### Iterate Transactions (Pagination) +```php +use Apoloz\AlfaBank\Requests\Statement\GetTransactionsRequest; + +$paginator = AlfaBank::paginate(new GetTransactionsRequest('40702...')); + +foreach ($paginator as $transaction) { + echo $transaction->amount; +} +``` + +### SBP Payout +```php +use Sbp; +use Apoloz\AlfaBank\Sbp\Requests\Payouts\CreatePayoutRequest; + +// The SDK handles body signing automatically +Sbp::send(new CreatePayoutRequest($payoutData)); +``` + +## ✅ Verification Status +- **Tests Passed:** 63/63 +- **Static Analysis:** PHPStan Level 5 (0 errors) +- **Integration Test:** Verified in Laravel 12 environment via `alfa-bank-app`. + +--- +*Ready for deployment.*