لإنشاء وتحديث جهات الاتصال بشكل جماعي عبر البرمجة، استخدم واجهة برمجة التطبيقات REST من Papo. باستخدام المصادقة بالمفتاح السري (Bearer token) والمفتاح العام للحساب، يمكنك إرسال طلبات تُدرج سجلات جديدة أو تعدل البيانات الموجودة في CRM — مثالي لمزامنة القواعد الخارجية، أو ترحيل القوائم، أو الحفاظ على السجل محدثًا دائمًا دون تدخل يدوي.
تعرض واجهة برمجة تطبيقات Papo نقاط نهاية الكتابة التي تسمح بإنشاء جهة اتصال (بالاسم والبريد الإلكتروني و/أو الهاتف) وتحديث جهة اتصال موجودة. عند دمجها مع المصادقة البسيطة وتنسيق JSON، تتيح نقاط النهاية هذه عمليات الدفعات عند تنفيذها بالتسلسل بواسطة البرامج النصية أو أدوات الأتمتة (مثل n8n) أو التكاملات المخصصة.
ملخص عملية التكامل
| المرحلة | الإجراء | التفاصيل المهمة |
|---|---|---|
| 1. الحصول على المفاتيح | إنشاء المفتاح السري (sk_live_…) ونسخ المفتاح العام (pk_live_…) في لوحة تحكم Papo. | يظهر المفتاح السري مرة واحدة فقط؛ احتفظ به في مكان آمن. |
| 2. مصادقة الاستدعاءات | تضمين العنوان Authorization: Bearer sk_live_… في جميع طلبات الكتابة. |
يمكن إرسال المفتاح العام في العنوان X-Papo-Public-Key (اختياري). |
| 3. تحضير الحمولة | تجميع كائن JSON مع حقول جهة الاتصال (الاسم، البريد الإلكتروني، الهاتف، إلخ). | الحقول الإلزامية والتنسيق الدقيق موجودان في وثائق API. |
| 4. إرسال الطلبات | إجراء POST إلى نقطة نهاية الإنشاء أو PUT/PATCH للتحديث. | تعالج كل طلب جهة اتصال واحدة؛ بالنسبة للعديد من السجلات، قم بأتمتة الإرسال في حلقة. |
| 5. التحقق من الردود | تُرجع API success: true وبيانات جهة الاتصال التي تم إنشاؤها/تحديثها. |
في حالة حدوث خطأ، يحتوي النص على الرمز والرسالة للتصحيح. |
كيف تعمل المصادقة ونقاط النهاية
كل استدعاء يعدل البيانات (إنشاء، تحديث) يتطلب المفتاح السري للحساب. يجب إرساله كرمز Bearer في العنوان Authorization أو، بدلاً من ذلك، في العنوان X-Papo-Secret-Key. يمكن أن يصاحب المفتاح العام (ثابت لكل حساب) الطلب في العنوان X-Papo-Public-Key — استخدامه اختياري، ولكن إذا تم إرساله يجب أن يتوافق مع نفس حساب المفتاح السري.
عنوان URL الأساسي لواجهة برمجة التطبيقات هو https://app.papo.global/api/v1. انطلاقًا منه، تقبل نقاط نهاية جهات الاتصال أفعال HTTP المناسبة لإنشاء سجل جديد أو تعديل سجل موجود. نظرًا لأن الوثائق الكاملة تفصل المسارات والمعلمات والحقول المقبولة، نوصي بالرجوع إلى المرجع الرسمي لواجهة برمجة التطبيقات قبل الترميز.
مثال على المصادقة (طلب اختبار)
للتحقق من أن مفاتيحك تعمل، يمكنك استدعاء نقطة النهاية GET /api/v1/me، التي تُرجع بيانات الحساب. نمط المصادقة هو نفسه المستخدم في جميع نقاط النهاية الأخرى:
curl https://app.papo.global/api/v1/me \
-H "Authorization: Bearer sk_live_…" \
-H "X-Papo-Public-Key: pk_live_…"
تتضمن الاستجابة الناجحة success: true والكائن data مع معلومات الحساب. من هناك، ما عليك سوى استبدال نقطة النهاية وطريقة HTTP وفقًا للعملية المطلوبة مع جهات الاتصال.
إنشاء وتحديث جهات الاتصال بشكل جماعي
على الرغم من أن API تعالج جهة اتصال واحدة لكل طلب، يتم تحقيق العملية الجماعية عن طريق تنفيذ استدعاءات متعددة بالتسلسل. يمكن لنص برمجي بلغة Python أو Node.js أو أتمتة في n8n:
- قراءة قائمة جهات الاتصال من ملف CSV أو قاعدة بيانات أو ERP.
- لكل سجل، تجميع حمولة JSON بالحقول المطلوبة.
- إرسال الطلب إلى نقطة نهاية الإنشاء (إذا لم تكن جهة الاتصال موجودة) أو التحديث (باستخدام معرف جهة الاتصال).
- جمع الردود ومعالجة الأخطاء المحتملة (بريد إلكتروني مكرر، حقل غير صالح، إلخ).
نظرًا لأن API هي REST وتستخدم JSON، فإن أي لغة تدعم HTTP تعمل. توفر Papo أيضًا أمثلة بلغات JavaScript و Python في صفحة الوثائق، والتي يمكن تكييفها مع نقاط نهاية جهات الاتصال.
المشغلات التلقائية بعد الإنشاء
كلما تم إنشاء جهة اتصال جديدة عبر API، يتم تشغيل نفس الأحداث الداخلية لنظام CRM. إذا كان لديك Flow مُهيأ بمشغل "جهة اتصال تم إنشاؤها"، فسيتم تنفيذ الأتمتة تلقائيًا — على سبيل المثال، إرسال رسالة ترحيب عبر WhatsApp أو إخطار فريق المبيعات. هذا يعني أن التكامل عبر API لا يملأ القاعدة فحسب، بل ينشط أيضًا تدفقات الاتصال الموجودة بالفعل في الحساب.
لمن هذا التكامل مناسب
- الشركات التي تنتقل من CRM آخر أو جدول بيانات وتحتاج إلى استيراد آلاف جهات الاتصال دفعة واحدة، مع الحفاظ على قاعدة Papo متزامنة.
- العمليات التي تجمع العملاء المحتملين في أنظمة خارجية (صفحات الهبوط، أنظمة ERP، التجارة الإلكترونية) وترغب في دخولهم تلقائيًا إلى CRM الخاص بـ Papo، جاهزين لتلقي الدعم أو الحملات.
- فرق تكنولوجيا المعلومات التي تبني تكاملات مخصصة بين Papo والأدوات الداخلية، باستخدام API كجسر للحفاظ على بيانات العملاء محدثة دائمًا.
- الموزعون بعلامة بيضاء الذين يديرون حسابات متعددة ويرغبون في أتمتة إنشاء جهات الاتصال على نطاق واسع لعملائهم.
الأسئلة الشائعة
هل أحتاج إلى مفتاح سري لإنشاء أو تحديث جهات الاتصال؟
نعم. تتطلب جميع عمليات الكتابة (الإنشاء، التحديث) المصادقة باستخدام المفتاح السري للحساب. المفتاح العام وحده لا يصرح بالتعديلات.
هل يمكنني إرسال آلاف جهات الاتصال دفعة واحدة؟
تعالج API جهة اتصال واحدة لكل طلب. بالنسبة للأحجام الكبيرة، يجب عليك أتمتة الإرسال المتسلسل، مع مراعاة حدود المعدل الموضحة في الوثائق الرسمية.
هل تؤدي جهات الاتصال التي تم إنشاؤها عبر API إلى تشغيل Flow "جهة اتصال تم إنشاؤها"؟
نعم. حدث الإنشاء هو نفسه، بغض النظر عن المصدر. إذا كان هناك Flow نشط بهذا المشغل، فسيتم تنفيذه لكل جهة اتصال يتم إدراجها عبر API.
كيف أعرف ما إذا كانت جهة الاتصال موجودة بالفعل لتجنب التكرار؟
يمكنك استخدام نقاط نهاية البحث (التصفية حسب البريد الإلكتروني أو الهاتف) قبل الإنشاء. توضح وثائق API معلمات الاستعلام المتاحة.
هل تسمح API بتحديث بعض حقول جهة الاتصال فقط؟
نعم. في نص طلب التحديث، أرسل فقط الحقول التي تريد تعديلها. تظل الحقول الأخرى دون تغيير.
أين أجد القائمة الكاملة لنقاط النهاية والمعلمات؟
المرجع الكامل متاح في صفحة وثائق API. هناك تجد المسارات والطرق والحمولات والأمثلة المحدثة.
اقرأ أيضًا
- كيفية تشغيل Flow تلقائيًا عند إنشاء جهة اتصال جديدة في CRM
- كيفية تصدير جهات الاتصال المستخرجة في Extrator إلى CSV واستيرادها في CRM الخاص بـ Papo
ابدأ مجانًا ودمج CRM الخاص بك مع Papo عبر API → مع المستخدم الأول المجاني، يمكنك بالفعل إنشاء مفاتيح API الخاصة بك واختبار إنشاء جهات الاتصال بشكل جماعي دون تكلفة أولية.