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

# Импорт данных через API

> Когда и как использовать 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)