ربط التطبيقات بواجهة API
أنشئ مفاتيح API وامنح الإذن لتطبيقات مثل Zapier وتحكم فيما يمكنها الوصول إليه.
للمستخدمين المتقدمين
تغطي هذه الصفحة الجانب الموجه للمطورين في ITB: مفاتيح API واتصالات تطبيقات OAuth. إذا كنت تريد فقط دفع البيانات إلى أدوات أخرى عند حدوث الأشياء، فراجع الويب هوكس أولًا.
هناك طريقتان يمكن بهما لتطبيق خارجي الوصول إلى حسابك عبر واجهة برمجة تطبيقات Go Toolbelt الخارجية:
- مفاتيح API — تنشئ مفتاحًا وتلصقه في سكربتك الخاص أو في أداة تطلبه. الأفضل للتكاملات من خادم إلى خادم والبرمجيات المخصصة.
- OAuth — تطبيقات مثل Zapier ترسلك إلى شاشة موافقة ITB حيث توافق على الوصول بنقرة واحدة. لا حاجة للتعامل مع المفاتيح.
قبل أن تبدأ
- توجد مفاتيح API والويب هوكس في الإعداداتالتكاملات.
- يعمل مفتاح API على بيانات حسابك أنت. ويمنح فقط الأذونات التي تختارها عند إنشائه، وجميع الأذونات تقريبًا للقراءة فقط (الاستثناء هو إدارة الويب هوكس).
- يمكنك امتلاك ما يصل إلى 10 مفاتيح API نشطة في وقت واحد.
إنشاء مفتاح API
افتح بطاقة مفاتيح API
اذهب إلى الإعداداتالتكاملات. بطاقة مفاتيح API في الأعلى.
سمِّ المفتاح واختر الأذونات
انقر على إنشاء مفتاح API. أعطِ المفتاح اسمًا يخبرك بالغرض منه (مثل "تكامل Zapier")، ثم علّم الأذونات التي يحتاجها. الطلبات (قراءة) وجهات الاتصال (قراءة) محددتان مسبقًا؛ راجع جدول الأذونات أدناه للقائمة الكاملة.
انسخ المفتاح
انقر على إنشاء المفتاح. يظهر مفتاحك الجديد مرة واحدة — انسخه بزر النسخ واحفظه في مكان آمن.
انسخ مفتاحك الآن
يُعرض المفتاح مرة واحدة فقط. إذا فقدته، فألغِه وأنشئ واحدًا جديدًا — لا توجد طريقة لعرضه مرة أخرى.
ما الذي يجب أن تراه
يظهر المفتاح الجديد في قائمة مفاتيح API مع اسمه وشارات أذوناته وتاريخ إنشائه. وبمجرد أن يبدأ تطبيق باستخدامه، يظهر أيضًا تاريخ آخر استخدام.
إذا كنت أنت المطور: أرسل المفتاح في الترويسة X-API-Key مع الطلبات إلى https://api.gotoolbelt.com/v1/.... توجد وثائق تفاعلية لنقاط النهاية على api.gotoolbelt.com/docs (مرتبطة أيضًا من بطاقة مفاتيح API).
إلغاء مفتاح API
ابحث عن المفتاح في قائمة مفاتيح API وانقر على زر سلة المهملات بجواره.
أكّد بـ إلغاء. تتوقف أي تكاملات تستخدم هذا المفتاح عن العمل فورًا.
منح الإذن لتطبيق عبر OAuth
بعض التطبيقات (Zapier وMake وشركاء مسجلون آخرون) تتصل عبر OAuth بدلًا من مفتاح API. من جهتك، يبدو التدفق هكذا:
في التطبيق الخارجي، اختر ربط حساب ITB / Go Toolbelt الخاص بك. يرسلك التطبيق إلى شاشة موافقة ITB (سيُطلب منك تسجيل الدخول أولًا إن لم تكن مسجلًا بالفعل).
تعرض شاشة الموافقة اسم التطبيق والحساب الذي سجّلت الدخول به وبالضبط ما الذي سيتمكن التطبيق من فعله — مثلًا "عرض Orders وتفاصيل الطلبات الخاصة بك".
انقر على السماح بالوصول للموافقة، أو رفض للإلغاء. في الحالتين تعود إلى التطبيق.
لا يمكن لتطبيق أبدًا أن يحصل على أكثر من الأذونات التي سُجّل بها — وهي القائمة نفسها في جدول الأذونات أدناه.
لا يمكنك تسجيل تطبيق OAuth خاص بك
تطبيقات OAuth يسجلها فريق ITB، وليس من إعدادات حسابك. إذا كنت تبني تكاملًا مخصصًا لنفسك، فاستخدم مفتاح API بدلًا من ذلك.
ربط Zapier أو Make
يتصل Zapier وMake عبر تدفق OAuth أعلاه — ابحث عن تطبيق ITB / Go Toolbelt في دليل تطبيقاتهما وانقر على "connect". عند إعداد مشغّل Zap، ينشئ Zapier تلقائيًا اشتراك الويب هوك المطابق على حسابك، فلا يوجد شيء تضبطه بنفسك تحت الويب هوكس.
مشغّلات Zapier المتاحة: إنشاء Order واعتماده وإكماله وإعادة جدولته وتغيير حالته، بالإضافة إلى دفع فاتورة ونشر Report. الحمولات الدقيقة موثقة في مرجع أحداث الويب هوك.
مرجع الأذونات
هذه هي الأذونات (النطاقات) التي يمكن أن يحملها مفتاح API أو تطبيق OAuth:
| الإذن | النطاق | ما الذي يسمح به |
|---|---|---|
| الطلبات (قراءة) | orders:read | عرض Orders وتفاصيلها |
| جهات الاتصال (قراءة) | contacts:read | عرض جهات الاتصال |
| الفواتير والفوترة (قراءة) | billing:read | عرض الفواتير والمعاملات |
| التقويم (قراءة) | calendar:read | عرض أحداث التقويم والتوفر |
| القوالب (قراءة) | templates:read | عرض قوالب Report |
| ملف الشركة (قراءة) | company:read | عرض ملف شركتك |
| أعضاء الفريق (قراءة) | team:read | عرض أعضاء الفريق |
| الإشعارات (قراءة) | notifications:read | عرض إعدادات الإشعارات |
| الويب هوك (قراءة) | webhooks:read | عرض إعدادات نقاط نهاية الويب هوك |
| الويب هوك (إدارة) | webhooks:write | إنشاء نقاط نهاية الويب هوك وتحديثها وحذفها |
كل الأذونات باستثناء الويب هوك (إدارة) للقراءة فقط — لا يمكن لمفتاح أو تطبيق متصل أبدًا إنشاء Orders أو جهات الاتصال أو الفواتير الخاصة بك أو تغييرها أو حذفها عبر واجهة API.
إذا حدث خطأ ما
- توقف تكامل فجأة عن العمل — تحقق مما إذا كان مفتاح API الخاص به قد أُلغي (الإلغاء فوري)، ومن أن المفتاح يحمل كل إذن يحتاجه التكامل. الطلب الذي ينقصه إذن يُرفض بخطأ "missing required scope".
- أخطاء "Invalid API key" — كُتب المفتاح خطأ أو أُلغي. لا يمكن عرض المفاتيح مرة أخرى بعد الإنشاء؛ أنشئ واحدًا جديدًا.
- زر إنشاء المفتاح لا يفعل شيئًا — تحتاج إلى اسم وإذن واحد على الأقل معلّم؛ وقد تكون أيضًا عند حد الـ10 مفاتيح (ألغِ مفتاحًا قديمًا أولًا).
مواضيع ذات صلة
- أحداث الويب هوك — كل حدث وحمولة ترسلها واجهة API
- الويب هوكس — استقبل بيانات الأحداث في الوقت الفعلي على نقطة النهاية الخاصة بك
- التكاملات — كل ما في تبويب التكاملات