إدارة الاشتراكات

حدّث الاشتراكات وألغِها واستأنفها واسردها باستخدام API الاشتراكات.

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

GET /api/v1/subscriptions/:id

يعيد كائن الاشتراك كاملًا. استخدمه للتحقق من الحالة وcurrent_period_end وlatest_payment_link و(في auto_charge) تفاصيل auto_charge.

مثال:

curl https://api.orcarail.com/api/v1/subscriptions/sub_550e8400e29b41d4a716446655440000 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

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

GET /api/v1/subscriptions

يدعم الترقيم بالمؤشر (cursor) والتصفية.

معاملات الاستعلام

المعامل	النوع	الوصف
status	string	التصفية حسب الحالة: trialing وactive وpast_due وcanceled وpaused وcompleted
collection_method	string	التصفية حسب send_payment_link أو auto_charge
current_period_start	object	التصفية حسب الفترة: gt وgte وlt وlte (طوابع ISO)
current_period_end	object	كما سبق لنهاية الفترة
created	object	التصفية حسب الإنشاء: gt وgte وlt وlte
limit	number	حجم الصفحة (الافتراضي 10، والحد الأقصى 100)
starting_after	string	المؤشر: معرّف الاشتراك الذي يُبدأ بعده
ending_before	string	المؤشر: معرّف الاشتراك الذي يُنتهى قبله

مثال:

curl "https://api.orcarail.com/api/v1/subscriptions?status=active&limit=20" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

شكل الاستجابة:

{
  "object": "list",
  "data": [ { ... subscription objects ... } ],
  "has_more": false
}

تحديث اشتراك

PATCH /api/v1/subscriptions/:id

تحديث جزئي. أرسل فقط الحقول التي تريد تغييرها.

الحقول القابلة للتحديث

المعامل	النوع	الوصف
description	string	وصف الاشتراك
amount	string	المبلغ الجديد لكل فترة
currency	string	رمز العملة
token_id	string	معرّف الرمز
network_id	string	معرّف الشبكة
collection_method	string	send_payment_link أو auto_charge
cancel_at	string | null	طابع زمني ISO للإلغاء، أو null لمسحه
cancel_at_period_end	boolean	الإلغاء في نهاية الفترة الحالية
days_until_due	number	الأيام بعد نهاية الفترة حتى التأخر
trial_end	string	موعد انتهاء الفترة التجريبية (ISO أو "now")
metadata	object	بيانات وصفية مفتاح-قيمة
withdrawal_addresses	object	نوع الشبكة ← العنوان
pause_collection	object | null	{ "behavior": "void" | "keep_as_draft" } للإيقاف المؤقت؛ وnull للاستئناف

مثال (الإلغاء في نهاية الفترة):

curl -X PATCH https://api.orcarail.com/api/v1/subscriptions/sub_xxx \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "cancel_at_period_end": true }'

مثال (إيقاف التحصيل مؤقتًا):

{
  "pause_collection": { "behavior": "void" }
}

إلغاء اشتراك

DELETE /api/v1/subscriptions/:id

الإلغاء فورًا أو في نهاية الفترة (إذا كنت قد ضبطت cancel_at_period_end سابقًا). جسم الطلب اختياري.

جسم الإلغاء (اختياري)

المعامل	النوع	الوصف
cancellation_details	object	ملاحظات اختيارية
cancellation_details.comment	string	تعليق نصي حر
cancellation_details.feedback	string	واحد من: too_expensive وmissing_features وswitched_service وunused وother

مثال:

curl -X DELETE https://api.orcarail.com/api/v1/subscriptions/sub_xxx \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cancellation_details": {
      "comment": "Switching to annual",
      "feedback": "other"
    }
  }'

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

POST /api/v1/subscriptions/:id/resume

يستأنف اشتراكًا متوقفًا مؤقتًا. لا يتطلب جسمًا. بعد الاستئناف يعود الاشتراك إلى active، وستنشئ الدورة التالية رابط دفع أو تشغّل الخصم التلقائي وفق الإعداد.

مثال:

curl -X POST https://api.orcarail.com/api/v1/subscriptions/sub_xxx/resume \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

سرد روابط الدفع لاشتراك

GET /api/v1/subscriptions/:id/payment-links

يعيد روابط الدفع (رابط لكل دورة فوترة) لهذا الاشتراك. يدعم الترقيم (مثل limit وstarting_after وending_before). استخدمه لعرض سجل الدورات أو حالة الرابط لكل فترة.

مثال:

curl "https://api.orcarail.com/api/v1/subscriptions/sub_xxx/payment-links?limit=10" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

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

• إنشاء اشتراك — أنشئ مع فترة تجريبية أو خصم تلقائي
• webhooks الاشتراكات — عالِج أحداث الاشتراك
• الفترات التجريبية — سلوك الفترة التجريبية