إنتقل إلى المحتوى الرئيسي

الاشتراكات (SDK)

تدعم حِزم Node.js وPHP SDK من OrcaRail إنشاء الاشتراكات وإدارتها بعقود REST API نفسها (بما فيها حقول الطلب بصيغة snake_case حيث ينطبق). تستخدم الأمثلة أدناه Node.js SDK؛ راجع PHP SDK للمقابلات في PHP.

واجهات التاجر مقابل واجهات الدافع​

تغطي الـ SDK العمليات التي يصادق عليها التاجر: الإنشاء، والاسترجاع، والتحديث، والإلغاء، والاستئناف، والسرد، وسرد روابط الدفع (كما في إدارة الاشتراكات).

استدعاءات جهة الدافع ليست في @orcarail/node أو orcarail/orcarail-php. نفّذها عبر HTTP من تطبيق الدفع المستضاف أو المتصفح (دون مفتاح API)، تمامًا كواجهة الدفع في OrcaRail:

  • POST /api/v1/subscriptions/:id/approve-auto-charge
  • POST /api/v1/subscriptions/:id/revoke-auto-charge
  • POST /api/v1/subscriptions/:id/set-collection-method

راجع الخصم التلقائي لأجسام الطلبات والسلوك.

التثبيت​

مثل الـ SDK الرئيسية:

npm install @orcarail/node
composer require orcarail/orcarail-php

إعداد العميل​

استخدم العميل نفسه المستخدم مع Payment Intents؛ تستخدم الاشتراكات المصادقة نفسها (مفتاح API أو Bearer)، وتستنتج استدعاءات مجموعة اشتراكات التاجر المؤسسة من مفتاح API المصادَق عليه.

import OrcaRail from '@orcarail/node'

const orcarail = new OrcaRail(
  process.env.ORCARAIL_API_KEY!,
  process.env.ORCARAIL_API_SECRET!,
  { baseUrl: 'https://api.orcarail.com/api/v1' }
)

إنشاء اشتراك​

const subscription = await orcarail.subscriptions.create({
  description: 'Monthly Pro Plan',
  amount: '10.00',
  currency: 'usd',
  token_id: tokenId,
  network_id: networkId,
  interval: 'month',
  interval_count: 1,
  collection_method: 'send_payment_link',
  total_cycles: 12,
  payer_email: '[email protected]',
  metadata: { plan_id: 'pro_monthly' },
})

console.log(subscription.id)
console.log(subscription.current_period_end)
console.log(subscription.latest_payment_link?.link)

استرجاع اشتراك​

const subscription = await orcarail.subscriptions.retrieve(
  'sub_550e8400e29b41d4a716446655440000'
)
console.log(subscription.status, subscription.completed_cycles)

سرد الاشتراكات​

const { data, has_more } = await orcarail.subscriptions.list({
  status: 'active',
  limit: 20,
  starting_after: 'sub_previous_id', // optional cursor
})

for (const sub of data) {
  console.log(sub.id, sub.description, sub.current_period_end)
}

تحديث اشتراك​

const updated = await orcarail.subscriptions.update(
  'sub_550e8400e29b41d4a716446655440000',
  {
    cancel_at_period_end: true,
    metadata: { reason: 'customer_requested' },
  }
)

إلغاء اشتراك​

await orcarail.subscriptions.cancel('sub_550e8400e29b41d4a716446655440000', {
  cancellation_details: {
    comment: 'Switching to annual',
    feedback: 'other',
  },
})

استئناف اشتراك​

await orcarail.subscriptions.resume('sub_550e8400e29b41d4a716446655440000')
const { data } = await orcarail.subscriptions.listPaymentLinks(
  'sub_550e8400e29b41d4a716446655440000',
  { limit: 10 }
)

معالجة الـ webhooks​

تستخدم أحداث الاشتراك نقطة نهاية الـ webhook نفسها وconstructEvent نفسها المستخدمة مع Payment Intents:

const event = orcarail.webhooks.constructEvent(
  rawBody,
  req.headers['x-webhook-signature'],
  process.env.ORCARAIL_WEBHOOK_SECRET!
)

switch (event.type) {
  case 'subscription.created':
    console.log('Subscription created:', event.data.object.id)
    break
  case 'subscription.payment_link.paid':
    console.log('Cycle paid:', event.data.object.id)
    break
  case 'subscription.canceled':
    console.log('Canceled:', event.data.object.id)
    break
  case 'subscription.past_due':
    console.log('Past due:', event.data.object.id)
    break
  // ... other subscription.* types
}

PHP SDK​

توفر PHP SDK العمليات نفسها على $orcarail->subscriptions، بمعاملات في مصفوفات ترابطية واستجابات OrcaRailObject. يتم السرد بـ all() بدلًا من list() لأن list كلمة محجوزة في PHP.

use OrcaRail\OrcaRailClient;

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

$subscription = $orcarail->subscriptions->create([
    'description' => 'Monthly Pro Plan',
    'amount' => '10.00',
    'currency' => 'usd',
    'token_id' => $tokenId,
    'network_id' => $networkId,
    'interval' => 'month',
    'interval_count' => 1,
    'collection_method' => 'send_payment_link',
    'total_cycles' => 12,
    'payer_email' => '[email protected]',
    'metadata' => ['plan_id' => 'pro_monthly'],
]);

echo $subscription->id;
echo $subscription->latest_payment_link?->link;

$page = $orcarail->subscriptions->all(['status' => 'active', 'limit' => 20]);
foreach ($page->data as $sub) {
    echo $sub->id . ' ' . $sub->current_period_end . PHP_EOL;
}

$orcarail->subscriptions->retrieve($subscription->id);
$orcarail->subscriptions->update($subscription->id, ['cancel_at_period_end' => true]);
$orcarail->subscriptions->cancel($subscription->id, [
    'cancellation_details' => ['comment' => 'Switching to annual', 'feedback' => 'other'],
]);
$orcarail->subscriptions->resume($subscription->id);
$orcarail->subscriptions->listPaymentLinks($subscription->id, ['limit' => 10]);

تستخدم webhooks الاشتراكات الدالة المساعدة الثابتة نفسها المستخدمة مع Payment Intents:

$event = \OrcaRail\Webhook::constructEvent(
    file_get_contents('php://input'),
    $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '',
    getenv('ORCARAIL_WEBHOOK_SECRET'),
);

if ($event->type === 'subscription.payment_link.paid') {
    // credit the cycle for $event->data->object->id
}

راجع مرجع API لـ PHP SDK لكل المعاملات وأشكال الإرجاع.

الأنواع (TypeScript)​

تصدّر الـ SDK أنواع اشتراك متوافقة مع API:

  • Subscription — كائن الاشتراك الكامل
  • SubscriptionCreateParams — حمولة الإنشاء
  • SubscriptionUpdateParams — حمولة التحديث
  • SubscriptionCancelParams — حمولة الإلغاء
  • SubscriptionStatus وSubscriptionInterval وSubscriptionCollectionMethod — أنواع تعداد (enums)

راجع مرجع API لـ Node SDK للتعريفات الكاملة للأنواع.

الخطوات التالية​