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

Конвертировать лид

POST /v1/leads/:id/convert

Создаёт из лида сделку, контакт и компанию, связывает созданные записи между собой и закрывает лид как сконвертированный. Состав создаваемых записей задаётся телом запроса.

Параметры

Параметр Тип Обяз. Описание
id (path) number да ID лида. Список: GET /v1/leads

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

Тело запроса необязательно. Без тела и с пустым объектом {} применяются значения по умолчанию.

Поле Тип По умолч. Описание
createDeal boolean true Создать сделку
createContact boolean true Создать контакт
createCompany boolean false Создать компанию по названию компании из лида

Примеры

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

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/leads/1001207/convert \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "createDeal": true,
    "createContact": true,
    "createCompany": false
  }'

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

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/leads/1001207/convert \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "createDeal": true,
    "createContact": true,
    "createCompany": false
  }'

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

javascript 
const res = await fetch(`https://vibecode.bitrix24.tech/v1/leads/${leadId}/convert`, {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    createDeal: true,
    createContact: true,
    createCompany: false,
  }),
})

const body = await res.json()

if (!res.ok) {
  // 422 CONVERSION_FAILED: часть записей уже создана и не откатится —
  // что именно, лежит в error.details
  throw new Error(`${body.error.code}: ${JSON.stringify(body.error.details ?? {})}`)
}

// Созданные записи читаются тем же методом, что и обычное чтение, поэтому их
// ключи приходят в общем стиле платформы
console.log('Сделка:', body.data.deal?.id, 'Контакт:', body.data.contact?.id)

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

javascript 
const res = await fetch(`https://vibecode.bitrix24.tech/v1/leads/${leadId}/convert`, {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    createDeal: true,
    createContact: true,
    createCompany: false,
  }),
})

const body = await res.json()

if (!res.ok) {
  throw new Error(`${body.error.code}: ${JSON.stringify(body.error.details ?? {})}`)
}

const { data } = body

Поля ответа

Поле Тип Описание
success boolean true, когда созданы все запрошенные записи
data.lead object Лид после конвертации
data.deal object | null Созданная сделка. null, когда сделка не запрашивалась
data.contact object | null Созданный контакт. null, когда контакт не запрашивался
data.company object | null Созданная компания. null, когда компания не запрашивалась

Ключи внутри data.lead, data.deal, data.contact и data.company приходят в том же виде, что и при обычном чтении записи — id, title, stageId, createdTime. Раньше этот маршрут отдавал сырой формат Битрикс24 в верхнем регистре через подчёркивание; теперь имена полей совпадают с остальными страницами раздела.

Каждая созданная запись несёт leadId — ссылку на лид, из которого она возникла, а сам лид получает ссылки на созданные контакт и компанию.

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

Показаны характерные поля. Каждая запись приходит со всем набором своих полей, включая пользовательские.

JSON 
{
  "success": true,
  "data": {
    "lead": {
      "id": 1001207,
      "title": "Заявка с сайта",
      "name": "Мария",
      "sourceId": "CALL",
      "statusId": "CONVERTED",
      "statusSemanticId": "S",
      "currencyId": "RUB",
      "amount": 0,
      "contactId": 2733,
      "assignedById": 1,
      "createdTime": "2026-08-25T13:47:11+03:00",
      "updatedTime": "2026-08-25T13:47:25+03:00"
    },
    "deal": {
      "id": 8345,
      "title": "Заявка с сайта",
      "stageId": "NEW",
      "categoryId": 0,
      "currencyId": "RUB",
      "amount": 0,
      "contactId": 2733,
      "companyId": null,
      "leadId": 1001207,
      "sourceId": "CALL",
      "assignedById": 1,
      "createdTime": "2026-08-25T13:47:24+03:00"
    },
    "contact": {
      "id": 2733,
      "name": "Мария",
      "lastName": null,
      "typeId": "CLIENT",
      "sourceId": "CALL",
      "leadId": 1001207,
      "companyId": null,
      "assignedById": 1,
      "createdTime": "2026-08-25T13:47:23+03:00"
    },
    "company": null
  }
}

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

404 — лида с указанным ID не существует:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Not found"
  }
}

422 — контакт создался, а сделка нет. Структура ответа здесь другая: добавляется поле error.details с исходом каждой запрошенной операции.

JSON 
{
  "success": false,
  "error": {
    "code": "CONVERSION_FAILED",
    "message": "Lead conversion partially failed",
    "details": {
      "contact": { "id": 2733, "success": true },
      "deal": { "success": false, "error": "Required field is missing" }
    }
  }
}

Контакт 2733 остался в CRM: отката нет. Прежде чем повторять вызов, сверьте, что уже появилось в CRM, — повтор создаст второй комплект записей.

Ошибки

HTTP Код Описание
400 INVALID_PARAMS Идентификатор лида в пути не является целым числом. Проверка идёт до обращения к Битрикс24: раньше нечисловое значение приводилось к числу на стороне Битрикс24 и конвертация выполнялась над ДРУГОЙ записью
422 CONVERSION_FAILED Созданы не все запрошенные записи. Исходы отдельных операций — в поле error.details: по ключу на каждую запрошенную запись. Уже созданные записи не откатываются, статус лида не меняется
404 ENTITY_NOT_FOUND Лида с указанным id не существует
422 BITRIX_ERROR Битрикс24 отклонил чтение лида или его закрытие. Отказ на создании сделки, контакта или компании сюда не попадает — он приходит как CONVERSION_FAILED. Текст в message приходит от Битрикс24 дословно, поля error.details в этом ответе нет
403 BITRIX_ACCESS_DENIED Битрикс24 отказал в доступе к лиду
403 SCOPE_DENIED API-ключу не хватает скоупа crm
403 WRITE_BLOCKED_READONLY_KEY Ключ переведён в режим только для чтения, а конвертация создаёт записи
401 TOKEN_MISSING У API-ключа нет действующих токенов Битрикс24
429 RATE_LIMITED Превышен лимит запросов к порталу

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

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

  • Повторный вызов создаёт второй комплект записей. Эндпоинт не проверяет, был ли лид сконвертирован раньше, поэтому повтор после обрыва связи задваивает данные в CRM. Признак уже сконвертированного лида — статус CONVERTED. Перед повтором запросите лид через GET /v1/leads/:id — там статус приходит в поле stageId.
  • Отката при частичном отказе нет. Сделка, контакт и компания создаются отдельными записями одна за другой. Если одна из них не создалась, ранее созданные остаются в CRM, а статус лида не меняется. Перед повторным вызовом сверьте, что уже появилось в CRM, иначе повтор добавит дубли к уже созданному.
  • Вернуться к camelCase можно перечитыванием записи. Возьмите ID созданной записи и запросите её через GET /v1/deals/:id или GET /v1/contacts/:id — там поля приходят в camelCase.
  • В создаваемые записи переносится ограниченный набор полей. Контакт получает имя, фамилию, отчество, источник и ответственного. Компания — название компании из лида и ответственного. Сделка — название, сумму, валюту, источник и ответственного. Остальные поля лида, включая пользовательские, не копируются, поэтому недостающие значения дописывайте отдельным вызовом PATCH /v1/deals/:id.
  • Товарные позиции лида копируются в созданную сделку. Когда перенос позиций не удался, сделка остаётся созданной, а конвертация — успешной. Состав товаров сверяйте вызовом GET /v1/deals/:id/products.
  • Созданные записи несут обратную ссылку на исходный лид. У сделки, контакта и компании проставляется leadId, а сам лид получает contactId и companyId — так что сделку можно найти по лиду, из которого она возникла, фильтром по leadId, и хранить соответствие на своей стороне больше не нужно.

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