مرجع API لـ PHP SDK

تسرد هذه الصفحة الأصناف والدوال العامة في الحزمة orcarail/orcarail-php (النطاق OrcaRail\). للتثبيت والإعداد والأمثلة، راجع دليل PHP SDK.

العميل

`new OrcaRail\OrcaRailClient(array $config)`

ينشئ عميلًا. تستخدم كل الاستدعاءات المصادَق عليها مصادقة HTTP Basic بمفتاح API وسرّه.

مفاتيح الإعداد:

المفتاح	النوع	الافتراضي	الوصف
`api_key`	`string`	—	مفتاح API في OrcaRail (مثل `ak_live_xxx`). مطلوب ما لم يُقدَّم `http_client`.
`api_secret`	`string`	—	سر API في OrcaRail (مثل `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`	وسيلة نقل مخصصة، للاختبارات أساسًا. تحل محل عميل cURL المدمج.

يرمي InvalidArgumentException عندما لا ينفّذ http_client الواجهة ClientInterface، أو عند غياب بيانات الاعتماد لوسيلة النقل الافتراضية، أو عندما تكون مهلة ما غير موجبة.

خصائص الخدمات (تُنشأ عند أول وصول ثم يُعاد استخدامها):

الخاصية	الصنف
`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 Intents ومرجع 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`. ترسل المصادقة بمفتاح API إضافةً إلى الـ client secret.
`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`

أسعار الكتالوج المرتبطة بالمؤسسة، إضافةً إلى أدوات مساعدة للأسعار لمرة واحدة.

الدالة	الوصف
`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.

الـ webhooks

الأداتان المساعدتان ثابتتان (static) ولا تحتاجان إلى عميل. مرّر دائمًا جسم الطلب دون تعديل.

`OrcaRail\Webhook`

الدالة	الوصف
`Webhook::constructEvent(string $payload, string $signature, string $secret)`	تتحقق من التوقيع وتحلل الجسم إلى `OrcaRailObject`. ترمي `SignatureVerificationException` عند توقيع غير صالح أو JSON غير صالح أو جسم ليس كائنًا.

`OrcaRail\WebhookSignature`

الدالة	الوصف
`WebhookSignature::verifyHeader(string $payload, string $signature, string $secret)`	تعيد `true` عندما تساوي ترويسة `x-webhook-signature` توقيع HMAC-SHA256 للجسم الخام، مع المقارنة عبر `hash_equals()`. تعيد القيم الفارغة والتوقيعات غير الست عشرية `false`.
`WebhookSignature::assertValid(string $payload, string $signature, string $secret)`	التحقق نفسه، لكنها ترمي `SignatureVerificationException` بدلًا من إعادة `false`.

راجع الـ webhooks والتوقيعات.

`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)`	دالة مساعدة ثابتة تُستخدم لملء JSON المفكوك.

التعدادات (Enums)

تعدادات نصية مدعومة ضمن OrcaRail\Enum\. قارنها بـ $enum->value عند قراءة سلاسل API.

التعداد	الحالات
`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`

تعامل بسلاسة مع أنواع الأحداث غير المعروفة؛ فقد تُضاف أحداث جديدة.

الاستثناءات

ترث كل استثناءات الـ SDK من OrcaRail\Exception\OrcaRailException التي ترث من RuntimeException.

الصنف	متى يُرمى
`OrcaRailException`	الصنف الأساسي لكل استثناءات الـ SDK.
`ApiException`	أعادت API حالة غير 2xx. الخصائص: `statusCode` و`type` و`details` و`request`.
`AuthenticationException`	401 — مفتاح API أو سرّه غير صالح. يرث من `ApiException` مع `type` بقيمة `authentication_error`.
`TransportException`	فشل الشبكة، أو انتهاء المهلة، أو طلب لا يمكن ترميزه، أو استجابة لا يمكن فكها. الخاصية: `request`.
`SignatureVerificationException`	توقيع webhook غير صالح أو جسم ليس كائن JSON. الخاصية: `signature`.

تشير InvalidArgumentException وUnexpectedValueException (المدمجتان في PHP) إلى سوء استخدام محلي: تركيبات معاملات غير صالحة، أو إعداد غير صالح، أو أسماء خدمات غير معروفة، أو شكل استجابة غير متوقع.

وسيلة نقل HTTP

الصنف / الواجهة	الوصف
`OrcaRail\HttpClient\ClientInterface`	`request(string $method, string $path, ?array $body = null, bool $requireAuth = true): mixed`. نفّذها لتبديل وسيلة النقل في الاختبارات.
`OrcaRail\HttpClient\CurlClient`	وسيلة نقل 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، وسلاسل الاستعلام وفق RFC 3986.

أصناف أخرى

الصنف	الوصف
`OrcaRail\Version`	`Version::VERSION` — إصدار الحزمة المستخدم في ترويسة `User-Agent`.
`OrcaRail\CatalogPlanMetadata`	تطبّع `parse()` البيانات الوصفية لخطط الكتالوج (مصفوفة أو كائن) إلى `OrcaRailObject`.

انظر أيضًا

دليل PHP SDK — التثبيت والإعداد والأمثلة
مرجع API لـ Node SDK — المرجع المقابل لـ JavaScript وTypeScript
API الـ Payment Intents — مرجع REST

العميل​

new OrcaRail\OrcaRailClient(array $config)​

الخدمات​

$orcarail->paymentIntents​

$orcarail->subscriptions​

$orcarail->pay​

$orcarail->rates​

$orcarail->products​

$orcarail->prices​

الـ webhooks​

OrcaRail\Webhook​

OrcaRail\WebhookSignature​

OrcaRail\OrcaRailObject​

التعدادات (Enums)​

الاستثناءات​

وسيلة نقل HTTP​

أصناف أخرى​

انظر أيضًا​