# قراءة عميل واحد بمعرّفه، الطلب GET /api/v1/contacts/{id}

> قراءة عميل واحد عبر واجهة مُجيب البرمجية بمعرّفه، بطلب GET /api/v1/contacts/{id}، مع أمثلة بـ curl وJavaScript وPython، وشكل الرد، ومعنى الخطأ 404.

قراءة عميل واحد تتم بالطلب `GET /api/v1/contacts/{id}`، حيث `{id}` معرّف العميل من قائمة العملاء أو من حجز. يعيد الطلب العميل بالحقول نفسها التي في القائمة، ويحتاج إلى مفتاح بصلاحية `contacts.read`.

## متى أستخدم قراءة عميل واحد؟

استخدمها عندما يكون معك معرّف عميل وتريد بياناته الحالية، دون أن تقرأ القائمة كلها.

- **من حجز:** كل حجز يحمل `customer.contactId`، فتقرأ به اسم العميل ورقمه ومرحلته الحالية.
- **لتحديث سجل عندك:** إذا حفظت العملاء في نظامك، فاقرأ العميل بمعرّفه لتعرف مرحلته ووسومه الآن.

## ما المعاملات التي يأخذها الطلب؟

يأخذ معاملًا واحدًا في المسار:

| المعامل | المكان | معناه |
| --- | --- | --- |
| `id` | المسار | معرّف العميل كما جاء في `id` بالقائمة أو في `customer.contactId` بالحجز |

المعرّف بصيغة غير صحيحة يعود بالخطأ 404، تمامًا كالمعرّف غير الموجود.

## كيف أرسل الطلب؟

```bash
curl https://api.mujib.ai/api/v1/contacts/5d8f2a61-0c4e-4b7a-9f13-6e2b8c0d4a57 \
  -H "Authorization: Bearer $MUJIB_API_KEY"
```

```js
const id = '5d8f2a61-0c4e-4b7a-9f13-6e2b8c0d4a57';
const res = await fetch(`https://api.mujib.ai/api/v1/contacts/${encodeURIComponent(id)}`, {
  headers: { Authorization: `Bearer ${process.env.MUJIB_API_KEY}` },
});
const body = await res.json();
if (res.status === 404) console.log('not in this business');
else if (!res.ok) throw new Error(`${res.status} ${body.error.code}: ${body.error.message}`);
else console.log(body.data.name, body.data.stage);
```

```python
import os
import requests

contact_id = "5d8f2a61-0c4e-4b7a-9f13-6e2b8c0d4a57"
res = requests.get(
    f"https://api.mujib.ai/api/v1/contacts/{contact_id}",
    headers={"Authorization": f"Bearer {os.environ['MUJIB_API_KEY']}"},
    timeout=30,
)
body = res.json()
if res.status_code == 404:
    print("not in this business")
elif not res.ok:
    raise RuntimeError(f"{res.status_code} {body['error']['code']}: {body['error']['message']}")
else:
    print(body["data"]["name"], body["data"]["stage"])
```

## كيف يبدو الرد؟

رد ناجح بالرمز 200، والعميل في `data`. البيانات مثال مختلَق:

```json
{
  "data": {
    "id": "5d8f2a61-0c4e-4b7a-9f13-6e2b8c0d4a57",
    "name": "سارة",
    "phone": "962790000000",
    "channel": "whatsapp",
    "stage": "qualified",
    "tags": ["استشارة"],
    "createdAt": "2026-11-02T09:14:37.205Z",
    "lastActiveAt": "2026-11-03T16:40:02.918Z"
  }
}
```

معنى كل حقل وقيمه الممكنة في [قائمة العملاء](https://docs.mujib.ai/developers/api-contacts/).

## ماذا يعني الخطأ 404 هنا؟

يعني أن نشاطك لا يملك عميلًا بهذا المعرّف، مهما كان السبب:

```json
{ "error": { "code": "NOT_FOUND", "message": "Contact not found" } }
```

يعود الخطأ نفسه للمعرّف غير الموجود، وللمعرّف الذي يتبع نشاطًا آخر، وللمعرّف بصيغة غير صحيحة، فلا يكشف الرد شيئًا عن بيانات غيرك. وباقي الأخطاء:

| HTTP | `code` | السبب |
| --- | --- | --- |
| 401 | `UNAUTHORIZED` | لا مفتاح، أو مفتاح غير صالح |
| 403 | `FORBIDDEN` | المفتاح لا يحمل `contacts.read` |
| 429 | `RATE_LIMITED` | تجاوزت حدود الطلبات |
| 500 | `INTERNAL` | خطأ غير متوقع في الخادم |

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

### من أين أحصل على معرّف العميل؟

من الحقل id في قائمة العملاء، أو من الحقل customer.contactId في الحجز.

### لماذا يعود الخطأ 404 لمعرّف أعرف أنه موجود؟

غالبًا لأن المفتاح يتبع نشاطًا غير الذي أُخذ منه المعرّف، أو لأن حرفًا سقط عند النسخ. الحالتان تعودان بالخطأ 404 نفسه.

### هل يعيد هذا الطلب حقولًا أكثر من القائمة؟

لا. يعيد الحقول نفسها التي يحملها كل عميل في القائمة.

---

المصدر: https://docs.mujib.ai/developers/api-contact/ · آخر تحديث: 2026-11-04