واجهة برمجة التطبيقات العامة القديمة

يتناول هذا الدليل تكاملات /api/v1 الحالية التي تستبدل مفتاح الوصول إلى واجهة برمجة التطبيقات برمز حامل (bearer token). تختلف بيانات الاعتماد وتنسيق الطلبات فيها عن واجهة برمجة التطبيقات العامة /v1. للحصول على تكامل جديد، ابدأ بـالبدء السريع لواجهة برمجة التطبيقات والمصادقة. تستخدم واجهة برمجة التطبيقات /v1 الجديدة مفاتيح واجهة برمجة التطبيقات الخاصة بحسابات الخدمة أو رموز وصول OAuth.

قبل أن تبدأ

تحتاج إلى ما يلي:

صلاحية وصول إلى Living Security تتيح إدارة مفاتيح الوصول إلى واجهة برمجة التطبيقات
مفتاح وصول إلى واجهة برمجة التطبيقات تم إنشاؤه ضمن الإعدادات → Access Keys
السر الخاص بمفتاح الوصول الذي يظهر مرة واحدة فقط عند إنشاء بيانات الاعتماد
معرّف جهة إصدار واجهة برمجة التطبيقات (API issuer ID) الذي تزوّدك به Living Security مع بيانات اعتماد واجهة برمجة التطبيقات العامة
عنوان URL الأساسي الإقليمي للمؤسسة التي تجري تكاملها
بيئة تشغيل على جانب الخادم ومدير أسرار

يجب عدم وضع أسرار مفاتيح الوصول في شيفرة المتصفح أو تطبيقات الجوّال أو أنظمة التحكم في الإصدارات أو متغيرات البيئة على جانب العميل أو التذاكر أو السجلات المشتركة.

يعرض مربع حوار Access Keys السر الذي يظهر مرة واحدة، لكنه لا يعرض معرّف جهة إصدار واجهة برمجة التطبيقات. إذا لم تزوّدك Living Security بمعرّف جهة الإصدار مع بيانات اعتماد واجهة برمجة التطبيقات العامة، فاطلبه من دعم Living Security. معرّف جهة الإصدار ليس معرّف مفتاح الوصول ولا معرّف المؤسسة.

المضيفات الإقليمية

يستخدم العقد القديم مضيفات الإنتاج الإقليمية /api/v1 التالية:

المنطقة	عنوان URL الأساسي
US	`https://api.us-east-1.livingsecurity.ai/api/v1`
EU	`https://api.eu-west-1.livingsecurity.ai/api/v1`

استخدم المنطقة المعيّنة لمؤسسة Living Security. لا تبدّل المناطق للالتفاف على خطأ في التفويض أو التوافر.

الموارد القديمة

المورد	العمليات المدعومة
الأشخاص	البحث عن أشخاص المؤسسة واسترجاع عضوية شخص
مفاتيح الوصول إلى واجهة برمجة التطبيقات	إنشاء مفاتيح الوصول إلى واجهة برمجة التطبيقات وعرضها وتدويرها وإلغاؤها

استخدم Developers → Public API Reference للاطلاع على القائمة الكاملة للعمليات والمعلمات والطلبات والاستجابات والمخططات. إذا لم تكن العملية مدرجة هناك، فهي ليست جزءًا من واجهة برمجة التطبيقات العامة حاليًا.

المصادقة

يتم الوصول إلى واجهة برمجة التطبيقات العامة على مرحلتين:

استبدل مفتاح الوصول السري ومعرّف جهة إصدار واجهة برمجة التطبيقات برمز حامل قصير العمر ومعرّف المؤسسة.
أرسل الرمز الحامل ومعرّف المؤسسة مع كل طلب إلى واجهة برمجة التطبيقات.

ترويسات الطلب المطلوبة هي:

Authorization: Bearer <access-token>
x-organization-id: <organization-id>

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

TypeScript SDK

ثبّت الإصدار الرئيسي الحالي:

npm install @livingsecurity/sdk@^1

ثم استبدل المفتاح وهيّئ حزمة SDK:

import { configure, exchangeAccessKey } from "@livingsecurity/sdk";

const accessKeySecret = process.env.LS_API_ACCESS_KEY_SECRET;
const apiIssuerId = process.env.LS_API_ISSUER_ID;

if (!accessKeySecret || !apiIssuerId) {
  throw new Error("LS_API_ACCESS_KEY_SECRET and LS_API_ISSUER_ID are required");
}

const { accessToken, organizationId } = await exchangeAccessKey(
  accessKeySecret,
  apiIssuerId,
);

configure({
  baseUrl: "https://api.us-east-1.livingsecurity.ai/api/v1",
  accessToken,
  organizationId,
});

استخدم عنوان URL الأساسي للاتحاد الأوروبي (EU) بالنسبة إلى مؤسسة في الاتحاد الأوروبي. تم تصميم عملية الاستبدال عبر SDK للاستخدام في بيئات Node.js على جانب الخادم.

طلب REST مباشر

إذا أجريت عملية الاستبدال خارج SDK، فأرسل الرمز الحامل ومعرّف المؤسسة مع كل طلب:

curl --request GET \
  "https://api.us-east-1.livingsecurity.ai/api/v1/people/search?limit=1" \
  --header "Authorization: Bearer $LIVING_SECURITY_BEARER_TOKEN" \
  --header "x-organization-id: $LIVING_SECURITY_ORG_ID" \
  --header "Accept: application/json"

الرموز الحاملة قصيرة العمر. استبدل مفتاح الوصول مرة أخرى عند الحصول على رمز جديد بدلًا من حفظ الرمز الحامل كبيانات اعتماد دائمة.

دورة حياة مفتاح الوصول

سمِّ المفاتيح بحسب التكامل أو الأتمتة المالكة لها.
اختر أقل النطاقات امتيازًا من بين ما يتيحه نموذج مفتاح الوصول.
احفظ السر الذي يظهر مرة واحدة فورًا؛ إذ لا يمكن استرجاعه بعد الإنشاء أو التدوير.
دوّر المفتاح من خلال الإعدادات → Access Keys وانشر المفتاح البديل قبل إلغاء بيانات الاعتماد القديمة.
ألغِ المفاتيح التي لم تعد مستخدمة أو التي ربما تعرّض سرها للانكشاف.
استخدم مفاتيح حسابات الخدمة للتكاملات غير البشرية عندما يكون نوع المفتاح هذا متاحًا لمؤسستك.

ترقيم الصفحات

يدعم البحث عن الأشخاص المعلمات limit وcursor وoffset وincludeTotal. يُفضَّل استخدام المؤشر الذي أعادته الاستجابة السابقة للتصفح المتسلسل.

القيمة الافتراضية للمعلمة limit هي 50 وتقبل من 1 إلى 100.
تواصل المعلمة cursor من استجابة سابقة.
تتخطى المعلمة offset عددًا من السجلات وقيمتها الافتراضية 0.
تطلب المعلمة includeTotal=true عددًا دقيقًا بعد التصفية؛ احذفها عندما لا تحتاج إلى العدد.

اقرأ الكائن pagination الذي تعيده نقطة النهاية. لا تحسب الصفحة التالية استنادًا إلى عدد الصفوف المستلمة، ولا تجمع طلبات مرقّمة بشكل مستقل ثم تفرز النتائج الجزئية بنفسك.

الأخطاء

تستخدم أخطاء JSON الموثقة الشكل العام التالي:

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

يمكن أن يكون message سلسلة نصية أو مصفوفة من رسائل التحقق.

الحالة	المعنى	الإجراء
`400`	معلمات أو نص طلب غير صالح	صحّح أخطاء التحقق المذكورة
`401`	الرمز الحامل مفقود أو غير صالح أو منتهي الصلاحية	استبدل مفتاح الوصول مرة أخرى وأعد المحاولة مرة واحدة
`403`	لا تملك بيانات الاعتماد الصلاحية أو الوصول إلى المؤسسة	تحقق من نطاقات المفتاح وسياق المؤسسة
`404`	المورد غير موجود في المؤسسة المصرح بها	تحقق من معرّف المورد والمؤسسة
`408`	انتهت مهلة الطلب	أعد المحاولة مع تراجع أسي محدود
`429`	تم بلوغ حد المعدل	انتظر مدة لا تقل عن `Retry-After` عند وجوده
`5xx`	عطل مؤقت في الخدمة	أعد محاولة عمليات القراءة الآمنة مع تراجع أسي محدود

لا ينشر العقد المنسّق حاليًا حدًّا رقميًا موحدًا للمعدل، ولا يضمن وجود ترويسة استجابة لمعرّف الطلب لكل عملية. سجّل الوقت بالتوقيت العالمي المنسّق (UTC) والطريقة والمسار والحالة ونص الاستجابة بعد تنقيته عند طلب الدعم. لا تعِد محاولة عمليات الإنشاء أو التدوير أو الإلغاء أو الحذف تلقائيًا ما لم توثّق العملية صراحةً أنها متماثلة القوة (idempotent). تحقق من الحالة الحالية للمورد بعد أي فشل غامض في الشبكة.

التوافق وإيقاف الدعم

يتطور الإصدار V1 بصورة إضافية افتراضيًا. يجب على العملاء تجاهل حقول الاستجابة غير المعروفة. يتطلب أي تغيير جذري مسار ترحيل موثقًا؛ وتبقى العمليات التي أُعلن إيقاف دعمها في المرجع مع ذكر السبب والبديل عند توفره وتاريخ الإيقاف النهائي خلال فترة الترحيل. ثبّت حزمة SDK على إصدار رئيسي متوافق، وراجع ملاحظات الإصدار قبل الترقية. اعتبر مرجع واجهة برمجة التطبيقات العامة المُنشأ آليًا، وليس عملاء التطبيق التابعين للجهة المصنّعة، المصدر المرجعي للمخطط.

واجهة برمجة التطبيقات العامة وMCP وتطبيق الويب

الواجهة	الاستخدام	نموذج التوافق
واجهة برمجة التطبيقات العامة	أنظمة العملاء والشركاء والأتمتة الخارجية	موارد مستقرة ومُرقَّمة الإصدار
MCP	تفاعلات أدوات الذكاء الاصطناعي الخاضعة للأذونات	عقود الأدوات ومخرجات منظمة موجزة
تطبيق الويب	سير العمل البشري في منتج Living Security	عقود مملوكة للتطبيق قد تتطور مع واجهة المستخدم

راجع تكامل MCP لربط أداة ذكاء اصطناعي بـ Living Security.

الحصول على المساعدة

تواصل مع دعم Living Security مع تزويدنا بما يلي:

المؤسسة والمنطقة
اسم SDK وإصداره، إن كان مستخدمًا
الطابع الزمني بالتوقيت العالمي المنسّق (UTC) والطريقة والمسار
حالة HTTP ونص الخطأ بعد تنقيته

لا تُدرج أبدًا أسرار مفاتيح الوصول أو الرموز الحاملة أو بيانات العملاء الخاصة.

ذو صلة

مفاتيح الوصول إلى واجهة برمجة التطبيقات

إنشاء بيانات اعتماد واجهة برمجة التطبيقات وتدويرها وإلغاؤها.

تكامل MCP

ربط أدوات الذكاء الاصطناعي المدعومة من خلال Model Context Protocol.