метод REST scope: crm

crm.item.add

Создать новый элемент CRM

Кто может выполнять: любой пользователь с правом «добавления» элемента объекта 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_1639669411830
  • N — имена пользовательских полей в 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

Ответ

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 Вы не можете создать новый элемент из-за ограничений вашего тарифа

Что будем искать? Например,Продвижение

Этот сайт использует куки-файлы. Оставаясь на сайте, Вы соглашаетесь на их использование. Для получения дополнительной информации, пожалуйста, ознакомьтесь с политикой в отношении персональных данных.