crm.item.import — метод REST API Битрикс24

Описание

Универсальный метод для импорта объектов в 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 — значение поля

Для мультиполей, например PHONE, EMAIL передавайте данные по структуре crm_multifield:

{
    field_name: [
        {
            VALUE: "value_1",
            VALUE_TYPE: "type_1"
        },
        {
            VALUE: "value_2",
            VALUE_TYPE: "type_2"
        },
        ...
    ]
}

field_name — название поля, например PHONE
VALUE — значение поля, например номер телефона
VALUE_TYPE — тип значения, например WORK

У каждого объекта CRM свой набор полей. Это значит, что набор полей для создания Лида не обязан подходить набору полей для создания Контакта или Смарт-процесса.

Список доступных полей для каждого типа объектов описан ниже.

Некорректное поле в fields будет проигнорировано.

Узнать набор полей также можно универсальным методом crm.item.fields или методами для конкретных объектов CRM:
- crm.lead.fields
- crm.deal.fields
- crm.contact.fields
- crm.company.fields
- crm.quote.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.import

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.import

from b24pysdk.errors import BitrixAPIError, BitrixSDKException

try:
    bitrix_response = client.crm.item.import_(
        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}")

const formatDate = (date) => {
    return 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 = `
Пример комментария внутри сделки

[B]Жирный текст[/B]
[I]Курсив[/I]
[U]Подчеркнутый[/U]
[S]Зачеркнутый[/S]
[B][I][U][S]Микс[/S][/U][/I][/B]

[LIST]
[*]Элемент списка #1
[*]Элемент списка #2
[*]Элемент списка #3
[/LIST]

[LIST=1]
[*]Нумерованный элемент списка #1
[*]Нумерованный элемент списка #2
[*]Нумерованный элемент списка #3
[/LIST]
`;

BX24.callMethod(
    'crm.item.import', 
    {
        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,
        },
    },
    (result) => 
    {
        result.error() 
            ? console.error(result.error()) 
            : console.info(result.data())
        ;
    }
);

require_once('crest.php');

$result = CRest::call(
    'crm.item.import',
    [
        '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>';

Ответ

HTTP-статус: 200

{
    "result": {
        "item": {
            "id": 4
        }
    },
    "time": {
        "start": 1722940215.145257,
        "finish": 1722940217.94124,
        "duration": 2.795983076095581,
        "processing": 2.4315829277038574,
        "date_start": "2024-08-06T10:30:15+00:00",
        "date_finish": "2024-08-06T10:30:17+00:00",
        "operating": 2.4314892292022705
    }
}

Возвращаемые данные

result object

Корневой элемент ответа.

Содержит единственный ключ — item

item object

Информация о созданном элементе.

Содержит единственный ключ — id

id integer

Идентификатор созданного элемента

time time

Информация о времени выполнения запроса

Обработка ошибок

HTTP-статус: 401

{
    "error": "NOT_FOUND",
    "error_description": "Смарт-процесс не найден"
}

Код	Описание	Значение
`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`	Вы не можете создать новый элемент из-за ограничений вашего тарифа
`401`	`INVALID_CREDENTIALS`	Неверные данные авторизации для запроса
`403`	`allowed_only_intranet_user`	Действие разрешено только интранет-пользователям