إنشاء شركة

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

تُنشئ هذه النقطة شركة جديدة. يحتاج مفتاح واجهة التطبيق البرمجية إلى الإمكانية company-create، ويحتاج عضو الفريق الذي أنشأ المفتاح إلى صلاحية إنشاء شركة جديدة.

ترويسة الطلب

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

محتوى الطلب

محتوى الطلب كائن مسطّح من قيم الخصائص: كل مفتاح فيه هو internal_name لإحدى خصائص الشركات، مدمجة أو من إنشائك، ويجب أن تطابق كل قيمة نوع خاصيتها. راجع صفحة الخصائص لمعرفة الأنواع، وقائمة خصائص الشركات لمعرفة الخصائص الموجودة في حسابك. لا توجد خاصية مطلوبة.

{
    name?: string,
    registered_name?: string | null,
    website_url?: string,
    phone?: string,
    owner?: number,
    communication_team?: number,
    association_ids?: {
        [object_type: string]: string[]
    },
    [internal_name: string]: any
}
الحقل مطلوب التحققات الوصف
name اختياري نص اسم الشركة، وهو مفتاح فريد افتراضياً.
registered_name اختياري نص أو null الاسم القانوني المسجّل للشركة.
website_url اختياري نص موقع الشركة الإلكتروني، وهو مفتاح فريد افتراضياً.
phone اختياري رقم هاتف بالصيغة الدولية، مثل +96265000000 يُعاد في الاستجابة بلا علامة + في أوله.
owner اختياري معرّف عضو في الفريق عضو الفريق الذي يملكها.
communication_team اختياري معرّف فريق الفريق الذي ينتمي إليه السجل.
association_ids اختياري كائن من أنواع السجلات، لكل نوع مصفوفة من المعرّفات يربط السجل الجديد بسجلات موجودة. راجع الربط عند الإنشاء.
أي خاصية أخرى اختياري يطابق نوع الخاصية استخدم internal_name للخاصية مفتاحاً.

يضع نظام علاقات _id بنفسه، ويُرفض الطلب الذي يرسلها، وكذلك الطلب الذي يرسل خاصية تحمل "system_only": true.

تقبل خاصية الصورة، مثل logo للشركة، ملف صورة حتى 2 ميغابايت. لتعيينها، أرسل الطلب بصيغة multipart/form-data بدلاً من JSON، وضع الملف تحت internal_name للخاصية.

{
    "name": "Blue Harbor Trading",
    "website_url": "https://blueharbor.example.com",
    "industry": "Wholesale",
    "city": "Amman",
    "country_region": "Jordan",
    "phone": "+96265000000",
    "num_employees": 45,
    "lifecycle_stage": "customer",
    "owner": 12,
    "association_ids": {
        "contact": [
            "6650f1a2b3c4d5e6f7a8b901"
        ]
    }
}

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

لا يمكن أن يأخذ السجل قيمة يحملها سجل آخر من الشركات في خاصية تعمل مفتاحاً فريداً. الخاصيتان name وwebsite_url مفتاحان فريدان للشركات افتراضياً، ويمكنك أن تجعل خصائصك أنت مفاتيح فريدة أيضاً، راجع المفاتيح الفريدة.

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

الربط عند الإنشاء

يربط الحقل association_ids السجل الجديد بسجلات موجودة لديك في الطلب نفسه. كل مفتاح فيه نوع سجل: contact أو company أو deal أو ticket أو product أو invoice، عدا company، وقيمة كل مفتاح مصفوفة من قيم _id لسجلات من ذلك النوع. ويُتجاوز المعرّف الذي لا يعود لسجل في حسابك.

للربط لاحقاً، راجع الارتباطات.

الإستجابة

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

{
    "data": {
        "properties": {
            "_id": "6655a1b2c3d4e5f6a7b8c901",
            "name": "Blue Harbor Trading",
            "website_url": "https://blueharbor.example.com",
            "industry": "Wholesale",
            "city": "Amman",
            "country_region": "Jordan",
            "phone": "96265000000",
            "num_employees": 45,
            "lifecycle_stage": "customer",
            "owner": 12,
            "created_by": 12,
            "updated_at": "2026-10-20T09:30:00.000000Z",
            "created_at": "2026-10-20T09:30:00.000000Z"
        },
        "account_id": 1024
    },
    "message": "Entity was created successfully."
}

الأخطاء

الرمز المعنى
422 قيمة لا تطابق نوع خاصيتها، أو أُرسل حقل يضعه نظام علاقات بنفسه، أو قيمة مفتاح فريد مستخدمة مسبقاً.