مرجع API کلیدهای API

مرجع کامل اندپوینت‌های API کلیدهای API.

آدرس پایه

https://api.orcarail.com/api/v1

ساخت کلید API

برای یک سازمان مشخص کلید API جدید بسازید.

POST /organizations/:organizationId/api-keys

احراز هویت

• توکن Bearer (JWT) — الزامی

پارامترهای مسیر

پارامتر	نوع	الزامی	توضیح
organizationId	string	بله	شناسه سازمانی که کلید برایش ساخته می‌شود. توکن bearer باید دسترسی داشته باشد.

از id سازمان در داشبورد ← تنظیمات سازمان یا پاسخ API فهرست سازمان‌ها استفاده کنید. پارامتر مسیر الزامی است؛ کلیدهای API دقیقاً برای همان سازمان ساخته می‌شوند.

بدنه درخواست

پارامتر	نوع	الزامی	توضیح
name	string	خیر	نام توصیفی کلید API
webhookUrl	string	خیر	آدرس وب‌هوک برای دریافت رویدادهای پرداخت

پاسخ

{
  "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",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  },
  "key": "ak_live_abc123def456",
  "secret": "sk_live_xyz789uvw012"
}

:::warning مهم secret فقط یک بار نمایش داده می‌شود. فوراً ذخیره‌اش کنید! :::

فهرست کلیدهای API

همه کلیدهای API یک سازمان مشخص را فهرست کنید.

GET /organizations/:organizationId/api-keys

احراز هویت

• توکن Bearer (JWT) — الزامی

پارامترهای مسیر

پارامتر	نوع	الزامی	توضیح
organizationId	string	بله	شناسه سازمانی که کلیدهایش فهرست می‌شود. توکن bearer باید دسترسی داشته باشد.

فهرست فقط به سازمان موجود در مسیر محدود است؛ وقتی این پارامتر وجود دارد، OrcaRail سازمان دیگری را از نشست استنباط نمی‌کند.

پاسخ

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

ویرایش کلید API

نام یا آدرس وب‌هوک یک کلید API را ویرایش کنید.

PATCH /api-keys/:id

احراز هویت

• توکن Bearer (JWT) — الزامی

پارامترهای مسیر

پارامتر	نوع	الزامی	توضیح
id	number	بله	شناسه کلید API

بدنه درخواست

پارامتر	نوع	الزامی	توضیح
name	string	خیر	نام توصیفی کلید API
webhookUrl	string	خیر	آدرس وب‌هوک برای دریافت رویدادهای پرداخت (برای حذف، null بگذارید)

پاسخ

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

لغو کلید API

یک کلید API را لغو کنید تا غیرفعال شود.

POST /api-keys/:id/revoke

احراز هویت

• توکن Bearer (JWT) — الزامی

پارامترهای مسیر

پارامتر	نوع	الزامی	توضیح
id	number	بله	شناسه کلید API

پاسخ

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

تست کلید API

معتبر بودن یک کلید API را تست کنید.

POST /api-keys/test

احراز هویت

• لازم نیست

بدنه درخواست

پارامتر	نوع	الزامی	توضیح
key	string	بله	کلید API (مثلاً ak_live_...)
secret	string	بله	secret API (مثلاً sk_live_...)

پاسخ

{
  "ok": true
}

پاسخ خطا

اگر کلید API نامعتبر باشد:

{
  "statusCode": 401,
  "message": "Invalid API key",
  "error": "Unauthorized"
}

شیء کلید API

فیلدها

فیلد	نوع	توضیح
id	number	شناسه یکتا
name	string	نام توصیفی
keyPrefix	string	۸ کاراکتر اول کلید (مثلاً ak_live_)
status	string	وضعیت: active یا revoked
webhookUrl	string	آدرس وب‌هوک برای دریافت رویدادهای پرداخت (می‌تواند null باشد)
createdAt	string	زمان ساخت به قالب ISO 8601
updatedAt	string	زمان آخرین ویرایش به قالب ISO 8601

مقادیر وضعیت

وضعیت	توضیح
active	کلید API فعال و قابل استفاده است
revoked	کلید API لغو شده و قابل استفاده نیست

کدهای وضعیت

کد وضعیت	توضیح
200	موفق
201	ساخته شد
400	درخواست نامعتبر
401	احراز هویت نشده
404	یافت نشد
500	خطای داخلی سرور

قالب پاسخ خطا

{
  "statusCode": 400,
  "message": "Invalid request",
  "error": "Bad Request"
}

همچنین ببینید

• راهنمای کلیدهای API — مستندات کامل کلیدهای API
• پیکربندی وب‌هوک — تنظیم وب‌هوک برای کلیدهای API
• نمای کلی احراز هویت — روش‌های احراز هویت