> ## Documentation Index
> Fetch the complete documentation index at: https://docs.get-clara.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Prepare Your CSV Files

> دليل كامل خطوة بخطوة لتنسيق بياناتك لاستيرادها إلى Twenty.

## نظرة عامة

يرشدك هذا الدليل إلى كيفية إعداد ملف CSV لاستيراد ناجح. اتّبع هذه الخطوات لتجنّب الأخطاء.

## الخطوة 1: التحقّق من متطلبات الملف

قبل البدء، تأكّد من أنّ ملفك يستوفي هذه المتطلبات:

| المتطلب               | تفاصيل                |
| --------------------- | --------------------- |
| **التنسيق**           | CSV، XLSX، أو XLS     |
| **الحد الأقصى للحجم** | 10,000 سجل لكل ملف    |
| **الترميز**           | يوصى باستخدام UTF-8   |
| **البنية**            | نوع كائن واحد لكل ملف |

<Note>بالنسبة لمجموعات البيانات التي تزيد على 10,000 سجل، قم بتقسيمها إلى عدة ملفات أو استخدم [الاستيراد عبر API](/l/ar/user-guide/data-migration/how-tos/import-data-via-api).</Note>

## الخطوة 2: تنزيل الملف النموذجي

**هذه هي أهم خطوة.** يوضّح لك الملف النموذجي أسماء الأعمدة الدقيقة والتنسيق الذي تتوقعه Twenty.

1. انتقل إلى عرض الكائن (الأشخاص، الشركات، إلخ)
2. انقر **⋮** → **استيراد السجلات**
3. انقر **تنزيل الملف النموذجي**
4. استخدم هذا الملف كقالب

<Note>**نصيحة احترافية:** بدلًا من ذلك، صدِّر عددًا قليلًا من السجلات الموجودة. سيوفّر لك هذا أمثلة حقيقية على كيفية تنسيق البيانات، كما ستُطابَق أسماء الأعمدة تلقائيًا أثناء الاستيراد.</Note>

## الخطوة 3: إزالة القيم المكررة

تفرض Twenty التفرّد على حقول معيّنة. ستتسبب القيَم المكررة في أخطاء أثناء الاستيراد.

| كائن             | الحقول الفريدة                        |
| ---------------- | ------------------------------------- |
| **الأشخاص**      | `id`, `email`                         |
| **الشركات**      | `id`, `domain`                        |
| **كائنات مخصصة** | `id`، بالإضافة إلى أي حقل وضعته كفريد |

**قبل الاستيراد:**

1. قم بفرز جدول البيانات حسب الحقل الفريد (البريد الإلكتروني أو النطاق)
2. أزِل الصفوف المكررة أو ادمجها
3. تحقّق من التكرارات الموجودة مسبقًا في Twenty

<Warning>**السجلات المحذوفة مؤقتًا تُحتسب ضمن التفرّد.** السجلات الموجودة في قائمة الأوامر → عرض السجلات المحذوفة ستتسبب في أخطاء تكرار. احذفها نهائيًا أو استعدها وقم بتحديثها.</Warning>

## الخطوة 4: تنسيق كل نوع من الحقول بشكل صحيح

تتطلب أنواع الحقول المختلفة تنسيقات محددة. إليك المرجع الكامل:

### حقول النص

* لا يلزم تنسيق خاص
* تُزال الفراغات في البداية والنهاية تلقائيًا

### حقول البريد الإلكتروني

* يجب أن يكون بتنسيق بريد إلكتروني صالح: `name@domain.com`
* يجب أن تكون فريدة (بدون تكرارات في الملف أو في Twenty)
* للعناوين الإضافية للبريد الإلكتروني، استخدم هذا التنسيق في عمود **Emails / Additional Emails**:

```
[\"jane@twenty.com\",\"jane.doe@twenty.com\"]
```

### حقول النطاق

* **التنسيق الموصى به**: `https://domain.com`
* يتطابق هذا مع التنسيق المستخدم في مزامنة صندوق البريد/التقويم (يمنع التكرارات)
* املأ كلا العمودين:
  * **Domain / Domain Label**: `domain.com`
  * **Domain / Domain URL**: `https://domain.com`
* يجب أن تكون فريدة داخل ملفك وفي Twenty

### حقول الهاتف

الهاتف حقل **متداخل** يتطلب عدة أعمدة:

| العمود                                  | مثال         |
| --------------------------------------- | ------------ |
| **Phones / Primary Phone Number**       | `4159095555` |
| **Phones / Primary Phone Country Code** | `US`         |
| **Phones / Primary Phone Calling Code** | `+1`         |

### حقول العنوان

العنوان هو **حقل متداخل** يحتوي على أعمدة متعددة (يمكن ترك بعضها فارغًا):

* **العنوان / العنوان 1**: السطر الأول لعنوان الشارع
* **العنوان / العنوان 2**: السطر الثاني لعنوان الشارع (اختياري)
* **العنوان / المدينة**: اسم المدينة
* **العنوان / الولاية**: ولاية أو مقاطعة
* **العنوان / البلد**: اسم البلد
* **العنوان / الرمز البريدي**: رمز بريدي/ZIP

### حقول التاريخ

استخدم تنسيقًا موحدًا في كامل ملفك:

* `YYYY-MM-DD` (مُوصى به): `2024-03-15`
* ISO 8601: `2024-03-15T10:30:00Z`

### حقول الأرقام

* أرقام فقط (بدون نص)
* استخدم النقطة للفواصل العشرية: `1234.56`
* بدون فواصل لآلاف الأرقام (ليس `1,234.56`)

### حقول العملة

العملة هي **حقل متداخل** يتطلب عمودين يجب **ملؤهما كليهما**:

| العمود              | مثال      |
| ------------------- | --------- |
| **المبلغ / المبلغ** | `1234.56` |
| **المبلغ / العملة** | `USD`     |

### حقول منطقية

استخدم أحرفًا كبيرة: `TRUE` أو `FALSE`

<Warning>الأحرف الصغيرة `true` أو `false` لن تعمل.</Warning>

### اختر الحقول

استخدم **اسم واجهة برمجة التطبيقات (API)** للخيار، وليس اسم العرض.

**كيفية العثور على أسماء واجهة برمجة التطبيقات (API):**

1. انتقل إلى **الإعدادات → نموذج البيانات**
2. اختر الكائن والحقل
3. فعّل **الوضع المتقدم** (المبدّل في أسفل اليمين)
4. انسخ اسم واجهة برمجة التطبيقات (مثال: `OPTION_1`، وليس "Option 1")

<Note>خيارات الاختيار الجديدة لا يتم إنشاؤها تلقائيًا. أضِفها في **الإعدادات → نموذج البيانات** قبل الاستيراد.</Note>

### حقول متعددة الاختيار

استخدم أسماء واجهة برمجة التطبيقات بصيغة المصفوفة:

```
["VALUE1","VALUE2"]
```

### حقول المصفوفة

استخدم صيغة مصفوفة JSON:

```
["value1","value2"]
```

### حقول التقييم

استخدم الصيغة: `RATING_1` و`RATING_2` و`RATING_3` و`RATING_4` أو `RATING_5`

### حقول الروابط/عناوين URL

املأ كلا العمودين:

* **الروابط / تسمية الرابط**: `Twenty`
* **الروابط / عنوان URL للرابط**: `https://twenty.com`

بالنسبة للروابط الثانوية، استخدم عمود **الروابط / الروابط الثانوية**:

```
[{"url":"https://twenty.com","label":"Twenty"}]
```

### حقول JSON

استخدم تنسيق JSON صالحًا:

```
{"key":"value","key2":"value2"}
```

### حقول المعرّف

* **اختياري**: يقوم Twenty بإنشاء المعرّفات تلقائيًا إذا لم تُوفَّر
* **التنسيق**: UUID (مثلًا: `c776ee49-f608-4a77-8cc8-6fe96ae1e43f`)
* **حالة الاستخدام**: تضمين المعرّف لتحديث السجلات الموجودة بدلًا من إنشاء سجلات جديدة

## الخطوة 5: إضافة أعمدة العلاقات (إذا كنت تربط السجلات)

لربط السجلات بكائنات أخرى (مثل الأشخاص بالشركات)، أضِف عمودًا يحتوي على المعرّف الفريد للسجل المرتبط.

**مثال**: ربط الأشخاص بالشركات

أضِف عمودًا إلى ملف CSV الخاص بالأشخاص:

```
firstName,lastName,email,companyDomain
John,Smith,john@acme.com,https://acme.com
Jane,Doe,jane@widgets.co,https://widgets.co
```

**قواعد مهمة للعلاقات:**

* يجب أن يكون السجل الأب موجودًا مسبقًا في Twenty
* استخدم صيغة **عنوان المجال (Domain URL)** (`https://domain.com`) وليس التسمية
* قم بربط مُعرّف فريد واحد فقط (لا تُدرج كلاً من `companyId` و`companyDomain`)
* بالنسبة لأعضاء مساحة العمل، استخدم **البريد الإلكتروني** الخاص بهم (وليس الاسم)

<Warning>
  **ترتيب الاستيراد مهم!**

  استورد طرف "الواحد" قبل طرف "الكثير":

  1. **الشركات** أولاً
  2. **الأشخاص** ثانيًا (مع مرجع الشركة)
  3. **الفرص** ثالثًا

  يجب أن يوجد السجل الأب قبل أن تتمكن من الإشارة إليه.
</Warning>

اطلع على [كيفية استيراد العلاقات](/l/ar/user-guide/data-migration/how-tos/import-relations-between-objects-via-csv) للحصول على تعليمات مفصلة.

## الخطوة 6: تأكد من وجود الحقول في Twenty

تقوم عملية الاستيراد بإنشاء **سجلات**، وليس **حقولًا**. يجب أن تكون جميع الحقول التي تريد استيرادها موجودة مسبقًا في نموذج البيانات لديك.

**قبل الاستيراد:**

1. انتقل إلى **الإعدادات → نموذج البيانات**
2. اختر الكائن الخاص بك
3. أنشئ أي حقول مخصصة تحتاجها
4. دوّن أسماء الحقول بدقة (يجب أن تتطابق مع عناوين أعمدتك)

## الخطوة 7: قائمة التحقق النهائية

قبل رفع ملفك، تحقّق مما يلي:

<Check>الملف بصيغة CSV أو XLSX أو XLS</Check>
<Check>يحتوي الملف على أقل من 10,000 سجل</Check>
<Check>الترميز UTF-8</Check>
<Check>لا توجد رسائل بريد إلكتروني مكررة (للأشخاص) أو نطاقات (للشركات)</Check>
<Check>التواريخ تستخدم تنسيقًا موحدًا طوال الملف</Check>
<Check>النطاقات تستخدم الصيغة `https://domain.com`</Check>
<Check>الحقول المنطقية تستخدم `TRUE` أو `FALSE` (أحرف كبيرة)</Check>
<Check>حقول الاختيار تستخدم أسماء واجهة برمجة التطبيقات، وليس أسماء العرض</Check>
<Check>جميع الحقول المخصصة موجودة في الإعدادات → نموذج البيانات</Check>
<Check>تم استيراد السجلات الأصلية قبل السجلات الفرعية</Check>
<Check>أعمدة العلاقات تشير إلى سجلات موجودة</Check>

## أخطاء شائعة يجب تجنبها

| الخطأ                              | الحل                                                        |
| ---------------------------------- | ----------------------------------------------------------- |
| استخدام `true` بدلًا من `TRUE`     | يجب أن تكون القيم المنطقية بأحرف كبيرة                      |
| استخدام أسماء العرض لحقول الاختيار | اعثر على أسماء واجهة برمجة التطبيقات في الإعدادات واستخدمها |
| استيراد الأشخاص قبل الشركات        | احرص دائمًا على استيراد الكائنات الأصل أولًا                |
| رمز العملة مفقود لحقول العملة      | املأ عمودي المبلغ والعملة معًا                              |
| تنسيق نطاق غير صحيح                | استخدم `https://domain.com` بصورة متسقة                     |
| ربط عدة حقول فريدة للعلاقات        | اربط حقلًا واحدًا فقط (النطاق أو المعرّف، وليس كليهما)      |

## الخطوات التالية

ملفك جاهز! الآن:

* [استيراد الشركات](/l/ar/user-guide/data-migration/how-tos/import-companies-via-csv) (قم باستيرادها أولًا)
* [استيراد جهات الاتصال](/l/ar/user-guide/data-migration/how-tos/import-contacts-via-csv)
* [إصلاح أي أخطاء في الاستيراد](/l/ar/user-guide/data-migration/how-tos/fix-import-errors)