upstream-twenty/packages/twenty-docs/l/ru/user-guide/data-migration/how-tos/prepare-your-csv-files.mdx

---
title: Подготовить файлы CSV
description: Полное пошаговое руководство по форматированию ваших данных для импорта в Twenty.
---

## Обзор

Это руководство проведет вас через подготовку файла CSV для успешного импорта. Следуйте этим шагам, чтобы избежать ошибок.

## Шаг 1: Проверьте требования к файлу

Прежде чем начать, убедитесь, что ваш файл соответствует этим требованиям:

| Требование              | Подробности              |
| ----------------------- | ------------------------ |
| **Формат**              | CSV, XLSX или XLS        |
| **Ограничение размера** | 10 000 записей на файл   |
| **Кодировка**           | Рекомендуется UTF-8      |
| **Структура**           | Один тип объекта на файл |

<Note>Для наборов данных более 10 000 записей разделите их на несколько файлов или используйте [импорт через API](/l/ru/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. Отсортируйте таблицу по уникальному полю (email или домен)
2. Удалите или объедините дублирующиеся строки
3. Проверьте наличие дубликатов, которые уже существуют в Twenty

<Warning>**Записи, помеченные как удалённые, учитываются при проверке уникальности.** Записи в Командном меню → Просмотреть удалённые записи вызовут ошибки из‑за дубликатов. Удалите их окончательно или восстановите и обновите.</Warning>

## Шаг 4: Правильно отформатируйте каждый тип поля

Разные типы полей требуют специфического формата. Полная справка:

### Текстовые поля

* Специальное форматирование не требуется
* Начальные и конечные пробелы автоматически удаляются

### Поля электронной почты

* Должны быть в корректном формате email: `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. Скопируйте имя API (например, `OPTION_1`, а не "Option 1")

<Note>Новые варианты списка не создаются автоматически. Добавьте их в **Настройки → Модель данных** перед импортом.</Note>

### Поля множественного выбора

Используйте имена API в формате массива:

```
["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
* Используйте формат URL домена (`https://domain.com`), а не метку
* Сопоставляйте только ОДИН уникальный идентификатор (не указывайте одновременно `companyId` И `companyDomain`)
* Для участников рабочей области используйте их email (а не имя)

<Warning>
**Порядок импорта имеет значение!**

Сначала импортируйте сторону «один», затем сторону «многие»:
1. Сначала — **Компании**
2. Затем — **Контакты** (со ссылкой на компанию)
3. Третьими — **Возможности**

Родительская запись должна существовать до того, как вы сможете на неё сослаться.
</Warning>

См. [как импортировать связи](/l/ru/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>Нет повторяющихся email-адресов (для контактов) или доменов (для компаний)</Check>
<Check>Даты используют единый формат по всему файлу</Check>
<Check>Домены в формате `https://domain.com`</Check>
<Check>Булевы поля используют `TRUE` или `FALSE` (в верхнем регистре)</Check>
<Check>Поля выбора используют имена API, а не отображаемые метки</Check>
<Check>Все пользовательские поля существуют в Настройках → Модели данных</Check>
<Check>Родительские записи импортированы до дочерних</Check>
<Check>Столбцы связей ссылаются на существующие записи</Check>

## Распространённые ошибки, которых следует избегать

| Ошибка                                               | Решение                                            |
| ---------------------------------------------------- | -------------------------------------------------- |
| Использование `true` вместо `TRUE`                   | Логические значения должны быть в верхнем регистре |
| Использование отображаемых меток для полей выбора    | Найдите и используйте имена API в Настройках       |
| Импорт контактов раньше компаний                     | Всегда импортируйте сначала родительские объекты   |
| Отсутствует код валюты для валютных полей            | Заполните столбцы «Сумма» и «Валюта»               |
| Неверный формат домена                               | Последовательно используйте `https://domain.com`   |
| Сопоставление нескольких уникальных полей для связей | Сопоставляйте только ОДИН (домен ИЛИ id, не оба)   |

## Следующие шаги

Ваш файл готов! Теперь:

* [Импорт компаний](/l/ru/user-guide/data-migration/how-tos/import-companies-via-csv) (сначала импортируйте их)
* [Импорт контактов](/l/ru/user-guide/data-migration/how-tos/import-contacts-via-csv)
* [Исправьте ошибки импорта](/l/ru/user-guide/data-migration/how-tos/fix-import-errors)