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

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

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

POST /v1/{entity}/import

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

Параметры

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

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

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

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

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

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

Примеры

curl — личный ключ

curl -X POST 'https://vibecode.bitrix24.tech/v1/leads/import' \
  -H 'X-Api-Key: YOUR_API_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
      }
    ]
  }'

curl — OAuth-приложение

curl -X POST 'https://vibecode.bitrix24.tech/v1/leads/import' \
  -H 'X-Api-Key: YOUR_APP_KEY' \
  -H 'Authorization: Bearer USER_SESSION_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "items": [
      {
        "title": "Website request",
        "name": "Jane",
        "lastName": "Doe",
        "phone": "+15551234567",
        "email": "jane@example.com",
        "assignedById": 31,
        "createdBy": 11
      }
    ]
  }'

JavaScript — личный ключ

const res = await fetch('https://vibecode.bitrix24.tech/v1/leads/import', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    items: [
      {
        title: 'Website request',
        name: 'Jane',
        lastName: 'Doe',
        phone: '+15551234567',
        email: 'jane@example.com',
        assignedById: 31,
        createdBy: 11,
      },
    ],
  }),
})

const { data } = await res.json()
console.log('Не создано:', data.summary.failed)

JavaScript — OAuth-приложение

const res = await fetch('https://vibecode.bitrix24.tech/v1/leads/import', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    items: [
      {
        title: 'Website request',
        name: 'Jane',
        lastName: 'Doe',
        phone: '+15551234567',
        email: 'jane@example.com',
        assignedById: 31,
        createdBy: 11,
      },
    ],
  }),
})

const { data } = await res.json()
console.log('Не создано:', data.summary.failed)

Поля ответа

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

Пример ответа

Первая запись создана, вторая отклонена Битрикс24 — дата создания в будущем:

{
  "success": true,
  "data": {
    "results": [
      { "index": 0, "success": true, "id": 1001349 },
      {
        "index": 1,
        "success": false,
        "error": "CRM_FIELD_ERROR_VALUE_NOT_VALID",
        "message": "Значение поля \"Когда создан\" не может быть в будущем времени"
      }
    ],
    "summary": { "total": 2, "succeeded": 1, "failed": 1 }
  }
}

Пример ответа при ошибке

400 — массив items не передан:

{
  "success": false,
  "error": {
    "code": "IMPORT_ITEM_VALIDATION",
    "message": "items must be a non-empty array of lead objects"
  }
}

Ошибки

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

Полный список общих ошибок API — Ошибки.

Известные особенности

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

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

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

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

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

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

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

Проверка итогов импорта

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

Стадия и ручная сумма сверяются после импорта. Битрикс24 принимает импорт с несуществующей стадией и молча кладёт запись на стадию по умолчанию. Ручной режим суммы у типа без товарной части так же молча теряется. Поэтому после всех пачек платформа перечитывает созданные записи — один раз на каждые 50, страницей списка — и помечает те, у кого стадия, воронка или явно запрошенный isManualOpportunity: true не применились, кодом STAGE_NOT_APPLIED / AMOUNT_NOT_APPLIED — с сохранённым id: запись существует, повторять её нельзя, исправьте значение через PATCH или /move. Перечитываются только записи, у которых была стадия, воронка или явный ручной режим суммы. Импорт без них стоит ровно столько, сколько раньше. Импорт не запускает правила автоматизации, поэтому перечитанная запись — итог самого импорта, а не робота. Если перечитать не удалось, строки остаются такими, как их вернул Битрикс24. Пустая стадия (null, "") не сверяется — запись ляжет на стадию по умолчанию. Сумма без явного isManualOpportunity: true не проверяется. Лид, который портал в простом режиме CRM сам перевёл в «сконвертирован», за неприменённую стадию не считается.

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

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

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

Смотрите также

• Создать лид
• Поля лида
• Пакетные вызовы