> ## Documentation Index
> Fetch the complete documentation index at: https://docs.livingsecurity.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> صيانة تكاملات /api/v1 الحالية التي تستبدل مفتاح الوصول إلى واجهة برمجة التطبيقات برمز حامل (bearer token).

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

للحصول على تكامل جديد، ابدأ بـ[البدء السريع لواجهة برمجة التطبيقات](/ar/developers/v1/quickstart) و[المصادقة](/ar/developers/v1/authentication). تستخدم واجهة برمجة التطبيقات `/v1` الجديدة مفاتيح واجهة برمجة التطبيقات الخاصة بحسابات الخدمة أو رموز وصول OAuth.

## قبل أن تبدأ

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

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

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

<Note>
  يعرض مربع حوار Access Keys السر الذي يظهر مرة واحدة، لكنه لا يعرض معرّف جهة
  إصدار واجهة برمجة التطبيقات. إذا لم تزوّدك Living Security بمعرّف جهة الإصدار
  مع بيانات اعتماد واجهة برمجة التطبيقات العامة، فاطلبه من [دعم Living
  Security](mailto:support@livingsecurity.com). معرّف جهة الإصدار ليس معرّف مفتاح
  الوصول ولا معرّف المؤسسة.
</Note>

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

يستخدم العقد القديم مضيفات الإنتاج الإقليمية `/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** للاطلاع على القائمة الكاملة للعمليات والمعلمات والطلبات والاستجابات والمخططات. إذا لم تكن العملية مدرجة هناك، فهي ليست جزءًا من واجهة برمجة التطبيقات العامة حاليًا.

## المصادقة

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

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

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

```http theme={null}
Authorization: Bearer <access-token>
x-organization-id: <organization-id>
```

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

### TypeScript SDK

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

```bash theme={null}
npm install @livingsecurity/sdk@^1
```

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

```typescript theme={null}
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، فأرسل الرمز الحامل ومعرّف المؤسسة مع كل طلب:

```bash theme={null}
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 الموثقة الشكل العام التالي:

```json theme={null}
{
  "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](/ar/integrations/mcp) لربط أداة ذكاء اصطناعي بـ Living Security.

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

تواصل مع [دعم Living Security](mailto:support@livingsecurity.com) مع تزويدنا بما يلي:

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

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

## ذو صلة

<CardGroup cols={2}>
  <Card title="مفاتيح الوصول إلى واجهة برمجة التطبيقات" icon="key" href="/ar/integrations/api-keys">
    إنشاء بيانات اعتماد واجهة برمجة التطبيقات وتدويرها وإلغاؤها.
  </Card>

  <Card title="تكامل MCP" icon="robot" href="/ar/integrations/mcp">
    ربط أدوات الذكاء الاصطناعي المدعومة من خلال Model Context Protocol.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.