مرجع API لـ Node SDK

تسرد هذه الصفحة كل الدوال والأنواع العامة في الحزمة @orcarail/node. للتثبيت والإعداد والأمثلة، راجع دليل Node.js SDK.

العميل

new OrcaRail(apiKey, apiSecret, config?)

ينشئ عميل OrcaRail جديدًا. تستخدم كل استدعاءات API مصادقة HTTP Basic بالمفتاح والسر المحددين.

المعاملات:

• apiKey (string) — مفتاح API الخاص بك في OrcaRail (مثل ak_live_xxx).
• apiSecret (string) — سر API الخاص بك في OrcaRail (مثل 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 Intents. راجع نظرة عامة على Payment Intents ومرجع 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

عرض السعر بالعملة الورقية والعملات المدعومة. راجع API الأسعار للتفاصيل الكاملة لنقاط النهاية (بما فيها GET /rates/fiat-quote وGET /rates/currencies).

الدالة	الوصف
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

التحقق من توقيعات الـ webhooks وتحليل الأحداث. راجع الـ webhooks والتوقيعات.

الدالة	الوصف
verifySignature(rawBody, signature, secret)	تعيد true إذا طابق x-webhook-signature توقيع HMAC-SHA256 للجسم الخام بالسر؛ وإلا false.
constructEvent(rawBody, signature, secret)	تتحقق من التوقيع وتحلل الجسم كـ WebhookEvent. ترمي OrcaRailSignatureVerificationError إذا كان غير صالح.

أصناف الأخطاء

استوردها من @orcarail/node:

import {
  OrcaRailError,
  OrcaRailAPIError,
  OrcaRailAuthenticationError,
  OrcaRailSignatureVerificationError,
} from '@orcarail/node'

الصنف	متى يُرمى
OrcaRailError	الصنف الأساسي لكل أخطاء الـ SDK.
OrcaRailAPIError	أعادت API رمزًا غير 2xx. يحتوي statusCode وtype وdetails.
OrcaRailAuthenticationError	401 — مفتاح API أو سرّه غير صالح.
OrcaRailSignatureVerificationError	توقيع الـ webhook غير صالح أو فشل تحليل الجسم. يحتوي signature.

الأنواع

تصدّر الـ SDK أنواع TypeScript للطلبات والاستجابات. استوردها من @orcarail/node:

• الإعداد: OrcaRailConfig
• Payment Intents: PaymentIntent وPaymentIntentStatus وPaymentIntentCreateParams وPaymentIntentUpdateParams وPaymentIntentConfirmParams
• الدفع / الروابط: PaymentLink وLatestTransaction
• الـ webhooks: WebhookEvent وWebhookEventType وWebhookEventData
• الأسعار: FiatQuoteParams وFiatQuote وCurrency
• الاشتراكات: Subscription وSubscriptionStatus وSubscriptionInterval وSubscriptionCollectionMethod وSubscriptionCreateParams وSubscriptionUpdateParams وSubscriptionCancelParams وSubscriptionListParams وSubscriptionListResponse وSubscriptionPaymentLinksListParams

لأمثلة الاستخدام وأشكال الطلبات والاستجابات، راجع دليل Node.js SDK ومرجع API.