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

مرجع API SDK نود

این صفحه همه متدها و انواع عمومی SDK به نام @orcarail/node را فهرست می‌کند. برای نصب، پیکربندی و نمونه‌ها راهنمای SDK نود را ببینید.

کلاینت​

new OrcaRail(apiKey, apiSecret, config?)​

یک کلاینت جدید OrcaRail می‌سازد. همه فراخوانی‌های API از HTTP Basic Auth با کلید و secret داده‌شده استفاده می‌کنند.

پارامترها:

  • apiKey (string) — کلید API اورکاریل شما (مثلاً ak_live_xxx).
  • apiSecret (string) — secret API اورکاریل شما (مثلاً sk_live_xxx).
  • config (اختیاری) — OrcaRailConfig:
    • baseUrl (string) — آدرس پایه API. پیش‌فرض: https://api.orcarail.com/api/v1.
    • apiVersion (string) — نسخه API. پیش‌فرض: v1.
    • timeout (number) — مهلت درخواست بر حسب میلی‌ثانیه. پیش‌فرض: 30000.

نمونه:

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', timeout: 30000 }
)

منابع​

orcarail.paymentIntents​

منبع Payment Intentها. نمای کلی Payment Intentها و مرجع REST را ببینید.

متدتوضیح
create(params)یک payment intent می‌سازد. پارامترها: PaymentIntentCreateParams (amount، currency، tokenId، networkId، return_url، withdrawal_addresses و غیره). خروجی PaymentIntent.
retrieve(id)یک payment intent را با شناسه می‌گیرد (مثلاً 550e8400-e29b-41d4-a716-446655440000). خروجی PaymentIntent.
cancel(id)یک payment intent را لغو می‌کند (مثلاً وقتی کاربر به cancel_url می‌رسد). خروجی PaymentIntent.
confirm(id, params)تأیید و انتقال به پرداخت میزبانی‌شده. پارامترها: PaymentIntentConfirmParams (client_secret، return_url). احراز هویت با کلید API را می‌فرستد. خروجی PaymentIntent.
complete(id)وقتی کاربر به آدرس موفقیت/بازگشت می‌رسد، intent را در حال پردازش علامت می‌زند. خروجی PaymentIntent.
update(id, params)مبلغ، فراداده، آدرس‌ها یا آدرس برداشت را تغییر می‌دهد. پارامترها: PaymentIntentUpdateParams. خروجی PaymentIntent.

شبکه‌ها و توکن‌ها: SDK متدی برای فهرست شبکه‌ها یا توکن‌ها ندارد. برای گرفتن شناسه‌ها از REST API استفاده کنید: GET پرداخت‌ها: فهرست شبکه‌ها و GET پرداخت‌ها: فهرست توکن‌ها بر اساس شبکه. UUIDهای برگشتی را به‌عنوان networkId و tokenId در paymentIntents.create(params) بفرستید.

orcarail.pay​

پرداخت با slug لینک پرداخت. API پرداخت را ببینید.

متدتوضیح
get(slug)پرداخت (payment intent) را با slug می‌گیرد. خروجی PaymentIntent & Record<string, unknown>.
cancel(slug)لغو با slug. intent لغوشده و cancel_url اختیاری را برمی‌گرداند.

orcarail.subscriptions​

مسیرهای مجموعه اشتراک‌ها سازمان را از کلید API احراز هویت‌شده تشخیص می‌دهند؛ مسیرهای تک‌آیتم همچنان در سطح بالا و بر اساس شناسه اشتراک هستند.

متدتوضیح
create(params)در سازمان کلید API اشتراک می‌سازد. پارامترها: SubscriptionCreateParams. خروجی Subscription.
list(params?)اشتراک‌های سازمان کلید API را فهرست می‌کند. پارامترها: SubscriptionListParams. خروجی SubscriptionListResponse.
retrieve(id)یک اشتراک را با شناسه می‌گیرد. خروجی Subscription.
update(id, params)یک اشتراک را با شناسه ویرایش می‌کند. پارامترها: SubscriptionUpdateParams. خروجی Subscription.
cancel(id, params?)یک اشتراک را با شناسه لغو می‌کند. پارامترها: SubscriptionCancelParams. خروجی Subscription.
resume(id)یک اشتراک متوقف را با شناسه ازسر می‌گیرد. خروجی Subscription.
listPaymentLinks(id, params?)لینک‌های پرداخت یک اشتراک را فهرست می‌کند. خروجی { data, has_more }.

orcarail.rates​

پیش‌فاکتور فیات و ارزهای پشتیبانی‌شده. برای جزئیات کامل اندپوینت‌ها (از جمله GET /rates/fiat-quote و GET /rates/currencies) API قیمت را ببینید.

متدتوضیح
getFiatQuote(params)پیش‌فاکتور فیات به USD/USDC می‌گیرد. پارامترها: FiatQuoteParams ({ amount: string, currency: string }). خروجی FiatQuote.
getCurrencies(options?)ارزهای فیات پشتیبانی‌شده را فهرست می‌کند. گزینه‌ها: { active?: boolean }. خروجی Currency[].

انواع: FiatQuoteParams، FiatQuote (amountUsd، amountUsdc، sourceAmount، sourceCurrency)، Currency (id، code، name، symbol، decimals، isActive و غیره). برای فیلدهای پاسخ API قیمت را ببینید.

orcarail.webhooks​

بررسی امضای وب‌هوک و تجزیه رویداد. وب‌هوک‌ها و امضاها را ببینید.

متدتوضیح
verifySignature(rawBody, signature, secret)اگر x-webhook-signature با HMAC-SHA256 بدنه خام و secret مطابقت داشته باشد true و در غیر این صورت false برمی‌گرداند.
constructEvent(rawBody, signature, secret)امضا را بررسی و بدنه را به‌صورت WebhookEvent تجزیه می‌کند. اگر نامعتبر باشد OrcaRailSignatureVerificationError پرتاب می‌کند.

کلاس‌های خطا​

از @orcarail/node import کنید:

import {
  OrcaRailError,
  OrcaRailAPIError,
  OrcaRailAuthenticationError,
  OrcaRailSignatureVerificationError,
} from '@orcarail/node'
کلاسچه زمانی پرتاب می‌شود
OrcaRailErrorکلاس پایه همه خطاهای SDK.
OrcaRailAPIErrorAPI کدی غیر از 2xx برگرداند. دارای statusCode، type، details.
OrcaRailAuthenticationError401 — کلید یا secret API نامعتبر.
OrcaRailSignatureVerificationErrorامضای وب‌هوک نامعتبر است یا تجزیه بدنه شکست خورد. دارای signature.

انواع​

SDK انواع TypeScript را برای درخواست‌ها و پاسخ‌ها export می‌کند. از @orcarail/node import کنید:

  • پیکربندی: OrcaRailConfig
  • Payment Intentها: PaymentIntent، PaymentIntentStatus، PaymentIntentCreateParams، PaymentIntentUpdateParams، PaymentIntentConfirmParams
  • پرداخت / لینک‌ها: PaymentLink، LatestTransaction
  • وب‌هوک‌ها: WebhookEvent، WebhookEventType، WebhookEventData
  • نرخ‌ها: FiatQuoteParams، FiatQuote، Currency
  • اشتراک‌ها: Subscription، SubscriptionStatus، SubscriptionInterval، SubscriptionCollectionMethod، SubscriptionCreateParams، SubscriptionUpdateParams، SubscriptionCancelParams، SubscriptionListParams، SubscriptionListResponse، SubscriptionPaymentLinksListParams

برای نمونه‌های استفاده و ساختار درخواست/پاسخ، راهنمای SDK نود و مرجع API را ببینید.