پرش به مطلب اصلی

اشتراک‌ها (SDK)

SDKهای Node.js و PHP اورکاریل از ساخت و مدیریت اشتراک‌ها با همان قراردادهای REST API پشتیبانی می‌کنند (از جمله فیلدهای snake_case درخواست در جای لازم). نمونه‌های زیر از SDK نود استفاده می‌کنند؛ برای معادل‌های PHP بخش SDK پی‌اچ‌پی را ببینید.

API فروشنده در برابر API پرداخت‌کننده​

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 Intentها استفاده کنید؛ اشتراک‌ها از همان احراز هویت (کلید 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 }
)

پردازش وب‌هوک​

رویدادهای اشتراک از همان اندپوینت وب‌هوک و همان constructEvent مربوط به Payment Intentها استفاده می‌کنند:

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
}

SDK پی‌اچ‌پی​

SDK پی‌اچ‌پی همان عملیات را روی $orcarail->subscriptions با پارامترهای آرایه انجمنی و پاسخ‌های OrcaRailObject ارائه می‌دهد. برای فهرست کردن به‌جای list() از all() استفاده می‌شود، چون 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]);

وب‌هوک‌های اشتراک از همان helper ایستای Payment Intentها استفاده می‌کنند:

$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 SDK پی‌اچ‌پی را ببینید.

انواع (TypeScript)​

SDK انواع اشتراک هم‌راستا با API را export می‌کند:

  • Subscription — شیء کامل اشتراک
  • SubscriptionCreateParams — payload ساخت
  • SubscriptionUpdateParams — payload ویرایش
  • SubscriptionCancelParams — payload لغو
  • SubscriptionStatus، SubscriptionInterval، SubscriptionCollectionMethod — enumها

برای تعریف کامل انواع مرجع API SDK نود را ببینید.

قدم‌های بعدی​