إنشاء خاصية لجهات الاتصال

POST https://app.alaaqat.com/api/contacts/properties

تُنشئ هذه النقطة خاصية مخصصة لجهات الاتصال. يحتاج مفتاح واجهة التطبيق البرمجية إلى الإمكانية contact-property-create.

راجع صفحة الخصائص لمعرفة أنواع الخصائص المتاحة وصيغة خيارات الخاصية من نوع single_select.

ترويسة الطلب

{
    "Accept": "application/json",
    "Content-Type": "application/json"
}

محتوى الطلب

{
    type: string,
    name: {
        en?: string,
        ar?: string
    },
    desc?: {
        en?: string,
        ar?: string
    },
    internal_name: string,
    group_id: string,
    enum?: [
        {
            en?: string,
            ar?: string,
            internal_name: string
        }
    ],
    is_unique_key?: boolean
}
الحقل مطلوب التحققات الوصف
type مطلوب أحد أنواع الخصائص نوع القيمة التي تحملها الخاصية، ولا يمكن تغييره لاحقاً.
name مطلوب كائن يضم لغة واحدة على الأقل، وقيمة كل لغة نص اسم الخاصية بالإنجليزية en أو بالعربية ar أو بكلتيهما.
desc اختياري كائن من اللغات، وقيمة كل لغة نص أو null وصف الخاصية بالإنجليزية أو بالعربية أو بكلتيهما.
internal_name مطلوب أحرف وأرقام وشرطات سفلية فقط، ولا يجوز أن يبدأ بـ alaaqat، ولا أن تكون خاصية أخرى لجهات الاتصال، مدمجة أو من إنشائك، تستخدمه مسبقاً. المفتاح الذي تُحفظ فيه قيمة الخاصية على جهة الاتصال، ولا يمكن تغييره لاحقاً.
group_id مطلوب قيمة _id لمجموعة خصائص جهات الاتصال، مدمجة أو من إنشائك المجموعة التي تظهر الخاصية ضمنها.
enum اختياري مصفوفة من الخيارات، لكل خيار internal_name لا يتكرر داخل المصفوفة خيارات الخاصية من نوع single_select، ولا تُرسل مع الأنواع الأخرى.
is_unique_key اختياري true أو false يجعل الخاصية مفتاحاً فريداً. راجع المفاتيح الفريدة أدناه.

يملأ نظام علاقات الحقلين account_id وmade_by بنفسه، ويُرفض الطلب الذي يرسل أياً منهما.

خاصية نصية تعمل مفتاحاً فريداً:

{
    "type": "string",
    "name": {
        "en": "Membership number",
        "ar": "رقم العضوية"
    },
    "desc": {
        "en": "The number printed on the loyalty card",
        "ar": "الرقم المطبوع على بطاقة الولاء"
    },
    "internal_name": "membership_number",
    "group_id": "6653c0d1e2f3a4b5c6d7e801",
    "is_unique_key": true
}

خاصية من نوع single_select:

{
    "type": "single_select",
    "name": {
        "en": "Preferred branch",
        "ar": "الفرع المفضل"
    },
    "internal_name": "preferred_branch",
    "group_id": "6653c0d1e2f3a4b5c6d7e801",
    "enum": [
        {
            "en": "Downtown",
            "ar": "وسط البلد",
            "internal_name": "downtown"
        },
        {
            "en": "Airport Road",
            "ar": "طريق المطار",
            "internal_name": "airport_road"
        }
    ]
}

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

يمنع المفتاح الفريد أن تحمل جهتا اتصال القيمة نفسها لهذه الخاصية:

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

الخصائص email وphone وwhatsapp_number مفاتيح فريدة لجهات الاتصال افتراضياً. للسماح بتكرار القيم في أحدها، حدّث الخاصية وأرسل "is_unique_key": false.

الإستجابة

201 Created، وتأتي الخاصية الجديدة ضمن data.

{
    "data": {
        "type": "string",
        "name": {
            "en": "Membership number",
            "ar": "رقم العضوية"
        },
        "desc": {
            "en": "The number printed on the loyalty card",
            "ar": "الرقم المطبوع على بطاقة الولاء"
        },
        "internal_name": "membership_number",
        "group_id": "6653c0d1e2f3a4b5c6d7e801",
        "is_unique_key": true,
        "account_id": 1024,
        "made_by": 12,
        "updated_at": "2026-10-20T09:15:00.000000Z",
        "created_at": "2026-10-20T09:15:00.000000Z",
        "_id": "6654d0e1f2a3b4c5d6e7f801",
        "user": {
            "id": 12,
            "email": "sara.haddad@example.com",
            "firstname": "Sara",
            "lastname": "Haddad",
            "image": null,
            "locale": "en",
            "created_at": "2026-03-02T08:00:00.000000Z",
            "updated_at": "2026-10-01T07:30:00.000000Z",
            "fullname": "Sara Haddad"
        },
        "group": {
            "_id": "6653c0d1e2f3a4b5c6d7e801",
            "internal_name": "contact_information",
            "name": {
                "en": "Contact Information",
                "ar": "معلومات جهة الاتصال"
            },
            "desc": [],
            "account_id": null,
            "made_by": null,
            "updated_at": "2026-01-10T00:00:00.000000Z",
            "created_at": "2026-01-10T00:00:00.000000Z"
        }
    },
    "message": "Entity was created successfully."
}

الأخطاء

الرمز المعنى
402 بلغت الحد الأقصى للخصائص المخصصة في خطتك. اطّلع على الخطط في صفحة الأسعار.
422 فشل التحقق من أحد الحقول، كأن يكون الاسم الداخلي مستخدماً مسبقاً أو يحتوي على رموز غير مسموحة، أو تكون المجموعة غير موجودة، أو تكون قيمة is_unique_key هي true بينما تشترك جهات الاتصال في قيمة واحدة.