مدیریت اشتراک‌ها

با 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	اندازه صفحه (پیش‌فرض ۱۰، حداکثر ۱۰۰)
starting_after	string	cursor: شناسه اشتراکی که بعد از آن شروع شود
ending_before	string	cursor: شناسه اشتراکی که پیش از آن تمام شود

نمونه:

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"

قدم‌های بعدی

• ساخت اشتراک — ساخت با دوره آزمایشی یا برداشت خودکار
• وب‌هوک‌های اشتراک — رویدادهای اشتراک را پردازش کنید
• دوره‌های آزمایشی — رفتار دوره آزمایشی