Hasan/alfa-bank-sdk
1
0
Fork 0
forked from apoloz/alfa-bank-sdk
Code Pull Requests Activity

refactor(core): enhance SDK structure and documentation

Browse Source 
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
Download Patch File Download Diff File Expand all files Collapse all files

27
src/Sbp/Requests/CashLink/ActivateCashQrRequest.php
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>
}

30
src/Sbp/Requests/CashLink/ChangeAccountForCashQrRequest.php
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>
}

30
src/Sbp/Requests/CashLink/ChangeTermNoForCashQrRequest.php
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>
}

30
src/Sbp/Requests/CashLink/DeleteCashQrRequest.php
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>
}

30
src/Sbp/Requests/CashLink/GetCashQrHistoryRequest.php
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>
}

30
src/Sbp/Requests/CashLink/GetCashQrStatusRequest.php
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>
}

27
src/Sbp/Requests/CashLink/RegCashQrRequest.php
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>
}

27
src/Sbp/Requests/DigitalRuble/CashLink/ChangeAccForCashUniQrRequest.php
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>
}

27
src/Sbp/Requests/DigitalRuble/CashLink/CreateCashUniQrRequest.php
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>
}

27
src/Sbp/Requests/DigitalRuble/CashLink/GetCashUniQrStatusRequest.php
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>
}

30
src/Sbp/Requests/DigitalRuble/CreateUniQrRequest.php
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>
}

30
src/Sbp/Requests/DigitalRuble/GetUniQrStatusRequest.php
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>
}

17
src/Sbp/Requests/DigitalRuble/Notifications/ParsePaymentDrNotification.php
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>
}

63
src/Sbp/Requests/GetQrCodeRequest.php
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>
}

30
src/Sbp/Requests/Management/BlockQrRequest.php
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>
}

30
src/Sbp/Requests/Management/GetBlockedQrListRequest.php
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>
}

30
src/Sbp/Requests/Management/UnblockQrRequest.php
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>
}

27
src/Sbp/Requests/Registry/GetBankListRequest.php
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>
}

27
src/Sbp/Requests/Reversal/GetQrcReversalDataRequest.php
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>
}

27
src/Sbp/Requests/Reversal/GetQrcReversalStatusRequest.php
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>
}

27
src/Sbp/Requests/Reversal/QrcReversalRequest.php
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>
}

27
src/Sbp/Requests/Status/GetQrcStatusRequest.php
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>
}

30
src/Sbp/Requests/Subscription/GetQrSubStatusRequest.php
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>
}

27
src/Sbp/Requests/Subscription/QrcSubPayPetitionRequest.php
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>
}

27
src/Sbp/Requests/Subscription/RegQrSubRequest.php
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>
}