snapshot of https://github.com/twentyhq/twenty.git (main, 2026-09-17; blobs > 131072B omitted)

packages/twenty-docs/l/ru/user-guide/data-migration/how-tos/import-data-via-api.mdx

@@ -0,0 +1,176 @@
+---
+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:
+
+| API         | Лучше всего подходит для                                     | Документация                                  |
+| ----------- | ------------------------------------------------------------ | --------------------------------------------- |
+| **GraphQL** | Гибкие запросы, получение связанных данных, сложные операции | [Документация по API](/l/ru/developers/extend/api) |
+| **REST**    | Простые операции CRUD, привычные шаблоны REST                | [Документация по API](/l/ru/developers/extend/api) |
+
+Оба API поддерживают:
+
+* Создание, чтение, обновление и удаление записей
+* **Пакетные операции** — создание или обновление до 60 записей за один вызов
+
+**Для импорта используйте пакетные операции**, чтобы максимизировать пропускную способность в рамках лимитов.
+
+### Шаг 3: Спланируйте порядок импорта
+
+Как и при импорте CSV, для связей **важен порядок**:
+
+1. **Компании** в первую очередь (без зависимостей)
+2. **Контакты** во вторую очередь (могут быть связаны с компаниями)
+3. **Возможности** в третью очередь (могут быть связаны с компаниями и контактами)
+4. **Задачи/Заметки** (могут быть связаны с любым из вышеперечисленных)
+5. **Пользовательские объекты** (с учётом их зависимостей)
+
+## Лучшие практики
+
+### Объединяйте запросы в пакеты
+
+* Не отправляйте записи по одной
+* Группируйте до **60 записей на один вызов API**
+* Так вы максимально используете пропускную способность в рамках лимитов
+
+### Обрабатывайте ограничения скорости
+
+* Реализуйте задержки между запросами (минимум 600 мс для длительных импортов)
+* При достижении лимитов используйте экспоненциальное увеличение интервала повторных попыток
+* Отслеживайте ответы 429 (Too Many Requests)
+
+### Сначала проверьте данные
+
+* Очистите и проверьте данные перед импортом
+* Проверьте, что обязательные поля заполнены
+* Убедитесь, что форматы соответствуют требованиям Twenty (см. [Сопоставление полей](/l/ru/user-guide/data-migration/capabilities/field-mapping))
+
+### Логируйте всё
+
+* Логируйте каждую импортированную запись (включая идентификаторы)
+* Логируйте ошибки с полным контекстом
+* Это помогает устранять неполадки и подтверждать завершение
+
+### Сначала протестируйте
+
+* Протестируйте на небольшой выборке (10-20 записей)
+* Проверьте, что данные корректно отображаются в Twenty
+* Затем запустите полный импорт
+
+### Upsert для предотвращения дубликатов
+
+GraphQL API поддерживает **пакетный upsert** — обновление, если запись существует, и создание, если нет. Это предотвращает дубликаты при повторном запуске импорта.
+
+## Поиск названий объектов и полей
+
+Чтобы увидеть доступные объекты и поля:
+
+1. Перейдите в **Настройки → API и вебхуки**
+2. Просмотрите **Metadata API**
+3. Просмотрите все стандартные и пользовательские объекты и их поля
+
+В документации перечислены все стандартные и пользовательские объекты, их поля и ожидаемые типы данных.
+
+## Профессиональные услуги
+
+Для сложных миграций по API наши партнёры могут помочь:
+
+| Услуга                           | Что включено                                      |
+| -------------------------------- | ------------------------------------------------- |
+| **Проектирование модели данных** | проектирование оптимальной структуры данных       |
+| **Скрипты миграции**             | написание и запуск скриптов импорта               |
+| **Преобразование данных**        | обработка сложного сопоставления и очистки данных |
+| **Проверка и контроль качества** | проверка завершённости миграции                   |
+
+**Лучше всего подходит для:**
+
+* Миграции объёмом 100 000+ записей
+* Сложные преобразования данных
+* Сжатые сроки
+* Команды без ресурсов на разработку
+
+Свяжитесь с нами по адресу [contact@twenty.com](mailto:contact@twenty.com) или изучите наши [услуги по внедрению](/l/ru/user-guide/getting-started/capabilities/implementation-services).
+
+## Часто задаваемые вопросы
+
+<AccordionGroup>
+  <Accordion title="В чём разница между GraphQL и REST?">
+    GraphQL позволяет запрашивать ровно те данные, которые нужны, в одном запросе и лучше подходит для сложных операций. REST использует стандартные методы HTTP (GET, POST, PUT, DELETE) и может быть более привычен, если вы работали с традиционными API.
+  </Accordion>
+
+  <Accordion title="Могу ли я обновлять существующие записи через API?">
+    Да! Используйте мутации обновления (GraphQL) или запросы PUT/PATCH (REST) с `id` записи.
+  </Accordion>
+
+  <Accordion title="Как обрабатывать дубликаты?">
+    Сначала запросите существующие записи, используя уникальные идентификаторы (email, домен). Обновляйте, если запись существует, и создавайте, если нет.
+  </Accordion>
+
+  <Accordion title="Могу ли я удалять записи через API?">
+    Да, используйте мутации удаления (GraphQL) или запросы DELETE (REST).
+  </Accordion>
+
+  <Accordion title="Есть ли SDK для Python или Node.js?">
+    Пока нет, но оба API работают с любым HTTP-клиентом на любом языке.
+  </Accordion>
+</AccordionGroup>
+
+## Документация по API
+
+Полная информация о реализации, примеры кода и справочник по схеме:
+
+* [Документация по API](/l/ru/developers/extend/api)