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

کلیدهای API

کلیدهای API روشی امن برای احراز هویت درخواست‌های سرور به سرور به API اورکاریل فراهم می‌کنند.

نمای کلی​

کلید API دو بخش دارد:

  • کلید (ak_live_...) — شناسه عمومی
  • Secret (sk_live_...) — راز خصوصی (امن نگهش دارید!)

برای احراز هویت با Basic Auth هر دو لازم‌اند.

کلیدهای live و sandbox​

سازمانکلیدSecretشبکه‌ها
Liveak_live_…sk_live_…شبکه‌های اصلی، وجوه واقعی
Sandboxak_test_…sk_test_…شبکه‌های آزمایشی، بدون وجوه واقعی

پیشوند فقط برای تشخیص کلیدها از هم است؛ API همیشه حالت را از سازمان کلید تعیین می‌کند. داشبورد کنار هر کلید نشان Test یا Live را نمایش می‌دهد.

ساخت کلید API در داشبورد​

ساده‌ترین راه ساخت و مدیریت کلیدهای API داشبورد OrcaRail است:

  1. ورود — داشبورد ← ورود را باز کنید و اطلاعات ورود را وارد کنید.
  2. اگر خواسته شد، اولین سازمان خود را بسازید — حساب‌های جدید پیش از ادامه در داشبورد باید یک سازمان بسازند. راه‌اندازی راهنما slug ساخته‌شده را نشان می‌دهد و در صورت نیاز اجازه می‌دهد پیش از ساخت ویرایشش کنید.
  3. گام‌های الزامی راه‌اندازی راهنما را تکمیل کنید — OrcaRail داشبورد را قفل نگه می‌دارد تا سازمان شما یک حالت فروش، دست‌کم یک محصول، دست‌کم یک قیمت، یک کلید API و یک ویجت داشته باشد.
  4. ساخت کلید API — راه‌اندازی راهنما یک گام درون‌خطی برای کلید API دارد، یا می‌توانید داشبورد ← کلیدهای API را از نوار کناری باز کنید.
  5. کپی کلید و secret — کلید و secret را فوراً کپی کنید؛ secret فقط یک بار نمایش داده می‌شود و بعداً قابل بازیابی نیست.

در همان صفحه داشبورد می‌توانید کلیدهای 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 (اختیاری): عددی بین ۰ تا ۱۰۰. اگر تعیین شود، این درصد روی پرداخت‌های ساخته‌شده با این کلید اعمال می‌شود؛ مبلغ آن به پرداخت‌کننده نمایش داده و به آدرس برداشت شما فرستاده می‌شود.

پاسخ:

{
  "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​

احراز هویت Basic​

کلیدهای API از HTTP Basic Authentication استفاده می‌کنند. قالب آن:

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 را ویرایش کنید:

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"
}

برای حذف آدرس وب‌هوک، مقدار آن را 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"
}

بهترین روش‌های امنیتی​

۱. secretها را امن نگه دارید​

  • هرگز کلید API را در کنترل نسخه commit نکنید
  • secretها را در متغیرهای محیطی یا سیستم‌های مدیریت راز ذخیره کنید
  • برای هر محیط (توسعه، staging، عملیاتی) کلید جداگانه استفاده کنید

۲. کلیدها را به‌طور منظم عوض کنید​

  • به‌صورت دوره‌ای کلید API جدید بسازید
  • پس از ساخت کلیدهای جدید، کلیدهای قدیمی را لغو کنید
  • اپلیکیشن‌هایتان را برای استفاده از کلیدهای جدید به‌روز کنید

۳. از نام‌های توصیفی استفاده کنید​

برای پیگیری استفاده از کلیدهای API، نام‌های توصیفی برایشان بگذارید:

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

۴. دامنه کلید را محدود کنید​

برای سرویس‌ها یا محیط‌های مختلف کلیدهای API جداگانه بسازید:

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

۵. استفاده از کلیدها را پایش کنید​

کلیدهای 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"
}

پیکربندی وب‌هوک​

کلیدهای API می‌توانند یک webhookUrl اختیاری داشته باشند که رویدادهای پرداخت را دریافت می‌کند. وقتی رویداد پرداختی رخ دهد، OrcaRail یک وب‌هوک به آدرس تنظیم‌شده می‌فرستد.

برای راهنمای کامل راه‌اندازی وب‌هوک‌ها پیکربندی وب‌هوک را ببینید.

قدم‌های بعدی​