# REST API لـ CRM مع webhooks موقّعة | AiCrm

> CRM مع REST API عامة: أنشئ جهات الاتصال واستعلم عنها بترويسة X-Api-Key، وحتى 20 مفتاحًا لكل تكامل، وwebhooks صادرة موقّعة بـ HMAC-SHA256. إضافة العملاء المحتملين من موقعك بلا تكرار.

- **المصدر (source):** https://aistohire.com/ar/aicrm-nzam-crm-bsit-ma-api-lidara-alamla-walamla-almhtmlin-109/f/crm-rest-api-webhooks
- **المنصة (platform):** AIstoHire
- **اللغة (language):** ar

## باختصار

- REST API عامة مع عدة مفاتيح API وwebhooks موقّعة
- أضف العملاء من موقعك أو نموذجك أو خادمك الخلفي بطلب HTTP واحد، واستقبل كل تغيير على خادمك موقّعًا بـ HMAC-SHA256.
- إضافة جهات الاتصال بطلب واحد
- بلا تكرار بحكم التصميم
- حتى 20 مفتاحًا مسمّى

## REST API عامة مع عدة مفاتيح API وwebhooks موقّعة

يوفّر AiCrm، تطبيق CRM من AIsToHire، REST API عامة على جهات اتصالك الخاصة. بمفتاح في الترويسة `X-Api-Key` يمكنك إنشاء جهات الاتصال وعرضها والاستعلام عنها وتحديثها وحذفها، وإضافة أنشطة لأي منها، من نموذج موقعك أو روبوت المحادثة أو Zap أو سكربت Python أو خادمك الخلفي. الاستجابات بصيغة JSON على شكل `{ success, data }`، والحد 100 طلب في الدقيقة لكل مفتاح.

الإضافة عبر API لا تكرر: إذا كان البريد الإلكتروني الذي ترسله موجودًا في قاعدتك، يحدّث AiCrm البطاقة التي كانت لديك (يستكمل الهاتف أو الاسم أو الشركة الناقصة ويضم الوسوم) ويسجّل إرسالًا جديدًا في سجلها الزمني، ويعيد HTTP 200؛ وإذا كان جديدًا ينشئه ويعيد 201. وكل جهة اتصال تدخل عبر API توسم تلقائيًا بـ `api-lead`، وتحتفظ بالوسوم التي ترسلها، وتحفظ قيمة `subId` المصدر، إضافة إلى البلد وعنوان IP والمتصفح الذي وصلت منه.

يمكنك امتلاك حتى 20 مفتاح API بأسماء خاصة، إضافة إلى مفتاح التطبيق الداخلي. وهكذا تعطي مفتاحًا مختلفًا لكل تكامل — الموقع، ونموذج حملة مايو، والمتدرب، والمورّد — وتلغيه وحده عندما ينتهي ذلك التكامل، دون المساس بالبقية. تُعرض القيمة الكاملة للمفتاح مرة واحدة فقط عند إنشائه؛ وبعد ذلك لا تظهر في القائمة إلا مخفية جزئيًا.

وفي الاتجاه المعاكس، تُعلم الـ webhooks أنظمتك. تضبط حتى 10 وجهات، وتختار الأحداث التي يشترك فيها كل منها (`customer.created` و`customer.updated` و`customer.deleted` و`activity.created`) ويرسل AiCrm طلب POST إلى عنوانك مع الترويستين `X-AiCrm-Event` و`X-AiCrm-Signature: sha256=…`، وهي توقيع HMAC-SHA256 لنص الطلب بسر ذلك الـ webhook، لتتحقق من أن التسليم شرعي. وعند حفظ العنوان، ترفض حماية SSRF العناوين localhost و127.0.0.0/8 و10.x و192.168.x و172.16-31.x و::1 و0.0.0.0 والنطاقات `.local` و`.internal`.

## ما الذي يتضمنه

- **إضافة جهات الاتصال بطلب واحد** — طلب POST إلى `/api/apps/public/crm/customers` مع البريد الإلكتروني والوسوم التي تريدها، فيصبح العميل المحتمل في CRM لديك مصنفًا.
- **بلا تكرار بحكم التصميم** — إذا كان البريد الإلكتروني موجودًا، تُحدَّث البطاقة ويُسجَّل الإرسال الجديد في سجلها الزمني بدل إنشاء بطاقة ثانية.
- **حتى 20 مفتاحًا مسمّى** — مفتاح لكل تكامل، ويمكن إلغاؤه بشكل منفصل. إذا تسرّب مفتاح، تحذف ذلك المفتاح وحده ولا يتوقف أي شيء آخر.
- **webhooks موقّعة بـ HMAC-SHA256** — تتحقق من الترويسة `X-AiCrm-Signature` بسرّك الخاص فتعرف أن الإشعار صادر من CRM لديك وليس من طرف ثالث.
- **حماية مدمجة من SSRF** — يرفض التطبيق تسليم webhooks إلى localhost أو إلى نطاقات الشبكات الخاصة، فلا يمكن استخدام CRM لديك لاستكشاف شبكة داخلية.
- **عمليات CRUD كاملة وليس الإضافة فقط** — عرض القائمة مع ترقيم الصفحات والتصفية (بحث، حالة، وسوم، بلد)، واستعلام عن جهة اتصال مع نشاطها، وتحديثها، وحذفها، وتسجيل أنشطة لها.
- **تتبّع المصدر تلقائيًا** — كل إضافة عبر API تحفظ قيمة `subId` التي ترسلها مع البلد وعنوان IP والمتصفح، وتُوسم بـ `api-lead` لتصفيتها لاحقًا في التطبيق.
- **اختبارات بلا تخمين** — يوفر التطبيق توثيق نقاط النهاية مع مثال `curl` قابل للنسخ وزرًا لإرسال تسليم تجريبي إلى كل webhook، مع حالة آخر محاولة ووقتها.

## الأسئلة الشائعة

### كيف أنشئ جهة اتصال في CRM من موقعي؟

ترسل طلب POST إلى `/api/apps/public/crm/customers` مع الترويسة `X-Api-Key` وJSON يحتوي على البريد الإلكتروني أو الهاتف على الأقل. ويمكنك أيضًا إرسال الاسم والهاتف والشركة والبلد والحالة والملاحظات والوسوم و`subId` لتحديد الحملة أو النموذج المصدر. يعيد AiCrm الرمز 201 إذا أنشأها و200 إذا كانت جهة الاتصال موجودة مسبقًا.

### ماذا يحدث إذا دخل البريد الإلكتروني نفسه مرتين عبر API؟

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

### كم مفتاح API يمكنني امتلاكه وهل يمكنني إلغاء مفتاح واحد فقط؟

يمكنك إنشاء حتى 20 مفتاحًا بأسماء خاصة، إضافة إلى مفتاح التطبيق الداخلي الذي لا يمكن حذفه. يُحذف كل مفتاح بشكل مستقل، فيمكنك إعطاء مفتاح مختلف لكل تكامل وإلغاؤه دون التأثير على البقية. تظهر القيمة الكاملة عند الإنشاء فقط؛ وبعد ذلك تظهر مخفية جزئيًا في القائمة. وتشترك جميع المفاتيح في حد 100 طلب في الدقيقة لكل مفتاح.

### كيف أتحقق من أن webhook قادم فعلًا من CRM لديّ؟

يحمل كل تسليم الترويسة `X-AiCrm-Signature: sha256=<firma>`، وهي HMAC-SHA256 لنص الطلب كما هو تمامًا باستخدام السر الذي يعرضه لك التطبيق عند إنشاء webhook. احسب هذا الـ HMAC على خادمك فوق النص المستلم وقارنه. كما تُرسل الترويسة `X-AiCrm-Event` باسم الحدث: `customer.created` أو `customer.updated` أو `customer.deleted` أو `activity.created`.

### ماذا يحدث إذا كانت نقطة نهاية webhook لديّ متوقفة؟

التسليم بأفضل جهد (best-effort): ينتظر AiCrm حتى 5 ثوانٍ، وإذا فشل يعيد المحاولة مرة واحدة بعد ثانية ونصف. لا توجد قائمة دائمة لإعادة المحاولات، لذا قد يتسبب انقطاع طويل في خادمك بفقدان بعض الإشعارات؛ وفي هذه الحالة قم بالمطابقة بطلب GET إلى `/api/apps/public/crm/customers`. ويعرض لك التطبيق حالة آخر محاولة ووقتها لكل webhook، ويمكنك إطلاق تسليم تجريبي متى شئت.

- [AiCrm — نظام CRM خفيف مع API لإضافة العملاء من أي نظام](https://aistohire.com/ar/aicrm-nzam-crm-bsit-ma-api-lidara-alamla-walamla-almhtmlin-109)

## عن المنصة

**AiCrm — نظام CRM خفيف مع API لإضافة العملاء من أي نظام** — تطبيق من AIstoHire. متاح في: https://aistohire.com/ar/aicrm-nzam-crm-bsit-ma-api-lidara-alamla-walamla-almhtmlin-109/f/crm-rest-api-webhooks

### لغات أخرى

- `es`: https://aistohire.com/es/aicrm-crm-ligero-con-api-109/f/api-rest-crm-webhooks-firmados
- `en`: https://aistohire.com/aicrm-lightweight-crm-with-api-109/f/api-rest-crm-signed-webhooks
- `fr`: https://aistohire.com/fr/aicrm-crm-leger-avec-api-109/f/api-rest-crm-webhooks-signes
- `it`: https://aistohire.com/it/aicrm-crm-leggero-con-api-109/f/api-rest-crm-webhook-firmati
- `pt`: https://aistohire.com/pt/aicrm-crm-leve-com-api-109/f/api-rest-crm-webhooks-assinados
- `de`: https://aistohire.com/de/aicrm-leichtes-crm-mit-api-109/f/api-rest-crm-signierte-webhooks
- `bg`: https://aistohire.com/bg/aicrm-lesen-crm-s-api-za-upravlenie-na-klienti-i-liydove-109/f/rest-api-crm-podpisani-uebhukove
- `ja`: https://aistohire.com/ja/aicrm-lightweight-crm-with-api-109/f/crm-rest-api-signed-webhooks
- `nl`: https://aistohire.com/nl/aicrm-eenvoudige-crm-met-api-om-klanten-en-leads-te-beheren-109/f/rest-api-crm-ondertekende-webhooks
- `ko`: https://aistohire.com/ko/aicrm-api-gyeongnyang-crm-109/f/crm-rest-api-seomyeong-webhook
- `sv`: https://aistohire.com/sv/aicrm-enkelt-crm-med-api-for-att-hantera-kunder-och-leads-109/f/rest-api-crm-signerade-webhooks
- `da`: https://aistohire.com/da/aicrm-enkelt-crm-med-api-til-at-styre-kunder-og-leads-109/f/rest-api-crm-signerede-webhooks
- `no`: https://aistohire.com/no/aicrm-enkelt-crm-med-api-for-a-styre-kunder-og-leads-109/f/rest-api-crm-signerte-webhooks
- `fi`: https://aistohire.com/fi/aicrm-yksinkertainen-crm-rajapinnalla-asiakkaille-ja-liideille-109/f/crm-rest-api-allekirjoitetut-webhookit
- `zh`: https://aistohire.com/zh/ai-crm-rest-api-webhooks-109/f/crm-rest-api-webhook
- `pl`: https://aistohire.com/pl/aicrm-prosty-crm-z-api-do-zarzadzania-klientami-i-leadami-109/f/api-rest-crm-podpisane-webhooki
- `he`: https://aistohire.com/he/aicrm-crm-pshot-am-api-lnihol-lkochot-vlidim-109/f/api-rest-crm-webhooks-chatumim
- `cs`: https://aistohire.com/cs/aicrm-jednoduche-crm-s-api-pro-spravu-klientu-a-leadu-109/f/rest-api-crm-podepsane-webhooky
- `id`: https://aistohire.com/id/aicrm-crm-sederhana-dengan-api-untuk-mengelola-pelanggan-dan-lead-109/f/api-rest-crm-webhook-bertanda-tangan
