---
title: استيراد البيانات عبر واجهة API
description: متى وكيف تستخدم واجهات API الخاصة بـ Twenty لاستيراد البيانات على نطاق واسع.
---

## نظرة عامة

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

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

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

<Note>بالنسبة لمجموعات البيانات التي تبلغ مئات الآلاف، تكون واجهة API أسرع بكثير وأكثر موثوقية من عمليات استيراد CSV المتعددة.</Note>

## حدود معدل API

تفرض Twenty حدودًا للمعدل لضمان استقرار النظام:

| الحد                         | القيمة           |
| ---------------------------- | ---------------- |
| **الطلبات في الدقيقة**       | 100              |
| **السجلات لكل استدعاء دفعي** | 60               |
| **الحد الأقصى للإنتاجية**    | ~6,000 سجل/دقيقة |

<Warning>
  **خطّط لعملية الاستيراد وفق هذه الحدود.**

  بالنسبة إلى 100,000 سجل عند أقصى إنتاجية، توقّع نحو 17 دقيقة من وقت الاستيراد. أضِف وقتًا احتياطيًا لمعالجة الأخطاء وإعادة المحاولة.
</Warning>

## البدء

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

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

<Warning>
  **أبقِ مفتاح API سريًا.**

  يمكن لأي شخص لديه مفتاح API الخاص بك الوصول إلى بيانات مساحة العمل الخاصة بك وتعديلها. لا تقم أبدًا بإيداعه في مستودعات الكود أو مشاركته علنًا.
</Warning>

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

تدعم Twenty نوعين من واجهات API:

| واجهة برمجة التطبيقات | الأفضل لـ                                              | التوثيق                                           |
| --------------------- | ------------------------------------------------------ | ------------------------------------------------- |
| **GraphQL**           | استعلامات مرنة، وجلب البيانات المرتبطة، وعمليات معقّدة | [وثائق API](/l/ar/developers/extend/capabilities/apis) |
| **REST**              | عمليات CRUD بسيطة، وأنماط REST مألوفة                  | [وثائق API](/l/ar/developers/extend/capabilities/apis) |

كلتا واجهتي API تدعمان:

* إنشاء السجلات وقراءتها وتحديثها وحذفها
* **عمليات الدُفعات** — إنشاء أو تحديث ما يصل إلى 60 سجلًا لكل استدعاء

**لعمليات الاستيراد، استخدم عمليات الدُفعات** لتعظيم الإنتاجية ضمن حدود المعدل.

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

تمامًا مثل عمليات استيراد CSV، فإن **الترتيب مهم** للعلاقات:

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

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

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

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

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

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

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

* نظّف بياناتك وتحقّق منها قبل الاستيراد
* تحقّق من تعبئة الحقول المطلوبة
* تحقّق من توافق التنسيقات مع متطلبات Twenty (راجع [تعيين الحقول](/l/ar/user-guide/data-migration/capabilities/field-mapping))

### سجّل كل شيء

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

### اختبر أولًا

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

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

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

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

للاطلاع على الكائنات والحقول المتاحة:

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

تُظهر الوثائق جميع الكائنات القياسية والمخصّصة وحقولها وأنواع البيانات المتوقعة.

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

بالنسبة لعمليات ترحيل API المعقّدة، يمكن لشركائنا تقديم المساعدة:

| الخدمة                   | ما الذي يتضمّنه                       |
| ------------------------ | ------------------------------------- |
| **تصميم نموذج البيانات** | تصميم الهيكل الأمثل لبياناتك          |
| **برامج نصية للترحيل**   | كتابة وتشغيل البرامج النصية للاستيراد |
| **تحويل البيانات**       | التعامل مع التعيين المعقّد والتنظيف   |
| **التحقق وضمان الجودة**  | التحقق من اكتمال عملية الترحيل        |

**الأفضل لـ:**

* عمليات ترحيل لأكثر من 100,000 سجل
* تحويلات بيانات معقّدة
* جداول زمنية ضيّقة
* الفرق التي تفتقر إلى موارد المطورين

تواصل معنا عبر [contact@twenty.com](mailto:contact@twenty.com) أو استكشف [خدمات التنفيذ](/l/ar/user-guide/getting-started/capabilities/implementation-services).

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

<AccordionGroup>
  <Accordion title="ما الفرق بين GraphQL وREST؟">
    يتيح لك GraphQL طلب البيانات التي تحتاجها بدقة ضمن استعلام واحد، وهو أفضل للعمليات المعقّدة. يعتمد REST على طرق HTTP القياسية (GET وPOST وPUT وDELETE)، وقد يكون أكثر ألفة إذا سبق لك العمل مع واجهات API التقليدية.
  </Accordion>

  <Accordion title="هل يمكنني تحديث السجلات الموجودة عبر API؟">
    نعم! استخدم تحديثات mutations في GraphQL أو طلبات PUT/PATCH في REST مع `id` الخاص بالسجل.
  </Accordion>

  <Accordion title="كيف أتعامل مع التكرارات؟">
    استعلم أولًا عن السجلات الموجودة باستخدام معرّفات فريدة (البريد الإلكتروني، النطاق). حدِّث إذا كان موجودًا، وأنشئ إذا لم يكن كذلك.
  </Accordion>

  <Accordion title="هل يمكنني حذف السجلات عبر API؟">
    نعم، استخدم delete mutations في GraphQL أو طلبات DELETE في REST.
  </Accordion>

  <Accordion title="هل يوجد SDK لـ Python أو Node.js؟">
    لا يتوفر ذلك في الوقت الحالي، لكن كلتا واجهتي API تعملان مع أي عميل HTTP بأي لغة.
  </Accordion>
</AccordionGroup>

## وثائق API

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

* [وثائق API](/l/ar/developers/extend/capabilities/apis)
