مرجع 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	لا	رابط webhook لتلقي أحداث الدفع

الاستجابة

{
  "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 أو رابط الـ webhook الخاص به.

PATCH /api-keys/:id

المصادقة

• رمز Bearer (JWT) — مطلوب

معاملات المسار

المعامل	النوع	مطلوب	الوصف
id	number	نعم	معرّف مفتاح API

جسم الطلب

المعامل	النوع	مطلوب	الوصف
name	string	لا	اسم وصفي لمفتاح API
webhookUrl	string	لا	رابط webhook لتلقي أحداث الدفع (اضبطه على 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	نعم	سر API (مثل sk_live_...)

الاستجابة

{
  "ok": true
}

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

إذا كان مفتاح API غير صالح:

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

كائن مفتاح API

الحقول

الحقل	النوع	الوصف
id	number	معرّف فريد
name	string	اسم وصفي
keyPrefix	string	أول 8 أحرف من المفتاح (مثل ak_live_)
status	string	الحالة: active أو revoked
webhookUrl	string	رابط webhook لتلقي أحداث الدفع (قد يكون 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
• إعداد الـ webhooks — اضبط الـ webhooks لمفاتيح API
• نظرة عامة على المصادقة — طرق المصادقة