الارتباطات

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

يمكن ربط كل كيان بأي كيان آخر، والارتباط يعمل دائماً في الاتجاهين: إذا ربطت منتجاً بشركة، تظهر الشركة على المنتج أيضاً.

المتطلب القيمة
إمكانية المفتاح {object}-update، حيث {object} هو كيان السجل الموجود في الرابط، مثل company-update
الصلاحية أن يستطيع عضو الفريق الذي أنشأ المفتاح تعديل ذلك الكيان، مثل تعديل معلومات الشركة

راجع الصلاحيات والقدرات لمعرفة الإمكانيات.

السجلات التي يمكن ربطها

السجل الموجود في الرابط هو السجل الذي تبدأ منه، ومساره أحد المسارات /api/contacts أو /api/companies أو /api/deals أو /api/tickets أو /api/products أو /api/invoices. أما السجل الذي تربطه به فيحدده آخر الرابط وحقل محتوى الطلب:

لربط… ينتهي رابط الربط بـ حقل الربط ينتهي رابط إلغاء الربط بـ حقل إلغاء الربط
جهات الاتصال /attach-contacts contact_ids /detach-contact contact_id
الشركات /attach-companies company_ids /detach-company company_id
الصفقات /attach-deals deal_ids /detach-deal deal_id
التذاكر /attach-tickets ticket_ids /detach-ticket ticket_id
المنتجات /attach-products product_ids /detach-product product_id
الفواتير /attach-invoices invoice_ids /detach-invoice invoice_id

لا يمكن ربط سجل بسجل من الكيان نفسه، كربط شركة بشركة أخرى.

ولأن الارتباط يعمل في الاتجاهين، يمكن إنشاؤه من أي طرف. فربط منتج بشركة عبر /api/companies/{id}/attach-products يعطي النتيجة نفسها التي يعطيها ربط الشركة بالمنتج عبر /api/products/{id}/attach-companies، ولا يختلف إلا الإمكانية التي يحتاجها المفتاح: company-update في الأول، وproduct-update في الثاني.

ويمكن أيضاً ربط الشركات والمنتجات والفواتير عند إنشائها عبر الحقل association_ids، راجع إنشاء شركة. أما الصفقات فتقبل contact_ids عند إنشائها.

ربط السجلات

POST https://app.alaaqat.com/api/{path}/{id}/attach-{objects}

حيث {path} هو كيان السجل الذي تبدأ منه، و{id} هو قيمة _id له، و{objects} هو الكيان الذي تربطه به، من الجدول أعلاه. تربط هذه النقطة سجلاً واحداً أو أكثر بالسجل، وتبقى السجلات المرتبطة مسبقاً مرتبطة.

ترويسة الطلب

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

محتوى الطلب

{
    [link_field: string]: string[]
}
الحقل مطلوب التحققات الوصف
حقل الربط، مثل product_ids مطلوب مصفوفة من قيم _id لسجلات من ذلك الكيان في حسابك السجلات التي تُربط.

ربط منتجين بشركة عبر POST https://app.alaaqat.com/api/companies/6655a1b2c3d4e5f6a7b8c901/attach-products:

{
    "product_ids": [
        "6656b1c2d3e4f5a6b7c8d901",
        "6656b1c2d3e4f5a6b7c8d902"
    ]
}

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

الإستجابة

200 OK، وتأتي ضمن data جميع سجلات ذلك الكيان المرتبطة الآن، بما فيها المرتبطة من قبل. ويحمل كل سجل بعض خصائصه، بما يكفي للتعرّف عليه.

{
    "data": [
        {
            "properties": {
                "_id": "6656b1c2d3e4f5a6b7c8d901",
                "name": "Ergonomic office chair",
                "sku": "CH-ERGO-01",
                "created_at": "2026-10-20T09:30:00.000000Z"
            },
            "account_id": 1024
        },
        {
            "properties": {
                "_id": "6656b1c2d3e4f5a6b7c8d902",
                "name": "Standing desk",
                "sku": "DK-STAND-02",
                "created_at": "2026-10-18T11:00:00.000000Z"
            },
            "account_id": 1024
        }
    ]
}

إلغاء ربط سجل

POST https://app.alaaqat.com/api/{path}/{id}/detach-{object}

حيث {path} هو كيان السجل الذي تبدأ منه، و{id} هو قيمة _id له، و{object} هو كيان السجل الذي تلغي ربطه، من الجدول أعلاه. تُلغي هذه النقطة الارتباط بين السجلين، ولا يُحذف أي منهما.

ترويسة الطلب

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

محتوى الطلب

الحقل مطلوب التحققات الوصف
حقل إلغاء الربط، مثل product_id مطلوب قيمة _id لسجل واحد من ذلك الكيان مرتبط بالسجل الموجود في الرابط السجل الذي يُلغى ربطه.

إلغاء ربط منتج بشركة عبر POST https://app.alaaqat.com/api/companies/6655a1b2c3d4e5f6a7b8c901/detach-product:

{
    "product_id": "6656b1c2d3e4f5a6b7c8d902"
}

أرسل قيمة _id لسجل موجود في حسابك، فإن أرسلت قيمة أخرى يفشل الطلب ولا يُلغى أي ربط.

الإستجابة

200 OK، ويأتي السجل الموجود في الرابط ضمن data.

{
    "data": {
        "properties": {
            "_id": "6655a1b2c3d4e5f6a7b8c901",
            "name": "Blue Harbor Trading",
            "product_ids": [
                "6656b1c2d3e4f5a6b7c8d901"
            ],
            "products_count": 1,
            "created_by": 12,
            "updated_at": "2026-10-21T08:40:12.000000Z",
            "created_at": "2026-10-20T09:30:00.000000Z"
        },
        "account_id": 1024
    },
    "message": "Entity was modified successfully."
}

قراءة ارتباطات سجل

تحمل استجابة السجل الواحد، مثل عرض شركة، قيم _id للسجلات المرتبطة به وعددها، زوجاً لكل كيان يرتبط به:

الحقل يحمل
contact_ids وcompany_ids وdeal_ids وticket_ids وproduct_ids وinvoice_ids قيم _id للسجلات المرتبطة من ذلك الكيان
contacts_count وcompanies_count وdeals_count وtickets_count وproducts_count وinvoices_count عدد السجلات المرتبطة من ذلك الكيان

قد يغيب الزوج إذا لم يكن للسجل أي ارتباط بذلك الكيان.

عرض السجلات المرتبطة بسجل

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

المفتاح القيمة
forAssociationType كيان السجل الذي تبدأ منه بصيغة المفرد: contact أو company أو deal أو ticket أو product أو invoice
forAssociationId قيمة _id لذلك السجل

المنتجات المرتبطة بشركة:

GET https://app.alaaqat.com/api/products?forAssociationType=company&forAssociationId=6655a1b2c3d4e5f6a7b8c901

تأتي الإجابة قائمةً عادية مقسّمة إلى صفحات كما تصفها قائمة المنتجات، ويحتاج المفتاح إلى إمكانية -index للكيان الذي تعرضه، وهي هنا product-index. وتبقى معطيات الصفحات والتصفية المعقدة متاحة كالمعتاد.

الأخطاء

الرمز المعنى
403 المفتاح لا يحمل الإمكانية {object}-update، أو عضو الفريق لا يستطيع تعديل ذلك الكيان، أو لا يستطيع إلا تعديل السجلات التي يملكها هو أو فرقه والسجل الموجود في الرابط ليس منها.
404 لا يوجد في حسابك سجل بقيمة _id هذه.
422 حقل الربط غير موجود، أو أحد معرّفاته ليس لسجل من ذلك الكيان في حسابك.