Для AI-агентов: markdown этой страницы — /docs-content/import.md индекс документации — /llms.txt

Импорт записей CRM

Перенос уже существующих данных в CRM: до 100 записей за запрос, с сохранением автора и дат из внешней системы.

Импорт не запускает автоматизацию. Роботы, триггеры и бизнес-процессы, настроенные на создание элемента, на импортированных записях не срабатывают — это свойство самой операции в Битрикс24, а не наш параметр. Если вам нужно, чтобы автоматизация отработала, создавайте записи обычным способом — POST /v1/{entity}.

POST /v1/{entity}/import

Скоуп: crm | Базовый URL: https://vibecode.bitrix24.tech/v1 | Авторизация: X-Api-Key (APP-ключ)

Для каких объектов доступен

Путь Объект
POST /v1/leads/import Лиды
POST /v1/deals/import Сделки
POST /v1/contacts/import Контакты
POST /v1/companies/import Компании
POST /v1/quotes/import Предложения
POST /v1/invoices/import Счета
POST /v1/items/{entityTypeId}/import Элементы смарт-процессов

У остальных сущностей такого маршрута нет — Битрикс24 умеет импортировать только объекты CRM.

Чем импорт отличается от создания

POST /v1/{entity} POST /v1/{entity}/import
Право в Битрикс24 право на добавление право на импорт — отдельное, выдаёт администратор портала
Роботы и бизнес-процессы запускаются не запускаются
Автор и даты записи проставляет Битрикс24 можно передать свои (см. ниже)
За один запрос одна запись до 100 записей
Ответ созданная запись целиком исход по каждой записи

Поля запроса (body)

Поле Тип Обяз. Описание
items array ★ Массив записей, от 1 до 100. Поля каждой записи — те же, что у POST /v1/{entity}, плюс служебные поля ниже.
Terminal 
curl -X POST 'https://vibecode.bitrix24.tech/v1/leads/import' \
  -H 'X-Api-Key: YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "items": [
      {
        "title": "Website request",
        "name": "Jane",
        "lastName": "Doe",
        "phone": "+15551234567",
        "email": "jane@example.com",
        "assignedById": 31,
        "createdBy": 11
      }
    ]
  }'

Служебные поля

Только на импорте принимаются шесть полей, которые Битрикс24 обычно заполняет сам:

Поле Что задаёт
createdBy Кто создал запись
createdTime Когда запись создана
updatedBy Кто изменил запись
updatedTime Когда запись изменена
movedBy Кто перевёл запись на текущую стадию
movedTime Когда стадия изменилась

Проставить их может только администратор портала. Обычному пользователю Битрикс24 ответит по такой записи ошибкой CRM_FIELD_ERROR_VALUE_NOT_VALID — остальные записи пакета при этом создадутся.

Передавайте существующего сотрудника. Битрикс24 не проверяет идентификатор на существование и запишет любое число — в карточке будет призрачный автор. Записью при этом можно управлять как обычно.

Набор доступных полей отличается по объектам: у сделок и счетов есть все шесть, у лидов — автор и даты создания и изменения. Точный перечень для конкретной сущности возвращает GET /v1/{entity}/fields — служебные поля помечены там "importable": true рядом с "readonly": true.

Ограничение на даты

У createdTime есть окно, которое задаёт Битрикс24, и обойти его нельзя:

  • дата не может быть позже текущего момента;
  • дата не может быть раньше, чем у самой свежей уже существующей записи этого объекта.

То есть перенести историю целиком получится в пустую CRM или в такую, где все записи старше переносимых. В наполненную CRM «подложить» записи задним числом Битрикс24 не даст — ответит CRM_FIELD_ERROR_VALUE_NOT_VALID с пояснением. Каждая успешно импортированная запись поднимает нижнюю границу окна, поэтому переносите пачки от старых к новым.

updatedTime должен быть не раньше createdTime, а movedTime — попадать между ними.

Если история не нужна, просто не передавайте даты: автора можно проставить и без них.

Ответ

Ответ приходит со статусом 200 даже когда часть записей не прошла — импорт не транзакционен, и результат нужно читать по каждой записи.

JSON 
{
  "success": true,
  "data": {
    "results": [
      { "index": 0, "success": true, "id": 147 },
      {
        "index": 1,
        "success": false,
        "error": "CRM_FIELD_ERROR_VALUE_NOT_VALID",
        "message": "Значение поля \"Когда создан\" не может быть в будущем времени"
      }
    ],
    "summary": { "total": 2, "succeeded": 1, "failed": 1 }
  }
}
Поле Описание
results[].index Позиция записи в отправленном массиве items. Длина results всегда равна длине items.
results[].success Создана ли запись.
results[].id Идентификатор созданной записи. Приходит только при success: true.
results[].error Код ошибки Битрикс24.
results[].message Пояснение к ошибке.
summary Сводка: total, succeeded, failed.

Всегда проверяйте summary.failed. Статус 200 означает «запрос обработан», а не «все записи созданы».

Повторный импорт создаст дубли — идемпотентности у операции нет. Если повторы возможны, записывайте идентификатор записи из внешней системы в поля originatorId и originId: по ним потом можно найти уже перенесённое.

Ошибки

HTTP Код Когда
400 IMPORT_ITEM_VALIDATION items отсутствует, пуст или не массив; элемент не объект либо пуст; в элементе поле, недоступное на запись. Текст называет позицию: Item at index N: …
400 IMPORT_LIMIT_EXCEEDED Больше 100 записей в запросе. Разбейте пакет и отправьте части по порядку.
400 INVALID_DYNAMIC_PARAM Некорректный entityTypeId в пути /v1/items/{entityTypeId}/import, либо у этого типа есть свой маршрут (например для сделок — /v1/deals/import).
403 WRITE_BLOCKED_READONLY_KEY Ключ работает в режиме «только чтение».
403 SCOPE_DENIED У ключа нет скоупа crm.
429 RATE_LIMITED Слишком часто. Импорт ограничен по темпу на портал, чтобы массовая заливка не блокировала другие интеграции. Повторите через время из заголовка Retry-After.
404 — У этой сущности импорта нет.

Ошибки по отдельным записям приходят внутри 200, в results[] — там коды самого Битрикс24.

Что учесть при переносе базы

  • Один поток. Внутри одного запроса порядок гарантирован, между параллельными запросами — нет, а Битрикс24 требует неубывающих дат создания. Импортируйте последовательно.
  • Скорость. Сто записей за запрос — примерно 12–15 секунд; лимит темпа даёт около тысячи записей в минуту на портал. Для базы в десятки тысяч записей закладывайте время.
  • Сбой посреди пакета. Если связь с Битрикс24 оборвалась после того, как часть записей уже создана, ответ всё равно придёт со статусом 200: созданные будут с идентификаторами, оставшиеся — помечены ошибкой. Это единственный источник знания о том, что успело пройти, — перед повтором сверьтесь с ним.
  • Телефон и почта. Передавайте как обычно ("phone": "+15551234567" или массивом объектов) — приведение к формату, который принимает импорт, платформа делает сама.

Смежные страницы