مرجع API SDK پی‌اچ‌پی

این صفحه کلاس‌ها و متدهای عمومی پکیج orcarail/orcarail-php (namespace به نام OrcaRail\) را فهرست می‌کند. برای نصب، پیکربندی و نمونه‌ها راهنمای SDK پی‌اچ‌پی را ببینید.

کلاینت

`new OrcaRail\OrcaRailClient(array $config)`

یک کلاینت می‌سازد. همه فراخوانی‌های احراز هویت‌شده از HTTP Basic Auth با کلید و secret API شما استفاده می‌کنند.

کلیدهای پیکربندی:

کلید	نوع	پیش‌فرض	توضیح
`api_key`	`string`	—	کلید API اورکاریل (مثلاً `ak_live_xxx`). الزامی است مگر اینکه `http_client` داده شود.
`api_secret`	`string`	—	secret API اورکاریل (مثلاً `sk_live_xxx`). الزامی است مگر اینکه `http_client` داده شود.
`base_url`	`string`	`https://api.orcarail.com/api/v1`	آدرس پایه نسخه‌دار API. برای نسخه دیگر به آدرس پایه آن اشاره کنید.
`timeout`	`int`	`30000`	مهلت کل درخواست بر حسب میلی‌ثانیه.
`connect_timeout`	`int`	`10000`	مهلت اتصال بر حسب میلی‌ثانیه.
`http_client`	`OrcaRail\HttpClient\ClientInterface`	`OrcaRail\HttpClient\CurlClient`	transport سفارشی، عمدتاً برای آزمون‌ها. جایگزین کلاینت cURL داخلی می‌شود.

وقتی http_client رابط ClientInterface را پیاده نکند، اطلاعات احراز هویت برای transport پیش‌فرض نباشد یا مهلتی مثبت نباشد، InvalidArgumentException پرتاب می‌کند.

ویژگی‌های سرویس (در اولین دسترسی ساخته و سپس دوباره استفاده می‌شوند):

ویژگی	کلاس
`paymentIntents`	`OrcaRail\Service\PaymentIntentService`
`subscriptions`	`OrcaRail\Service\SubscriptionService`
`pay`	`OrcaRail\Service\PayService`
`rates`	`OrcaRail\Service\RateService`
`products`	`OrcaRail\Service\ProductService`
`prices`	`OrcaRail\Service\PriceService`

دسترسی به هر ویژگی دیگری InvalidArgumentException پرتاب می‌کند.

use OrcaRail\OrcaRailClient;

$orcarail = new OrcaRailClient([
    'api_key' => getenv('ORCARAIL_API_KEY'),
    'api_secret' => getenv('ORCARAIL_API_SECRET'),
]);

سرویس‌ها

پارامترهای درخواست آرایه‌های انجمنی با همان نام فیلدهای REST API هستند. پاسخ‌ها نمونه‌های OrcaRailObject هستند مگر خلافش ذکر شود.

`$orcarail->paymentIntents`

نمای کلی Payment Intentها و مرجع REST را ببینید.

متد	توضیح
`create(array $params)`	یک payment intent می‌سازد. یا `price_id` یا همه موارد `amount`، `currency`، `tokenId`، `networkId` لازم است. پیش‌فرض `payment_method_types` برابر `['crypto']` است.
`retrieve(string $id)`	یک payment intent را با UUID می‌گیرد.
`confirm(string $id, array $params)`	تأیید و گرفتن آدرس صفحه پرداخت میزبانی‌شده. پارامترها: `client_secret`، `return_url`. علاوه بر client secret، احراز هویت با کلید API را هم می‌فرستد.
`complete(string $id)`	وقتی مشتری به آدرس بازگشت می‌رسد، intent را در حال پردازش علامت می‌زند. `payment_intent.processing` را فعال می‌کند.
`update(string $id, array $params)`	`amount`، `currency`، `tokenId`، `networkId`، `price_id`، `metadata`، آدرس‌ها، `expires_at` یا `withdrawal_addresses` را تغییر می‌دهد.
`cancel(string $id)`	یک payment intent را لغو می‌کند.

پارامترهای ساخت: price_id، amount، currency، tokenId، networkId، payment_method_types، return_url، cancel_url، description، metadata، expires_at، withdrawal_addresses (کلیدگذاری‌شده بر اساس خانواده زنجیره، مثلاً ['evm' => '0x…']).

ترکیب price_id با هر یک از amount، currency، tokenId یا networkId، و همچنین نبود هر دو شکل، InvalidArgumentException پرتاب می‌کند.

شبکه‌ها و توکن‌ها: SDK متدی برای فهرست آن‌ها ندارد. از GET پرداخت‌ها: فهرست شبکه‌ها و GET پرداخت‌ها: فهرست توکن‌ها بر اساس شبکه استفاده کنید و UUIDهای برگشتی را به‌عنوان networkId و tokenId بفرستید.

`$orcarail->subscriptions`

مسیرهای مجموعه سازمان را از کلید API احراز هویت‌شده تشخیص می‌دهند؛ مسیرهای تک‌آیتم در سطح بالا و بر اساس شناسه اشتراک هستند.

متد	توضیح
`create(array $params)`	یک اشتراک می‌سازد. یا `price_id` یا همه موارد `amount`، `currency`، `token_id`، `network_id`، `interval` لازم است.
`retrieve(string $id)`	یک اشتراک را با شناسه می‌گیرد.
`update(string $id, array $params)`	یک اشتراک را ویرایش می‌کند (مثلاً `cancel_at_period_end`، `pause_collection`، `metadata`).
`cancel(string $id, array $params = [])`	یک اشتراک را لغو می‌کند. `cancellation_details` اختیاری (`comment`، `feedback`). وقتی `$params` خالی باشد بدنه‌ای نمی‌فرستد.
`resume(string $id)`	یک اشتراک متوقف را ازسر می‌گیرد.
`all(array $params = [])`	اشتراک‌ها را فهرست می‌کند. پوششی با `data` و `has_more` برمی‌گرداند. نامش `all()` است چون `list` در PHP کلمه رزروشده است.
`listPaymentLinks(string $id, array $params = [])`	لینک‌های پرداخت یک اشتراک را فهرست می‌کند. پوششی با `data` و `has_more` برمی‌گرداند.

پارامترهای فهرست: status، collection_method، limit، starting_after، ending_before و فیلترهای بازه‌ای created، current_period_start، current_period_end. فیلترهای بازه‌ای آرایه‌های تودرتو هستند و به‌صورت پارامترهای کوئری کروشه‌دار کدگذاری می‌شوند؛ پس ['current_period_end' => ['lte' => $iso]] به‌صورت current_period_end[lte]=… ارسال می‌شود. مقادیر بولی به‌صورت true/false کدگذاری می‌شوند.

اندپوینت‌های برداشت خودکار سمت پرداخت‌کننده عمداً حذف شده‌اند؛ برداشت خودکار را ببینید.

`$orcarail->pay`

پرداخت با slug لینک پرداخت. API پرداخت را ببینید.

متد	توضیح
`retrieve(string $slug)`	payment intent پشت slug یک لینک پرداخت را می‌گیرد.
`get(string $slug)`	نام دیگر `retrieve()`.
`cancel(string $slug)`	لغو با slug.

`$orcarail->rates`

پیش‌فاکتور فیات و ارزهای پشتیبانی‌شده. API قیمت را ببینید.

متد	توضیح
`getFiatQuote(array $params)`	پیش‌فاکتور فیات به USD/USDC. پارامترها: `amount`، `currency`. شیئی با `amountUsd`، `amountUsdc`، `sourceAmount`، `sourceCurrency` برمی‌گرداند.
`getCurrencies(array $options = [])`	ارزهای فیات را فهرست می‌کند. گزینه: `active` (bool). خروجی `list<OrcaRailObject>`.

`$orcarail->products`

محصولات کاتالوگ وابسته به سازمان. هر متد ابتدا UUID سازمان را می‌گیرد.

متد	توضیح
`all(string $organizationId)`	محصولات را فهرست می‌کند. پوشش فهرست را باز می‌کند؛ خروجی `list<OrcaRailObject>`.
`create(string $organizationId, array $params)`	یک محصول می‌سازد (`name`، `description`، `active`، `metadata`).
`update(string $organizationId, string $productId, array $params)`	یک محصول را ویرایش می‌کند.
`delete(string $organizationId, string $productId)`	یک محصول را حذف (غیرفعال) می‌کند.

`$orcarail->prices`

قیمت‌های کاتالوگ وابسته به سازمان، به‌علاوه helperهایی برای قیمت‌های یک‌باره.

متد	توضیح
`all(string $organizationId, array $params = [])`	قیمت‌ها را فهرست می‌کند (مثلاً `['active' => true, 'recurring' => true]`). خروجی `list<OrcaRailObject>`.
`create(string $organizationId, array $params)`	یک قیمت می‌سازد (`product`، `nickname`، `unit_amount_decimal`، `currency`، `token_id`، `network_id`، `recurring`، `active`، `metadata`).
`update(string $organizationId, string $priceId, array $params)`	یک قیمت را ویرایش می‌کند.
`deactivate(string $organizationId, string $priceId)`	یک قیمت را غیرفعال می‌کند.
`listActiveRecurring(string $organizationId)`	میان‌بر برای قیمت‌های دوره‌ای فعال.
`findOneTimeByAmount(string $organizationId, array $params)`	قیمت یک‌باره فعالی را پیدا می‌کند که با `amount`، `currencyCode` و `productName` مطابقت دارد. اگر نباشد `null` برمی‌گرداند.
`ensureOneTime(string $organizationId, array $params)`	قیمت یک‌باره را پیدا یا ایجاد می‌کند و در صورت نیاز محصول را هم می‌سازد. پارامترها: `amount`، `currencyCode`، `tokenId`، `networkId`، `productName` و اختیاری `productDescription`، `productMetadata`.

مبالغ به دو رقم اعشار نرمال‌سازی می‌شوند؛ مبلغ غیرعددی یا غیرمثبت InvalidArgumentException پرتاب می‌کند. پوشش کاتالوگ ناسالم UnexpectedValueException پرتاب می‌کند.

وب‌هوک‌ها

هر دو helper ایستا هستند و به کلاینت نیاز ندارند. همیشه بدنه دست‌نخورده درخواست را بفرستید.

`OrcaRail\Webhook`

متد	توضیح
`Webhook::constructEvent(string $payload, string $signature, string $secret)`	امضا را بررسی و بدنه را به `OrcaRailObject` تجزیه می‌کند. برای امضای نامعتبر، JSON نامعتبر یا بدنه غیرشیء `SignatureVerificationException` پرتاب می‌کند.

`OrcaRail\WebhookSignature`

متد	توضیح
`WebhookSignature::verifyHeader(string $payload, string $signature, string $secret)`	وقتی هدر `x-webhook-signature` با HMAC-SHA256 بدنه خام برابر باشد (مقایسه با `hash_equals()`) `true` برمی‌گرداند. مقادیر خالی و امضاهای غیرهگزادسیمال `false` برمی‌گردانند.
`WebhookSignature::assertValid(string $payload, string $signature, string $secret)`	همان بررسی، اما به‌جای برگرداندن `false`، `SignatureVerificationException` پرتاب می‌کند.

وب‌هوک‌ها و امضاها را ببینید.

`OrcaRail\OrcaRailObject`

شیء پاسخ سازگار با نسخه‌های آینده. اشیای JSON تودرتو به OrcaRailObject تبدیل می‌شوند؛ آرایه‌های JSON به‌صورت فهرست PHP می‌مانند. فیلدهای ناشناخته حفظ می‌شوند، پس با اضافه شدن فیلد به API پاسخ‌ها خراب نمی‌شوند.

عضو	توضیح
`__get(string $name)`	دسترسی ویژگی. برای کلیدهای ناموجود `null` برمی‌گرداند.
`ArrayAccess`	خواندن، نوشتن، `isset()` و `unset()` با `$object['field']`. کلیدها باید رشته باشند.
`IteratorAggregate`، `Countable`	`foreach` روی فیلدها و `count($object)`.
`toArray()`	تبدیل بازگشتی به آرایه ساده.
`jsonSerialize()`	باعث می‌شود `json_encode($object)` همان ساختار را برگرداند.
`OrcaRailObject::convert(mixed $value)`	helper ایستا برای پر کردن JSON رمزگشایی‌شده.

enumها

enumهای رشته‌ای پشتیبان‌دار در OrcaRail\Enum\. هنگام خواندن رشته‌های API با $enum->value مقایسه کنید.

Enum	حالت‌ها
`PaymentIntentStatus`	`requires_payment_method`، `requires_confirmation`، `processing`، `completed`، `canceled`
`PaymentStatus`	`pending`، `partial_confirmed`، `confirmed`، `canceled`، `expired`، `completed`، `withdrawn`
`SubscriptionStatus`	`trialing`، `active`، `past_due`، `canceled`، `paused`، `completed`
`WebhookEventType`	`payment_intent.completed`، `payment_intent.processing`، `payment_intent.canceled`، `payment_intent.requires_payment_method`، `payment_intent.requires_confirmation`، `subscription.created`، `subscription.updated`، `subscription.canceled`، `subscription.paused`، `subscription.resumed`، `subscription.trial_will_end`، `subscription.payment_link.created`، `subscription.payment_link.paid`، `subscription.payment_link.payment_failed`، `subscription.past_due`، `subscription.completed`

انواع رویداد ناشناخته را با دقت مدیریت کنید؛ ممکن است رویدادهای جدید اضافه شوند.

exceptionها

همه exceptionهای SDK از OrcaRail\Exception\OrcaRailException ارث می‌برند که خودش از RuntimeException ارث می‌برد.

کلاس	چه زمانی پرتاب می‌شود
`OrcaRailException`	کلاس پایه همه exceptionهای SDK.
`ApiException`	API وضعیتی غیر از 2xx برگرداند. ویژگی‌ها: `statusCode`، `type`، `details`، `request`.
`AuthenticationException`	401 — کلید یا secret API نامعتبر. از `ApiException` با `type` برابر `authentication_error` ارث می‌برد.
`TransportException`	خرابی شبکه، اتمام مهلت، درخواست غیرقابل کدگذاری یا پاسخ غیرقابل رمزگشایی. ویژگی: `request`.
`SignatureVerificationException`	امضای وب‌هوک نامعتبر است یا بدنه شیء JSON نیست. ویژگی: `signature`.

InvalidArgumentException و UnexpectedValueException (داخلی PHP) نشان‌دهنده استفاده نادرست محلی هستند: ترکیب نادرست پارامترها، پیکربندی نامعتبر، نام سرویس ناشناخته یا ساختار پاسخ غیرمنتظره.

transport مربوط به HTTP

کلاس / رابط	توضیح
`OrcaRail\HttpClient\ClientInterface`	`request(string $method, string $path, ?array $body = null, bool $requireAuth = true): mixed`. برای جایگزینی transport در آزمون‌ها پیاده‌اش کنید.
`OrcaRail\HttpClient\CurlClient`	transport پیش‌فرض cURL. `Accept`/`Content-Type: application/json`، در صورت نیاز Basic auth و `User-Agent: orcarail-php/<version>` را می‌فرستد. بدنه‌های غیر JSON به‌صورت رشته و بدنه‌های خالی به‌صورت `null` برگردانده می‌شوند.

CurlClient::DEFAULT_BASE_URL برابر https://api.orcarail.com/api/v1 است. بخش‌های مسیر URL-encode و رشته‌های کوئری طبق RFC 3986 کدگذاری می‌شوند.

کلاس‌های دیگر

کلاس	توضیح
`OrcaRail\Version`	`Version::VERSION` — نسخه پکیج که در هدر `User-Agent` استفاده می‌شود.
`OrcaRail\CatalogPlanMetadata`	`parse()` فراداده پلن‌های کاتالوگ (آرایه یا شیء) را به `OrcaRailObject` نرمال‌سازی می‌کند.

همچنین ببینید

راهنمای SDK پی‌اچ‌پی — نصب، پیکربندی و نمونه‌ها
مرجع API SDK نود — مرجع معادل برای JavaScript و TypeScript
API مربوط به Payment Intentها — مرجع REST

کلاینت​

new OrcaRail\OrcaRailClient(array $config)​

سرویس‌ها​

$orcarail->paymentIntents​

$orcarail->subscriptions​

$orcarail->pay​

$orcarail->rates​

$orcarail->products​

$orcarail->prices​

وب‌هوک‌ها​

OrcaRail\Webhook​

OrcaRail\WebhookSignature​

OrcaRail\OrcaRailObject​

enumها​

exceptionها​

transport مربوط به HTTP​

کلاس‌های دیگر​

همچنین ببینید​