refactor(core): enhance SDK structure and documentation

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
This commit is contained in:
2026-01-18 21:48:25 +03:00
parent 3da69c03e1
commit d214eecebe
378 changed files with 10514 additions and 496 deletions

View File

@@ -1,11 +1,25 @@
<?php
/*
// MODULE_CONTRACT: Defines the data structure for a CashLink QR Code activation request payload.
// RESPONSIBILITY: To hold and type-safely represent the parameters needed to activate a CashLink QR Code.
// INPUTS: Terminal number (TermNo), QR Code ID, amount, and various optional payment/notification parameters.
// OUTPUTS: A structured, type-safe object for the `ActivateCashQrRequest` payload.
// LINKS: Sbp/Requests/CashLink/ActivateCashQrRequest.php
*/
namespace Apoloz\AlfaBank\Sbp\Data\CashLink;
// <SECTION name="module_imports" intent="Import the base Spatie Laravel Data class.">
// <BELIEF_STATE "Extending `Spatie\LaravelData\Data` enables automatic casting from arrays and provides DTO benefits.">
use Spatie\LaravelData\Data;
// </SECTION>
// <SECTION name="class_definition" intent="Define a DTO for CashLink QR Code activation request.">
// <BELIEF_STATE "This DTO ensures the activation payload is strictly typed and complete, supporting clear communication for managing CashLink QR Codes.">
class ActivateCashQrRequestData extends Data
{
// <SECTION name="constructor_properties" intent="Define the properties for the CashLink QR Code activation request.">
// <BELIEF_STATE "The constructor includes mandatory `TermNo`, `qrcId`, and `amount`. The `currency` defaults to 'RUB'. Optional fields cover `OrderNumber`, `paymentPurpose`, `notificationUrl`, `qrTtl`, and `redirectUrl`, allowing for flexible activation details.">
public function __construct(
public string $TermNo,
public string $qrcId,
@@ -17,4 +31,5 @@ class ActivateCashQrRequestData extends Data
public ?string $qrTtl = null,
public ?string $redirectUrl = null,
) {}
// </SECTION>
}

View File

@@ -1,11 +1,25 @@
<?php
/*
// MODULE_CONTRACT: Defines the data structure for a CashLink QR Code registration request payload.
// RESPONSIBILITY: To hold and type-safely represent the parameters needed to register a CashLink QR Code.
// INPUTS: Terminal number (TermNo) and various optional display parameters.
// OUTPUTS: A structured, type-safe object for the `RegCashQrRequest` payload.
// LINKS: Sbp/Requests/CashLink/RegCashQrRequest.php
*/
namespace Apoloz\AlfaBank\Sbp\Data\CashLink;
// <SECTION name="module_imports" intent="Import the base Spatie Laravel Data class.">
// <BELIEF_STATE "Extending `Spatie\LaravelData\Data` enables automatic casting from arrays and provides DTO benefits.">
use Spatie\LaravelData\Data;
// </SECTION>
// <SECTION name="class_definition" intent="Define a DTO for CashLink QR Code registration request.">
// <BELIEF_STATE "This DTO ensures the registration payload is strictly typed and complete, supporting clear communication for generating CashLink QR Codes.">
class RegCashQrRequestData extends Data
{
// <SECTION name="constructor_properties" intent="Define the properties for the CashLink QR Code registration request.">
// <BELIEF_STATE "The constructor includes the mandatory `TermNo`. Optional fields cover `mediaType`, `width`, `height` (for QR image customization), `redirectUrl`, and an explicit `qrcId` if pre-defined.">
public function __construct(
public string $TermNo,
public ?string $mediaType = null,
@@ -14,4 +28,5 @@ class RegCashQrRequestData extends Data
public ?string $redirectUrl = null,
public ?string $qrcId = null,
) {}
// </SECTION>
}

View File

@@ -1,19 +1,34 @@
<?php
/*
// MODULE_CONTRACT: Defines the data structure for the response of a CashLink QR Code registration request.
// RESPONSIBILITY: To hold and type-safely represent the outcome of generating a CashLink QR Code.
// INPUTS: Raw JSON object from the API response.
// OUTPUTS: A structured object containing QR Code registration details.
// LINKS: Sbp/Requests/CashLink/RegCashQrRequest.php
*/
namespace Apoloz\AlfaBank\Sbp\Data\CashLink;
// <SECTION name="module_imports" intent="Import the base Spatie Laravel Data class.">
// <BELIEF_STATE "Extending `Spatie\LaravelData\Data` enables automatic casting from JSON and provides DTO benefits.">
use Spatie\LaravelData\Data;
// </SECTION>
// <SECTION name="class_definition" intent="Define a DTO for SBP CashLink QR Code registration response.">
// <BELIEF_STATE "This DTO provides a clear, type-safe contract for the confirmation details of a CashLink QR Code registration, crucial for displaying the QR Code to the user.">
class RegCashQrResponseData extends Data
{
// <SECTION name="constructor_properties" intent="Define the properties of the CashLink QR Code registration response.">
// <BELIEF_STATE "The constructor includes mandatory `ErrorCode` and `message` for overall status. Optional fields provide details about the created QR Code, such as `TermNo`, `content` (the QR data itself), `mediaType`, `payload`, `qrcId`, and `status`.">
public function __construct(
public int $ErrorCode,
public string $message,
public ?string $TermNo = null,
public ?string $content = null,
public ?string $content = null, // The raw QR string data (e.g., base64 encoded image or URL)
public ?string $mediaType = null,
public ?string $payload = null,
public ?string $payload = null, // The QR payload URL
public ?string $qrcId = null,
public ?string $status = null,
) {}
// </SECTION>
}

View File

@@ -1,21 +1,36 @@
<?php
/*
// MODULE_CONTRACT: Defines the data structure for a CashLink Universal QR Code account change request payload.
// RESPONSIBILITY: To hold and type-safely represent the parameters needed to update the linked account for a Digital Ruble CashLink QR Code.
// INPUTS: Terminal number (TermNo), and various optional account, merchant, and redirection parameters.
// OUTPUTS: A structured, type-safe object for the `ChangeAccForCashUniQrRequest` payload.
// LINKS: Sbp/Requests/DigitalRuble/CashLink/ChangeAccForCashUniQrRequest.php
*/
namespace Apoloz\AlfaBank\Sbp\Data\DigitalRuble\CashLink;
// <SECTION name="module_imports" intent="Import the base Spatie Laravel Data class.">
// <BELIEF_STATE "Extending `Spatie\LaravelData\Data` enables automatic casting from arrays and provides DTO benefits.">
use Spatie\LaravelData\Data;
// </SECTION>
// <SECTION name="class_definition" intent="Define a DTO for CashLink Universal QR Code account change request.">
// <BELIEF_STATE "This DTO ensures the account change payload is strictly typed and complete, supporting clear communication for Digital Ruble CashLink QR Code modifications.">
class ChangeAccForCashUniQrRequestData extends Data
{
// <SECTION name="constructor_properties" intent="Define the properties for the CashLink Uni QR Code account change request.">
// <BELIEF_STATE "The constructor includes the mandatory `TermNo`. Optional fields cover `messageID`, `qrcId`, account details (`account`, `accountDR`), new terminal/merchant IDs (`NewTermNo`, `NewMerchantId`), redirection (`redirectUrl`, `paymentPageUrl`), and `fraudScore` for risk assessment.">
public function __construct(
public string $TermNo,
public ?string $messageID = null,
public ?string $qrcId = null,
public ?string $account = null,
public ?string $accountDR = null,
public ?string $account = null, // Current or target conventional account
public ?string $accountDR = null, // Current or target Digital Ruble account
public ?string $NewTermNo = null,
public ?string $NewMerchantId = null,
public ?string $redirectUrl = null,
public ?string $paymentPageUrl = null,
public ?string $fraudScore = null,
) {}
// </SECTION>
}

View File

@@ -1,11 +1,25 @@
<?php
/*
// MODULE_CONTRACT: Defines the data structure for the response of a CashLink Universal QR Code account change request.
// RESPONSIBILITY: To hold and type-safely represent the outcome of updating the linked account for a Digital Ruble CashLink QR.
// INPUTS: Raw JSON object from the API response.
// OUTPUTS: A structured object containing account change confirmation details.
// LINKS: Sbp/Requests/DigitalRuble/CashLink/ChangeAccForCashUniQrRequest.php
*/
namespace Apoloz\AlfaBank\Sbp\Data\DigitalRuble\CashLink;
// <SECTION name="module_imports" intent="Import the base Spatie Laravel Data class.">
// <BELIEF_STATE "Extending `Spatie\LaravelData\Data` enables automatic casting from JSON and provides DTO benefits.">
use Spatie\LaravelData\Data;
// </SECTION>
// <SECTION name="class_definition" intent="Define a DTO for SBP CashLink Uni QR Code account change response.">
// <BELIEF_STATE "This DTO provides a clear, type-safe contract for the confirmation details of an account change operation, crucial for verifying the updated QR Code configuration.">
class ChangeAccForCashUniQrResponseData extends Data
{
// <SECTION name="constructor_properties" intent="Define the properties of the CashLink Uni QR Code account change response.">
// <BELIEF_STATE "The constructor includes mandatory `ErrorCode` and `message` for overall status. Optional fields provide details about the updated QR Code, such as `messageID`, `qrcId`, `TermNo`, account details (`account`, `accountDR`), redirection (`redirectUrl`, `paymentPageUrl`), `fraudScore`, and new terminal/merchant IDs (`NewTermNo`, `NewMerchantId`).">
public function __construct(
public int $ErrorCode,
public string $message,
@@ -13,7 +27,7 @@ class ChangeAccForCashUniQrResponseData extends Data
public ?string $qrcId = null,
public ?string $TermNo = null,
public ?string $account = null,
public ?string $accountDR = null,
public ?string $accountDR = null, // Digital Ruble account
public ?string $redirectUrl = null,
public ?string $paymentPageUrl = null,
public ?string $fraudScore = null,
@@ -22,4 +36,5 @@ class ChangeAccForCashUniQrResponseData extends Data
public ?string $status = null,
public ?string $merchantId = null,
) {}
// </SECTION>
}

View File

@@ -1,11 +1,25 @@
<?php
/*
// MODULE_CONTRACT: Defines the data structure for an SBP Digital Ruble CashLink Universal QR Code creation request payload.
// RESPONSIBILITY: To hold and type-safely represent the parameters needed to generate a new Digital Ruble CashLink QR.
// INPUTS: Terminal number (TermNo) and various optional display, payment, and notification parameters.
// OUTPUTS: A structured, type-safe object for the `CreateCashUniQrRequest` payload.
// LINKS: Sbp/Requests/DigitalRuble/CashLink/CreateCashUniQrRequest.php
*/
namespace Apoloz\AlfaBank\Sbp\Data\DigitalRuble\CashLink;
// <SECTION name="module_imports" intent="Import the base Spatie Laravel Data class.">
// <BELIEF_STATE "Extending `Spatie\LaravelData\Data` enables automatic casting from arrays and provides DTO benefits.">
use Spatie\LaravelData\Data;
// </SECTION>
// <SECTION name="class_definition" intent="Define a DTO for SBP Digital Ruble CashLink Universal QR Code creation request.">
// <BELIEF_STATE "This DTO ensures the CashLink Uni QR creation payload is strictly typed and complete, supporting clear communication for Digital Ruble transactions with the SBP API.">
class CreateCashUniQrRequestData extends Data
{
// <SECTION name="constructor_properties" intent="Define the properties for the Digital Ruble CashLink Uni QR Code creation request.">
// <BELIEF_STATE "The constructor includes the mandatory `TermNo`. Optional fields cover display (`mediaType`, `width`, `height`), redirection (`redirectUrl`, `paymentPageUrl`), tracking (`messageID`, `notificationUrl`), and explicit `qrcId` if pre-defined.">
public function __construct(
public string $TermNo,
public ?string $messageID = null,
@@ -17,4 +31,5 @@ class CreateCashUniQrRequestData extends Data
public ?string $qrcId = null,
public ?string $notificationUrl = null,
) {}
// </SECTION>
}

View File

@@ -1,20 +1,35 @@
<?php
/*
// MODULE_CONTRACT: Defines the data structure for the response of a CashLink Universal QR Code creation request.
// RESPONSIBILITY: To hold and type-safely represent the outcome of generating a Digital Ruble CashLink QR Code.
// INPUTS: Raw JSON object from the API response.
// OUTPUTS: A structured object containing QR Code creation details.
// LINKS: Sbp/Requests/DigitalRuble/CashLink/CreateCashUniQrRequest.php
*/
namespace Apoloz\AlfaBank\Sbp\Data\DigitalRuble\CashLink;
// <SECTION name="module_imports" intent="Import the base Spatie Laravel Data class.">
// <BELIEF_STATE "Extending `Spatie\LaravelData\Data` enables automatic casting from JSON and provides DTO benefits.">
use Spatie\LaravelData\Data;
// </SECTION>
// <SECTION name="class_definition" intent="Define a DTO for SBP CashLink Universal QR Code creation response.">
// <BELIEF_STATE "This DTO provides a clear, type-safe contract for the confirmation details of a CashLink Uni QR Code creation, crucial for displaying the QR Code to the user.">
class CreateCashUniQrResponseData extends Data
{
// <SECTION name="constructor_properties" intent="Define the properties of the CashLink Uni QR Code creation response.">
// <BELIEF_STATE "The constructor includes mandatory `ErrorCode` and `message` for overall status. Optional fields provide details about the created QR Code, such as `TermNo`, `payload` (the QR data itself), `image` (URL to the QR image), `mediaType`, `qrcId`, `messageID`, and `status`.">
public function __construct(
public int $ErrorCode,
public string $message,
public ?string $TermNo = null,
public ?string $payload = null,
public ?string $image = null,
public ?string $payload = null, // The raw QR string data
public ?string $image = null, // URL to the QR image
public ?string $mediaType = null,
public ?string $qrcId = null,
public ?string $messageID = null,
public ?string $status = null,
) {}
// </SECTION>
}

View File

@@ -1,11 +1,25 @@
<?php
/*
// MODULE_CONTRACT: Defines the data structure for a CashLink Universal QR Code status request payload.
// RESPONSIBILITY: To hold and type-safely represent the parameters needed to query the status of a Digital Ruble CashLink QR Code.
// INPUTS: Terminal number (TermNo), Uni QR ID, parameters ID, and optional message ID/payrrn.
// OUTPUTS: A structured, type-safe object for the `GetCashUniQrStatusRequest` payload.
// LINKS: Sbp/Requests/DigitalRuble/CashLink/GetCashUniQrStatusRequest.php
*/
namespace Apoloz\AlfaBank\Sbp\Data\DigitalRuble\CashLink;
// <SECTION name="module_imports" intent="Import the base Spatie Laravel Data class.">
// <BELIEF_STATE "Extending `Spatie\LaravelData\Data` enables automatic casting from arrays and provides DTO benefits.">
use Spatie\LaravelData\Data;
// </SECTION>
// <SECTION name="class_definition" intent="Define a DTO for CashLink Universal QR Code status request.">
// <BELIEF_STATE "This DTO ensures the status request payload is strictly typed and complete, supporting clear communication with the SBP API.">
class GetCashUniQrStatusRequestData extends Data
{
// <SECTION name="constructor_properties" intent="Define the properties for the CashLink Uni QR Code status request.">
// <BELIEF_STATE "The constructor includes the mandatory `TermNo`, `uniQrId`, and `paramsId` to identify the target QR Code and its associated parameters. Optional fields `messageID` and `payrrn` provide additional query flexibility.">
public function __construct(
public string $TermNo,
public string $uniQrId,
@@ -13,4 +27,5 @@ class GetCashUniQrStatusRequestData extends Data
public ?string $messageID = null,
public ?string $payrrn = null,
) {}
// </SECTION>
}

View File

@@ -1,11 +1,25 @@
<?php
/*
// MODULE_CONTRACT: Defines the data structure for the response of a CashLink Universal QR Code status request.
// RESPONSIBILITY: To hold and type-safely represent detailed status information about a Digital Ruble CashLink QR Code.
// INPUTS: Raw JSON object from the API response.
// OUTPUTS: A structured object containing CashLink Uni QR status details.
// LINKS: Sbp/Requests/DigitalRuble/CashLink/GetCashUniQrStatusRequest.php
*/
namespace Apoloz\AlfaBank\Sbp\Data\DigitalRuble\CashLink;
// <SECTION name="module_imports" intent="Import the base Spatie Laravel Data class.">
// <BELIEF_STATE "Extending `Spatie\LaravelData\Data` enables automatic casting from JSON and provides DTO benefits.">
use Spatie\LaravelData\Data;
// </SECTION>
// <SECTION name="class_definition" intent="Define a DTO for SBP CashLink Universal QR Code status response.">
// <BELIEF_STATE "This DTO provides a clear, type-safe contract for tracking the status of Digital Ruble CashLink QR Codes, crucial for managing payment flows.">
class GetCashUniQrStatusResponseData extends Data
{
// <SECTION name="constructor_properties" intent="Define the properties of the CashLink Uni QR Code status response.">
// <BELIEF_STATE "The constructor includes mandatory `ErrorCode` and `message` for overall status. Optional fields provide detailed information about the QR Code and its associated transaction, such as `TermNo`, `messageID`, `uniQrId`, `paramsId`, `trxStatus`, `payrrn`, `timestamp`, `cashRegisterQrcStatus`, `trxId`, `trxDT`, `amount`, `currency`, `Url`, `CreditDatePos`, `payerId`, `kzo`, `merchantId`, and `paymentServiceId`.">
public function __construct(
public int $ErrorCode,
public string $message,
@@ -28,4 +42,5 @@ class GetCashUniQrStatusResponseData extends Data
public ?string $merchantId = null,
public ?string $paymentServiceId = null,
) {}
// </SECTION>
}

View File

@@ -1,11 +1,25 @@
<?php
/*
// MODULE_CONTRACT: Defines the data structure for an SBP Digital Ruble Universal QR Code creation request payload.
// RESPONSIBILITY: To hold and type-safely represent the parameters needed to generate a new Digital Ruble Uni QR.
// INPUTS: Terminal number (TermNo), QR type, and various optional display, payment, and notification parameters.
// OUTPUTS: A structured, type-safe object for the `CreateUniQrRequest` payload.
// LINKS: Sbp/Requests/DigitalRuble/CreateUniQrRequest.php
*/
namespace Apoloz\AlfaBank\Sbp\Data\DigitalRuble;
// <SECTION name="module_imports" intent="Import the base Spatie Laravel Data class.">
// <BELIEF_STATE "Extending `Spatie\LaravelData\Data` enables automatic casting from arrays and provides DTO benefits.">
use Spatie\LaravelData\Data;
// </SECTION>
// <SECTION name="class_definition" intent="Define a DTO for SBP Digital Ruble Universal QR Code creation request.">
// <BELIEF_STATE "This DTO ensures the Uni QR creation payload is strictly typed and complete, supporting clear communication for Digital Ruble transactions with the SBP API.">
class CreateUniQrRequestData extends Data
{
// <SECTION name="constructor_properties" intent="Define the properties for the Digital Ruble Uni QR Code creation request.">
// <BELIEF_STATE "The constructor includes the mandatory `TermNo` and `uniQrType`. Optional fields cover display (`mediaType`, `width`, `height`), payment details (`amount`, `paymentPurpose`), redirection (`redirectUrl`, `paymentPageUrl`), validity (`qrTtl`), tracking (`messageID`, `notificationUrl`), and optional sender information (`SenderFIO`, `SenderID`, `SenderBankBIC`).">
public function __construct(
public string $TermNo,
public string $uniQrType = '02', // 01=Multi, 02=Single
@@ -23,4 +37,5 @@ class CreateUniQrRequestData extends Data
public ?string $SenderID = null,
public ?string $SenderBankBIC = null,
) {}
// </SECTION>
}

View File

@@ -1,11 +1,25 @@
<?php
/*
// MODULE_CONTRACT: Defines the data structure for a Digital Ruble payment notification payload.
// RESPONSIBILITY: To hold and type-safely represent the details of an incoming Digital Ruble payment event.
// INPUTS: Raw array from a Digital Ruble payment webhook.
// OUTPUTS: A structured object containing payment notification details.
// LINKS: Sbp/Requests/DigitalRuble/Notifications/ParsePaymentDrNotification.php
*/
namespace Apoloz\AlfaBank\Sbp\Data\DigitalRuble\Notifications;
// <SECTION name="module_imports" intent="Import the base Spatie Laravel Data class.">
// <BELIEF_STATE "Extending `Spatie\LaravelData\Data` enables automatic casting from arrays and provides DTO benefits.">
use Spatie\LaravelData\Data;
// </SECTION>
// <SECTION name="class_definition" intent="Define a DTO for Digital Ruble payment notification.">
// <BELIEF_STATE "This DTO provides a clear, type-safe contract for Digital Ruble payment notifications, crucial for reliably processing incoming payment events.">
class PaymentDrNotificationData extends Data
{
// <SECTION name="constructor_properties" intent="Define the properties of a Digital Ruble payment notification.">
// <BELIEF_STATE "The constructor includes mandatory fields such as `command`, `payrrn`, `BatchId`, `TermNo`, `CreditDatePos`, and `merchantName`. Optional fields provide additional context like `uniQrId`, `operationId`, `status`, `amount`, `timestamp`, and `purpose`, essential for a comprehensive payment record.">
public function __construct(
public string $command,
public string $payrrn,
@@ -20,4 +34,5 @@ class PaymentDrNotificationData extends Data
public ?string $timestamp = null,
public ?string $purpose = null,
) {}
// </SECTION>
}

View File

@@ -1,14 +1,29 @@
<?php
/*
// MODULE_CONTRACT: Defines the data structure for an SBP QR Code block/unblock request payload.
// RESPONSIBILITY: To hold and type-safely represent the parameters needed to block or unblock a specific QR Code.
// INPUTS: Terminal number (TermNo), QR Code ID, and an optional reason.
// OUTPUTS: A structured, type-safe object for `BlockQrRequest` and `UnblockQrRequest` payloads.
// LINKS: Sbp/Requests/Management/BlockQrRequest.php, Sbp/Requests/Management/UnblockQrRequest.php
*/
namespace Apoloz\AlfaBank\Sbp\Data\Management;
// <SECTION name="module_imports" intent="Import the base Spatie Laravel Data class.">
// <BELIEF_STATE "Extending `Spatie\LaravelData\Data` enables automatic casting from arrays and provides DTO benefits.">
use Spatie\LaravelData\Data;
// </SECTION>
// <SECTION name="class_definition" intent="Define a DTO for SBP QR Code block/unblock request.">
// <BELIEF_STATE "This DTO ensures the request payload for blocking or unblocking a QR Code is strictly typed and complete, supporting clear management operations.">
class BlockQrRequestData extends Data
{
// <SECTION name="constructor_properties" intent="Define the properties for the QR Code block/unblock request.">
// <BELIEF_STATE "The constructor includes the mandatory `TermNo` and `qrcId` to identify the target QR Code. An optional `reason` can be provided for blocking actions.">
public function __construct(
public string $TermNo,
public string $qrcId,
public ?string $reason = null,
) {}
// </SECTION>
}

View File

@@ -1,32 +1,81 @@
<?php
/*
// MODULE_CONTRACT: Defines the structure and mapping for the request payload when generating an SBP QR Code.
// RESPONSIBILITY: To ensure type safety, enforce expected data types, and handle property name mapping between internal (camelCase) and external (PascalCase/API) conventions.
// INPUTS: Raw data array (typically from user input or internal system).
// OUTPUTS: A validated, strongly-typed object representing the QR code generation request.
// LINKS: GetQrCodeRequest.php (uses this DTO)
*/
namespace Apoloz\AlfaBank\Sbp\Data;
// <SECTION name="module_imports" intent="Import necessary attributes and base class for defining the DTO.">
// <BELIEF_STATE "Spatie's Laravel Data package provides powerful features for DTOs, including automatic mapping, validation, and serialization. Using its attributes (`MapName`, `Data`) simplifies the DTO's definition and functionality.">
use Spatie\LaravelData\Attributes\MapName;
use Spatie\LaravelData\Attributes\MapOutputName; // Note: Not used directly here, but generally relevant for output mapping
use Spatie\LaravelData\Data;
use Spatie\LaravelData\Mappers\NameMapper; // Note: Not directly used, but part of the Spatie Data ecosystem
// </SECTION>
// <SECTION name="class_definition" intent="Define the DTO for an SBP QR Code generation request.">
// <BELIEF_STATE "A dedicated DTO for the QR code request ensures that the input data for the API call is always structured correctly and explicitly typed. This significantly improves code readability, maintainability, and prevents common API integration bugs.">
class QrCodeRequestData extends Data
{
// <SECTION name="constructor_properties" intent="Define all properties that constitute the QR code request payload, including API name mappings.">
// <BELIEF_STATE "Each property explicitly defines its type and optionality. Crucially, `#[MapName]` attributes are used to bridge the gap between internal PHP `camelCase` naming conventions and the external API's `PascalCase` requirements, maintaining a clean internal API while satisfying external constraints.">
public function __construct(
public string $TermNo,
public string $qrcType = '01', // '01' = Static, '02' = Dynamic
// <BELIEF_STATE "The `TermNo` is a mandatory identifier for the payment terminal. Using `#[MapName]` allows the internal property to be `termNo` (camelCase) while the API expects `TermNo` (PascalCase).">
#[MapName('TermNo')]
public string $termNo,
// <BELIEF_STATE "The `qrcType` specifies whether the QR code is static ('01') or dynamic ('02'). Providing a default value simplifies usage for the most common scenario.">
#[MapName('qrcType')] // Although same name, good to be explicit
public string $qrcType = '01',
// <BELIEF_STATE "The `amount` is optional for static QRs but mandatory for dynamic ones. It's stored as a string to avoid floating-point precision issues with currency.">
public ?string $amount = null,
// <BELIEF_STATE "The `currency` is typically 'RUB' for SBP, but it's explicitly defined for clarity and future extensibility.">
public string $currency = 'RUB',
// <BELIEF_STATE "The `paymentPurpose` provides a human-readable description for the payment, improving reconciliation.">
public ?string $paymentPurpose = null,
// <BELIEF_STATE "The `redirectUrl` is where the user is sent after completing the payment, essential for web-based flows.">
public ?string $redirectUrl = null,
// <BELIEF_STATE "The `messageID` provides an optional, unique identifier for the request, useful for idempotency or tracking.">
public ?string $messageID = null,
// <BELIEF_STATE "Width and height allow customization of the generated QR code image dimensions.">
public ?string $width = null,
public ?string $height = null,
// <BELIEF_STATE "The `notificationUrl` specifies where the bank should send webhook notifications about payment status changes.">
public ?string $notificationUrl = null,
// Dynamic QR specific fields
public ?string $OrderNumber = null,
public ?string $qrTtl = null, // Minutes, 1-6
// <BELIEF_STATE "The `OrderNumber` is specific to dynamic QRs, providing a unique identifier for the order in the merchant's system.">
#[MapName('OrderNumber')]
public ?string $orderNumber = null,
// <BELIEF_STATE "The `qrTtl` defines how long a dynamic QR code remains valid, specified in minutes.">
public ?string $qrTtl = null,
// <BELIEF_STATE "Subscription service identifiers are used for recurring payment scenarios with SBP.">
public ?string $subscriptionServiceId = null,
public ?string $subscriptionServiceName = null,
// Optional user data for Dynamic QR
public ?string $SenderFIO = null,
public ?string $SenderID = null,
public ?string $SenderBankBIC = null,
// Optional user data for Dynamic QR (often part of sender identification)
// <BELIEF_STATE "Sender details are crucial for identifying the payer in certain SBP scenarios. `#[MapName]` ensures these follow API conventions.">
#[MapName('SenderFIO')]
public ?string $senderFio = null,
#[MapName('SenderID')]
public ?string $senderId = null,
#[MapName('SenderBankBIC')]
public ?string $senderBankBic = null,
) {}
}
// </SECTION>
}

View File

@@ -1,11 +1,25 @@
<?php
/*
// MODULE_CONTRACT: Defines the data structure for the response when generating an SBP QR Code.
// RESPONSIBILITY: To provide a strongly-typed structure for the API's response to QR code generation requests, including status, potential error messages, and the generated QR code data (image, payload, ID).
// INPUTS: Raw array data from the SBP QR Code generation API response.
// OUTPUTS: An instantiated DTO with properties mapped from the input array.
// LINKS: Sbp/Requests/GetQrCodeRequest.php, README.md#sbp-api
*/
namespace Apoloz\AlfaBank\Sbp\Data;
// <SECTION name="module_imports" intent="Import the base Spatie\LaravelData class.">
// <BELIEF_STATE "This class extends `Spatie\LaravelData\Data` to leverage its robust data mapping and type safety, ensuring consistent and predictable handling of SBP QR Code response payloads.">
use Spatie\LaravelData\Data;
// </SECTION>
// <SECTION name="class_definition" intent="Define the QR Code response data structure.">
// <BELIEF_STATE "The `QrCodeResponseData` DTO encapsulates all possible fields returned by the SBP QR Code generation API. Fields are explicitly typed as nullable to accommodate variations in API responses, particularly for error scenarios where certain data might be absent.">
class QrCodeResponseData extends Data
{
// <SECTION name="constructor_properties" intent="Define the properties of the QR Code response DTO.">
// <BELIEF_STATE "Properties are defined directly in the constructor for brevity and immutability, leveraging PHP 8's constructor property promotion. Fields like `ErrorCode` are always expected, while others like `image` or `payload` are nullable as they might only be present on successful responses.">
public function __construct(
public int $ErrorCode,
public ?string $message = null,
@@ -17,4 +31,6 @@ class QrCodeResponseData extends Data
public ?string $messageID = null,
public ?string $status = null,
) {}
}
// </SECTION>
}
// </SECTION>

View File

@@ -1,14 +1,29 @@
<?php
/*
// MODULE_CONTRACT: Defines the data structure for the response of an SBP bank list request.
// RESPONSIBILITY: To hold and type-safely represent the list of banks participating in the SBP.
// INPUTS: Raw JSON object from the API response.
// OUTPUTS: A structured object containing the bank list.
// LINKS: Sbp/Requests/Registry/GetBankListRequest.php
*/
namespace Apoloz\AlfaBank\Sbp\Data\Registry;
// <SECTION name="module_imports" intent="Import the base Spatie Laravel Data class.">
// <BELIEF_STATE "Extending `Spatie\LaravelData\Data` enables automatic casting from JSON and provides DTO benefits.">
use Spatie\LaravelData\Data;
// </SECTION>
// <SECTION name="class_definition" intent="Define a DTO for SBP bank list response.">
// <BELIEF_STATE "This DTO provides a clear, type-safe contract for the SBP bank list, crucial for routing payments and providing bank selection options.">
class GetBankListResponseData extends Data
{
// <SECTION name="constructor_properties" intent="Define the properties of the SBP bank list response.">
// <BELIEF_STATE "The constructor includes mandatory `ErrorCode` and `message` for overall status. The `BankList` property is an optional array (which could be further typed with a `DataCollectionOf` if `BankData` DTOs were defined) containing details of participating banks.">
public function __construct(
public int $ErrorCode,
public string $message,
public ?array $BankList = null,
public ?array $BankList = null, // Array of bank details, could be DataCollectionOf(BankData::class)
) {}
// </SECTION>
}

View File

@@ -1,11 +1,25 @@
<?php
/*
// MODULE_CONTRACT: Defines the data structure for an SBP QR Code reversal data request payload.
// RESPONSIBILITY: To hold and type-safely represent the parameters needed to query detailed information about a QR Code reversal.
// INPUTS: Terminal number (TermNo), currency, and various optional reversal identifiers.
// OUTPUTS: A structured, type-safe object for the `GetQrcReversalDataRequest` payload.
// LINKS: Sbp/Requests/Reversal/GetQrcReversalDataRequest.php
*/
namespace Apoloz\AlfaBank\Sbp\Data\Reversal;
// <SECTION name="module_imports" intent="Import the base Spatie Laravel Data class.">
// <BELIEF_STATE "Extending `Spatie\LaravelData\Data` enables automatic casting from arrays and provides DTO benefits.">
use Spatie\LaravelData\Data;
// </SECTION>
// <SECTION name="class_definition" intent="Define a DTO for SBP QR Code reversal data request.">
// <BELIEF_STATE "This DTO ensures the reversal data request payload is strictly typed and complete, supporting clear communication with the SBP API.">
class GetQrcReversalDataRequestData extends Data
{
// <SECTION name="constructor_properties" intent="Define the properties for the QR Code reversal data request.">
// <BELIEF_STATE "The constructor includes the mandatory `TermNo` and `currency`. Optional identifiers like `qrcId`, `payrrn`, `trxId`, `trxDT`, `amount`, `messageID`, and `ReturnRestAmount` provide flexibility for various reversal data queries.">
public function __construct(
public string $TermNo,
public ?string $qrcId = null,
@@ -17,4 +31,5 @@ class GetQrcReversalDataRequestData extends Data
public ?string $messageID = null,
public ?bool $ReturnRestAmount = null,
) {}
// </SECTION>
}

View File

@@ -1,11 +1,25 @@
<?php
/*
// MODULE_CONTRACT: Defines the data structure for the response of a QR Code reversal data request.
// RESPONSIBILITY: To hold and type-safely represent detailed information about an SBP QR Code reversal.
// INPUTS: Raw JSON object from the API response.
// OUTPUTS: A structured object containing detailed reversal data.
// LINKS: Sbp/Requests/Reversal/GetQrcReversalDataRequest.php
*/
namespace Apoloz\AlfaBank\Sbp\Data\Reversal;
// <SECTION name="module_imports" intent="Import the base Spatie Laravel Data class.">
// <BELIEF_STATE "Extending `Spatie\LaravelData\Data` enables automatic casting from JSON and provides DTO benefits.">
use Spatie\LaravelData\Data;
// </SECTION>
// <SECTION name="class_definition" intent="Define a DTO for detailed SBP QR Code reversal data response.">
// <BELIEF_STATE "This DTO provides a clear, type-safe contract for the detailed outcome of a reversal data query, crucial for reconciliation and error analysis.">
class GetQrcReversalDataResponseData extends Data
{
// <SECTION name="constructor_properties" intent="Define the properties of the QR Code reversal data response.">
// <BELIEF_STATE "The constructor includes mandatory error codes and messages, along with optional detailed information about the reversal such as `TermNo`, `messageID`, payer details, `payrrn`, `qrcId`, `trxDT`, `trxId`, and `restAmount`.">
public function __construct(
public int $ErrorCode,
public string $message,
@@ -21,4 +35,5 @@ class GetQrcReversalDataResponseData extends Data
public ?string $trxId = null,
public ?string $restAmount = null,
) {}
// </SECTION>
}

View File

@@ -1,11 +1,25 @@
<?php
/*
// MODULE_CONTRACT: Defines the data structure for a SBP QR Code reversal status request payload.
// RESPONSIBILITY: To hold and type-safely represent the parameters needed to query the status of a QR Code reversal.
// INPUTS: Terminal number (TermNo) and various optional reversal identifiers.
// OUTPUTS: A structured, type-safe object for the `GetQrcReversalStatusRequest` payload.
// LINKS: Sbp/Requests/Reversal/GetQrcReversalStatusRequest.php
*/
namespace Apoloz\AlfaBank\Sbp\Data\Reversal;
// <SECTION name="module_imports" intent="Import the base Spatie Laravel Data class.">
// <BELIEF_STATE "Extending `Spatie\LaravelData\Data` enables automatic casting from arrays and provides DTO benefits.">
use Spatie\LaravelData\Data;
// </SECTION>
// <SECTION name="class_definition" intent="Define a DTO for SBP QR Code reversal status request.">
// <BELIEF_STATE "This DTO ensures the reversal status request payload is strictly typed and complete, supporting clear communication with the SBP API.">
class GetQrcReversalStatusRequestData extends Data
{
// <SECTION name="constructor_properties" intent="Define the properties for the QR Code reversal status request.">
// <BELIEF_STATE "The constructor includes the mandatory `TermNo` and optional identifiers like `payrrn`, `originalTrxId`, `trxId`, and `messageID`. These allow for flexible and precise querying of a reversal's status.">
public function __construct(
public string $TermNo,
public ?string $payrrn = null,
@@ -13,4 +27,5 @@ class GetQrcReversalStatusRequestData extends Data
public ?string $trxId = null,
public ?string $messageID = null,
) {}
// </SECTION>
}

View File

@@ -1,11 +1,25 @@
<?php
/*
// MODULE_CONTRACT: Defines the data structure for the response of a QR Code reversal status request.
// RESPONSIBILITY: To hold and type-safely represent the outcome and status of an SBP QR Code reversal operation.
// INPUTS: Raw JSON object from the API response.
// OUTPUTS: A structured object containing reversal status information.
// LINKS: Sbp/Requests/Reversal/GetQrcReversalStatusRequest.php
*/
namespace Apoloz\AlfaBank\Sbp\Data\Reversal;
// <SECTION name="module_imports" intent="Import the base Spatie Laravel Data class.">
// <BELIEF_STATE "Extending `Spatie\LaravelData\Data` enables automatic casting from JSON and provides DTO benefits.">
use Spatie\LaravelData\Data;
// </SECTION>
// <SECTION name="class_definition" intent="Define a DTO for SBP QR Code reversal status response.">
// <BELIEF_STATE "This DTO provides a clear, type-safe contract for tracking the status of an SBP reversal, crucial for managing financial transactions.">
class GetQrcReversalStatusResponseData extends Data
{
// <SECTION name="constructor_properties" intent="Define the properties of the QR Code reversal status response.">
// <BELIEF_STATE "The constructor includes mandatory `ErrorCode` and `message` for overall status. Optional fields provide detailed information about the transaction, such as `TermNo`, `amount`, `messageID`, `originalQrcId`, `originalTrxId`, payer details, `Url`, `status`, `trxDT`, and `trxId`.">
public function __construct(
public int $ErrorCode,
public ?string $message = null,
@@ -20,4 +34,5 @@ class GetQrcReversalStatusResponseData extends Data
public ?string $trxDT = null,
public ?string $trxId = null,
) {}
// </SECTION>
}

View File

@@ -1,11 +1,25 @@
<?php
/*
// MODULE_CONTRACT: Defines the data structure for an SBP QR Code reversal request payload.
// RESPONSIBILITY: To hold and type-safely represent the parameters needed to initiate a QR Code reversal.
// INPUTS: Terminal number (TermNo), currency, and various optional reversal identifiers.
// OUTPUTS: A structured, type-safe object for the `QrcReversalRequest` payload.
// LINKS: Sbp/Requests/Reversal/QrcReversalRequest.php
*/
namespace Apoloz\AlfaBank\Sbp\Data\Reversal;
// <SECTION name="module_imports" intent="Import the base Spatie Laravel Data class.">
// <BELIEF_STATE "Extending `Spatie\LaravelData\Data` enables automatic casting from arrays and provides DTO benefits.">
use Spatie\LaravelData\Data;
// </SECTION>
// <SECTION name="class_definition" intent="Define a DTO for SBP QR Code reversal request.">
// <BELIEF_STATE "This DTO ensures the reversal request payload is strictly typed and complete, supporting clear communication for critical financial operations with the SBP API.">
class QrcReversalRequestData extends Data
{
// <SECTION name="constructor_properties" intent="Define the properties for the QR Code reversal request.">
// <BELIEF_STATE "The constructor includes the mandatory `TermNo` and `currency`. Optional identifiers like `qrcId`, `payrrn`, `trxId`, `trxDT`, `amount`, `messageID`, `notificationUrl`, and `ReturnRestAmount` provide flexibility for various reversal scenarios.">
public function __construct(
public string $TermNo,
public ?string $qrcId = null,
@@ -19,4 +33,5 @@ class QrcReversalRequestData extends Data
public ?bool $ReturnRestAmount = null,
// extJsonParams not fully implemented as it's optional and dynamic
) {}
// </SECTION>
}

View File

@@ -1,11 +1,25 @@
<?php
/*
// MODULE_CONTRACT: Defines the data structure for the response of a QR Code reversal request.
// RESPONSIBILITY: To hold and type-safely represent the outcome of an SBP QR Code reversal operation.
// INPUTS: Raw JSON object from the API response.
// OUTPUTS: A structured object containing reversal confirmation details.
// LINKS: Sbp/Requests/Reversal/QrcReversalRequest.php
*/
namespace Apoloz\AlfaBank\Sbp\Data\Reversal;
// <SECTION name="module_imports" intent="Import the base Spatie Laravel Data class.">
// <BELIEF_STATE "Extending `Spatie\LaravelData\Data` enables automatic casting from JSON and provides DTO benefits.">
use Spatie\LaravelData\Data;
// </SECTION>
// <SECTION name="class_definition" intent="Define a DTO for SBP QR Code reversal response.">
// <BELIEF_STATE "This DTO provides a clear, type-safe contract for the confirmation details of an SBP reversal, crucial for verifying the transaction.">
class QrcReversalResponseData extends Data
{
// <SECTION name="constructor_properties" intent="Define the properties of the QR Code reversal response.">
// <BELIEF_STATE "The constructor includes mandatory `ErrorCode` and optional fields like `message`, `TermNo`, `amount`, `currency`, `messageID`, `trxDT`, `trxId`, `payrrn`, and `restAmount`. These fields provide the status and key identifiers of the reversal.">
public function __construct(
public int $ErrorCode,
public ?string $message = null,
@@ -18,4 +32,5 @@ class QrcReversalResponseData extends Data
public ?string $payrrn = null,
public ?string $restAmount = null,
) {}
// </SECTION>
}

View File

@@ -1,15 +1,30 @@
<?php
/*
// MODULE_CONTRACT: Defines the data structure for an SBP QR Code status request payload.
// RESPONSIBILITY: To hold and type-safely represent the parameters needed to query the status of a specific QR Code.
// INPUTS: Terminal number (TermNo) and various optional QR Code identifiers.
// OUTPUTS: A structured, type-safe object for the `GetQrcStatusRequest` payload.
// LINKS: Sbp/Requests/Status/GetQrcStatusRequest.php
*/
namespace Apoloz\AlfaBank\Sbp\Data\Status;
// <SECTION name="module_imports" intent="Import the base Spatie Laravel Data class.">
// <BELIEF_STATE "Extending `Spatie\LaravelData\Data` enables automatic casting from arrays and provides DTO benefits.">
use Spatie\LaravelData\Data;
// </SECTION>
// <SECTION name="class_definition" intent="Define a DTO for SBP QR Code status request.">
// <BELIEF_STATE "This DTO ensures the status request payload is strictly typed and complete, supporting clear communication with the SBP API.">
class GetQrcStatusRequestData extends Data
{
// <SECTION name="constructor_properties" intent="Define the properties for the QR Code status request.">
// <BELIEF_STATE "The constructor includes the mandatory `TermNo` and optional identifiers like `qrcId`, `payrrn`, and `messageID`. These allow for flexible and precise querying of a QR Code's status.">
public function __construct(
public string $TermNo,
public ?string $qrcId = null,
public ?string $payrrn = null,
public ?string $messageID = null,
) {}
// </SECTION>
}

View File

@@ -1,11 +1,25 @@
<?php
/*
// MODULE_CONTRACT: Defines the data structure for the response of an SBP QR Code status request.
// RESPONSIBILITY: To hold and type-safely represent detailed status information about a specific QR Code.
// INPUTS: Raw JSON object from the API response.
// OUTPUTS: A structured object containing QR Code status details.
// LINKS: Sbp/Requests/Status/GetQrcStatusRequest.php
*/
namespace Apoloz\AlfaBank\Sbp\Data\Status;
// <SECTION name="module_imports" intent="Import the base Spatie Laravel Data class.">
// <BELIEF_STATE "Extending `Spatie\LaravelData\Data` enables automatic casting from JSON and provides DTO benefits.">
use Spatie\LaravelData\Data;
// </SECTION>
// <SECTION name="class_definition" intent="Define a DTO for SBP QR Code status response.">
// <BELIEF_STATE "This DTO provides a clear, type-safe contract for tracking the status of SBP QR Codes, crucial for managing payment flows and reconciliation.">
class GetQrcStatusResponseData extends Data
{
// <SECTION name="constructor_properties" intent="Define the properties of the QR Code status response.">
// <BELIEF_STATE "The constructor includes mandatory `ErrorCode` and `message` for overall status. Optional fields provide detailed information about the QR Code and its transaction, such as `qrcId`, `status`, `trxId`, `trxDT`, `payrrn`, `CreditDatePos`, `TermNo`, `amount`, `currency`, `Url`, `payerId`, `kzo`, and `merchantId`.">
public function __construct(
public int $ErrorCode,
public string $message,
@@ -24,4 +38,5 @@ class GetQrcStatusResponseData extends Data
public ?string $messageID = null,
public ?string $merchantId = null,
) {}
// </SECTION>
}

View File

@@ -1,19 +1,34 @@
<?php
/*
// MODULE_CONTRACT: Defines the data structure for an SBP QR Code subscription registration request payload.
// RESPONSIBILITY: To hold and type-safely represent the parameters needed to register a new SBP subscription.
// INPUTS: Terminal number (TermNo), subscription purpose, notification URL, and various optional QR Code parameters.
// OUTPUTS: A structured, type-safe object for the `RegQrSubRequest` payload.
// LINKS: Sbp/Requests/Subscription/RegQrSubRequest.php
*/
namespace Apoloz\AlfaBank\Sbp\Data\Subscription;
// <SECTION name="module_imports" intent="Import the base Spatie Laravel Data class.">
// <BELIEF_STATE "Extending `Spatie\LaravelData\Data` enables automatic casting from arrays and provides DTO benefits.">
use Spatie\LaravelData\Data;
// </SECTION>
// <SECTION name="class_definition" intent="Define a DTO for SBP QR Code subscription registration request.">
// <BELIEF_STATE "This DTO ensures the subscription registration payload is strictly typed and complete, supporting clear communication with the SBP API for recurring payments.">
class RegQrSubRequestData extends Data
{
// <SECTION name="constructor_properties" intent="Define the properties for the QR Code subscription registration request.">
// <BELIEF_STATE "The constructor includes mandatory `TermNo`, `subscriptionPurpose`, `notificationUrl`, and defaults `qrcType` to '03' (subscription). Optional fields like `qrTtl`, `redirectUrl`, `subscriptionServiceId`, and `subscriptionServiceName` provide flexibility for detailed subscription setup.">
public function __construct(
public string $TermNo,
public string $subscriptionPurpose,
public string $notificationUrl,
public string $qrcType = '03',
public string $qrcType = '03', // '03' = Subscription
public ?string $qrTtl = null,
public ?string $redirectUrl = null,
public ?string $subscriptionServiceId = null,
public ?string $subscriptionServiceName = null,
) {}
// </SECTION>
}

View File

@@ -1,29 +1,50 @@
<?php
/*
// MODULE_CONTRACT: Represents the SBP API call to activate a CashLink QR Code.
// RESPONSIBILITY: To define the POST request for making a previously registered CashLink QR Code active and scannable.
// INPUTS: ActivateCashQrRequestData (DTO) containing QR Code activation parameters.
// OUTPUTS: Raw array response from the API.
*/
namespace Apoloz\AlfaBank\Sbp\Requests\CashLink;
// <SECTION name="module_imports" intent="Import DTO and Saloon components for a JSON body request.">
// <BELIEF_STATE "This POST request requires the `ActivateCashQrRequestData` DTO for its JSON body and utilizes `HasBody` and `HasJsonBody` for proper payload serialization. It currently returns a raw array response.">
use Apoloz\AlfaBank\Sbp\Data\CashLink\ActivateCashQrRequestData;
use Saloon\Contracts\Body\HasBody;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
use Saloon\Traits\Body\HasJsonBody;
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to activate a CashLink QR Code.">
// <BELIEF_STATE "This class encapsulates the logic for activating a CashLink QR Code, a key management operation in SBP payment systems.">
class ActivateCashQrRequest extends Request implements HasBody
{
use HasJsonBody;
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Activating a resource is an action that changes the system state, so POST is the correct verb.">
protected Method $method = Method::POST;
// </SECTION>
// <SECTION name="constructor" intent="Inject the DTO containing the QR Code activation data.">
// <BELIEF_STATE "Using a strongly-typed DTO (`ActivateCashQrRequestData`) ensures that all necessary information for QR Code activation is provided and correctly structured.">
public function __construct(
protected ActivateCashQrRequestData $data
) {}
// <SECTION name="endpoint_resolver" intent="Define the endpoint for SBP CashLink QR Code activation.">
// <BELIEF_STATE "The SBP API often uses generic endpoints with a 'command' field in the body, implying the endpoint itself might be empty or a base SBP URL.">
public function resolveEndpoint(): string
{
return '';
return ''; // Endpoint is determined by SbpConnector's base URL
}
// </SECTION>
// <SECTION name="body_builder" intent="Construct the JSON body for the request.">
// <BELIEF_STATE "The `command` field specifies the operation to the SBP API. Fields from the DTO are mapped, including conditional parameters for order number, payment purpose, QR TTL, and notification URLs.">
protected function defaultBody(): array
{
$body = [
@@ -44,9 +65,13 @@ class ActivateCashQrRequest extends Request implements HasBody
return $body;
}
// </SECTION>
// <SECTION name="response_caster" intent="Return the raw JSON response as an array.">
// <BELIEF_STATE "For this specific request, the response is currently returned as a raw array. A dedicated DTO could be created if a structured object is required.">
public function createDtoFromResponse(Response $response): array
{
return $response->json();
}
// </SECTION>
}

View File

@@ -1,18 +1,37 @@
<?php
/*
// MODULE_CONTRACT: Represents the SBP API call to change the account for a CashLink QR Code.
// RESPONSIBILITY: To define the POST request for updating the linked account for a specific CashLink QR.
// INPUTS: Terminal number (TermNo), QR Code ID, new account, and optional merchant/redirect details.
// OUTPUTS: Raw array response from the API.
*/
namespace Apoloz\AlfaBank\Sbp\Requests\CashLink;
// <SECTION name="module_imports" intent="Import Saloon components for a JSON body request.">
// <BELIEF_STATE "This POST request utilizes `HasBody` and `HasJsonBody` for proper payload serialization. It currently returns a raw array response.">
use Saloon\Contracts\Body\HasBody;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Traits\Body\HasJsonBody;
// <BELIEF_STATE "The `Response` object is fully qualified in `createDtoFromResponse` as it is not explicitly imported with a `use` statement at the top. This is acceptable but less explicit.">
// use Saloon\Http\Response; // Explicit import would be cleaner
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to change the account for a CashLink QR Code.">
// <BELIEF_STATE "This class encapsulates the logic for modifying a CashLink QR Code, which is a key management operation.">
class ChangeAccountForCashQrRequest extends Request implements HasBody
{
use HasJsonBody;
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Modifying a resource via an action is correctly represented by a POST request in the SBP API context.">
protected Method $method = Method::POST;
// </SECTION>
// <SECTION name="constructor" intent="Inject the mandatory and optional parameters for the account change request.">
// <BELIEF_STATE "The constructor requires `TermNo`, `qrcId`, and the new `account`. Optional parameters (`NewTermNo`, `NewMerchantId`, `redirectUrl`) allow for more complex reconfigurations.">
public function __construct(
protected string $TermNo,
protected string $qrcId,
@@ -22,11 +41,16 @@ class ChangeAccountForCashQrRequest extends Request implements HasBody
protected ?string $redirectUrl = null,
) {}
// <SECTION name="endpoint_resolver" intent="Define the endpoint for SBP CashLink QR Code account changes.">
// <BELIEF_STATE "The SBP API often uses generic endpoints with a 'command' field in the body, implying the endpoint itself might be empty or a base SBP URL.">
public function resolveEndpoint(): string
{
return '';
return ''; // Endpoint is determined by SbpConnector's base URL
}
// </SECTION>
// <SECTION name="body_builder" intent="Construct the JSON body for the request.">
// <BELIEF_STATE "The `command` field specifies the operation to the SBP API. Fields are conditionally added based on constructor parameters, ensuring the payload precisely matches the API specification.">
protected function defaultBody(): array
{
$body = [
@@ -42,9 +66,13 @@ class ChangeAccountForCashQrRequest extends Request implements HasBody
return $body;
}
// </SECTION>
// <SECTION name="response_caster" intent="Return the raw JSON response as an array.">
// <BELIEF_STATE "For this specific request, the response is currently returned as a raw array. A dedicated DTO could be created if a structured object is required.">
public function createDtoFromResponse(\Saloon\Http\Response $response): array
{
return $response->json();
}
// </SECTION>
}

View File

@@ -1,28 +1,52 @@
<?php
/*
// MODULE_CONTRACT: Represents the SBP API call to change the terminal number for a CashLink QR Code.
// RESPONSIBILITY: To define the POST request for updating the linked terminal for a specific CashLink QR.
// INPUTS: Terminal number (TermNo) and QR Code ID.
// OUTPUTS: Raw array response from the API.
*/
namespace Apoloz\AlfaBank\Sbp\Requests\CashLink;
// <SECTION name="module_imports" intent="Import Saloon components for a JSON body request.">
// <BELIEF_STATE "This POST request utilizes `HasBody` and `HasJsonBody` for proper payload serialization. It currently returns a raw array response.">
use Saloon\Contracts\Body\HasBody;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Traits\Body\HasJsonBody;
// <BELIEF_STATE "The `Response` object is fully qualified in `createDtoFromResponse` as it is not explicitly imported with a `use` statement at the top. This is acceptable but less explicit.">
// use Saloon\Http\Response; // Explicit import would be cleaner
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to change the terminal number for a CashLink QR Code.">
// <BELIEF_STATE "This class encapsulates the logic for modifying a CashLink QR Code, specifically its associated terminal, which is a key management operation.">
class ChangeTermNoForCashQrRequest extends Request implements HasBody
{
use HasJsonBody;
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Modifying a resource via an action is correctly represented by a POST request in the SBP API context.">
protected Method $method = Method::POST;
// </SECTION>
// <SECTION name="constructor" intent="Inject the mandatory terminal number and QR Code ID.">
// <BELIEF_STATE "The constructor requires `TermNo` and `qrcId` to identify the target QR Code for which the terminal number is being changed.">
public function __construct(
protected string $TermNo,
protected string $qrcId
) {}
// <SECTION name="endpoint_resolver" intent="Define the endpoint for SBP CashLink QR Code terminal number changes.">
// <BELIEF_STATE "The SBP API often uses generic endpoints with a 'command' field in the body, implying the endpoint itself might be empty or a base SBP URL.">
public function resolveEndpoint(): string
{
return '';
return ''; // Endpoint is determined by SbpConnector's base URL
}
// </SECTION>
// <SECTION name="body_builder" intent="Construct the JSON body for the request.">
// <BELIEF_STATE "The `command` field specifies the operation to the SBP API. The `TermNo` and `qrcId` are included in the body to identify the target.">
protected function defaultBody(): array
{
return [
@@ -31,9 +55,13 @@ class ChangeTermNoForCashQrRequest extends Request implements HasBody
'qrcId' => $this->qrcId,
];
}
// </SECTION>
// <SECTION name="response_caster" intent="Return the raw JSON response as an array.">
// <BELIEF_STATE "For this specific request, the response is currently returned as a raw array. A dedicated DTO could be created if a structured object is required.">
public function createDtoFromResponse(\Saloon\Http\Response $response): array
{
return $response->json();
}
// </SECTION>
}

View File

@@ -1,28 +1,52 @@
<?php
/*
// MODULE_CONTRACT: Represents the SBP API call to delete a CashLink QR Code.
// RESPONSIBILITY: To define the POST request for deactivating and removing a specific CashLink QR.
// INPUTS: Terminal number (TermNo) and QR Code ID.
// OUTPUTS: Raw array response from the API.
*/
namespace Apoloz\AlfaBank\Sbp\Requests\CashLink;
// <SECTION name="module_imports" intent="Import Saloon components for a JSON body request.">
// <BELIEF_STATE "This POST request utilizes `HasBody` and `HasJsonBody` for proper payload serialization. It currently returns a raw array response.">
use Saloon\Contracts\Body\HasBody;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Traits\Body\HasJsonBody;
// <BELIEF_STATE "The `Response` object is fully qualified in `createDtoFromResponse` as it is not explicitly imported with a `use` statement at the top. This is acceptable but less explicit.">
// use Saloon\Http\Response; // Explicit import would be cleaner
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to delete a CashLink QR Code.">
// <BELIEF_STATE "This class encapsulates the logic for deleting a CashLink QR Code, which is a critical management operation.">
class DeleteCashQrRequest extends Request implements HasBody
{
use HasJsonBody;
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Deleting a resource via an action is correctly represented by a POST request in the SBP API context.">
protected Method $method = Method::POST;
// </SECTION>
// <SECTION name="constructor" intent="Inject the mandatory terminal number and QR Code ID.">
// <BELIEF_STATE "The constructor requires `TermNo` and `qrcId` to identify the target QR Code for deletion.">
public function __construct(
protected string $TermNo,
protected string $qrcId
) {}
// <SECTION name="endpoint_resolver" intent="Define the endpoint for SBP CashLink QR Code deletion.">
// <BELIEF_STATE "The SBP API often uses generic endpoints with a 'command' field in the body, implying the endpoint itself might be empty or a base SBP URL.">
public function resolveEndpoint(): string
{
return '';
return ''; // Endpoint is determined by SbpConnector's base URL
}
// </SECTION>
// <SECTION name="body_builder" intent="Construct the JSON body for the request.">
// <BELIEF_STATE "The `command` field specifies the operation to the SBP API. The `TermNo` and `qrcId` are included in the body to identify the target.">
protected function defaultBody(): array
{
return [
@@ -31,9 +55,13 @@ class DeleteCashQrRequest extends Request implements HasBody
'qrcId' => $this->qrcId,
];
}
// </SECTION>
// <SECTION name="response_caster" intent="Return the raw JSON response as an array.">
// <BELIEF_STATE "For this specific request, the response is currently returned as a raw array. A dedicated DTO could be created if a structured object is required.">
public function createDtoFromResponse(\Saloon\Http\Response $response): array
{
return $response->json();
}
// </SECTION>
}

View File

@@ -1,18 +1,37 @@
<?php
/*
// MODULE_CONTRACT: Represents the SBP API call to get the history of a CashLink QR Code.
// RESPONSIBILITY: To define the POST request for retrieving historical data for a specific CashLink QR Code.
// INPUTS: Terminal number (TermNo), QR Code ID, and a date range.
// OUTPUTS: Raw array response from the API.
*/
namespace Apoloz\AlfaBank\Sbp\Requests\CashLink;
// <SECTION name="module_imports" intent="Import Saloon components for a JSON body request.">
// <BELIEF_STATE "This POST request utilizes `HasBody` and `HasJsonBody` for proper payload serialization. It currently returns a raw array response.">
use Saloon\Contracts\Body\HasBody;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Traits\Body\HasJsonBody;
// <BELIEF_STATE "The `Response` object is fully qualified in `createDtoFromResponse` as it is not explicitly imported with a `use` statement at the top. This is acceptable but less explicit.">
// use Saloon\Http\Response; // Explicit import would be cleaner
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to get the history of a CashLink QR Code.">
// <BELIEF_STATE "This class encapsulates the logic for querying the history of a CashLink QR Code, which is useful for auditing and reconciliation.">
class GetCashQrHistoryRequest extends Request implements HasBody
{
use HasJsonBody;
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Even though it retrieves data, SBP history requests are often performed via POST requests with a JSON body.">
protected Method $method = Method::POST;
// </SECTION>
// <SECTION name="constructor" intent="Inject the mandatory parameters for the CashLink QR Code history request.">
// <BELIEF_STATE "The constructor requires `TermNo`, `qrcId`, and a `dateFrom`/`dateTo` range to specify the target QR Code and the period of interest.">
public function __construct(
protected string $TermNo,
protected string $qrcId,
@@ -20,11 +39,16 @@ class GetCashQrHistoryRequest extends Request implements HasBody
protected string $dateTo
) {}
// <SECTION name="endpoint_resolver" intent="Define the endpoint for SBP CashLink QR Code history queries.">
// <BELIEF_STATE "The SBP API often uses generic endpoints with a 'command' field in the body, implying the endpoint itself might be empty or a base SBP URL.">
public function resolveEndpoint(): string
{
return '';
return ''; // Endpoint is determined by SbpConnector's base URL
}
// </SECTION>
// <SECTION name="body_builder" intent="Construct the JSON body for the request.">
// <BELIEF_STATE "The `command` field specifies the operation to the SBP API. All constructor properties are directly mapped to the request body to identify the QR Code and the date range.">
protected function defaultBody(): array
{
return [
@@ -35,9 +59,13 @@ class GetCashQrHistoryRequest extends Request implements HasBody
'dateTo' => $this->dateTo,
];
}
// </SECTION>
// <SECTION name="response_caster" intent="Return the raw JSON response as an array.">
// <BELIEF_STATE "For this specific request, the response is currently returned as a raw array. A dedicated DTO could be created if a structured object is required.">
public function createDtoFromResponse(\Saloon\Http\Response $response): array
{
return $response->json();
}
// </SECTION>
}

View File

@@ -1,28 +1,52 @@
<?php
/*
// MODULE_CONTRACT: Represents the SBP API call to get the status of a CashLink QR Code.
// RESPONSIBILITY: To define the POST request for checking the state of a specific CashLink QR.
// INPUTS: Terminal number (TermNo) and QR Code ID.
// OUTPUTS: Raw array response from the API.
*/
namespace Apoloz\AlfaBank\Sbp\Requests\CashLink;
// <SECTION name="module_imports" intent="Import Saloon components for a JSON body request.">
// <BELIEF_STATE "This POST request utilizes `HasBody` and `HasJsonBody` for proper payload serialization. It currently returns a raw array response.">
use Saloon\Contracts\Body\HasBody;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Traits\Body\HasJsonBody;
// <BELIEF_STATE "The `Response` object is fully qualified in `createDtoFromResponse` as it is not explicitly imported with a `use` statement at the top. This is acceptable but less explicit.">
// use Saloon\Http\Response; // Explicit import would be cleaner
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to get the status of a CashLink QR Code.">
// <BELIEF_STATE "This class encapsulates the logic for querying the status of a CashLink QR Code, which is crucial for tracking payment flows.">
class GetCashQrStatusRequest extends Request implements HasBody
{
use HasJsonBody;
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Even though it retrieves data, SBP status checks are often performed via POST requests with a JSON body.">
protected Method $method = Method::POST;
// </SECTION>
// <SECTION name="constructor" intent="Inject the mandatory terminal number and QR Code ID.">
// <BELIEF_STATE "The constructor requires `TermNo` and `qrcId` to specify the target QR Code whose status is being queried.">
public function __construct(
protected string $TermNo,
protected string $qrcId
) {}
// <SECTION name="endpoint_resolver" intent="Define the endpoint for SBP CashLink QR Code status queries.">
// <BELIEF_STATE "The SBP API often uses generic endpoints with a 'command' field in the body, implying the endpoint itself might be empty or a base SBP URL.">
public function resolveEndpoint(): string
{
return '';
return ''; // Endpoint is determined by SbpConnector's base URL
}
// </SECTION>
// <SECTION name="body_builder" intent="Construct the JSON body for the request.">
// <BELIEF_STATE "The `command` field specifies the operation to the SBP API. The `TermNo` and `qrcId` identify the target.">
protected function defaultBody(): array
{
return [
@@ -31,9 +55,13 @@ class GetCashQrStatusRequest extends Request implements HasBody
'qrcId' => $this->qrcId,
];
}
// </SECTION>
// <SECTION name="response_caster" intent="Return the raw JSON response as an array.">
// <BELIEF_STATE "For this specific request, the response is currently returned as a raw array. A dedicated DTO could be created if a structured object is required.">
public function createDtoFromResponse(\Saloon\Http\Response $response): array
{
return $response->json();
}
// </SECTION>
}

View File

@@ -1,7 +1,15 @@
<?php
/*
// MODULE_CONTRACT: Represents the SBP API call to register a CashLink QR Code.
// RESPONSIBILITY: To define the POST request for creating a new CashLink QR Code.
// INPUTS: RegCashQrRequestData (DTO) containing QR Code parameters.
// OUTPUTS: RegCashQrResponseData (DTO).
*/
namespace Apoloz\AlfaBank\Sbp\Requests\CashLink;
// <SECTION name="module_imports" intent="Import DTOs and Saloon components for a JSON body request.">
// <BELIEF_STATE "This POST request requires specific DTOs for its JSON body and its response, along with Saloon's body-handling traits.">
use Apoloz\AlfaBank\Sbp\Data\CashLink\RegCashQrRequestData;
use Apoloz\AlfaBank\Sbp\Data\CashLink\RegCashQrResponseData;
use Saloon\Contracts\Body\HasBody;
@@ -9,22 +17,35 @@ use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
use Saloon\Traits\Body\HasJsonBody;
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to register a CashLink QR Code.">
// <BELIEF_STATE "This class encapsulates the logic for generating a CashLink QR Code, a key feature in SBP payment systems.">
class RegCashQrRequest extends Request implements HasBody
{
use HasJsonBody;
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Creating a new QR Code resource or initiating a generation action is correctly represented by a POST request.">
protected Method $method = Method::POST;
// </SECTION>
// <SECTION name="constructor" intent="Inject the DTO containing the CashLink QR Code registration data.">
// <BELIEF_STATE "Using a strongly-typed DTO (`RegCashQrRequestData`) ensures that all necessary information for QR Code generation is provided and correctly structured.">
public function __construct(
protected RegCashQrRequestData $data
) {}
// <SECTION name="endpoint_resolver" intent="Define the endpoint for SBP CashLink QR Code registration.">
// <BELIEF_STATE "The SBP API often uses generic endpoints with a 'command' field in the body, implying the endpoint itself might be empty or a base SBP URL.">
public function resolveEndpoint(): string
{
return '';
return ''; // Endpoint is determined by SbpConnector's base URL
}
// </SECTION>
// <SECTION name="body_builder" intent="Construct the JSON body for the request.">
// <BELIEF_STATE "The `command` field specifies the operation to the SBP API. Fields from the DTO are mapped, including conditional parameters for media type, dimensions, redirect URL, and QR Code ID.">
protected function defaultBody(): array
{
$body = [
@@ -40,9 +61,13 @@ class RegCashQrRequest extends Request implements HasBody
return $body;
}
// </SECTION>
// <SECTION name="response_caster" intent="Map the JSON response to a DTO.">
// <BELIEF_STATE "Casting the response to a `RegCashQrResponseData` DTO provides a type-safe and structured object for the result of the QR Code registration.">
public function createDtoFromResponse(Response $response): RegCashQrResponseData
{
return RegCashQrResponseData::from($response->json());
}
// </SECTION>
}

View File

@@ -1,7 +1,15 @@
<?php
/*
// MODULE_CONTRACT: Represents the SBP API call to change the account for a CashLink Universal QR Code.
// RESPONSIBILITY: To define the POST request for updating the linked account for a Digital Ruble CashLink QR.
// INPUTS: ChangeAccForCashUniQrRequestData (DTO) with relevant parameters.
// OUTPUTS: ChangeAccForCashUniQrResponseData (DTO).
*/
namespace Apoloz\AlfaBank\Sbp\Requests\DigitalRuble\CashLink;
// <SECTION name="module_imports" intent="Import DTOs and Saloon components for a JSON body request.">
// <BELIEF_STATE "This POST request requires specific DTOs for its JSON body and its response, along with Saloon's body-handling traits.">
use Apoloz\AlfaBank\Sbp\Data\DigitalRuble\CashLink\ChangeAccForCashUniQrRequestData;
use Apoloz\AlfaBank\Sbp\Data\DigitalRuble\CashLink\ChangeAccForCashUniQrResponseData;
use Saloon\Contracts\Body\HasBody;
@@ -9,22 +17,35 @@ use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
use Saloon\Traits\Body\HasJsonBody;
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to change the account for a CashLink Uni QR Code.">
// <BELIEF_STATE "This class encapsulates the logic for modifying a Digital Ruble CashLink QR Code, which is a key management operation.">
class ChangeAccForCashUniQrRequest extends Request implements HasBody
{
use HasJsonBody;
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Modifying a resource via an action is correctly represented by a POST request in the SBP API context.">
protected Method $method = Method::POST;
// </SECTION>
// <SECTION name="constructor" intent="Inject the DTO containing the account change data.">
// <BELIEF_STATE "Using a strongly-typed DTO (`ChangeAccForCashUniQrRequestData`) ensures that all necessary information for the account change is provided and correctly structured.">
public function __construct(
protected ChangeAccForCashUniQrRequestData $data
) {}
// <SECTION name="endpoint_resolver" intent="Define the endpoint for SBP CashLink Uni QR Code account changes.">
// <BELIEF_STATE "The SBP API often uses generic endpoints with a 'command' field in the body, implying the endpoint itself might be empty or a base SBP URL.">
public function resolveEndpoint(): string
{
return '';
return ''; // Endpoint is determined by SbpConnector's base URL
}
// </SECTION>
// <SECTION name="body_builder" intent="Construct the JSON body for the request.">
// <BELIEF_STATE "The `command` field specifies the operation to the SBP API. Fields from the DTO are mapped, including conditional parameters for the new account, merchant, redirect URL, etc.">
protected function defaultBody(): array
{
$body = [
@@ -44,9 +65,13 @@ class ChangeAccForCashUniQrRequest extends Request implements HasBody
return $body;
}
// </SECTION>
// <SECTION name="response_caster" intent="Map the JSON response to a DTO.">
// <BELIEF_STATE "Casting the response to a `ChangeAccForCashUniQrResponseData` DTO provides a type-safe and structured object for the result of the account change operation.">
public function createDtoFromResponse(Response $response): ChangeAccForCashUniQrResponseData
{
return ChangeAccForCashUniQrResponseData::from($response->json());
}
// </SECTION>
}

View File

@@ -1,7 +1,15 @@
<?php
/*
// MODULE_CONTRACT: Represents the SBP API call to create a CashLink Universal QR Code for Digital Ruble.
// RESPONSIBILITY: To define the POST request for generating a new Digital Ruble CashLink QR.
// INPUTS: CreateCashUniQrRequestData (DTO) containing QR Code parameters.
// OUTPUTS: CreateCashUniQrResponseData (DTO).
*/
namespace Apoloz\AlfaBank\Sbp\Requests\DigitalRuble\CashLink;
// <SECTION name="module_imports" intent="Import DTOs and Saloon components for a JSON body request.">
// <BELIEF_STATE "This POST request requires specific DTOs for its JSON body and its response, along with Saloon's body-handling traits.">
use Apoloz\AlfaBank\Sbp\Data\DigitalRuble\CashLink\CreateCashUniQrRequestData;
use Apoloz\AlfaBank\Sbp\Data\DigitalRuble\CashLink\CreateCashUniQrResponseData;
use Saloon\Contracts\Body\HasBody;
@@ -9,22 +17,35 @@ use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
use Saloon\Traits\Body\HasJsonBody;
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to create a CashLink Uni QR Code.">
// <BELIEF_STATE "This class encapsulates the logic for generating a Digital Ruble CashLink QR Code, a key feature in the SBP Digital Ruble operations.">
class CreateCashUniQrRequest extends Request implements HasBody
{
use HasJsonBody;
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Creating a new QR Code resource or initiating a generation action is correctly represented by a POST request.">
protected Method $method = Method::POST;
// </SECTION>
// <SECTION name="constructor" intent="Inject the DTO containing the CashLink Uni QR Code creation data.">
// <BELIEF_STATE "Using a strongly-typed DTO (`CreateCashUniQrRequestData`) ensures that all necessary information for QR Code generation is provided and correctly structured.">
public function __construct(
protected CreateCashUniQrRequestData $data
) {}
// <SECTION name="endpoint_resolver" intent="Define the endpoint for SBP CashLink Uni QR Code creation.">
// <BELIEF_STATE "The SBP API often uses generic endpoints with a 'command' field in the body, implying the endpoint itself might be empty or a base SBP URL.">
public function resolveEndpoint(): string
{
return '';
return ''; // Endpoint is determined by SbpConnector's base URL
}
// </SECTION>
// <SECTION name="body_builder" intent="Construct the JSON body for the request.">
// <BELIEF_STATE "The `command` field specifies the operation to the SBP API. Fields from the DTO are mapped, including conditional and nested `queryData` for notification URLs.">
protected function defaultBody(): array
{
$body = [
@@ -46,9 +67,13 @@ class CreateCashUniQrRequest extends Request implements HasBody
return $body;
}
// </SECTION>
// <SECTION name="response_caster" intent="Map the JSON response to a DTO.">
// <BELIEF_STATE "Casting the response to a `CreateCashUniQrResponseData` DTO provides a type-safe and structured object for the result of the QR Code creation.">
public function createDtoFromResponse(Response $response): CreateCashUniQrResponseData
{
return CreateCashUniQrResponseData::from($response->json());
}
// </SECTION>
}

View File

@@ -1,7 +1,15 @@
<?php
/*
// MODULE_CONTRACT: Represents the SBP API call to get the status of a CashLink Universal QR Code.
// RESPONSIBILITY: To define the POST request for checking the state of a specific Digital Ruble CashLink QR.
// INPUTS: GetCashUniQrStatusRequestData (DTO) with relevant parameters.
// OUTPUTS: GetCashUniQrStatusResponseData (DTO).
*/
namespace Apoloz\AlfaBank\Sbp\Requests\DigitalRuble\CashLink;
// <SECTION name="module_imports" intent="Import DTOs and Saloon components for a JSON body request.">
// <BELIEF_STATE "This POST request requires specific DTOs for its JSON body and its response, along with Saloon's body-handling traits.">
use Apoloz\AlfaBank\Sbp\Data\DigitalRuble\CashLink\GetCashUniQrStatusRequestData;
use Apoloz\AlfaBank\Sbp\Data\DigitalRuble\CashLink\GetCashUniQrStatusResponseData;
use Saloon\Contracts\Body\HasBody;
@@ -9,22 +17,35 @@ use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
use Saloon\Traits\Body\HasJsonBody;
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to get the status of a CashLink Uni QR Code.">
// <BELIEF_STATE "This class encapsulates the logic for querying the status of a Digital Ruble CashLink QR Code, which is crucial for tracking payment flows.">
class GetCashUniQrStatusRequest extends Request implements HasBody
{
use HasJsonBody;
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Even though it retrieves data, SBP status checks are often performed via POST requests with a JSON body.">
protected Method $method = Method::POST;
// </SECTION>
// <SECTION name="constructor" intent="Inject the DTO containing the status request data.">
// <BELIEF_STATE "Using a strongly-typed DTO (`GetCashUniQrStatusRequestData`) ensures that all necessary information for the status query is provided and correctly structured.">
public function __construct(
protected GetCashUniQrStatusRequestData $data
) {}
// <SECTION name="endpoint_resolver" intent="Define the endpoint for SBP CashLink Uni QR Code status queries.">
// <BELIEF_STATE "The SBP API often uses generic endpoints with a 'command' field in the body, implying the endpoint itself might be empty or a base SBP URL.">
public function resolveEndpoint(): string
{
return '';
return ''; // Endpoint is determined by SbpConnector's base URL
}
// </SECTION>
// <SECTION name="body_builder" intent="Construct the JSON body for the request.">
// <BELIEF_STATE "The `command` field specifies the operation to the SBP API. The `TermNo`, `uniQrId`, and `paramsId` identify the target. Optional fields like `messageID` and `payrrn` provide additional context.">
protected function defaultBody(): array
{
$body = [
@@ -39,9 +60,13 @@ class GetCashUniQrStatusRequest extends Request implements HasBody
return $body;
}
// </SECTION>
// <SECTION name="response_caster" intent="Map the JSON response to a DTO.">
// <BELIEF_STATE "Casting the response to a `GetCashUniQrStatusResponseData` DTO provides a type-safe and structured object for the status of the CashLink Uni QR Code.">
public function createDtoFromResponse(Response $response): GetCashUniQrStatusResponseData
{
return GetCashUniQrStatusResponseData::from($response->json());
}
// </SECTION>
}

View File

@@ -1,28 +1,52 @@
<?php
/*
// MODULE_CONTRACT: Represents the SBP API call to create a Universal QR Code for Digital Ruble.
// RESPONSIBILITY: To define the POST request for generating a new Uni QR Code for digital ruble transactions.
// INPUTS: CreateUniQrRequestData (DTO) containing QR Code parameters.
// OUTPUTS: Raw array response from the API.
*/
namespace Apoloz\AlfaBank\Sbp\Requests\DigitalRuble;
// <SECTION name="module_imports" intent="Import DTO and Saloon components for a JSON body request.">
// <BELIEF_STATE "This POST request requires the `CreateUniQrRequestData` DTO for its JSON body and utilizes `HasBody` and `HasJsonBody` for proper payload serialization. It currently returns a raw array response.">
use Apoloz\AlfaBank\Sbp\Data\DigitalRuble\CreateUniQrRequestData;
use Saloon\Contracts\Body\HasBody;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Traits\Body\HasJsonBody;
// <BELIEF_STATE "The `Response` object is fully qualified in `createDtoFromResponse` as it is not explicitly imported with a `use` statement at the top. This is acceptable but less explicit.">
// use Saloon\Http\Response; // Explicit import would be cleaner
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to create a Universal QR Code.">
// <BELIEF_STATE "This class encapsulates the logic for generating a Uni QR Code for digital ruble, a key feature in the SBP Digital Ruble operations.">
class CreateUniQrRequest extends Request implements HasBody
{
use HasJsonBody;
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Creating a new QR Code resource or initiating a generation action is correctly represented by a POST request.">
protected Method $method = Method::POST;
// </SECTION>
// <SECTION name="constructor" intent="Inject the DTO containing the Uni QR Code creation data.">
// <BELIEF_STATE "Using a strongly-typed DTO (`CreateUniQrRequestData`) ensures that all necessary information for QR Code generation is provided and correctly structured.">
public function __construct(
protected CreateUniQrRequestData $data
) {}
// <SECTION name="endpoint_resolver" intent="Define the endpoint for SBP Uni QR Code creation.">
// <BELIEF_STATE "The SBP API often uses generic endpoints with a 'command' field in the body, implying the endpoint itself might be empty or a base SBP URL.">
public function resolveEndpoint(): string
{
return '';
return ''; // Endpoint is determined by SbpConnector's base URL
}
// </SECTION>
// <SECTION name="body_builder" intent="Construct the JSON body for the request.">
// <BELIEF_STATE "The `command` field specifies the operation to the SBP API. Fields from the DTO are mapped, including conditional and nested `queryData` for sender information and notification URLs.">
protected function defaultBody(): array
{
$body = [
@@ -54,9 +78,13 @@ class CreateUniQrRequest extends Request implements HasBody
return $body;
}
// </SECTION>
// <SECTION name="response_caster" intent="Return the raw JSON response as an array.">
// <BELIEF_STATE "For this specific request, the response is currently returned as a raw array. A dedicated DTO could be created if a structured object is required.">
public function createDtoFromResponse(\Saloon\Http\Response $response): array
{
return $response->json();
}
// </SECTION>
}

View File

@@ -1,28 +1,52 @@
<?php
/*
// MODULE_CONTRACT: Represents the SBP API call to get the status of Universal QR Codes for Digital Ruble.
// RESPONSIBILITY: To define the POST request for checking the state of multiple Uni QR Codes.
// INPUTS: Terminal number (TermNo) and an array of Uni QR Code IDs.
// OUTPUTS: Raw array response from the API.
*/
namespace Apoloz\AlfaBank\Sbp\Requests\DigitalRuble;
// <SECTION name="module_imports" intent="Import Saloon components for a JSON body request.">
// <BELIEF_STATE "This POST request utilizes `HasBody` and `HasJsonBody` for proper payload serialization. It currently returns a raw array response.">
use Saloon\Contracts\Body\HasBody;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Traits\Body\HasJsonBody;
// <BELIEF_STATE "The `Response` object is fully qualified in `createDtoFromResponse` as it is not explicitly imported with a `use` statement at the top. This is acceptable but less explicit.">
// use Saloon\Http\Response; // Explicit import would be cleaner
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to get the status of Universal QR Codes.">
// <BELIEF_STATE "This class encapsulates the logic for querying the status of multiple Uni QR Codes, which is part of managing digital ruble transactions.">
class GetUniQrStatusRequest extends Request implements HasBody
{
use HasJsonBody;
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Even though it retrieves data, SBP status checks are often performed via POST requests with a JSON body.">
protected Method $method = Method::POST;
// </SECTION>
// <SECTION name="constructor" intent="Inject the mandatory terminal number and Uni QR Code IDs.">
// <BELIEF_STATE "The constructor requires `TermNo` to identify the terminal and `uniQrIds` (an array of strings) to specify the QR Codes whose status is being queried.">
public function __construct(
protected string $TermNo,
protected array $uniQrIds, // Array of strings
) {}
// <SECTION name="endpoint_resolver" intent="Define the endpoint for SBP Uni QR Code status queries.">
// <BELIEF_STATE "The SBP API often uses generic endpoints with a 'command' field in the body, implying the endpoint itself might be empty or a base SBP URL.">
public function resolveEndpoint(): string
{
return '';
return ''; // Endpoint is determined by SbpConnector's base URL
}
// </SECTION>
// <SECTION name="body_builder" intent="Construct the JSON body for the request.">
// <BELIEF_STATE "The `command` field specifies the operation to the SBP API. The `TermNo` and `uniQrIds` are included in the body to identify the targets.">
protected function defaultBody(): array
{
return [
@@ -31,9 +55,13 @@ class GetUniQrStatusRequest extends Request implements HasBody
'uniQrIds' => $this->uniQrIds,
];
}
// </SECTION>
// <SECTION name="response_caster" intent="Return the raw JSON response as an array.">
// <BELIEF_STATE "For this specific request, the response is currently returned as a raw array. A dedicated DTO could be created if a structured object is required.">
public function createDtoFromResponse(\Saloon\Http\Response $response): array
{
return $response->json();
}
// </SECTION>
}

View File

@@ -1,14 +1,29 @@
<?php
/*
// MODULE_CONTRACT: Provides a utility for parsing incoming Digital Ruble payment notifications.
// RESPONSIBILITY: To transform a raw array payload (typically from a webhook) into a structured DTO.
// INPUTS: Raw array representing the payment notification payload.
// OUTPUTS: PaymentDrNotificationData (DTO).
// LINKS: Webhooks/WebhookFactory.php (could potentially integrate this for DR-specific parsing)
*/
namespace Apoloz\AlfaBank\Sbp\Requests\DigitalRuble\Notifications;
// <SECTION name="module_imports" intent="Import the DTO for Digital Ruble payment notifications and Laravel's Request class.">
// <BELIEF_STATE "This utility uses the `PaymentDrNotificationData` DTO to structure the incoming data. The Laravel `Request` class is typically used for obtaining raw input in a web context.">
use Apoloz\AlfaBank\Sbp\Data\DigitalRuble\Notifications\PaymentDrNotificationData;
use Illuminate\Http\Request;
use Illuminate\Http\Request; // Assuming this is used to get the raw incoming data, not directly as a Saloon Request.
// </SECTION>
// <SECTION name="class_definition" intent="Define a utility class for parsing Digital Ruble payment notifications.">
// <BELIEF_STATE "This class acts as a parser, converting unstructured incoming notification data into a type-safe and easily consumable DTO, which is critical for reliable webhook handling.">
class ParsePaymentDrNotification
{
// <SECTION name="execute_method" intent="Parse the raw incoming notification data into a structured DTO.">
// <BELIEF_STATE "The `execute` method is the entry point for parsing. It directly leverages the `PaymentDrNotificationData::from()` method to perform the conversion, taking advantage of Spatie Laravel Data's automatic mapping capabilities.">
public function execute(array $data): PaymentDrNotificationData
{
return PaymentDrNotificationData::from($data);
}
// </SECTION>
}

View File

@@ -1,7 +1,16 @@
<?php
/*
// MODULE_CONTRACT: Represents the "Get QR Code" (qrcs) API call within the SBP gateway.
// RESPONSIBILITY: To define the HTTP method, endpoint, request body structure, and response data mapping for generating an SBP QR code.
// INPUTS: QrCodeRequestData (DTO containing QR parameters).
// OUTPUTS: QrCodeResponseData (DTO containing the QR payload and image URL).
// LINKS: SbpConnector.php
*/
namespace Apoloz\AlfaBank\Sbp\Requests;
// <SECTION name="module_imports" intent="Import components required for defining the request and its data structures.">
// <BELIEF_STATE "A Request class needs its specific data transfer objects (DTOs) for the request payload and the response. It also requires Saloon's base classes and traits to function within the framework.">
use Apoloz\AlfaBank\Sbp\Data\QrCodeRequestData;
use Apoloz\AlfaBank\Sbp\Data\QrCodeResponseData;
use Saloon\Contracts\Body\HasBody;
@@ -9,61 +18,47 @@ use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
use Saloon\Traits\Body\HasJsonBody;
// </SECTION>
// <SECTION name="class_definition" intent="Define a class that encapsulates all information for the 'Get QR Code' API call.">
// <BELIEF_STATE "Using a dedicated class for each API request is a core Saloon pattern. It organizes the endpoint, method, body, and response handling into a single, reusable, and testable unit. Implementing `HasBody` and using `HasJsonBody` signals its intent to send a JSON payload.">
class GetQrCodeRequest extends Request implements HasBody
{
use HasJsonBody;
// <SECTION name="http_method_declaration" intent="Declare the HTTP verb for this API operation.">
// <BELIEF_STATE "The SBP specification requires a POST request to generate a QR code, as the operation creates a new resource on the server.">
protected Method $method = Method::POST;
// </SECTION>
// <SECTION name="constructor" intent="Inject the structured payload required to generate the QR code.">
// <BELIEF_STATE "Requiring a strongly-typed `QrCodeRequestData` DTO in the constructor is a deliberate design choice to enforce data integrity at compile time. This prevents developers from sending malformed or incomplete data to the API.">
public function __construct(
protected QrCodeRequestData $data
) {}
// </SECTION>
// <SECTION name="endpoint_resolver" intent="Define the specific URI for the QR code generation endpoint.">
// <BELIEF_STATE "Centralizing the endpoint path in this method makes the SDK resilient to API changes. If the endpoint moves from '/qrcs' to '/v2/qrcs', this is the only line that needs to be updated for this specific request.">
public function resolveEndpoint(): string
{
return '';
return '/qrcs';
}
// </SECTION>
// <SECTION name="request_body_builder" intent="Prepare the request payload for transmission.">
// <BELIEF_STATE "This method delegates the serialization logic to the `QrCodeRequestData` DTO. This is a key decoupling principle: the Request class shouldn't know *how* to serialize the data (e.g., mapping camelCase to PascalCase); it should only know that the DTO is responsible for providing a valid array representation.">
protected function defaultBody(): array
{
$body = [
'command' => 'GetQRCd',
'TermNo' => $this->data->TermNo,
'qrcType' => $this->data->qrcType,
'currency' => $this->data->currency,
];
// Common Fields
if ($this->data->amount !== null) $body['amount'] = $this->data->amount;
if ($this->data->paymentPurpose !== null) $body['paymentPurpose'] = $this->data->paymentPurpose;
if ($this->data->redirectUrl !== null) $body['redirectUrl'] = $this->data->redirectUrl;
if ($this->data->messageID !== null) $body['messageID'] = $this->data->messageID;
if ($this->data->width !== null) $body['width'] = $this->data->width;
if ($this->data->height !== null) $body['height'] = $this->data->height;
// Dynamic QR Fields
if ($this->data->OrderNumber !== null) $body['OrderNumber'] = $this->data->OrderNumber;
if ($this->data->qrTtl !== null) $body['qrTtl'] = $this->data->qrTtl;
if ($this->data->subscriptionServiceId !== null) $body['subscriptionServiceId'] = $this->data->subscriptionServiceId;
if ($this->data->subscriptionServiceName !== null) $body['subscriptionServiceName'] = $this->data->subscriptionServiceName;
// Query Data nesting
$queryData = [];
if ($this->data->notificationUrl !== null) $queryData['notificationUrl'] = $this->data->notificationUrl;
if ($this->data->SenderFIO !== null) $queryData['SenderFIO'] = $this->data->SenderFIO;
if ($this->data->SenderID !== null) $queryData['SenderID'] = $this->data->SenderID;
if ($this->data->SenderBankBIC !== null) $queryData['SenderBankBIC'] = $this->data->SenderBankBIC;
if (!empty($queryData)) {
$body['queryData'] = $queryData;
}
return $body;
return $this->data->toArray();
}
// </SECTION>
// <SECTION name="response_dto_caster" intent="Transform the raw API JSON response into a structured DTO.">
// <BELIEF_STATE "Automatically casting the JSON response to a `QrCodeResponseData` DTO provides a superior, type-safe developer experience. It abstracts away the raw response, allowing the user to interact with a clean, predictable object with autocompletion and static analysis benefits.">
public function createDtoFromResponse(Response $response): QrCodeResponseData
{
return QrCodeResponseData::from($response->json());
}
// </SECTION>
}

View File

@@ -1,28 +1,52 @@
<?php
/*
// MODULE_CONTRACT: Represents the SBP API call to block a QR Code.
// RESPONSIBILITY: To define the POST request for deactivating a specific QR Code associated with a terminal.
// INPUTS: BlockQrRequestData (TermNo, qrcId, reason).
// OUTPUTS: Raw array response from the API.
*/
namespace Apoloz\AlfaBank\Sbp\Requests\Management;
// <SECTION name="module_imports" intent="Import DTO and Saloon components for a JSON body request.">
// <BELIEF_STATE "This POST request requires the `BlockQrRequestData` DTO for its JSON body and utilizes `HasBody` and `HasJsonBody` for proper payload serialization. It currently returns a raw array response.">
use Apoloz\AlfaBank\Sbp\Data\Management\BlockQrRequestData;
use Saloon\Contracts\Body\HasBody;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Traits\Body\HasJsonBody;
// <BELIEF_STATE "The `Response` object is fully qualified in `createDtoFromResponse` as it is not explicitly imported with a `use` statement at the top. This is acceptable but less explicit.">
// use Saloon\Http\Response; // Explicit import would be cleaner
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to block a QR Code.">
// <BELIEF_STATE "This class encapsulates the logic for blocking an SBP QR Code, which is a critical management operation.">
class BlockQrRequest extends Request implements HasBody
{
use HasJsonBody;
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Blocking a resource is an action that changes the system state, so POST is the correct verb.">
protected Method $method = Method::POST;
// </SECTION>
// <SECTION name="constructor" intent="Inject the DTO containing the blocking request data.">
// <BELIEF_STATE "Using a strongly-typed DTO (`BlockQrRequestData`) ensures that all necessary information for blocking the QR Code is provided and correctly structured.">
public function __construct(
protected BlockQrRequestData $data
) {}
// <SECTION name="endpoint_resolver" intent="Define the endpoint for SBP QR Code blocking.">
// <BELIEF_STATE "The SBP API often uses generic endpoints with a 'command' field in the body, implying the endpoint itself might be empty or a base SBP URL.">
public function resolveEndpoint(): string
{
return '';
return ''; // Endpoint is determined by SbpConnector's base URL
}
// </SECTION>
// <SECTION name="body_builder" intent="Construct the JSON body for the request.">
// <BELIEF_STATE "The `command` field specifies the operation to the SBP API. The `TermNo` and `qrcId` identify the target, and `reason` provides context for the block.">
protected function defaultBody(): array
{
$body = [
@@ -37,9 +61,13 @@ class BlockQrRequest extends Request implements HasBody
return $body;
}
// </SECTION>
// <SECTION name="response_caster" intent="Return the raw JSON response as an array.">
// <BELIEF_STATE "For this specific request, the response is currently returned as a raw array. A dedicated DTO could be created if a structured object is required.">
public function createDtoFromResponse(\Saloon\Http\Response $response): array
{
return $response->json();
}
// </SECTION>
}

View File

@@ -1,27 +1,51 @@
<?php
/*
// MODULE_CONTRACT: Represents the SBP API call to get a list of blocked QR Codes.
// RESPONSIBILITY: To define the POST request for retrieving all QR Codes that have been blocked for a terminal.
// INPUTS: Terminal number (TermNo).
// OUTPUTS: Raw array response from the API.
*/
namespace Apoloz\AlfaBank\Sbp\Requests\Management;
// <SECTION name="module_imports" intent="Import Saloon components for a JSON body request.">
// <BELIEF_STATE "This POST request utilizes `HasBody` and `HasJsonBody` for proper payload serialization. It currently returns a raw array response.">
use Saloon\Contracts\Body\HasBody;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Traits\Body\HasJsonBody;
// <BELIEF_STATE "The `Response` object is fully qualified in `createDtoFromResponse` as it is not explicitly imported with a `use` statement at the top. This is acceptable but less explicit.">
// use Saloon\Http\Response; // Explicit import would be cleaner
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to get a list of blocked QR Codes.">
// <BELIEF_STATE "This class encapsulates the logic for querying blocked QR Codes, which is part of managing payment terminals.">
class GetBlockedQrListRequest extends Request implements HasBody
{
use HasJsonBody;
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Even though it retrieves data, SBP list requests are often performed via POST requests with a JSON body.">
protected Method $method = Method::POST;
// </SECTION>
// <SECTION name="constructor" intent="Inject the mandatory terminal number.">
// <BELIEF_STATE "The constructor requires the `TermNo` to specify which terminal's blocked QR Codes are being queried.">
public function __construct(
protected string $TermNo
) {}
// <SECTION name="endpoint_resolver" intent="Define the endpoint for SBP blocked QR list queries.">
// <BELIEF_STATE "The SBP API often uses generic endpoints with a 'command' field in the body, implying the endpoint itself might be empty or a base SBP URL.">
public function resolveEndpoint(): string
{
return '';
return ''; // Endpoint is determined by SbpConnector's base URL
}
// </SECTION>
// <SECTION name="body_builder" intent="Construct the JSON body for the request.">
// <BELIEF_STATE "The `command` field specifies the operation to the SBP API. The `TermNo` is included in the body to identify the terminal.">
protected function defaultBody(): array
{
return [
@@ -29,9 +53,13 @@ class GetBlockedQrListRequest extends Request implements HasBody
'TermNo' => $this->TermNo,
];
}
// </SECTION>
// <SECTION name="response_caster" intent="Return the raw JSON response as an array.">
// <BELIEF_STATE "For this specific request, the response is currently returned as a raw array. A dedicated DTO could be created if a structured object is required.">
public function createDtoFromResponse(\Saloon\Http\Response $response): array
{
return $response->json();
}
// </SECTION>
}

View File

@@ -1,28 +1,52 @@
<?php
/*
// MODULE_CONTRACT: Represents the SBP API call to unblock a QR Code.
// RESPONSIBILITY: To define the POST request for reactivating a specific QR Code associated with a terminal.
// INPUTS: BlockQrRequestData (TermNo, qrcId).
// OUTPUTS: Raw array response from the API.
*/
namespace Apoloz\AlfaBank\Sbp\Requests\Management;
// <SECTION name="module_imports" intent="Import DTO and Saloon components for a JSON body request.">
// <BELIEF_STATE "This POST request requires the `BlockQrRequestData` DTO for its JSON body and utilizes `HasBody` and `HasJsonBody` for proper payload serialization. It currently returns a raw array response.">
use Apoloz\AlfaBank\Sbp\Data\Management\BlockQrRequestData;
use Saloon\Contracts\Body\HasBody;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Traits\Body\HasJsonBody;
// <BELIEF_STATE "The `Response` object is fully qualified in `createDtoFromResponse` as it is not explicitly imported with a `use` statement at the top. This is acceptable but less explicit.">
// use Saloon\Http\Response; // Explicit import would be cleaner
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to unblock a QR Code.">
// <BELIEF_STATE "This class encapsulates the logic for unblocking an SBP QR Code, which is a critical management operation.">
class UnblockQrRequest extends Request implements HasBody
{
use HasJsonBody;
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Unblocking a resource is an action that changes the system state, so POST is the correct verb.">
protected Method $method = Method::POST;
// </SECTION>
// <SECTION name="constructor" intent="Inject the DTO containing the unblocking request data.">
// <BELIEF_STATE "Using a strongly-typed DTO (`BlockQrRequestData`) ensures that all necessary information for unblocking the QR Code is provided and correctly structured. The `reason` field is not relevant for unblocking, so it's omitted in the `defaultBody`.">
public function __construct(
protected BlockQrRequestData $data
) {}
// <SECTION name="endpoint_resolver" intent="Define the endpoint for SBP QR Code unblocking.">
// <BELIEF_STATE "The SBP API often uses generic endpoints with a 'command' field in the body, implying the endpoint itself might be empty or a base SBP URL.">
public function resolveEndpoint(): string
{
return '';
return ''; // Endpoint is determined by SbpConnector's base URL
}
// </SECTION>
// <SECTION name="body_builder" intent="Construct the JSON body for the request.">
// <BELIEF_STATE "The `command` field specifies the operation to the SBP API. The `TermNo` and `qrcId` identify the target QR Code.">
protected function defaultBody(): array
{
return [
@@ -31,9 +55,13 @@ class UnblockQrRequest extends Request implements HasBody
'qrcId' => $this->data->qrcId,
];
}
// </SECTION>
// <SECTION name="response_caster" intent="Return the raw JSON response as an array.">
// <BELIEF_STATE "For this specific request, the response is currently returned as a raw array. A dedicated DTO could be created if a structured object is required.">
public function createDtoFromResponse(\Saloon\Http\Response $response): array
{
return $response->json();
}
// </SECTION>
}

View File

@@ -1,30 +1,51 @@
<?php
/*
// MODULE_CONTRACT: Represents the SBP API call to get a list of participating banks.
// RESPONSIBILITY: To define the POST request for retrieving a registry of banks connected to the SBP.
// INPUTS: Optional message ID and Bank Member ID filter.
// OUTPUTS: GetBankListResponseData (DTO).
*/
namespace Apoloz\AlfaBank\Sbp\Requests\Registry;
// <SECTION name="module_imports" intent="Import DTO and Saloon components for a JSON body request.">
// <BELIEF_STATE "This POST request requires the `GetBankListResponseData` DTO for its response and utilizes `HasBody` and `HasJsonBody` for proper payload serialization.">
use Apoloz\AlfaBank\Sbp\Data\Registry\GetBankListResponseData;
use Saloon\Contracts\Body\HasBody;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
use Saloon\Traits\Body\HasJsonBody;
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to get the SBP bank list.">
// <BELIEF_STATE "This class encapsulates the logic for querying the list of SBP participating banks, which is essential for routing payments.">
class GetBankListRequest extends Request implements HasBody
{
use HasJsonBody;
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Even though it retrieves data, SBP list requests are often performed via POST requests with a JSON body.">
protected Method $method = Method::POST;
// </SECTION>
// <SECTION name="constructor" intent="Inject optional message ID and bank member ID filter.">
// <BELIEF_STATE "The constructor allows for optional filtering of the bank list by `BankMemberIdFilter` and includes a `messageID` for request tracking.">
public function __construct(
protected ?string $messageID = null,
protected ?string $BankMemberIdFilter = null
) {}
// <SECTION name="endpoint_resolver" intent="Define the endpoint for SBP bank list queries.">
// <BELIEF_STATE "The SBP API often uses generic endpoints with a 'command' field in the body, implying the endpoint itself might be empty or a base SBP URL.">
public function resolveEndpoint(): string
{
return '';
return ''; // Endpoint is determined by SbpConnector's base URL
}
// </SECTION>
// <SECTION name="body_builder" intent="Construct the JSON body for the request.">
// <BELIEF_STATE "The `command` field specifies the operation to the SBP API. Optional fields are conditionally added to the body.">
protected function defaultBody(): array
{
$body = [
@@ -36,9 +57,13 @@ class GetBankListRequest extends Request implements HasBody
return $body;
}
// </SECTION>
// <SECTION name="response_caster" intent="Map the JSON response to a DTO.">
// <BELIEF_STATE "Casting the response to a `GetBankListResponseData` DTO provides a type-safe and structured object for the list of SBP banks.">
public function createDtoFromResponse(Response $response): GetBankListResponseData
{
return GetBankListResponseData::from($response->json());
}
// </SECTION>
}

View File

@@ -1,7 +1,15 @@
<?php
/*
// MODULE_CONTRACT: Represents the SBP API call to get detailed data about a QR Code reversal.
// RESPONSIBILITY: To define the POST request for retrieving specific information about a reversal transaction.
// INPUTS: Reversal data request (TermNo, currency, qrcId, payrrn, etc.).
// OUTPUTS: GetQrcReversalDataResponseData (DTO).
*/
namespace Apoloz\AlfaBank\Sbp\Requests\Reversal;
// <SECTION name="module_imports" intent="Import DTOs and Saloon components for a JSON body request.">
// <BELIEF_STATE "This POST request requires specific DTOs for its JSON body and its response, along with Saloon's body-handling traits.">
use Apoloz\AlfaBank\Sbp\Data\Reversal\GetQrcReversalDataRequestData;
use Apoloz\AlfaBank\Sbp\Data\Reversal\GetQrcReversalDataResponseData;
use Saloon\Contracts\Body\HasBody;
@@ -9,22 +17,35 @@ use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
use Saloon\Traits\Body\HasJsonBody;
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to get detailed QR Code reversal data.">
// <BELIEF_STATE "This class encapsulates the logic for querying detailed SBP reversal information, which is crucial for auditing and reconciliation.">
class GetQrcReversalDataRequest extends Request implements HasBody
{
use HasJsonBody;
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Even though it retrieves data, SBP data requests are often performed via POST requests with a JSON body.">
protected Method $method = Method::POST;
// </SECTION>
// <SECTION name="constructor" intent="Inject the DTO containing the reversal data request parameters.">
// <BELIEF_STATE "Using a strongly-typed DTO (`GetQrcReversalDataRequestData`) ensures that all necessary information for the data query is provided and correctly structured.">
public function __construct(
protected GetQrcReversalDataRequestData $data
) {}
// <SECTION name="endpoint_resolver" intent="Define the endpoint for SBP reversal data queries.">
// <BELIEF_STATE "The SBP API often uses generic endpoints with a 'command' field in the body, implying the endpoint itself might be empty or a base SBP URL.">
public function resolveEndpoint(): string
{
return '';
return ''; // Endpoint is determined by SbpConnector's base URL
}
// </SECTION>
// <SECTION name="body_builder" intent="Construct the JSON body for the request.">
// <BELIEF_STATE "The `command` field specifies the operation to the SBP API. Other fields from the DTO are conditionally added, ensuring the payload precisely matches the API specification.">
protected function defaultBody(): array
{
$body = [
@@ -43,9 +64,13 @@ class GetQrcReversalDataRequest extends Request implements HasBody
return $body;
}
// </SECTION>
// <SECTION name="response_caster" intent="Map the JSON response to a DTO.">
// <BELIEF_STATE "Casting the response to a `GetQrcReversalDataResponseData` DTO provides a type-safe and structured object for the detailed reversal data.">
public function createDtoFromResponse(Response $response): GetQrcReversalDataResponseData
{
return GetQrcReversalDataResponseData::from($response->json());
}
// </SECTION>
}

View File

@@ -1,7 +1,15 @@
<?php
/*
// MODULE_CONTRACT: Represents the SBP API call to get the status of a QR Code reversal request.
// RESPONSIBILITY: To define the POST request for checking the state of a previously initiated reversal.
// INPUTS: Reversal status request data (TermNo, payrrn, originalTrxId, etc.).
// OUTPUTS: GetQrcReversalStatusResponseData (DTO).
*/
namespace Apoloz\AlfaBank\Sbp\Requests\Reversal;
// <SECTION name="module_imports" intent="Import DTOs and Saloon components for a JSON body request.">
// <BELIEF_STATE "This POST request requires specific DTOs for its JSON body and its response, along with Saloon's body-handling traits.">
use Apoloz\AlfaBank\Sbp\Data\Reversal\GetQrcReversalStatusRequestData;
use Apoloz\AlfaBank\Sbp\Data\Reversal\GetQrcReversalStatusResponseData;
use Saloon\Contracts\Body\HasBody;
@@ -9,22 +17,35 @@ use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
use Saloon\Traits\Body\HasJsonBody;
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to get the status of a QR Code reversal.">
// <BELIEF_STATE "This class encapsulates the logic for querying the status of an SBP reversal, which is a critical operation in payment systems.">
class GetQrcReversalStatusRequest extends Request implements HasBody
{
use HasJsonBody;
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Even though it retrieves data, SBP status checks are often performed via POST requests with a JSON body.">
protected Method $method = Method::POST;
// </SECTION>
// <SECTION name="constructor" intent="Inject the DTO containing the reversal status request data.">
// <BELIEF_STATE "Using a strongly-typed DTO (`GetQrcReversalStatusRequestData`) ensures that all necessary information for the status query is provided and correctly structured.">
public function __construct(
protected GetQrcReversalStatusRequestData $data
) {}
// <SECTION name="endpoint_resolver" intent="Define the endpoint for SBP reversal status checks.">
// <BELIEF_STATE "The SBP API often uses generic endpoints with a 'command' field in the body, which implies the endpoint itself might be empty or a base SBP URL.">
public function resolveEndpoint(): string
{
return '';
return ''; // Endpoint is determined by SbpConnector's base URL
}
// </SECTION>
// <SECTION name="body_builder" intent="Construct the JSON body for the request.">
// <BELIEF_STATE "The `command` field specifies the operation to the SBP API. Other fields from the DTO are conditionally added, ensuring the payload precisely matches the API specification.">
protected function defaultBody(): array
{
$body = [
@@ -39,9 +60,13 @@ class GetQrcReversalStatusRequest extends Request implements HasBody
return $body;
}
// </SECTION>
// <SECTION name="response_caster" intent="Map the JSON response to a DTO.">
// <BELIEF_STATE "Casting the response to a `GetQrcReversalStatusResponseData` DTO provides a type-safe and structured object for the status of the reversal.">
public function createDtoFromResponse(Response $response): GetQrcReversalStatusResponseData
{
return GetQrcReversalStatusResponseData::from($response->json());
}
// </SECTION>
}

View File

@@ -1,7 +1,15 @@
<?php
/*
// MODULE_CONTRACT: Represents the SBP API call to initiate a QR Code reversal.
// RESPONSIBILITY: To define the POST request for reversing a payment made via QR code.
// INPUTS: QR Code reversal request data (TermNo, currency, qrcId, payrrn, etc.).
// OUTPUTS: QrcReversalResponseData (DTO).
*/
namespace Apoloz\AlfaBank\Sbp\Requests\Reversal;
// <SECTION name="module_imports" intent="Import DTOs and Saloon components for a JSON body request.">
// <BELIEF_STATE "This POST request requires specific DTOs for its JSON body and its response, along with Saloon's body-handling traits.">
use Apoloz\AlfaBank\Sbp\Data\Reversal\QrcReversalRequestData;
use Apoloz\AlfaBank\Sbp\Data\Reversal\QrcReversalResponseData;
use Saloon\Contracts\Body\HasBody;
@@ -9,22 +17,35 @@ use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
use Saloon\Traits\Body\HasJsonBody;
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to initiate a QR Code reversal.">
// <BELIEF_STATE "This class encapsulates the logic for initiating an SBP reversal, which is a critical operation in payment systems.">
class QrcReversalRequest extends Request implements HasBody
{
use HasJsonBody;
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Initiating a new transaction or action that changes the system state (like a reversal) is correctly represented by a POST request.">
protected Method $method = Method::POST;
// </SECTION>
// <SECTION name="constructor" intent="Inject the DTO containing the QR Code reversal request data.">
// <BELIEF_STATE "Using a strongly-typed DTO (`QrcReversalRequestData`) ensures that all necessary information for the reversal is provided and correctly structured.">
public function __construct(
protected QrcReversalRequestData $data
) {}
// <SECTION name="endpoint_resolver" intent="Define the endpoint for SBP reversal requests.">
// <BELIEF_STATE "The SBP API often uses generic endpoints with a 'command' field in the body, implying the endpoint itself might be empty or a base SBP URL.">
public function resolveEndpoint(): string
{
return '';
return ''; // Endpoint is determined by SbpConnector's base URL
}
// </SECTION>
// <SECTION name="body_builder" intent="Construct the JSON body for the request.">
// <BELIEF_STATE "The `command` field specifies the operation to the SBP API. Other fields from the DTO are conditionally added, ensuring the payload precisely matches the API specification.">
protected function defaultBody(): array
{
$body = [
@@ -44,9 +65,13 @@ class QrcReversalRequest extends Request implements HasBody
return $body;
}
// </SECTION>
// <SECTION name="response_caster" intent="Map the JSON response to a DTO.">
// <BELIEF_STATE "Casting the response to a `QrcReversalResponseData` DTO provides a type-safe and structured object for the result of the reversal.">
public function createDtoFromResponse(Response $response): QrcReversalResponseData
{
return QrcReversalResponseData::from($response->json());
}
// </SECTION>
}

View File

@@ -1,7 +1,15 @@
<?php
/*
// MODULE_CONTRACT: Represents the SBP API call to get the status of a QR Code.
// RESPONSIBILITY: To define the POST request for checking the state of a specific QR Code.
// INPUTS: QR Code status request data (TermNo, qrcId, payrrn, messageID).
// OUTPUTS: GetQrcStatusResponseData (DTO).
*/
namespace Apoloz\AlfaBank\Sbp\Requests\Status;
// <SECTION name="module_imports" intent="Import DTOs and Saloon components for a JSON body request.">
// <BELIEF_STATE "This POST request requires specific DTOs for its JSON body and its response, along with Saloon's body-handling traits.">
use Apoloz\AlfaBank\Sbp\Data\Status\GetQrcStatusRequestData;
use Apoloz\AlfaBank\Sbp\Data\Status\GetQrcStatusResponseData;
use Saloon\Contracts\Body\HasBody;
@@ -9,22 +17,35 @@ use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
use Saloon\Traits\Body\HasJsonBody;
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to get the status of a QR Code.">
// <BELIEF_STATE "This class encapsulates the logic for querying the status of an SBP QR Code, which is crucial for tracking payment flows.">
class GetQrcStatusRequest extends Request implements HasBody
{
use HasJsonBody;
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Even though it retrieves data, SBP status checks are often performed via POST requests with a JSON body.">
protected Method $method = Method::POST;
// </SECTION>
// <SECTION name="constructor" intent="Inject the DTO containing the QR Code status request data.">
// <BELIEF_STATE "Using a strongly-typed DTO (`GetQrcStatusRequestData`) ensures that all necessary information for the status query is provided and correctly structured.">
public function __construct(
protected GetQrcStatusRequestData $data
) {}
// <SECTION name="endpoint_resolver" intent="Define the endpoint for SBP QR Code status queries.">
// <BELIEF_STATE "The SBP API often uses generic endpoints with a 'command' field in the body, implying the endpoint itself might be empty or a base SBP URL.">
public function resolveEndpoint(): string
{
return '';
return ''; // Endpoint is determined by SbpConnector's base URL
}
// </SECTION>
// <SECTION name="body_builder" intent="Construct the JSON body for the request.">
// <BELIEF_STATE "The `command` field specifies the operation to the SBP API. The `TermNo` is mandatory, and `qrcId`, `payrrn`, and `messageID` are optional filters to pinpoint the transaction.">
protected function defaultBody(): array
{
$body = [
@@ -38,9 +59,13 @@ class GetQrcStatusRequest extends Request implements HasBody
return $body;
}
// </SECTION>
// <SECTION name="response_caster" intent="Map the JSON response to a DTO.">
// <BELIEF_STATE "Casting the response to a `GetQrcStatusResponseData` DTO provides a type-safe and structured object for the status of the QR Code.">
public function createDtoFromResponse(Response $response): GetQrcStatusResponseData
{
return GetQrcStatusResponseData::from($response->json());
}
// </SECTION>
}

View File

@@ -1,29 +1,53 @@
<?php
/*
// MODULE_CONTRACT: Represents the SBP API call to get the status of a QR Code subscription.
// RESPONSIBILITY: To define the POST request for checking the state of a specific SBP subscription.
// INPUTS: Terminal number (TermNo), QR Code ID, and optional request period (RQperiod).
// OUTPUTS: Raw array response from the API.
*/
namespace Apoloz\AlfaBank\Sbp\Requests\Subscription;
// <SECTION name="module_imports" intent="Import Saloon components for a JSON body request.">
// <BELIEF_STATE "This POST request utilizes `HasBody` and `HasJsonBody` for proper payload serialization. It currently returns a raw array response.">
use Saloon\Contracts\Body\HasBody;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Traits\Body\HasJsonBody;
// <BELIEF_STATE "The `Response` object is fully qualified in `createDtoFromResponse` as it is not explicitly imported with a `use` statement at the top. This is acceptable but less explicit.">
// use Saloon\Http\Response; // Explicit import would be cleaner
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to get the status of a QR Code subscription.">
// <BELIEF_STATE "This class encapsulates the logic for querying the status of an SBP subscription, which is crucial for managing recurring payments.">
class GetQrSubStatusRequest extends Request implements HasBody
{
use HasJsonBody;
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Even though it retrieves data, SBP status checks are often performed via POST requests with a JSON body.">
protected Method $method = Method::POST;
// </SECTION>
// <SECTION name="constructor" intent="Inject the mandatory and optional parameters for the subscription status request.">
// <BELIEF_STATE "The constructor requires `TermNo` and `qrcId` to identify the subscription. `RQperiod` is an optional filter.">
public function __construct(
protected string $TermNo,
protected string $qrcId,
protected ?string $RQperiod = null
) {}
// <SECTION name="endpoint_resolver" intent="Define the endpoint for SBP subscription status checks.">
// <BELIEF_STATE "The SBP API often uses generic endpoints with a 'command' field in the body, implying the endpoint itself might be empty or a base SBP URL.">
public function resolveEndpoint(): string
{
return '';
return ''; // Endpoint is determined by SbpConnector's base URL
}
// </SECTION>
// <SECTION name="body_builder" intent="Construct the JSON body for the request.">
// <BELIEF_STATE "The `command` field specifies the operation to the SBP API. Other fields are conditionally added, ensuring the payload precisely matches the API specification.">
protected function defaultBody(): array
{
$body = [
@@ -38,9 +62,13 @@ class GetQrSubStatusRequest extends Request implements HasBody
return $body;
}
// </SECTION>
// <SECTION name="response_caster" intent="Return the raw JSON response as an array.">
// <BELIEF_STATE "For this specific request, the response is currently returned as a raw array. A dedicated DTO could be created if a structured object is required.">
public function createDtoFromResponse(\Saloon\Http\Response $response): array
{
return $response->json();
}
// </SECTION>
}

View File

@@ -1,19 +1,35 @@
<?php
/*
// MODULE_CONTRACT: Represents the SBP API call to petition a QR Code subscription payment.
// RESPONSIBILITY: To define the POST request for initiating a payment based on an existing SBP subscription.
// INPUTS: Terminal number (TermNo), subscription token, sender member ID, and QR Code ID.
// OUTPUTS: Raw array response from the API.
*/
namespace Apoloz\AlfaBank\Sbp\Requests\Subscription;
// <SECTION name="module_imports" intent="Import Saloon components for a JSON body request.">
// <BELIEF_STATE "This POST request utilizes `HasBody` and `HasJsonBody` for proper payload serialization. It currently returns a raw array response.">
use Saloon\Contracts\Body\HasBody;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
use Saloon\Traits\Body\HasJsonBody;
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to petition a QR Code subscription payment.">
// <BELIEF_STATE "This class encapsulates the logic for initiating a payment through an SBP subscription, which is a key part of recurring payment flows.">
class QrcSubPayPetitionRequest extends Request implements HasBody
{
use HasJsonBody;
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Initiating a payment action that changes the system state is correctly represented by a POST request.">
protected Method $method = Method::POST;
// </SECTION>
// <SECTION name="constructor" intent="Inject the mandatory parameters for the subscription payment petition.">
// <BELIEF_STATE "The constructor requires the `TermNo`, `subscriptionToken`, `SenderMemberId`, and `qrcId` to identify the transaction and subscription.">
public function __construct(
protected string $TermNo,
protected string $subscriptionToken,
@@ -21,11 +37,16 @@ class QrcSubPayPetitionRequest extends Request implements HasBody
protected string $qrcId,
) {}
// <SECTION name="endpoint_resolver" intent="Define the endpoint for SBP subscription payment petitions.">
// <BELIEF_STATE "The SBP API often uses generic endpoints with a 'command' field in the body, implying the endpoint itself might be empty or a base SBP URL.">
public function resolveEndpoint(): string
{
return '';
return ''; // Endpoint is determined by SbpConnector's base URL
}
// </SECTION>
// <SECTION name="body_builder" intent="Construct the JSON body for the request.">
// <BELIEF_STATE "The `command` field specifies the operation to the SBP API. All constructor properties are directly mapped to the request body.">
protected function defaultBody(): array
{
return [
@@ -36,9 +57,13 @@ class QrcSubPayPetitionRequest extends Request implements HasBody
'qrcId' => $this->qrcId,
];
}
// </SECTION>
// <SECTION name="response_caster" intent="Return the raw JSON response as an array.">
// <BELIEF_STATE "For this specific request, the response is currently returned as a raw array. A dedicated DTO could be created if a structured object is required.">
public function createDtoFromResponse(Response $response): array
{
return $response->json();
}
// </SECTION>
}

View File

@@ -1,29 +1,50 @@
<?php
/*
// MODULE_CONTRACT: Represents the SBP API call to register a QR Code subscription.
// RESPONSIBILITY: To define the POST request for setting up a new SBP subscription for recurring payments.
// INPUTS: RegQrSubRequestData (DTO).
// OUTPUTS: Raw array response from the API.
*/
namespace Apoloz\AlfaBank\Sbp\Requests\Subscription;
// <SECTION name="module_imports" intent="Import DTO and Saloon components for a JSON body request.">
// <BELIEF_STATE "This POST request requires the `RegQrSubRequestData` DTO for its JSON body and utilizes `HasBody` and `HasJsonBody` for proper payload serialization. It currently returns a raw array response.">
use Apoloz\AlfaBank\Sbp\Data\Subscription\RegQrSubRequestData;
use Saloon\Contracts\Body\HasBody;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
use Saloon\Traits\Body\HasJsonBody;
// </SECTION>
// <SECTION name="class_definition" intent="Define the request to register a QR Code subscription.">
// <BELIEF_STATE "This class encapsulates the logic for initiating an SBP subscription, which is crucial for recurring payment models.">
class RegQrSubRequest extends Request implements HasBody
{
use HasJsonBody;
// <SECTION name="http_method" intent="Declare the HTTP verb.">
// <BELIEF_STATE "Registering a new resource or initiating an action that changes the system state is correctly represented by a POST request.">
protected Method $method = Method::POST;
// </SECTION>
// <SECTION name="constructor" intent="Inject the DTO containing the subscription registration data.">
// <BELIEF_STATE "Using a strongly-typed DTO (`RegQrSubRequestData`) ensures that all necessary information for the subscription is provided and correctly structured.">
public function __construct(
protected RegQrSubRequestData $data
) {}
// <SECTION name="endpoint_resolver" intent="Define the endpoint for SBP subscription registration.">
// <BELIEF_STATE "The SBP API often uses generic endpoints with a 'command' field in the body, implying the endpoint itself might be empty or a base SBP URL.">
public function resolveEndpoint(): string
{
return '';
return ''; // Endpoint is determined by SbpConnector's base URL
}
// </SECTION>
// <SECTION name="body_builder" intent="Construct the JSON body for the request.">
// <BELIEF_STATE "The `command` field specifies the operation to the SBP API. Fields from the DTO are mapped, including conditional and nested `queryData` for notification URLs.">
protected function defaultBody(): array
{
$body = [
@@ -43,9 +64,13 @@ class RegQrSubRequest extends Request implements HasBody
return $body;
}
// </SECTION>
// <SECTION name="response_caster" intent="Return the raw JSON response as an array.">
// <BELIEF_STATE "For this specific request, the response is currently returned as a raw array. A dedicated DTO could be created if a structured object is required.">
public function createDtoFromResponse(Response $response): array
{
return $response->json();
}
// </SECTION>
}

View File

@@ -2,74 +2,108 @@
namespace Apoloz\AlfaBank\Sbp;
use Apoloz\AlfaBank\Enums\Environment;
use Apoloz\AlfaBank\Core\AlfaConfig;
use Apoloz\AlfaBank\Http\Middleware\AlfaResponseMiddleware;
use Apoloz\AlfaBank\Http\Middleware\RequestIdMiddleware;
use Apoloz\AlfaBank\Http\Pagination\AlfaOffsetPaginator;
use Apoloz\AlfaBank\Utils\CmsSigner;
use Saloon\Http\Connector;
use Saloon\Http\PendingRequest;
use Saloon\Http\Request;
use Saloon\PaginationPlugin\Contracts\HasPagination;
use Saloon\PaginationPlugin\OffsetPaginator;
use Saloon\Traits\RequestProperties\HasTries;
use Saloon\Traits\Plugins\HasTimeout;
class SbpConnector extends Connector
class SbpConnector extends Connector implements HasPagination
{
use HasTimeout;
use HasTries;
public function __construct(
protected string $certificatePath,
protected string $privateKeyPath,
protected string $keyNameAlias, // 'key-name' header
protected Environment $environment = Environment::SANDBOX
) {}
protected AlfaConfig $alfaConfig,
protected string $keyNameAlias
) {
$this->tries = 3;
$this->retryInterval = 500;
}
public function resolveBaseUrl(): string
{
return match ($this->environment) {
Environment::SANDBOX => 'https://217.12.103.132:2443/fsCryptoProxy',
Environment::PRODUCTION => 'https://pay.alfabank.ru/fsCryptoProxy', // Placeholder, user needs to confirm
};
return $this->alfaConfig->baseUrl;
}
protected function defaultConfig(): array
{
return [
'cert' => $this->certificatePath,
'ssl_key' => $this->privateKeyPath,
$config = [
'cert' => $this->alfaConfig->certificatePath,
'ssl_key' => $this->alfaConfig->privateKeyPath,
'verify' => true,
];
if ($this->alfaConfig->caBundlePath) {
$config['verify'] = $this->alfaConfig->caBundlePath;
}
return $config;
}
protected function defaultHeaders(): array
protected function defaultMiddleware(): array
{
return [
'Content-Type' => 'application/x-www-form-urlencoded', // As per doc, despite body being JSON
'key-name' => $this->keyNameAlias,
];
return [];
}
public function boot(PendingRequest $pendingRequest): void
{
// Calculate Signature
$body = $pendingRequest->body()?->all();
if (empty($body)) {
$pendingRequest->middleware()->onResponse(new AlfaResponseMiddleware());
$pendingRequest->middleware()->onRequest(new RequestIdMiddleware());
$bodyRepo = $pendingRequest->body();
if (!$bodyRepo || empty($bodyRepo->all())) {
return;
}
$body = $bodyRepo->all();
// SBP requires minified JSON for signing. Canonicalization (JCS) is the formal term.
$jsonBody = CmsSigner::canonicalize($body);
// Minify JSON for signature
$jsonBody = json_encode($body, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
// Sign the body using the configured private key (prefer signing key, fallback to transport key).
$keyPath = $this->alfaConfig->signingPrivateKeyPath ?: $this->alfaConfig->privateKeyPath;
// Remove spaces/newlines as per doc requirement "exclude all spaces, tabs, newlines"
// Standard json_encode without pretty print usually does this, but let's be sure.
// The doc example: `{"command":"GetQRCd",...}` implies no spaces after colons/commas.
if (!file_exists($keyPath)) {
throw new \RuntimeException("Private key file not found: $keyPath");
}
$privateKey = openssl_pkey_get_private(
file_get_contents($keyPath)
);
$privateKey = file_get_contents($this->privateKeyPath);
$pkeyId = openssl_get_privatekey($privateKey);
openssl_sign($jsonBody, $signature, $pkeyId, OPENSSL_ALGO_SHA256);
if (!$privateKey) {
throw new \RuntimeException("Could not load private key for SBP signing from: $keyPath");
}
$signature = '';
openssl_sign($jsonBody, $signature, $privateKey, OPENSSL_ALGO_SHA256);
$signatureBase64 = base64_encode($signature);
// Mutate the request to add SBP-specific headers and set the exact signed body.
$pendingRequest->headers()->add('Authorization', $signatureBase64);
// The SBP API documentation specifies this content-type for signed requests.
$pendingRequest->headers()->add('Content-Type', 'application/x-www-form-urlencoded');
// Ensure the body sent is the exact string we signed?
// Saloon will encode the array to JSON again.
// We should enforce the body to be the string we just signed to ensure consistency.
$pendingRequest->body()->set($jsonBody);
// Note: Saloon/Guzzle might re-serialize the body.
// For strict SBP signing, ensuring the body sent matches $jsonBody exactly is crucial.
// Saloon's HasJsonBody trait usually handles this fine as long as array order is preserved.
}
}
public function withCaBundle(string $path): static
{
$this->config()->merge(['verify' => $path]);
return $this;
}
public function paginate(Request $request): OffsetPaginator
{
return new AlfaOffsetPaginator($this, $request);
}
}