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

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

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

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

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

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

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

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

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

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

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

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);

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. البيانات مثال مختلَق:

{
  "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"
  }
}

معنى كل حقل وقيمه الممكنة في قائمة العملاء.

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

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

{ "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 نفسه.

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

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

صفحات ذات صلة

• قائمة العملاء عبر API بالطلب GET /api/v1/contacts
• قراءة حجز واحد بمعرّفه، الطلب GET /api/v1/bookings/{id}
• الأخطاء وحدود الطلبات في واجهة مُجيب البرمجية