لبدء استخدام واجهة برمجة تطبيقات Papo Global (https://papo.global/)، تحتاج إلى إنشاء مفتاح سري في لوحة التحكم، ومصادقة الطلبات باستخدام ترويسة Authorization، وإجراء استدعاءات REST إلى القاعدة https://app.papo.global/api/v1. أول اختبار عملي هو سرد جهات اتصال Extrator بأمر cURL بسيط.
واجهة Papo هي REST، وتستخدم JSON، وتقبل الطلبات من أي أصل (CORS مفتوح). بها تربط أنظمة CRM، ومنصات الأتمتة (مثل n8n)، وأنظمة ERP، أو الواجهة الخلفية الخاصة بك بمنظومة الدعم والمبيعات والذكاء الاصطناعي في Papo.
ملخص العناصر الأساسية
| العنصر | الوصف |
|---|---|
المفتاح العام (pk_live_…) |
معرّف ثابت لحسابك، يمكن كشفه في الواجهة الأمامية |
المفتاح السري (sk_live_…) |
رمز مصادقة، يجب الحفاظ عليه سرًا واستخدامه على الخادم فقط |
| المصادقة | ترويسة Authorization: Bearer sk_live_... (أو X-Papo-Secret-Key) في جميع الاستدعاءات عدا GET /api/v1 |
| عنوان URL الأساسي | https://app.papo.global/api/v1 |
| نقطة نهاية مثال | GET /api/v1/contacts — تسرد جهات الاتصال المستخرجة (Extrator)، مع ترقيم الصفحات |
خطوات أول استدعاء
1. أنشئ مفاتيح API الخاصة بك
انتقل إلى صفحة المطورين في لوحة Papo (متاحة على app.papo.global/developers). هناك يمكنك إنشاء مفتاح سري مُسمّى — على سبيل المثال، “primeiro-teste” — ونسخه فورًا. يُعرض المفتاح مرة واحدة فقط؛ بعد ذلك يمكنك فقط إلغاؤه وإنشاء آخر.
المفتاح العام (pk_live_…) ثابت لكل حساب ويظل مرئيًا في الصفحة نفسها في أي وقت. ورغم أنه اختياري في الطلبات، إذا أرسلته، فيجب أن يكون مرتبطًا بالحساب نفسه الخاص بالمفتاح السري.
2. اختر نقطة النهاية
في هذا الدليل، سنستخدم GET /api/v1/contacts، الذي يسرد العملاء المحتملين المستخرجين بواسطة وحدة Extrator. يمكنك ترقيم النتائج باستخدام المعاملين page (الافتراضي 1) وper_page (من 1 إلى 100، الافتراضي 20). كما يُقبل استعلام نصي باستخدام q للبحث حسب الشركة أو الهاتف أو البريد الإلكتروني.
3. نفّذ الاستدعاء باستخدام cURL
مع وجود المفتاح السري بحوزتك، جهّز الطلب. المثال التالي يسرد حتى 20 جهة اتصال:
curl "https://app.papo.global/api/v1/contacts?page=1&per_page=20" \
-H "Authorization: Bearer sk_live_…"
استبدل sk_live_… بمفتاحك السري. إذا أردت استخدام الترويسة البديلة، فافعل:
curl "https://app.papo.global/api/v1/contacts" \
-H "X-Papo-Secret-Key: sk_live_…"
الاستجابة هي JSON تتضمن success: true والبيانات داخل الكائن data. إذا حدث خطأ، فسيحتوي JSON على success: false وكائن error يتضمن رمزًا ورسالة توضيحية.
من هنا، يمكنك استكشاف نقاط نهاية أخرى موثّقة في صفحة API، مثل إرسال الرسائل (POST /api/v1/messages)، وتفاصيل الحساب (GET /api/v1/me)، أو إكمال النصوص بالذكاء الاصطناعي (POST /api/ai/v1/complete).
لمن هذا الدليل
هذا المحتوى موجّه للمطورين الذين يرغبون في دمج Papo مع أنظمة خارجية — أنظمة CRM، وأدوات الأتمتة (n8n، على سبيل المثال)، أو تطبيقات خاصة. إذا كنت مستخدمًا نهائيًا يريد فقط ربط القنوات وتقديم الدعم، فإن مركز المساعدة يوفّر مقالات أخرى أكثر ملاءمة.
الأسئلة الشائعة
هل أحتاج إلى إرسال المفتاح العام في كل الاستدعاءات؟
لا. المفتاح العام اختياري. إذا اخترت إرساله، فيجب أن يتوافق مع حساب المفتاح السري المستخدم.
هل ينتهي صلاحية المفتاح السري؟
لا تنتهي صلاحيته تلقائيًا. يمكنك إلغاؤه في أي وقت من لوحة التحكم وإنشاء مفتاح جديد إذا اشتبهت في تسريبه.
هل يمكنني اختبار API بحساب مجاني؟
نعم. أول مستخدم في Papo مجاني ويمكنك إنشاء مفاتيح لاستكشاف API. قد تستهلك عمليات الوصول إلى وحدات مثل Extrator رصيدًا حسب الاستخدام، لكن إنشاء المفاتيح والاستدعاءات الأساسية للقراءة قابلان للاختبار دون تكلفة إضافية.
ماذا أفعل إذا فقدت المفتاح السري؟
أنشئ مفتاحًا مُسمّى جديدًا في لوحة المطورين. لن يكون بالإمكان استرداد المفتاح السابق؛ فقط إلغاؤه لأغراض الأمان.
هل يمكنني استخدام API لإرسال رسائل جماعية؟
نعم، نقطة النهاية POST /api/v1/messages تتيح إرسال رسائل نصية. ومع ذلك، احترم سياسات الموافقة وشروط استخدام المنصة.
هل تسرد API جهات اتصال Extrator فقط؟
نقطة النهاية GET /api/v1/contacts تعيد جهات الاتصال المستخرجة. لإدارة قاعدة CRM الموحّدة (البحث عن أي جهة اتصال وإنشاؤها وتحديثها)، يمكنك الرجوع إلى التوثيق الكامل لـ API.
اقرأ أيضًا: كيفية استخدام API Papo لإنشاء نموذج تسجيل وتعبئة CRM تلقائيًا · كيفية استخدام API Papo لمراقبة استهلاك الأرصدة وفواتير إعادة البيع بالعلامة البيضاء
أول مستخدم R$ 0، بدون بطاقة. اعرف المزيد على papo.global.