تم تصميم Twenty ليكون صديقًا للمطورين، حيث يوفر واجهات برمجة قوية تتكيف مع نموذج البيانات المخصص. نحن نوفر أربعة أنواع متميزة من واجهات برمجة التطبيقات لتلبية احتياجات التكامل المختلفة.
النموذج الأول للمطورين
تقوم Twenty بإنشاء واجهات برمجة التطبيقات خصيصاً لنموذج بياناتك:
- لا حاجة إلى معرفات طويلة: استخدم أسماء الكائنات والحقول مباشرة في نقاط النهاية
- معالجة متساوية للأشياء القياسية والمخصصة: تحصل أشياؤك المخصصة على نفس معاملة واجهة برمجة التطبيقات كما هو الحال مع الأشياء المضمنة
- نقاط نهاية مخصصة: يحصل كل كائن وحقل على نقطة نهاية API الخاصة به
- وثائق مخصصة: يتم إنشاؤها خصيصًا لنموذج بيانات مساحة عملك
وثائق واجهة برمجة التطبيقات المخصصة لك متاحة ضمن الإعدادات → API & Webhooks بعد إنشاء مفتاح API. نظرًا لأن Twenty تُنشئ واجهات برمجة تطبيقات تتطابق مع نموذج البيانات المخصص لديك، فإن الوثائق فريدة لمساحة عملك.
نوعا واجهات برمجة التطبيقات
واجهة برمجة التطبيقات الأساسية
يتم الوصول إليها عبر /rest/ أو /graphql/
تعامَل مع السجلات الفعلية لديك (البيانات):
- إنشاء وقراءة وتحديث وحذف الأشخاص والشركات والفرص، إلخ.
- استعلام وتصفية البيانات
- إدارة العلاقات بين السجلات
واجهة برمجة البيانات الوصفية
يتم الوصول إليها عبر /rest/metadata/ أو /metadata/
إدارة مساحة العمل ونموذج البيانات لديك:
- إنشاء أو تعديل أو حذف الكائنات والحقول
- تكوين إعدادات مساحة العمل
- تعريف العلاقات بين الكائنات
REST مقابل GraphQL
تتوفر واجهات برمجة التطبيقات الأساسية وواجهات البيانات الوصفية بصيغتي REST وGraphQL:
| التنسيق | العمليات المتاحة |
|---|
| REST | CRUD، عمليات الدفعات، إدراج/تحديث |
| GraphQL | نفس الشيء + عمليات إدراج/تحديث مجمعة، واستعلامات العلاقات في استدعاء واحد |
نقاط نهاية API
| البيئة | عنوان URL الأساسي |
|---|
| السحابة | https://api.twenty.com/ |
| الاستضافة الذاتية | https://{your-domain}/ |
المصادقة
كل طلب API يتطلب تضمين مفتاح API في رأس الطلب:
Authorization: Bearer YOUR_API_KEY
قم بإنشاء مفتاح API
- انتقل إلى الإعدادات → APIs & Webhooks
- انقر على + إنشاء مفتاح
- التكوين:
- الاسم: اسم وصفي للمفتاح
- تاريخ الانتهاء: متى تنتهي صلاحية المفتاح
- انقر على حفظ
- انسخه فوراً — يظهر المفتاح مرة واحدة فقط
يمنح مفتاح API الخاص بك الوصول إلى بيانات حساسة. لا تشاركه مع خدمات غير موثوقة. إذا تم اختراقه، عطّلْه فوراً وأنشئ مفتاحاً جديداً.
تعيين دور لمفتاح API
لتحسين الأمان، عيّن دوراً محدداً لتقييد الوصول:
- اذهب إلى الإعدادات → الأدوار
- انقر على الدور الذي ترغب في تعيينه
- افتح علامة التبويب التعيين
- ضمن مفاتيح API، انقر على + تعيين إلى مفتاح API
- حدد مفتاح API
سيرث المفتاح أذونات ذلك الدور. راجع الأذونات للحصول على التفاصيل.
إدارة مفاتيح API
إعادة التوليد: الإعدادات → APIs & Webhooks → انقر على المفتاح → إعادة التوليد
حذف: الإعدادات → APIs & Webhooks → انقر على المفتاح → حذف
ملعب واجهة برمجة التطبيقات
اختبر واجهات برمجة التطبيقات لديك مباشرة في المتصفح باستخدام الملعب المدمج لدينا — متاح لكلٍ من REST وGraphQL.
الوصول إلى الملعب
- انتقل إلى الإعدادات → APIs & Webhooks
- أنشئ مفتاح API (مطلوب)
- انقر على REST API أو GraphQL API لفتح الملعب
ما الذي ستحصل عليه
- وثائق تفاعلية: يتم إنشاؤها لنموذج البيانات المحدد لديك
- اختبارات حيّة: تنفيذ استدعاءات API فعلية على مساحة عملك
- مستكشف المخطط: تصفح الكائنات والحقول والعلاقات المتاحة
- منشئ الطلبات: أنشئ الاستعلامات مع الإكمال التلقائي
يعكس الملعب الكائنات والحقول المخصصة لديك، لذا تكون الوثائق دائماً دقيقة لمساحة عملك.
عمليات المجموعة
كلٌ من REST وGraphQL يدعمان عمليات الدفعات:
- حجم المجموعة: حتى 60 سجل لكل طلب
- العمليات: إنشاء وتحديث وحذف سجلات متعددة
ميزات خاصة بـ GraphQL:
- إدراج/تحديث دفعي: إنشاء أو تحديث في استدعاء واحد
- استخدم الأسماء الجمع للكائنات (على سبيل المثال،
CreateCompanies بدلاً من CreateCompany)
حدود المعدل
يتم تنظيم طلبات API لضمان استقرار المنصة:
| الحد | القيمة |
|---|
| الطلبات | 100 استدعاء في الدقيقة |
| حجم الدفعة | 60 سجل لكل استدعاء |
استخدم عمليات الدفعات لزيادة الإنتاجية — عالج ما يصل إلى 60 سجلًا في استدعاء API واحد بدلاً من إجراء طلبات فردية.
