لإنشاء وتحديث الصفقات في كانبان برمجيًا، استخدم واجهة Papo REST API. من خلال المصادقة بالمفتاح السري (رمز Bearer) والمفتاح العام للحساب، يمكنك إرسال طلبات تنشئ بطاقات، وتنقل الفرص بين المراحل، وتحدد النتائج، مما يدمج مسار المبيعات مع أنظمة خارجية دون تدخل يدوي.
تعرض واجهة Papo API عمليات كتابة لكانبان، مما يتيح العمل مع مسارات CRM ومراحلها وبطاقاتها. وهذا يجعل من الممكن مزامنة نظام ERP أو صفحة هبوط أو أداة دفع مع مسار المبيعات، مع إبقاء الفرص محدثة دائمًا.
ملخص التكامل مع كانبان
| المرحلة | الإجراء | تفصيل مهم |
|---|---|---|
| 1. الحصول على المفاتيح | إنشاء المفتاح السري (sk_live_…) ونسخ المفتاح العام (pk_live_…) في لوحة Papo. |
يظهر المفتاح السري مرة واحدة فقط؛ احفظه في مكان آمن. |
| 2. مصادقة الطلبات | تضمين الترويسة Authorization: Bearer sk_live_… في جميع طلبات الكتابة. |
يمكن إرسال المفتاح العام في الترويسة X-Papo-Public-Key (اختياري). |
| 3. معرفة المسارات والمراحل | سرد مسارات كانبان ومراحلها للحصول على المعرّفات اللازمة. | تُرجع استجابة API المعرّفات المستخدمة في الطلبات التالية. |
| 4. إنشاء البطاقات أو نقلها | إرسال العملية لإنشاء بطاقة في مرحلة، أو نقل بطاقة جهة اتصال إلى مرحلة أخرى، أو تمييز النتيجة. | كل عملية تعالج إجراءً واحدًا؛ لسجلات كثيرة، أتمت الإرسال في حلقة. |
| 5. التحقق من الاستجابة | تُرجع API success: true وبيانات البطاقة أو القائمة. |
في حال الخطأ، يحتوي جسم الاستجابة على رمز ورسالة للتصحيح. |
ما الذي تتيحه API في كانبان
باستخدام نقاط نهاية كانبان، يمكنك برمجيًا:
- سرد المسارات المتاحة ومراحلها، مع الاسم والموضع.
- سرد بطاقات CRM.
- سرد جميع البطاقات المكتسبة، لتقارير المبيعات المغلقة.
- إنشاء بطاقة في مرحلة، وربطها اختياريًا بجهة اتصال موجودة.
- نقل بطاقة جهة اتصال إلى مرحلة أخرى في المسار.
- تمييز البطاقات كمكاسب أو كخسائر.
- إنشاء مسار كانبان بمراحل افتراضية أو مخصصة.
تتيح هذه العمليات أن يعكس المسار تلقائيًا ما يحدث خارج Papo، مثل عملية شراء مؤكدة، أو اجتماع مجدول، أو تسجيل قادم من الموقع.
كيف تعمل المصادقة والطلبات
كل طلب يعدّل البيانات يتطلب المفتاح السري للحساب. يجب إرساله كرمز Bearer في الترويسة Authorization أو، بدلًا من ذلك، في الترويسة X-Papo-Secret-Key. يمكن أن يرافق المفتاح العام الطلب في الترويسة X-Papo-Public-Key؛ استخدامه اختياري، لكن إذا أُرسل، يجب أن يطابق نفس حساب المفتاح السري.
عنوان URL الأساسي لواجهة API هو https://app.papo.global/api/v1. انطلاقًا منه، تقبل نقاط نهاية كانبان أفعال HTTP المناسبة للإنشاء والنقل والتحديث والسرد. وبما أن الوثائق الكاملة تفصّل المسارات والمعاملات والحقول المقبولة، نوصي بالرجوع إلى مرجع API الرسمي قبل البرمجة.
للتحقق من أن مفاتيحك تعمل، يمكنك استدعاء نقطة النهاية 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 مع معلومات الحساب.
تدفق نموذجي للتكامل مع الأنظمة الخارجية
يمكن لنص برمجي بلغة Python أو Node.js أو أتمتة في أدوات مثل n8n تنفيذ دورة المسار الكاملة:
- سرد المسارات والمراحل للحصول على معرّفات كل عمود.
- إنشاء بطاقة في المرحلة الأولية، مع ربطها بجهة اتصال إذا لزم الأمر.
- نقل البطاقة إلى مرحلة جديدة عند وقوع حدث خارجي — مثل تأكيد الدفع أو تحديد موعد اجتماع.
- تمييز البطاقة كمكسب أو خسارة عند اكتمال الفرصة.
- سرد البطاقات المكتسبة لتغذية التقارير أو لوحات المعلومات أو أنظمة BI.
بما أن API من نوع REST وتستخدم JSON، فإن أي لغة تدعم HTTP تعمل. تفاصيل الحمولة والحقول لكل عملية موجودة في الوثائق الرسمية.
لمن يُنصح بهذا التكامل
- الشركات التي تجمع الفرص في أنظمة خارجية، مثل صفحات الهبوط أو أنظمة ERP أو التجارة الإلكترونية، وترغب في دخولها تلقائيًا إلى مسار Papo.
- العمليات التي تحتاج إلى نقل البطاقات وفقًا لأحداث الدفع، مثل بوابات الدفع أو منصات الفوترة، دون فتح CRM يدويًا.
- فرق BI والبيانات التي تريد سحب البطاقات المكتسبة والقيم إلى لوحات معلومات في الوقت الفعلي.
- فرق تقنية المعلومات التي تبني تكاملات مخصصة بين Papo والأدوات الداخلية، باستخدام API كجسر بين مسار المبيعات وبقية العملية.
الأسئلة الشائعة
هل أحتاج إلى استخدام المفتاح العام في كل الطلبات؟
لا. المفتاح العام اختياري، لكن إذا أُرسل في الترويسة X-Papo-Public-Key، يجب أن يطابق نفس حساب المفتاح السري.
كيف أعرف ما المراحل الموجودة في مساري؟
اسرد مسارات كانبان عبر API. تُرجع الاستجابة مراحل كل مسار مع معرّفاتها، المستخدمة لإنشاء البطاقات أو نقلها.
هل يمكنني إنشاء بطاقة مرتبطة بجهة اتصال؟
نعم. يسمح إنشاء البطاقة بربطها اختياريًا بجهة اتصال موجودة، مع الحفاظ على السجل وبيانات العميل مرتبطة بالفرصة.
هل تتيح API تحديث قيمة بطاقة؟
تعرض API عمليات كتابة لبطاقات كانبان. الحقول الدقيقة التي يمكن تحديثها، بما في ذلك القيم، مفصّلة في الوثائق الرسمية لواجهة API.
هل يمكن تمييز بطاقة كمكسب أو خسارة عبر API؟
نعم. تتيح API تمييز البطاقات كمكاسب وكخسائر، إضافة إلى سرد جميع البطاقات المكتسبة للتقارير ولوحات المعلومات.
هل أحتاج إلى البرمجة أم يمكنني استخدام أدوات الأتمتة؟
يمكنك استخدام أي لغة تدعم HTTP أو أدوات أتمتة مثل n8n، وتنفيذ الطلبات بالتسلسل وفق التدفق المطلوب.
اقرأ أيضًا
- كيفية استخدام API من Papo لإنشاء وتحديث جهات الاتصال بشكل جماعي
- كيفية استقبال أحداث Papo في الوقت الفعلي عبر Webhook (صادر)
المستخدم الأول مجاني ولا يتطلب بطاقة ائتمان.