crm.item.add
Создать новый элемент CRM
Описание
Метод является универсальным методом для создания объектов в CRM. С помощью него вы можете создавать различные типы объектов, такие как сделки, контакты, компании и другие.
Для создания объекта необходимо передать соответствующие параметры, включая тип объекта и информацию о нем: название, описание, контактные данные и другие детали.
После успешного выполнения запроса создается новый объект.
Этот метод предоставляет гибкую возможность автоматизировать процесс создания объектов и интегрировать CRM с другими системами.
При создании элемента производится стандартный ряд проверок, модификаций и автоматических действий:
- проверяются права доступа
- проверяется заполненность обязательных полей
- проверяется заполненность зависимых от стадий обязательных полей
- проверяется корректность заполнения полей
- полям присваиваются значения по умолчанию
- после сохранения запускаются роботы
Далее рассмотрим подробнее, как использовать этот метод и какие параметры нужно передать.
Параметры
entityTypeId
integer
обязательный
Идентификатор системного или пользовательского типа, чей элемент мы хотим создать.
Числовые значения для системных типов (Лид — 1, Сделка — 2, Контакт — 3, Компания — 4, Счёт — 31 и др.) приведены в справочнике типов объектов CRM. Идентификатор смарт-процесса можно узнать методом crm.type.list
fields
object
обязательный
Объект формата.
{
field_1: value_1,
field_2: value_2,
...,
field_n: value_n,
}
где
- field_n — название поля
- value_n — значение поля
У каждого типа сущности CRM свой набор полей. Это значит, что набор полей для создания Лида не обязан подходить набору полей для создания Контакта или Смарт-процесса.
Список доступных полей для каждого типа сущности описан ниже.
Некорректное поле в fields будет проигнорировано
useOriginalUfNames
boolean
необязательный
Параметр для управления форматом имен пользовательских полей в запросе и ответе.
Возможные значения:
Y— оригинальные имена пользовательских полей, напримерUF_CRM_2_1639669411830N— имена пользовательских полей в camelCase, напримерufCrm2_1639669411830
По умолчанию — N
Примеры запроса
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"entityTypeId":2,"fields":{"title":"Новая сделка (специально для примера REST методов)","typeId":"SERVICE","categoryId":9,"stageId":"C9:UC_KN8KFI","isReccurring":"Y","probability":50,"currencyId":"RUB","isManualOpportunity":"Y","opportunity":999.99,"taxValue":99.9,"companyId":5,"contactId":4,"contactIds":[4,5],"quoteId":7,"begindate":"formatDate(monthAgo)","closedate":"formatDate(twelveDaysInAdvance)","opened":"N","comments":"commentsExample","assignedById":6,"sourceId":"WEB","sourceDescription":"Тут должно быть дополнительное описание об источнике","leadId":102,"additionalInfo":"Тут должна быть дополнительная информация","observers":[2,3],"utmSource":"google","utmMedium":"CPC","ufCrm_1721244707107":1111.1,"parentId1220":2}}' \
https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/crm.item.add
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"entityTypeId":2,"fields":{"title":"Новая сделка (специально для примера REST методов)","typeId":"SERVICE","categoryId":9,"stageId":"C9:UC_KN8KFI","isReccurring":"Y","probability":50,"currencyId":"RUB","isManualOpportunity":"Y","opportunity":999.99,"taxValue":99.9,"companyId":5,"contactId":4,"contactIds":[4,5],"quoteId":7,"begindate":"formatDate(monthAgo)","closedate":"formatDate(twelveDaysInAdvance)","opened":"N","comments":"commentsExample","assignedById":6,"sourceId":"WEB","sourceDescription":"Тут должно быть дополнительное описание об источнике","leadId":102,"additionalInfo":"Тут должна быть дополнительная информация","observers":[2,3],"utmSource":"google","utmMedium":"CPC","ufCrm_1721244707107":1111.1,"parentId1220":2},"auth":"**put_access_token_here**"}' \
https://**put_your_bitrix24_address**/rest/crm.item.add
// This snippet is an ES module: top-level await requires type="module" or a bundler.
// $b24 is an already-initialized SDK instance (see the SDK "Get started" guide).
import { Text } from '@bitrix24/b24jssdk'
import type { B24Frame } from '@bitrix24/b24jssdk'
declare const $b24: B24Frame
type CrmItem = {
id: number
title: string
}
// Shape of the payload returned in result (match the "response handling" section of the page)
type ItemAddResult = {
item: CrmItem
}
const formatDate = (date: Date): string => date.toISOString().slice(0, 10)
const day = 60 * 60 * 24 * 1000
const now = new Date()
const twelveDaysInAdvance = new Date(now.getTime() + 12 * day)
const monthAgo = new Date(now.getTime() - 30 * day)
const commentsExample = [
'Example comment inside a deal',
'',
'[B]Bold text[/B]',
'[I]Italic[/I]',
'[U]Underlined[/U]',
'[S]Strikethrough[/S]',
'[B][I][U][S]Mix[/S][/U][/I][/B]',
'',
'[LIST]',
'[*]List item #1',
'[*]List item #2',
'[*]List item #3',
'[/LIST]',
].join('\n')
try {
const response = await $b24.actions.v2.call.make<ItemAddResult>({
method: 'crm.item.add',
params: {
entityTypeId: 2,
fields: {
title: 'New deal (specifically for the REST methods example)',
typeId: 'SERVICE',
categoryId: 9,
stageId: 'C9:UC_KN8KFI',
isReccurring: 'Y',
probability: 50,
currencyId: 'RUB',
isManualOpportunity: 'Y',
opportunity: 999.99,
taxValue: 99.9,
companyId: 5,
contactId: 4,
contactIds: [4, 5],
quoteId: 7,
begindate: formatDate(monthAgo),
closedate: formatDate(twelveDaysInAdvance),
opened: 'N',
comments: commentsExample,
assignedById: 6,
sourceId: 'WEB',
sourceDescription: 'Additional description about the source goes here',
leadId: 102,
additionalInfo: 'Additional information goes here',
observers: [2, 3],
utmSource: 'google',
utmMedium: 'CPC',
ufCrm_1721244707107: 1111.1,
parentId1220: 2,
},
},
requestId: Text.getUuidRfc4122()
})
// The payload is available only on a successful response
if (!response.isSuccess) {
console.error(response.getErrorMessages().join('; '))
} else {
const result = response.getData()!.result
console.info(`Created item #${result.item.id} (${result.item.title})`)
}
} catch (error) {
// Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
console.error(error)
}
<!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
<script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
<script>
async function addCrmItem() {
try {
// Initialize the SDK inside a Bitrix24 frame
const $b24 = await B24Js.initializeB24Frame()
const formatDate = (date) => date.toISOString().slice(0, 10)
const day = 60 * 60 * 24 * 1000
const now = new Date()
const twelveDaysInAdvance = new Date(now.getTime() + 12 * day)
const monthAgo = new Date(now.getTime() - 30 * day)
const commentsExample = [
'Example comment inside a deal',
'',
'[B]Bold text[/B]',
'[I]Italic[/I]',
'[U]Underlined[/U]',
'[S]Strikethrough[/S]',
'[B][I][U][S]Mix[/S][/U][/I][/B]',
'',
'[LIST]',
'[*]List item #1',
'[*]List item #2',
'[*]List item #3',
'[/LIST]',
].join('\n')
const response = await $b24.actions.v2.call.make({
method: 'crm.item.add',
params: {
entityTypeId: 2,
fields: {
title: 'New deal (specifically for the REST methods example)',
typeId: 'SERVICE',
categoryId: 9,
stageId: 'C9:UC_KN8KFI',
isReccurring: 'Y',
probability: 50,
currencyId: 'RUB',
isManualOpportunity: 'Y',
opportunity: 999.99,
taxValue: 99.9,
companyId: 5,
contactId: 4,
contactIds: [4, 5],
quoteId: 7,
begindate: formatDate(monthAgo),
closedate: formatDate(twelveDaysInAdvance),
opened: 'N',
comments: commentsExample,
assignedById: 6,
sourceId: 'WEB',
sourceDescription: 'Additional description about the source goes here',
leadId: 102,
additionalInfo: 'Additional information goes here',
observers: [2, 3],
utmSource: 'google',
utmMedium: 'CPC',
ufCrm_1721244707107: 1111.1,
parentId1220: 2,
},
},
requestId: B24Js.Text.getUuidRfc4122()
})
// The payload is available only on a successful response
if (!response.isSuccess) {
console.error(response.getErrorMessages().join('; '))
return
}
const result = response.getData().result
console.info(`Created item #${result.item.id} (${result.item.title})`)
} catch (error) {
// Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
console.error(error)
}
}
document.addEventListener('DOMContentLoaded', addCrmItem)
</script>
from b24pysdk.errors import BitrixAPIError, BitrixSDKException
try:
bitrix_response = client.crm.item.add(
entity_type_id=1302,
fields=
{
"ufCrm44_1721812760630": "Строка для пользовательского поля типа Строка",
"ufCrm44_1721812814433": 81,
"ufCrm44_1721812853419": "2024-08-21",
"ufCrm44_1721812885588": [
"example.com",
"second-example.com",
],
"ufCrm44_1721812898903": [
"green_pixel.png",
"iVBORw0KGgoAAAANSUhEUgAAAIAAAAAMCAYAAACqTLVoAAAALklEQVR42u3SAQEAAAQDsEsuOj3YMqwy6fBWCSCAAAIgAAIgAAIgAAIgAAJw3QLOrRH1U/gU4gAAAABJRU5ErkJggg==",
],
"ufCrm44_1721812915476": "300|RUB",
"ufCrm44_1721812935209": "Y",
"ufCrm44_1721812948498": 9999.9,
}
).response
result = bitrix_response.result
print(result)
except BitrixAPIError as error:
print(
"Ошибка Bitrix API",
f"error: {error.error}",
f"error_description: {error.error_description}",
sep="\n",
)
except BitrixSDKException as error:
print(f"Ошибка Bitrix SDK: {error.message}")
except Exception as error:
print(f"Непредвиденная ошибка: {error}")
require_once('crest.php');
$result = CRest::call(
'crm.item.add',
[
'entityTypeId' => 2,
'fields' => [
'title' => "Новая сделка (специально для примера REST методов)",
'typeId' => "SERVICE",
'categoryId' => 9,
'stageId' => "C9:UC_KN8KFI",
'isReccurring' => "Y",
'probability' => 50,
'currencyId' => "RUB",
'isManualOpportunity' => "Y",
'opportunity' => 999.99,
'taxValue' => 99.9,
'companyId' => 5,
'contactId' => 4,
'contactIds' => [4, 5],
'quoteId' => 7,
'begindate' => formatDate(monthAgo),
'closedate' => formatDate(twelveDaysInAdvance),
'opened' => "N",
'comments' => $commentsExample,
'assignedById' => 6,
'sourceId' => "WEB",
'sourceDescription' => "Тут должно быть дополнительное описание об источнике",
'leadId' => 102,
'additionalInfo' => "Тут должна быть дополнительная информация",
'observers' => [2, 3],
'utmSource' => "google",
'utmMedium' => "CPC",
'ufCrm_1721244707107' => 1111.1,
'parentId1220' => 2,
],
]
);
echo '<PRE>';
print_r($result);
echo '</PRE>';
try {
$entityTypeId = 1; // Example entity type ID
$fields = [
'title' => 'New Item',
'createdTime' => (new DateTime())->format(DateTime::ATOM),
'updatedTime' => (new DateTime())->format(DateTime::ATOM),
'begindate' => (new DateTime())->format(DateTime::ATOM),
'closedate' => (new DateTime())->format(DateTime::ATOM),
// Add other necessary fields as required
];
$result = $serviceBuilder
->getCRMScope()
->item()
->add($entityTypeId, $fields);
print("ID: " . $result->item()->id . PHP_EOL);
print("Title: " . $result->item()->title . PHP_EOL);
print("Created By: " . $result->item()->createdBy . PHP_EOL);
print("Updated By: " . $result->item()->updatedBy . PHP_EOL);
print("Created Time: " . $result->item()->createdTime->format(DateTime::ATOM) . PHP_EOL);
print("Updated Time: " . $result->item()->updatedTime->format(DateTime::ATOM) . PHP_EOL);
} catch (Throwable $e) {
print("Error: " . $e->getMessage() . PHP_EOL);
}
// client и ctx уже созданы — см. раздел «SDK для Go»
res, err := client.Core().Call(ctx, "crm.item.add", b24.Params{
"entityTypeId": 2,
"fields": b24.Params{
"title": "Новая сделка (специально для примера REST методов)",
"typeId": "SERVICE",
"categoryId": 9,
"stageId": "C9:UC_KN8KFI",
"isReccurring": "Y",
"probability": 50,
"currencyId": "RUB",
"isManualOpportunity": "Y",
"opportunity": 999.99,
"taxValue": 99.9,
"companyId": 5,
"contactId": 4,
"contactIds": []int{4, 5},
"quoteId": 7,
"begindate": "formatDate(monthAgo)",
"closedate": "formatDate(twelveDaysInAdvance)",
"opened": "N",
"comments": "commentsExample",
"assignedById": 6,
"sourceId": "WEB",
"sourceDescription": "Тут должно быть дополнительное описание об источнике",
"leadId": 102,
"additionalInfo": "Тут должна быть дополнительная информация",
"observers": []int{2, 3},
"utmSource": "google",
"utmMedium": "CPC",
"ufCrm_1721244707107": 1111.1,
"parentId1220": 2,
},
})
if err != nil {
return fmt.Errorf("crm.item.add: %w", err)
}
// Ответ приходит как json.RawMessage — разберите его
// в структуру под форму ответа, показанную ниже на этой странице.
fmt.Printf("%s\n", res.Result)
Ответ
HTTP-статус: 200
{
"result": {
"item": {
"id": 342,
"createdTime": "2024-07-18T14:00:14+02:00",
"dateCreateShort": null,
"updatedTime": "2024-07-18T14:00:14+02:00",
"dateModifyShort": null,
"createdBy": 1,
"updatedBy": 1,
"assignedById": 6,
"opened": "N",
"leadId": 102,
"companyId": 5,
"contactId": 4,
"quoteId": 7,
"title": "Новая сделка (специально для примера rest методов)",
"productId": null,
"categoryId": 9,
"stageId": "C9:UC_KN8KFI",
"stageSemanticId": "P",
"isNew": "N",
"isRecurring": "N",
"isReturnCustomer": "N",
"isRepeatedApproach": "Y",
"closed": "N",
"typeId": "SERVICE",
"opportunity": 999.99,
"isManualOpportunity": "Y",
"taxValue": 0,
"currencyId": "RUB",
"probability": 50,
"comments": "\nПример комментария внутри сделки\n\n[B]Жирный текст[/B]\n[I]Курсив[/I]\n[U]Подчеркнутый[/U]\n[S]Зачеркнутый[/S]\n[B][I][U][S]Микс[/S][/U][/I][/B]\n\n[LIST]\n[*]Элемент списка #1\n[*]Элемент списка #2\n[*]Элемент списка #3\n[/LIST]\n\n[LIST=1]\n[*]Нумерованный элемент списка #1\n[*]Нумерованный элемент списка #2\n[*]Нумерованный элемент списка #3\n[/LIST]\n",
"begindate": "2024-06-18T02:00:00+02:00",
"begindateShort": null,
"closedate": "2024-07-30T02:00:00+02:00",
"closedateShort": null,
"eventDate": null,
"eventDateShort": null,
"eventId": null,
"eventDescription": null,
"locationId": null,
"webformId": null,
"sourceId": "WEB",
"sourceDescription": "Тут должно быть дополнительное описание об источнике",
"originatorId": null,
"originId": null,
"additionalInfo": "Тут должна быть дополнительная информация",
"searchContent": null,
"orderStage": null,
"movedBy": 1,
"movedTime": "2024-07-18T14:00:14+02:00",
"lastActivityBy": 1,
"lastActivityTime": "2024-07-18T14:00:14+02:00",
"isWork": null,
"isWon": null,
"isLose": null,
"receivedAmount": null,
"lostAmount": null,
"hasProducts": null,
"ufCrm_1721244707107": 1111.1,
"parentId1220": 2,
"utmSource": "google",
"utmMedium": "CPC",
"utmCampaign": null,
"utmContent": null,
"utmTerm": null,
"observers": [
2,
3
],
"contactIds": [
4,
5
],
"entityTypeId": 2
}
},
"time": {
"start": 1721304013.245896,
"finish": 1721304015.555471,
"duration": 2.309574842453003,
"processing": 1.8328988552093506,
"date_start": "2024-07-18T14:00:13+02:00",
"date_finish": "2024-07-18T14:00:15+02:00",
"operating": 1.8328571319580078
}
}
Возвращаемые данные
result
object
Корневой элемент ответа, содержит единственный ключ item
item
item
Информация о созданном элементе, описание полей
time
time
Информация о времени выполнения запроса
Обработка ошибок
HTTP-статус: 400
{
"error": "NOT_FOUND",
"error_description": "Смарт-процесс не найден"
}
| Код | Описание | Значение |
|---|---|---|
403 |
allowed_only_intranet_user |
Действие разрешено только интранет-пользователям |
400 |
NOT_FOUND |
Смарт-процесс не найден |
400 |
ACCESS_DENIED |
Доступ запрещен |
400 |
CRM_FIELD_ERROR_VALUE_NOT_VALID |
Неверное значение поля "field" |
400 |
100 |
Expected iterable value for multiple field, but got type instead |
400 |
CREATE_DYNAMIC_ITEM_RESTRICTED |
Вы не можете создать новый элемент из-за ограничений вашего тарифа |

