الانتقال إلى المحتوى الرئيسي

​
نظرة عامة

توفّر Twenty كلًا من GraphQL وواجهات REST API لاستيراد البيانات برمجيًا. استخدم واجهة API عندما لا يكون استيراد CSV عمليًا لحجم بياناتك أو عندما تحتاج إلى عمليات استيراد مؤتمتة ومتكررة.

​
متى تستخدم الاستيراد عبر API

السيناريوالطريقة الموصى بها
أقل من 10,000 سجلاستيراد CSV
10,000 - 50,000 سجلاستيراد CSV (قسّم إلى ملفات)
أكثر من 50,000 سجلاستيراد API
ترحيل لمرة واحدةأيّ منهما (حسب الحجم)
عمليات استيراد متكررةاستيراد API
مزامنة في الوقت الحقيقياستيراد API
التكامل مع الأنظمة الأخرىاستيراد API
بالنسبة لمجموعات البيانات التي تبلغ مئات الآلاف، تكون واجهة API أسرع بكثير وأكثر موثوقية من عمليات استيراد CSV المتعددة.

​
حدود معدل API

تفرض Twenty حدودًا للمعدل لضمان استقرار النظام:
الحدالقيمة
الطلبات في الدقيقة100
السجلات لكل استدعاء دفعي60
الحد الأقصى للإنتاجية~6,000 سجل/دقيقة
خطّط لعملية الاستيراد وفق هذه الحدود.بالنسبة إلى 100,000 سجل عند أقصى إنتاجية، توقّع نحو 17 دقيقة من وقت الاستيراد. أضِف وقتًا احتياطيًا لمعالجة الأخطاء وإعادة المحاولة.

​
البدء

​
الخطوة 1: احصل على مفتاح API الخاص بك

  1. انتقل إلى الإعدادات → المطوّرون
  2. انقر + إنشاء مفتاح API
  3. امنح مفتاحك اسمًا وصفيًا
  4. انسخ مفتاح API فورًا (لن يُعرَض مرة أخرى)
  5. احفظه في مكان آمن
أبقِ مفتاح API سريًا.يمكن لأي شخص لديه مفتاح API الخاص بك الوصول إلى بيانات مساحة العمل الخاصة بك وتعديلها. لا تقم أبدًا بإيداعه في مستودعات الكود أو مشاركته علنًا.

​
الخطوة 2: اختر واجهة API الخاصة بك

تدعم Twenty نوعين من واجهات API:
واجهة برمجة التطبيقاتالأفضل لـالتوثيق
GraphQLاستعلامات مرنة، وجلب البيانات المرتبطة، وعمليات معقّدةوثائق API
RESTعمليات CRUD بسيطة، وأنماط REST مألوفةوثائق API
كلتا واجهتي API تدعمان:
  • إنشاء السجلات وقراءتها وتحديثها وحذفها
  • عمليات الدُفعات — إنشاء أو تحديث ما يصل إلى 60 سجلًا لكل استدعاء
لعمليات الاستيراد، استخدم عمليات الدُفعات لتعظيم الإنتاجية ضمن حدود المعدل.

​
الخطوة 3: خطّط لترتيب الاستيراد

تمامًا مثل عمليات استيراد CSV، فإن الترتيب مهم للعلاقات:
  1. الشركات أولًا (من دون تبعيات)
  2. الأشخاص ثانيًا (يمكن ربطهم بالشركات)
  3. الفرص ثالثًا (يمكن ربطها بالشركات والأشخاص)
  4. المهام/الملاحظات (يمكن ربطها بأي مما سبق)
  5. الكائنات المخصّصة (وفقًا لتبعياتها)

​
أفضل الممارسات

​
اجمع طلباتك في دُفعات

  • لا ترسل السجلات واحدًا تلو الآخر
  • اجمع ما يصل إلى 60 سجلًا لكل استدعاء API
  • هذا يُعظّم الإنتاجية ضمن حدود المعدل

​
التعامل مع حدود المعدل

  • طبّق فواصل زمنية بين الطلبات (600 مللي ثانية كحد أدنى لعمليات الاستيراد المستمرة)
  • استخدم التراجع الأسي عند بلوغ الحدود
  • راقِب الاستجابات 429 (طلبات كثيرة جدًا)

​
تحقّق من البيانات أولًا

  • نظّف بياناتك وتحقّق منها قبل الاستيراد
  • تحقّق من تعبئة الحقول المطلوبة
  • تحقّق من توافق التنسيقات مع متطلبات Twenty (راجع تعيين الحقول)

​
سجّل كل شيء

  • سجّل كل سجل تم استيراده (بما في ذلك المعرّفات)
  • سجّل الأخطاء مع السياق الكامل
  • يساعد ذلك في تصحيح المشكلات والتحقق من الإكمال

​
اختبر أولًا

  • اختبر بدفعة صغيرة (10-20 سجلًا)
  • تحقّق من ظهور البيانات بشكل صحيح في Twenty
  • ثم نفّذ عملية الاستيراد الكاملة

​
استخدم upsert لتجنّب التكرارات

واجهة GraphQL API تدعم upsert على دفعات — حدِّث إذا كان السجل موجودًا، وأنشئ إذا لم يكن كذلك. يمنع هذا التكرارات عند إعادة تشغيل عمليات الاستيراد.

​
العثور على أسماء الكائنات والحقول

للاطلاع على الكائنات والحقول المتاحة:
  1. انتقل إلى الإعدادات → API وخطافات الويب
  2. استعرض واجهة API للبيانات الوصفية
  3. اعرض جميع الكائنات القياسية والمخصّصة مع حقولها
تُظهر الوثائق جميع الكائنات القياسية والمخصّصة وحقولها وأنواع البيانات المتوقعة.

​
الخدمات الاحترافية

بالنسبة لعمليات ترحيل API المعقّدة، يمكن لشركائنا تقديم المساعدة:
الخدمةما الذي يتضمّنه
تصميم نموذج البياناتتصميم الهيكل الأمثل لبياناتك
برامج نصية للترحيلكتابة وتشغيل البرامج النصية للاستيراد
تحويل البياناتالتعامل مع التعيين المعقّد والتنظيف
التحقق وضمان الجودةالتحقق من اكتمال عملية الترحيل
الأفضل لـ:
  • عمليات ترحيل لأكثر من 100,000 سجل
  • تحويلات بيانات معقّدة
  • جداول زمنية ضيّقة
  • الفرق التي تفتقر إلى موارد المطورين
تواصل معنا عبر contact@twenty.com أو استكشف خدمات التنفيذ.

​
الأسئلة الشائعة

يتيح لك GraphQL طلب البيانات التي تحتاجها بدقة ضمن استعلام واحد، وهو أفضل للعمليات المعقّدة. يعتمد REST على طرق HTTP القياسية (GET وPOST وPUT وDELETE)، وقد يكون أكثر ألفة إذا سبق لك العمل مع واجهات API التقليدية.
نعم! استخدم تحديثات mutations في GraphQL أو طلبات PUT/PATCH في REST مع id الخاص بالسجل.
استعلم أولًا عن السجلات الموجودة باستخدام معرّفات فريدة (البريد الإلكتروني، النطاق). حدِّث إذا كان موجودًا، وأنشئ إذا لم يكن كذلك.
نعم، استخدم delete mutations في GraphQL أو طلبات DELETE في REST.
لا يتوفر ذلك في الوقت الحالي، لكن كلتا واجهتي API تعملان مع أي عميل HTTP بأي لغة.

​
وثائق API

للحصول على تفاصيل التنفيذ الكاملة وأمثلة الشيفرة ومرجع المخطط (schema):