# مفتاحك ووكلاؤه

> تحقّق من مفتاح API الذي تحمله في مجيب واعرض الوكلاء الذين يستطيع العمل عليهم، عبر GET /v1/me وGET /v1/agents، أول استدعاءين في أي تكامل أو مساعد ذكاء اصطناعي.

استدعاءان يُخبران التكامل، أو مساعد الذكاء الاصطناعي، بما يستطيع فعله قبل أن يفعل أي شيء: `GET /v1/me` يصف المفتاح الذي تحمله، و`GET /v1/agents` يعرض الوكلاء الذين يستطيع العمل عليهم. وكل نقطة نهاية للوكيل تأخذ `id` الوكيل من هذه القائمة على أنه `agentId`.

## كيف أتحقّق من أن مفتاحي يعمل؟

استدعِ `GET /v1/me`. يصف المفتاح الذي تحمله ومنظمته وحد المعدّل الذي يعمل به؛ وكل حقوله في [مرجع وصف المفتاح المستدعي](../api-reference/get-me).

```bash
curl https://api.mojeeb.app/v1/me \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE"
```

يستطيع أي مفتاح صالح استدعاءه أياً كانت نطاقاته، لذا فهو أول استدعاء تجرّبه بمفتاح جديد. والرد `401` برمز `invalid_api_key` يعني أن المفتاح مفقود أو خاطئ أو مُلغى أو منتهي الصلاحية. أما `401` برمز `internal_server_error` فيعني أنه تعذّر على مجيب فحص المفتاح: أعد المحاولة بتراجع متصاعد ولا تُدوّره. راجع [التوثيق](../authentication). ولا يعود المفتاح نفسه أبداً: يعرض الرد منه فقط الجزأين اللذين تعرضهما صفحة **مفاتيح API**، لتميّز مفاتيحك بعضها عن بعض.

## كيف أجد معرّف الوكيل؟

استدعِ `GET /v1/agents`. يعرض الوكلاء الذين يستطيع مفتاحك العمل عليهم، الأحدث أولاً.

```bash
curl https://api.mojeeb.app/v1/agents \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE"
```

استخدم `id` الوكيل على أنه `agentId` في كل نقطة نهاية للوكيل، مثل `/v1/agents/{agentId}/leads`. و`id` نفسه هو `agent_id` الذي تأخذه نقطتا إرسال واتساب في جسم الطلب. راجع [مرجع عرض الوكلاء](../api-reference/list-agents) و[مرجع جلب وكيل](../api-reference/get-agent). وجلب وكيل واحد يُعيد إعداداته أيضاً؛ راجع [إعدادات الوكيل](./agent-settings).

ويمكنك أيضاً نسخ معرّفات الوكلاء من قسم **"معرّفات الوكلاء"** في صفحة **مفاتيح API** بلوحة التحكم.

## أسئلة شائعة

### لماذا لا يظهر وكيل في القائمة؟

إما أن المفتاح مقيّد ببعض الوكلاء، أو أن الوكيل حُذف، أو أنه يتبع منظمة أخرى. المفتاح المقيّد ببعض الوكلاء لا يعرض سواهم، ويُظهر `GET /v1/me` قائمته في `agent_ids`؛ والقيمة `null` هناك تعني كل وكلاء منظمتك، ومنهم من تضيفهم لاحقاً. ولا يصل المفتاح إلا إلى المنظمة التي يُظهرها `organization` في `GET /v1/me`. أما الوكلاء المحذوفون فلا يظهرون أبداً.

### هل `agent_ids` في `/v1/me` هي نفسها قائمة الوكلاء؟

لا. `agent_ids` هي إعداد المفتاح كما خُزّن، فقد تسمّي وكيلاً حُذف منذ ذلك الحين. أما `GET /v1/agents` فهو الجواب الحي: الوكلاء الذين يستطيع المفتاح العمل عليهم الآن.

### هل يحتاج `/v1/me` إلى نطاق؟

لا. تعرض صفحته في المرجع `x-scope: none`: يستطيع أي مفتاح صالح استدعاءه، لأنه لا يُعيد إلا بيانات المفتاح نفسه ومعرّف منظمتك واسمها. أما عرض الوكلاء وقراءتهم فيحتاجان `agents:read`، وتغيير إعداداتهم `agents:write`، ويحمل كل مفتاح الاثنين اليوم.

### هل يمكنني قراءة تعليمات الوكيل أو تغييرها عبر الواجهة البرمجية؟

نعم. يُعيد `GET /v1/agents/{agentId}` الوكيل مع [تعليماته الرئيسية](/docs/features/main-instructions) ومنطقته الزمنية وإيقاف ذكائه الاصطناعي بعد رد فريقك، ويغيّرها `PATCH /v1/agents/{agentId}`؛ راجع [إعدادات الوكيل](./agent-settings). أما القائمة من `GET /v1/agents` فتُبقي البيانات الأساسية وحدها. ولتشغيل الذكاء الاصطناعي لكل قناة ولإعدادات المتابعة نقاط نهاية خاصة؛ راجع [القنوات والمتابعات](./channels-and-follow-ups).

### لماذا لا تظهر حالة الوكيل؟

الحالة المخزّنة على الوكيل، مسودة كانت أو نشطة، لا تغيّر طريقة عمله اليوم، لذا لا تعرضها الواجهة البرمجية، ولا يستطيع المفتاح تغييرها: إرسال `status` في `PATCH /v1/agents/{agentId}` يُعيد `422 field_not_writable`. والوكلاء المحذوفون لا يظهرون في القائمة أبداً، وجلب أحدهم عبر `GET /v1/agents/{agentId}` يُعيد `404 agent_not_found`.