واجهة برمجة تطبيقات المطورين

تبويب المطورين هو المكان الذي تصدر فيه مفاتيح API للوصول البرمجي إلى Entergram. متاح في خطة Pro (ومقاعد مساحة عمل Pro). للمالكين والمسؤولين فقط.

إنشاء مفتاح

1. “Create API key”
2. سمّه (شيئًا تتعرّف عليه في قائمة الإلغاء لاحقًا)
3. اختر النطاقات - أذونات دقيقة مثل:
   • workspace.read
   • members.read
   • accounts.read
   • contacts.read
   • chats.read / chats.write
   • custom_fields.read / custom_fields.write
4. مدة البقاء الافتراضية هي 90 يومًا؛ يمكنك اختيار مدة أقصر
5. اختياري: قيّده بقائمة من نطاقات IP CIDR
6. انقر Create - يُعرض المفتاح الكامل مرة واحدة. انسخه فورًا؛ لا يعرضه Entergram مجددًا أبدًا.

خلف الكواليس

• تُخزّن المفاتيح كتجزئات أحادية الاتجاه - لا يوجد المفتاح الخام على القرص أبدًا
• يسجّل كل طلب البادئة وعنوان IP ووكيل المستخدم للتدقيق
• الإلغاء فوري
• ترجع المفاتيح منتهية الصلاحية 403 تلقائيًا
• كل استدعاء API محدّد بمساحة العمل - لا يمكن لمفتاح أن يعمل إلا على مساحة العمل التي أصدرته

إدارة المفاتيح

من تبويب المطورين:

• شاهد بادئة كل مفتاح وتاريخ إنشائه ونطاقاته ومدة بقائه ومعلومات آخر استخدام
• انسخ البادئة (وليس السر)
• ألغِ مفتاحًا أو دوّره
• التدوير = أنشئ مفتاحًا جديدًا بنفس النطاقات، ثم ألغِ القديم بمجرد تحويل تكاملك

مثال: تدوير مفتاح مسرّب

1. تدرك أن مهندسًا لصق مفتاحًا في متتبع مشكلات عام
2. تبويب المطورين ← جد المفتاح ← Revoke (يسري المفعول فورًا)
3. أنشئ مفتاحًا جديدًا بنفس النطاقات وقائمة IP المسموح بها
4. انشر المفتاح الجديد في تكاملك
5. تحقق من معلومات آخر استخدام للمفتاح القديم لتأكيد عدم وجود مزيد من حركة المرور

مثال: إصدار مفتاح لمهمة CI

1. تبويب المطورين ← Create API key
2. سمّه ci-deploy-bot
3. النطاقات: فقط workspace.read و chats.read (أقل امتياز)
4. مدة البقاء: 30 يومًا
5. قائمة IP المسموح بها: عناوين IP الصادرة من مزوّد CI
6. انسخ المفتاح واضبطه كسرّ في CI
7. دوّره قبل انتهاء مدة البقاء

تكامل Make.com

تتضمن خطط Pro تكامل Make.com حتى تتمكن من ربط Entergram بأتمتة منخفضة الكود دون كتابة كود API بنفسك. متاح من منطقة تكاملات مساحة العمل.

استجابات API

أخطاء HTTP الشائعة التي ستراها:

• 401 - المفتاح منتهي الصلاحية أو ملغى أو خاطئ لمساحة العمل
• 403 - يفتقر المفتاح إلى النطاق المطلوب، أو الطلب من عنوان IP خارج قائمة السماح
• 429 - وصلت إلى حد المعدل؛ تراجع وأعد المحاولة