إنشاء خاصية للشركات

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

تُنشئ هذه النقطة خاصية مخصصة للشركات. يحتاج مفتاح واجهة التطبيق البرمجية إلى الإمكانية company-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": "Tax number",
        "ar": "الرقم الضريبي"
    },
    "desc": {
        "en": "The tax registration number of the company",
        "ar": "رقم التسجيل الضريبي للشركة"
    },
    "internal_name": "tax_number",
    "group_id": "6653c0d1e2f3a4b5c6d7e821",
    "is_unique_key": true
}

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

{
    "type": "single_select",
    "name": {
        "en": "Customer tier",
        "ar": "فئة العميل"
    },
    "internal_name": "customer_tier",
    "group_id": "6653c0d1e2f3a4b5c6d7e821",
    "enum": [
        {
            "en": "Gold",
            "ar": "ذهبية",
            "internal_name": "gold"
        },
        {
            "en": "Silver",
            "ar": "فضية",
            "internal_name": "silver"
        },
        {
            "en": "Bronze",
            "ar": "برونزية",
            "internal_name": "bronze"
        }
    ]
}

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

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

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

الخاصيتان name وwebsite_url مفتاحان فريدان للشركات افتراضياً. وللسماح بتكرار قيم إحداهما، عدّل الخاصية وأرسل "is_unique_key": false.

الإستجابة

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

{
    "data": {
        "type": "string",
        "name": {
            "en": "Tax number",
            "ar": "الرقم الضريبي"
        },
        "desc": {
            "en": "The tax registration number of the company",
            "ar": "رقم التسجيل الضريبي للشركة"
        },
        "internal_name": "tax_number",
        "group_id": "6653c0d1e2f3a4b5c6d7e821",
        "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": "6654d0e1f2a3b4c5d6e7f811",
        "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": "6653c0d1e2f3a4b5c6d7e821",
            "internal_name": "company_information",
            "name": {
                "en": "Company 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 بينما تتشارك سجلات قيمة واحدة.