الارتباط يصل بين سجلين، كصفقة وجهة الاتصال التي تشتري، أو فاتورة والشركة التي صدرت باسمها. وبفضل الارتباطات يفتح عضو الفريق جهة اتصال في علاقات فيرى صفقاتها وتذاكرها وفواتيرها في مكان واحد. أما إذا أنشأ التكامل سجلات دون أن يربطها، فيبقى كل سجل منعزلاً، ويضطر الفريق إلى ربطها يدوياً.
يمكن ربط كل كيان بأي كيان آخر، والارتباط يعمل دائماً في الاتجاهين: إذا ربطت منتجاً بشركة، تظهر الشركة على المنتج أيضاً.
| المتطلب | القيمة |
|---|---|
| إمكانية المفتاح | {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 | حقل الربط غير موجود، أو أحد معرّفاته ليس لسجل من ذلك الكيان في حسابك. |