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

fix(statements/transactions)

Browse Source
This commit is contained in:
Анатолий Полоз
2026-06-02 21:00:44 +03:00
parent a412af3e07
commit c763fe6c71
9 changed files with 269 additions and 95 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
src/Data/Statement/CartInfoData.php Normal file
View File

@@ -0,0 +1,19 @@
<?php
declare(strict_types=1);
namespace Apoloz\AlfaBank\Data\Statement;
use Spatie\LaravelData\Data;
class CartInfoData extends Data
{
public function __construct(
public ?string $documentCode = null,
public ?string $documentContent = null,
public ?string $documentDate = null,
public ?string $documentNumber = null,
public ?string $paymentNumber = null,
public ?string $restAmount = null,
) {}
}

41
src/Data/Statement/CurTransferData.php Normal file
View File

@@ -0,0 +1,41 @@
<?php
declare(strict_types=1);
namespace Apoloz\AlfaBank\Data\Statement;
use Spatie\LaravelData\Data;
class CurTransferData extends Data
{
public function __construct(
public ?string $bankOperationCode = null,
public ?string $beneficiaryBankAccount = null,
public ?string $beneficiaryBankName = null,
public ?string $beneficiaryBankOption = null,
public ?string $beneficiaryCustomerAccount = null,
public ?string $beneficiaryCustomerName = null,
public ?string $detailsOfCharges = null,
public ?string $exchangeRate = null,
public ?string $instructedAmount = null,
public ?string $instructionCode = null,
public ?string $intermediaryBankAccount = null,
public ?string $intermediaryBankName = null,
public ?string $intermediaryBankOption = null,
public ?string $orderingCustomerAccount = null,
public ?string $orderingCustomerName = null,
public ?string $payeeBankBic = null,
public ?string $payeeBankCorrAccount = null,
public ?string $payeeBankName = null,
public ?string $payerInn = null,
public ?string $receiverCorrespondentAccount = null,
public ?string $receiverCorrespondentName = null,
public ?string $regulatoryReporting = null,
public ?string $senderCorrespondentAccount = null,
public ?string $senderCorrespondentName = null,
public ?string $senderCorrespondentOption = null,
public ?string $senderToReceiverInformation = null,
public ?string $transactionRelatedReference = null,
public ?string $valueDateCurrencyInterbankSettledAmount = null,
) {}
}

22
src/Data/Statement/DepartmentalInfoData.php Normal file
View File

@@ -0,0 +1,22 @@
<?php
declare(strict_types=1);
namespace Apoloz\AlfaBank\Data\Statement;
use Spatie\LaravelData\Data;
class DepartmentalInfoData extends Data
{
public function __construct(
public ?string $uip = null,
public ?string $drawerStatus101 = null,
public ?string $kbk = null,
public ?string $oktmo = null,
public ?string $reasonCode106 = null,
public ?string $taxPeriod107 = null,
public ?string $docNumber108 = null,
public ?string $docDate109 = null,
public ?string $paymentKind110 = null,
) {}
}

22
src/Data/Statement/RurTransferData.php
View File

@@ -1,29 +1,17 @@
<?php
declare(strict_types=1);
/*
// MODULE_CONTRACT: Defines the data structure for detailed Russian Ruble (RUR) transfer information within a transaction.
// RESPONSIBILITY: To hold and type-safely represent comprehensive details about the payer and payee in an RUR transfer.
// INPUTS: Raw JSON object from the API response.
// OUTPUTS: A structured object containing RUR transfer details.
// LINKS: TransactionData.php
*/
namespace Apoloz\AlfaBank\Data\Statement;
// <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 other DTO benefits.">
use Spatie\LaravelData\Data;
// </SECTION>
// <SECTION name="class_definition" intent="Define a DTO for Russian Ruble transfer details.">
// <BELIEF_STATE "This DTO provides a clear, type-safe contract for highly detailed RUR transfer information, which is critical for financial reconciliation and compliance with Russian banking standards.">
class RurTransferData extends Data
{
// <SECTION name="constructor_properties" intent="Define the comprehensive properties of an RUR transfer.">
// <BELIEF_STATE "The constructor includes a wide array of optional fields covering full payee and payer details (account, bank BIC, correspondent account, INN, KPP, name), as well as specific payment attributes like `paymentKind110`, `priority`, `receiptDate`, and `valueDate`. All are optional as not all fields may be present or relevant in every transaction record.">
public function __construct(
public ?CartInfoData $cartInfo = null,
public ?string $deliveryKind = null,
public ?DepartmentalInfoData $departmentalInfo = null,
public ?string $payeeAccount = null,
public ?string $payeeBankBic = null,
public ?string $payeeBankCorrAccount = null,
@@ -38,10 +26,10 @@ class RurTransferData extends Data
public ?string $payerInn = null,
public ?string $payerKpp = null,
public ?string $payerName = null,
public ?string $payingCondition = null,
public ?string $paymentKind110 = null,
public ?string $priority = null,
public ?string $purposeCode = null,
public ?string $receiptDate = null,
public ?string $valueDate = null,
) {}
// </SECTION>
}

41
src/Data/Statement/SwiftTransferData.php Normal file
View File

@@ -0,0 +1,41 @@
<?php
declare(strict_types=1);
namespace Apoloz\AlfaBank\Data\Statement;
use Spatie\LaravelData\Data;
class SwiftTransferData extends Data
{
public function __construct(
public ?string $bankOperationCode = null,
public ?string $beneficiaryBankAccount = null,
public ?string $beneficiaryBankName = null,
public ?string $beneficiaryBankOption = null,
public ?string $beneficiaryCustomerAccount = null,
public ?string $beneficiaryCustomerName = null,
public ?string $detailsOfCharges = null,
public ?string $exchangeRate = null,
public ?string $instructedAmount = null,
public ?string $instructionCode = null,
public ?string $intermediaryBankAccount = null,
public ?string $intermediaryBankName = null,
public ?string $intermediaryBankOption = null,
public ?string $orderingCustomerAccount = null,
public ?string $orderingCustomerName = null,
public ?string $payeeBankCorrAccount = null,
public ?string $payeeBankName = null,
public ?string $payeeBankBic = null,
public ?string $payerInn = null,
public ?string $receiverCorrespondentAccount = null,
public ?string $receiverCorrespondentName = null,
public ?string $regulatoryReporting = null,
public ?string $senderCorrespondentAccount = null,
public ?string $senderCorrespondentName = null,
public ?string $senderCorrespondentOption = null,
public ?string $senderToReceiverInformation = null,
public ?string $transactionRelatedReference = null,
public ?string $valueDateCurrencyInterbankSettledAmount = null,
) {}
}

22
src/Data/Statement/TransactionCollectionData.php
View File

@@ -1,34 +1,18 @@
<?php
declare(strict_types=1);
/*
// MODULE_CONTRACT: Defines the data structure for a paginated collection of TransactionData objects.
// RESPONSIBILITY: To provide a structured, type-safe container for lists of account transactions returned by the API, including pagination metadata.
// INPUTS: Raw JSON array from the API response.
// OUTPUTS: An object containing pagination details and a collection of `TransactionData`.
// LINKS: Requests/Statement/GetTransactionsRequest.php
*/
namespace Apoloz\AlfaBank\Data\Statement;
// <SECTION name="module_imports" intent="Import necessary DTOs and Spatie Laravel Data components.">
// <BELIEF_STATE "This collection DTO relies on `PaginationData` for metadata and `TransactionData` for the individual items. `DataCollection` and `DataCollectionOf` are Spatie Data features for handling typed arrays of DTOs.">
use Spatie\LaravelData\Attributes\DataCollectionOf;
use Spatie\LaravelData\Data;
use Spatie\LaravelData\DataCollection;
// </SECTION>
// <SECTION name="class_definition" intent="Define a DTO for a collection of account transactions.">
// <BELIEF_STATE "A dedicated DTO for a collection ensures that the structure of paginated lists is consistent and type-safe, providing a reliable contract for consumers to manage financial statements.">
class TransactionCollectionData extends Data
{
// <SECTION name="constructor_properties" intent="Define the properties of the transaction collection.">
// <BELIEF_STATE "The collection structure includes pagination metadata (`pagination`) and the actual list of transactions (`transactions`). The `#[DataCollectionOf(TransactionData::class)]` attribute is crucial for ensuring that each item in the `transactions` array is automatically cast to a `TransactionData` DTO.">
public function __construct(
#[DataCollectionOf(TransactionData::class)]
public DataCollection $transactions
) {
}
// </SECTION>
public DataCollection $transactions,
public ?array $_links = null,
) {}
}

33
src/Data/Statement/TransactionData.php
View File

@@ -1,39 +1,32 @@
<?php
declare(strict_types=1);
/*
// MODULE_CONTRACT: Defines the data structure for a single transaction record.
// RESPONSIBILITY: To hold and type-safely represent the details of an individual account transaction.
// INPUTS: Raw JSON object from the API response.
// OUTPUTS: A structured object containing transaction details.
// LINKS: TransactionCollectionData.php
*/
namespace Apoloz\AlfaBank\Data\Statement;
// <SECTION name="module_imports" intent="Import necessary DTOs and Spatie Laravel Data components.">
// <BELIEF_STATE "This DTO includes nested `AmountData` for monetary values and `RurTransferData` for detailed transfer information.">
use Spatie\LaravelData\Data;
// </SECTION>
// <SECTION name="class_definition" intent="Define a DTO for a single account transaction.">
// <BELIEF_STATE "This DTO provides a comprehensive, type-safe representation of a transaction, essential for consistent data handling and financial reporting.">
class TransactionData extends Data
{
// <SECTION name="constructor_properties" intent="Define all properties that describe an account transaction.">
// <BELIEF_STATE "The constructor includes key identifiers like `uuid`, `transactionId`, `operationDate`, `number`, and `direction` (DEBIT/CREDIT). Crucially, `amount` and `amountRub` use the nested `AmountData` DTO to ensure monetary values are correctly associated with their currencies. `paymentPurpose` and `rurTransfer` provide additional context, with `rurTransfer` being another nested DTO for specific RUR details.">
public function __construct(
public string $uuid,
public string $transactionId,
public string $operationDate,
public string $number,
public string $direction, // DEBIT, CREDIT
public AmountData $amount, // Nested DTO for amount
public AmountData $amountRub, // Nested DTO for amount in RUB
public string $direction,
public AmountData $amount,
public AmountData $amountRub,
public ?string $documentDate = null,
public ?string $filial = null,
public ?string $operationCode = null,
public ?string $paymentPurpose = null,
public ?RurTransferData $rurTransfer = null, // Nested DTO for RUR specific transfer details
public ?string $priority = null,
public ?string $revaln = null,
public ?string $correspondingAccount = null,
public ?string $debtorCode = null,
public ?string $extendedDebtorCode = null,
public ?RurTransferData $rurTransfer = null,
public ?SwiftTransferData $swiftTransfer = null,
public ?CurTransferData $curTransfer = null,
) {}
// </SECTION>
}

31
src/Requests/Statement/GetTransactionsRequest.php
View File

@@ -1,48 +1,30 @@
<?php
declare(strict_types=1);
/*
// MODULE_CONTRACT: Represents the API call to retrieve a list of account transactions.
// RESPONSIBILITY: To define the HTTP method, endpoint, and query parameters for fetching statement data, and to map the response to a structured collection DTO.
// INPUTS: Account number, date range, and pagination parameters.
// OUTPUTS: TransactionCollectionData (a DTO containing a list of transactions).
// LINKS: AlfaBankConnector.php#paginate
*/
namespace Apoloz\AlfaBank\Requests\Statement;
// <SECTION name="module_imports" intent="Import the response DTO and Saloon framework components.">
// <BELIEF_STATE "This request requires the `TransactionCollectionData` DTO to structure its response. It's a GET request, so it doesn't need body-related traits.">
use Apoloz\AlfaBank\Data\Statement\TransactionCollectionData;
use Apoloz\AlfaBank\Traits\HasAlfaPagination;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
class GetTransactionsRequest extends Request
{
use HasAlfaPagination;
protected Method $method = Method::GET;
public function __construct(
protected string $accountNumber,
protected string $statementDate,
?int $limit = 1000,
?int $offset = 0
) {
$this->limit = $limit;
$this->offset = $offset;
}
protected int $page = 1,
protected ?string $curFormat = null,
) {}
public function resolveEndpoint(): string
{
return '/api/jp/v1/statement/transactions';
}
// </SECTION>
// <SECTION name="response_dto_caster" intent="Transform the raw API JSON response into a structured collection DTO.">
// <BELIEF_STATE "The API returns a list of transactions. Casting this directly to a `TransactionCollectionData` DTO provides a type-safe, iterable object for the end-user, which is a significant improvement over dealing with raw arrays.">
public function createDtoFromResponse(Response $response): TransactionCollectionData
{
return TransactionCollectionData::from($response->json());
@@ -50,10 +32,11 @@ class GetTransactionsRequest extends Request
protected function defaultQuery(): array
{
return array_merge([
return array_filter([
'accountNumber' => $this->accountNumber,
'statementDate' => $this->statementDate,
], $this->getPaginationQuery());
'page' => $this->page,
'curFormat' => $this->curFormat,
], fn ($v) => $v !== null);
}
// </SECTION>
}