مفاتيح API

توفر مفاتيح API طريقة آمنة لمصادقة الطلبات من خادم إلى خادم إلى API الخاصة بـ OrcaRail.

نظرة عامة

يتكون مفتاح API من جزأين:

• المفتاح (ak_live_...) — معرّف عام
• السر (sk_live_...) — سر خاص (احفظه بأمان!)

كلاهما مطلوب للمصادقة عبر Basic Auth.

مفاتيح الإنتاج والـ sandbox

المؤسسة	المفتاح	السر	الشبكات
حية	ak_live_…	sk_live_…	الشبكات الرئيسية، أموال حقيقية
Sandbox	ak_test_…	sk_test_…	الشبكات التجريبية، دون أموال حقيقية

البادئة تساعدك فقط على التمييز بين المفاتيح؛ وتحدد API الوضع دائمًا من مؤسسة المفتاح. تعرض لوحة التحكم شارة Test أو Live بجوار كل مفتاح.

إنشاء مفاتيح API في لوحة التحكم

أسهل طريقة لإنشاء مفاتيح API وإدارتها هي لوحة تحكم OrcaRail:

1. سجّل الدخول — افتح لوحة التحكم ← تسجيل الدخول وأدخل بياناتك.
2. أنشئ مؤسستك الأولى إن طُلب منك ذلك — يجب على الحسابات الجديدة إنشاء مؤسسة قبل المتابعة في لوحة التحكم. يعرض الإعداد الموجَّه الـ slug المُنشأ ويتيح لك تعديله قبل الإنشاء عند الحاجة.
3. أكمل خطوات الإعداد الموجَّه المطلوبة — تُبقي OrcaRail لوحة التحكم مقفلة حتى يكون لمؤسستك وضع بيع، ومنتج واحد على الأقل، وسعر واحد على الأقل، ومفتاح API واحد، وأداة (widget) واحدة.
4. أنشئ مفتاح API — يتضمن الإعداد الموجَّه خطوة مدمجة لمفتاح API، أو يمكنك فتح لوحة التحكم ← مفاتيح API من الشريط الجانبي.
5. انسخ المفتاح والسر — انسخ المفتاح والسر فورًا؛ يُعرض السر مرة واحدة فقط ولا يمكن استرجاعه لاحقًا.

يمكنك أيضًا سرد مفاتيح API وتحديثها وإلغاؤها في صفحة لوحة التحكم نفسها.

العمولة (التقسيم والحصول على حصتك)

يمكنك تعيين نسبة عمولة (0–100) على مفتاح API. عند إنشاء مدفوعات بهذا المفتاح:

• تُحسب العمولة في عرض السعر وتُعرض للدافع في صفحة الدفع.
• يُخزَّن مبلغ العمولة في عرض السعر ويُضمَّن في المجاميع.
• عند السحب، تُرسل العمولة إلى عنوان إعدادات السحب في حسابك (الاستراتيجية والعنوان نفسيهما المستخدمَين لدفعاتك الرئيسية).

استخدمها لتقسيم الإيرادات مع الشركاء أو للحصول على حصة من كل دفعة تتم عبر تكاملك.

إنشاء مفاتيح API عبر API

عبر API

أنشئ مفتاح API بنقطة نهاية مفاتيح API:

POST /api/v1/organizations/:organizationId/api-keys
Authorization: Bearer YOUR_JWT_TOKEN

جسم الطلب:

{
  "name": "Production API Key",
  "webhookUrl": "https://api.example.com/webhooks/orcarail",
  "commissionPercent": 4
}

يتبع المفتاح المُنشأ المؤسسة المحددة بـ :organizationId. يجب أن ينتمي رمز bearer إلى مستخدم أو جلسة مخوّلة بإدارة تلك المؤسسة تحديدًا؛ معامل المسار مطلوب ويجب أن يطابق المؤسسة التي تنوي إدارتها.

• commissionPercent (اختياري): رقم من 0 إلى 100. عند تعيينه تُطبَّق هذه النسبة على المدفوعات المنشأة بهذا المفتاح؛ ويُعرض المبلغ للدافع ويُرسل إلى عنوان السحب الخاص بك.

الاستجابة:

{
  "apiKey": {
    "id": 1,
    "name": "Production API Key",
    "keyPrefix": "ak_live_",
    "status": "active",
    "webhookUrl": "https://api.example.com/webhooks/orcarail",
    "createdAt": "2024-01-01T00:00:00.000Z"
  },
  "key": "ak_live_abc123def456",
  "secret": "sk_live_xyz789uvw012"
}

:::warning مهم لا يُعرض secret إلا مرة واحدة عند إنشاء مفتاح API. احفظه فورًا! إن فقدته فسيلزمك إنشاء مفتاح API جديد. :::

مثال: إنشاء مفتاح API

const response = await fetch(
  'https://api.orcarail.com/api/v1/organizations/org_123/api-keys',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${jwtToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'Production API Key',
    }),
  }
)

const { apiKey, key, secret } = await response.json()

// IMPORTANT: Save the secret securely!
console.log('API Key:', key)
console.log('API Secret:', secret) // Only shown once!

استخدام مفاتيح API

المصادقة الأساسية

تستخدم مفاتيح API مصادقة HTTP Basic. الصيغة هي:

Authorization: Basic base64(key:secret)

مثال cURL

curl https://api.orcarail.com/api/v1/payment_intents \
  -u ak_live_abc123def456:sk_live_xyz789uvw012 \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "100.00",
    "currency": "usd",
    "payment_method_types": ["crypto"],
    "tokenId": 1,
    "networkId": 1,
    "return_url": "https://merchant.example.com/return"
  }'

مثال JavaScript

const key = 'ak_live_abc123def456'
const secret = 'sk_live_xyz789uvw012'

// Create base64 encoded credentials
const credentials = btoa(`${key}:${secret}`)

const response = await fetch(
  'https://api.orcarail.com/api/v1/payment_intents',
  {
    method: 'POST',
    headers: {
      Authorization: `Basic ${credentials}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      amount: '100.00',
      currency: 'usd',
      payment_method_types: ['crypto'],
      tokenId: 1,
      networkId: 1,
      return_url: 'https://merchant.example.com/return',
    }),
  }
)

مثال Node.js

const https = require('https')

const key = 'ak_live_abc123def456'
const secret = 'sk_live_xyz789uvw012'
const credentials = Buffer.from(`${key}:${secret}`).toString('base64')

const options = {
  hostname: 'api.orcarail.com',
  path: '/api/v1/payment_intents',
  method: 'POST',
  headers: {
    Authorization: `Basic ${credentials}`,
    'Content-Type': 'application/json',
  },
}

const req = https.request(options, (res) => {
  // Handle response
})

req.write(
  JSON.stringify({
    amount: '100.00',
    currency: 'usd',
    payment_method_types: ['crypto'],
    tokenId: 1,
    networkId: 1,
    return_url: 'https://merchant.example.com/return',
  })
)

req.end()

مثال Python

import requests
import base64

key = 'ak_live_abc123def456'
secret = 'sk_live_xyz789uvw012'

# Create base64 encoded credentials
credentials = base64.b64encode(f'{key}:{secret}'.encode()).decode()

response = requests.post(
    'https://api.orcarail.com/api/v1/payment_intents',
    headers={
        'Authorization': f'Basic {credentials}',
        'Content-Type': 'application/json',
    },
    json={
        'amount': '100.00',
        'currency': 'usd',
        'payment_method_types': ['crypto'],
        'tokenId': 1,
        'networkId': 1,
        'return_url': 'https://merchant.example.com/return',
    },
)

إدارة مفاتيح API

يمكنك سرد مفاتيح API وتحديثها وإلغاؤها من لوحة التحكم ← مفاتيح API، أو استخدام API كما يلي.

سرد مفاتيح API

GET /api/v1/organizations/:organizationId/api-keys
Authorization: Bearer YOUR_JWT_TOKEN

الاستجابة:

[
  {
    "id": 1,
    "name": "Production API Key",
    "keyPrefix": "ak_live_",
    "status": "active",
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
]

تحديث مفتاح API

حدّث اسم مفتاح API أو رابط الـ webhook الخاص به:

PATCH /api/v1/api-keys/:id
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

جسم الطلب:

{
  "name": "Updated API Key Name",
  "webhookUrl": "https://api.example.com/webhooks/orcarail"
}

الاستجابة:

{
  "id": 1,
  "name": "Updated API Key Name",
  "keyPrefix": "ak_live_",
  "status": "active",
  "webhookUrl": "https://api.example.com/webhooks/orcarail",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T12:00:00.000Z"
}

لإزالة رابط الـ webhook، اضبطه على null:

{
  "webhookUrl": null
}

إلغاء مفتاح API

POST /api/v1/api-keys/:id/revoke
Authorization: Bearer YOUR_JWT_TOKEN

الاستجابة:

{
  "id": 1,
  "name": "Production API Key",
  "keyPrefix": "ak_live_",
  "status": "revoked",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T12:00:00.000Z"
}

أفضل ممارسات الأمان

1. احفظ الأسرار بأمان

• لا تضف مفاتيح API أبدًا إلى نظام التحكم في الإصدارات
• خزّن الأسرار في متغيرات البيئة أو أنظمة إدارة الأسرار
• استخدم مفاتيح مختلفة لكل بيئة (التطوير، والاختبار المرحلي، والإنتاج)

2. دوّر المفاتيح بانتظام

• أنشئ مفاتيح API جديدة دوريًا
• ألغِ المفاتيح القديمة بعد إنشاء الجديدة
• حدّث تطبيقاتك لتستخدم المفاتيح الجديدة

3. استخدم أسماء وصفية

امنح مفاتيح API أسماء وصفية لتتبّع استخدامها:

{
  "name": "Production - Payment Service"
}

4. حدّد نطاق المفاتيح

أنشئ مفاتيح API منفصلة للخدمات أو البيئات المختلفة:

• Production - Web Server
• Production - Background Jobs
• Staging - Testing
• Development - Local

5. راقب استخدام المفاتيح

راجع مفاتيح API بانتظام وألغِ أي مفتاح لم تعد بحاجة إليه.

اختبار مفاتيح API

يمكنك اختبار صلاحية مفتاح API:

POST /api/v1/api-keys/test

جسم الطلب:

{
  "key": "ak_live_abc123def456",
  "secret": "sk_live_xyz789uvw012"
}

الاستجابة:

{
  "ok": true
}

استجابات الأخطاء

بيانات اعتماد غير صالحة

{
  "statusCode": 401,
  "message": "Unauthorized",
  "error": "Unauthorized"
}

غياب ترويسة Authorization

{
  "statusCode": 401,
  "message": "Unauthorized",
  "error": "Unauthorized"
}

إعداد الـ webhook

يمكن أن يكون لمفاتيح API رابط webhookUrl اختياري يستقبل أحداث الدفع. عند وقوع حدث دفع، ترسل OrcaRail webhook إلى الرابط المضبوط.

راجع إعداد الـ webhooks للتعليمات التفصيلية.

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

• إعداد الـ webhooks — اضبط الـ webhooks لمفاتيح API
• رموز Bearer — تعرّف على مصادقة JWT
• البدء — أنشئ أول دفعة لك