إنشاء اشتراك

أنشئ اشتراكًا لبدء تحصيل مدفوعات متكررة من دافع.

نقطة النهاية

POST /api/v1/subscriptions

المصادقة

تتطلب مصادقة المدفوعات: رمز Bearer (JWT) أو مفتاح API (Basic).

جسم الطلب (snake_case)

يستخدم جسم الطلب snake_case:

المعامل	النوع	مطلوب	الوصف
description	string	نعم	وصف الاشتراك (مثل «خطة Pro الشهرية»)
amount	string	نعم	المبلغ لكل فترة فوترة (مثل "10.00")
currency	string	نعم	رمز العملة ISO من ثلاثة أحرف (مثل usd)
token_id	string	نعم	معرّف الرمز المستلَم (مثل USDC)
network_id	string	نعم	معرّف شبكة الاستلام
interval	string	نعم	فترة الفوترة: day أو week أو month أو year
interval_count	number	لا	عدد الفترات لكل دورة (الافتراضي 1)
collection_method	string	لا	send_payment_link (افتراضي) أو auto_charge
total_cycles	number	لا	إجمالي دورات الفوترة؛ احذفه أو استخدم null لعدد غير محدود
billing_cycle_anchor	string	لا	طابع زمني ISO لبداية الفترة الأولى
cancel_at	string	لا	طابع زمني ISO للإلغاء
cancel_at_period_end	boolean	لا	إذا كان true، يُلغى في نهاية الفترة الحالية
days_until_due	number	لا	الأيام بعد نهاية الفترة قبل اعتبارها متأخرة
trial_end	string	لا	طابع زمني ISO لنهاية الفترة التجريبية (أو "now" لتخطيها)
trial_period_days	number	لا	عدد أيام الفترة التجريبية منذ الإنشاء
payer_user_id	string	لا	معرّف مستخدم الدافع المسجّل
payer_email	string	لا	بريد الدافع للإشعارات وروابط الدفع
withdrawal_addresses	object	لا	المفاتيح: نوع الشبكة (مثل evm)، والقيمة: العنوان
metadata	object	لا	بيانات وصفية مفتاح-قيمة

الاستجابة

تعيد كائن الاشتراك كاملًا (راجع النظرة العامة) مع status وcurrent_period_start وcurrent_period_end و(في send_payment_link) رابط دفع الدورة الأولى عند الاقتضاء.

أمثلة

cURL

curl -X POST https://api.orcarail.com/api/v1/subscriptions \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Monthly Pro Plan",
    "amount": "10.00",
    "currency": "usd",
    "token_id": "uuid-for-usdc",
    "network_id": "uuid-for-base",
    "interval": "month",
    "interval_count": 1,
    "collection_method": "send_payment_link",
    "total_cycles": 12,
    "payer_email": "[email protected]"
  }'

JavaScript (fetch)

const response = await fetch('https://api.orcarail.com/api/v1/subscriptions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${jwtToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    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' },
  }),
})

const subscription = await response.json()
console.log('Subscription ID:', subscription.id)
console.log('Current period end:', subscription.current_period_end)

مع فترة تجريبية

{
  "description": "Pro Plan with trial",
  "amount": "10.00",
  "currency": "usd",
  "token_id": "...",
  "network_id": "...",
  "interval": "month",
  "trial_period_days": 14,
  "payer_email": "[email protected]"
}

الخصم التلقائي

{
  "description": "Yearly Pro (auto-charge)",
  "amount": "100.00",
  "currency": "usd",
  "token_id": "...",
  "network_id": "...",
  "interval": "year",
  "collection_method": "auto_charge",
  "total_cycles": 1,
  "payer_email": "[email protected]"
}

عند استخدام auto_charge، يجب على الدافع لاحقًا الموافقة على allowance في ERC-20 (راجع الخصم التلقائي).

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

• إدارة الاشتراكات — التحديث والإلغاء والاستئناف والسرد
• الخصم التلقائي — تدفق الموافقة على الـ allowance
• webhooks الاشتراكات — تفاعل مع أحداث الاشتراك