Как сохранить дату оплаты в поле сделки

Scope: crm

Кто может выполнять метод: пользователи с правом на изменение элемента CRM

Выберите инструмент для разработки с AI-агентом:

  • используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
  • используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации

В Битрикс24 дата платежа хранится в документах оплаты. Иногда дата оплаты может понадобиться в поле сделки:

  • для интеграций с внешними системами,
  • отчетов BI-конструктора,
  • автоматизаций через роботы и бизнес-процессы.

Чтобы перенести информацию о дате оплаты в сделку, последовательно выполним три метода:

  1. crm.deal.userfield.list — получим идентификатор поля сделки, в которое сохраним информацию о дате
  2. crm.item.payment.list — получим информацию об оплате
  3. crm.deal.update — сохраним дату оплаты в поле сделки

1. Получаем идентификатор поля

Чтобы получить идентификатор поля cделки, используем метод crm.deal.userfield.list с параметрами:

  • filter[LANG] — фильтр по языку используем для вывода названий полей на нужном языке. Без данного фильтра названия выведены не будут.
  • filter[USER_TYPE_ID] — фильтр по типу поля используем, чтобы получить только поля с типом «Дата» в результате.

Как использовать примеры в документации

import { B24Hook } from '@bitrix24/b24jssdk'
        
        const $b24 = B24Hook.fromWebhookUrl(process.env.B24_HOOK)
        // B24_HOOK = 'https://your-domain.bitrix24.ru/rest/USER_ID/TOKEN/'
        
        const result = await $b24.actions.v2.call.make({
            method: 'crm.deal.userfield.list',
            params: {
                filter: {
                    LANG: 'ru',
                    USER_TYPE_ID: 'date'
                }
            }
        });
        
require_once 'vendor/autoload.php';
        
        use Bitrix24\SDK\Services\ServiceBuilderFactory;
        use Symfony\Component\EventDispatcher\EventDispatcher;
        use Monolog\Logger;
        use Monolog\Handler\StreamHandler;
        
        $logger = new Logger('b24');
        $logger->pushHandler(new StreamHandler('php://stdout'));
        
        $serviceBuilder = (new ServiceBuilderFactory(new EventDispatcher(), $logger))
            ->initFromWebhook('https://your-domain.bitrix24.ru/rest/USER_ID/TOKEN/');
        
        $result = $serviceBuilder->getCRMScope()->dealUserfield()->list(
            [],
            [
                'LANG' => 'ru',
                'USER_TYPE_ID' => 'date'
            ]
        );
        
from b24pysdk import BitrixWebhook, Client
        
        client = Client(
            BitrixWebhook(
                domain="your-domain.bitrix24.com",
                webhook_token="user_id/webhook_key",
            )
        )
        
        result = client.crm.deal.userfield.list(
            filter={
                "LANG": "ru",
                "USER_TYPE_ID": "date",
            }
        ).response.result
        

В результате получим информацию обо всех полях сделок с типом «Дата». Определим подходящее поле по названию в параметре EDIT_FORM_LABEL. Идентификатор поля возьмем из поля FIELD_NAME.

{
            "result": [
                {
                    "ID": "6787",
                    "ENTITY_ID": "CRM_DEAL",
                    "FIELD_NAME": "UF_CRM_1723209318",
                    "USER_TYPE_ID": "date",
                    "XML_ID": null,
                    "SORT": "150",
                    "MULTIPLE": "N",
                    "MANDATORY": "N",
                    "SHOW_FILTER": "E",
                    "SHOW_IN_LIST": "Y",
                    "EDIT_IN_LIST": "Y",
                    "IS_SEARCHABLE": "N",
                    "SETTINGS": {
                        "DEFAULT_VALUE": {
                            "TYPE": "NONE",
                            "VALUE": ""
                        }
                    },
                    "EDIT_FORM_LABEL": "Дата оплаты",
                    "LIST_COLUMN_LABEL": "Дата оплаты",
                    "LIST_FILTER_LABEL": "Дата оплаты",
                    "ERROR_MESSAGE": null,
                    "HELP_MESSAGE": null
                },
                {
                    "ID": "6795",
                    "ENTITY_ID": "CRM_DEAL",
                    "FIELD_NAME": "UF_CRM_1723206732",
                    "USER_TYPE_ID": "date",
                    "XML_ID": null,
                    "SORT": "150",
                    "MULTIPLE": "N",
                    "MANDATORY": "N",
                    "SHOW_FILTER": "E",
                    "SHOW_IN_LIST": "Y",
                    "EDIT_IN_LIST": "Y",
                    "IS_SEARCHABLE": "N",
                    "SETTINGS": {
                        "DEFAULT_VALUE": {
                            "TYPE": "NONE",
                            "VALUE": ""
                        }
                    },
                    "EDIT_FORM_LABEL": "Окончание РК",
                    "LIST_COLUMN_LABEL": "Окончание РК",
                    "LIST_FILTER_LABEL": "Окончание РК",
                    "ERROR_MESSAGE": null,
                    "HELP_MESSAGE": null
                },
                {
                    "ID": "6805",
                    "ENTITY_ID": "CRM_DEAL",
                    "FIELD_NAME": "UF_CRM_1723206709",
                    "USER_TYPE_ID": "date",
                    "XML_ID": null,
                    "SORT": "150",
                    "MULTIPLE": "N",
                    "MANDATORY": "N",
                    "SHOW_FILTER": "E",
                    "SHOW_IN_LIST": "Y",
                    "EDIT_IN_LIST": "Y",
                    "IS_SEARCHABLE": "N",
                    "SETTINGS": {
                        "DEFAULT_VALUE": {
                            "TYPE": "NONE",
                            "VALUE": ""
                        }
                    },
                    "EDIT_FORM_LABEL": "Старт РК",
                    "LIST_COLUMN_LABEL": "Старт РК",
                    "LIST_FILTER_LABEL": "Старт РК",
                    "ERROR_MESSAGE": null,
                    "HELP_MESSAGE": null
                }
            ],
            "total": 3,
        }
        

2. Получаем дату оплаты

Используем метод crm.item.payment.list с параметрами:

  • entityIdID сделки, для которой получаем дату оплаты
  • entityTypeIdтип объекта, укажем 2 для сделки
const result = await $b24.actions.v2.call.make({
            method: 'crm.item.payment.list',
            params: {
                entityId: 6917,
                entityTypeId: 2,
            }
        });
        
$result = $serviceBuilder->core->call(
            'crm.item.payment.list',
            [
                'entityId' => 6917,
                'entityTypeId' => 2
            ]
        );
        
result = client.crm.item.payment.list(
            entity_id=6917,
            entity_type_id=2,
        ).response.result
        

В результате получим список оплат с полями для сделки. Дату оплаты возьмем из поля datePaid.

{
            "result": [
                {
                    "id": 503,
                    "accountNumber": "831/1",
                    "paid": "Y",
                    "datePaid": "2025-04-29T13:03:20+03:00",
                    "empPaidId": 1,
                    "paySystemId": 19,
                    "sum": 15,
                    "currency": "RUB",
                    "paySystemName": "ЮKassa"
                }
            ],
        }
        

3. Сохраним дату в поле сделки

Чтобы изменить поле сделки и записать в него дату оплаты, используем метод crm.deal.update с параметрами:

  • idID сделки, обязательный параметр
  • fields[UF_CRM_1723209318] — укажем значение из поля datePaid, полученного на шаге 2. Как идентификатор поля передадим FIELD_NAME поля, полученное на шаге 1
const result = await $b24.actions.v2.call.make({
            method: 'crm.deal.update',
            params: {
                id: 6917,
                fields: {
                    UF_CRM_1723209318: "2025-04-29T13:03:20+03:00",
                },
            }
        });
        
$result = $serviceBuilder->getCRMScope()->deal()->update(
            6917,
            [
                'UF_CRM_1723209318' => '2025-04-29T13:03:20+03:00'
            ]
        );
        
result = client.crm.deal.update(
            bitrix_id=6917,
            fields={
                "UF_CRM_1723209318": "2025-04-29T13:03:20+03:00",
            },
        ).response.result
        

В результате получим true, изменение сделки прошло успешно. Если в результате вы получили ошибку error, изучите описание возможных ошибок в документации метода crm.deal.update.

{
            "result": true,
        }
        

Проверяем значение поля сделки

В полученном результате нет информации о полях сделки. Чтобы проверить, успешно ли обновилось поле с датой оплаты, выполним метод crm.deal.get с параметрами:

  • idID сделки, обязательный параметр
const result = await $b24.actions.v2.call.make({
            method: 'crm.deal.get',
            params: {
                id: 6917,
            }
        });
        
$result = $serviceBuilder->getCRMScope()->deal()->get(6917);
        
result = client.crm.deal.get(
            bitrix_id=6917,
        ).response.result
        

В результате получим значения всех полей сделки, включая пользовательские поля. Значение поля «Дата оплаты» UF_CRM_1723209318: 2025-04-29T03:00:00+03:00 установлено успешно.

{
            "result": {
                "ID": "6917",
                "TITLE": "Сделка #6531",
                "TYPE_ID": "SALE",
                "STAGE_ID": "C9:NEW",
                "PROBABILITY": "0",
                "CURRENCY_ID": "RUB",
                "OPPORTUNITY": "30.00",
                "IS_MANUAL_OPPORTUNITY": "N",
                "TAX_VALUE": "0.00",
                "LEAD_ID": null,
                "COMPANY_ID": "0",
                "CONTACT_ID": "275",
                "QUOTE_ID": null,
                "BEGINDATE": "2024-08-20T03:00:00+03:00",
                "CLOSEDATE": "2024-08-27T03:00:00+03:00",
                "ASSIGNED_BY_ID": "1",
                "CREATED_BY_ID": "1",
                "MODIFY_BY_ID": "1",
                "DATE_CREATE": "2025-04-29T00:03:19+03:00",
                "DATE_MODIFY": "2025-05-05T10:17:08+03:00",
                "OPENED": "Y",
                "CLOSED": "N",
                "COMMENTS": "",
                "ADDITIONAL_INFO": null,
                "LOCATION_ID": null,
                "CATEGORY_ID": "9",
                "STAGE_SEMANTIC_ID": "P",
                "IS_NEW": "Y",
                "IS_RECURRING": "N",
                "IS_RETURN_CUSTOMER": "Y",
                "IS_REPEATED_APPROACH": "N",
                "SOURCE_ID": "",
                "SOURCE_DESCRIPTION": "",
                "ORIGINATOR_ID": null,
                "ORIGIN_ID": null,
                "MOVED_BY_ID": "0",
                "MOVED_TIME": "2025-04-29T00:03:19+03:00",
                "LAST_ACTIVITY_TIME": "2025-04-29T13:03:21+03:00",
                "UTM_SOURCE": null,
                "UTM_MEDIUM": null,
                "UTM_CAMPAIGN": null,
                "UTM_CONTENT": null,
                "UTM_TERM": null,
                "PARENT_ID_156": null,
                "PARENT_ID_177": null,
                "LAST_COMMUNICATION_TIME": null,
                "LAST_ACTIVITY_BY": "1",
                "UF_CRM_66976FE3B2425": [],
                "UF_CRM_1723206732": "",
                "UF_CRM_1723206709": "",
                "UF_CRM_1740471712": "",
                "UF_CRM_1723209318": "2025-04-29T03:00:00+03:00",
                "UF_CRM_1722577765": "",
                "UF_CRM_1723188121": ""
            },
        }
        

Пример кода

import { B24Hook } from '@bitrix24/b24jssdk'
        import { createInterface } from 'node:readline/promises'
        
        const $b24 = B24Hook.fromWebhookUrl(process.env.B24_HOOK)
        // B24_HOOK = 'https://your-domain.bitrix24.ru/rest/USER_ID/TOKEN/'
        
        async function call(method, params) {
            const result = await $b24.actions.v2.call.make({ method, params });
            if (!result.isSuccess) {
                throw new Error(result.getErrorMessages().join('; '));
            }
            return result.getData().result;
        }
        
        try {
            // Шаг 1: Получение FIELD_NAME для поля с EDIT_FORM_LABEL "Дата оплаты"
            const fields = await call('crm.deal.userfield.list', {
                filter: {
                    LANG: 'ru',
                    USER_TYPE_ID: 'date'
                }
            });
            const dateField = fields.find(field => field.EDIT_FORM_LABEL === "Дата оплаты");
            if (dateField) {
                const fieldName = dateField.FIELD_NAME;
                console.log("FIELD_NAME для 'Дата оплаты':", fieldName);
        
                // Шаг 2: Запрос ID сделки у пользователя и получение даты оплаты
                const rl = createInterface({ input: process.stdin, output: process.stdout });
                const dealId = await rl.question("Введите ID сделки: ");
                rl.close();
        
                const payments = await call('crm.item.payment.list', {
                    entityId: dealId,
                    entityTypeId: 2
                });
                if (payments.length > 0) {
                    const datePaid = payments[0].datePaid;
                    console.log("Дата оплаты:", datePaid);
        
                    // Шаг 3: Изменение сделки
                    await call('crm.deal.update', {
                        id: dealId,
                        fields: {
                            [fieldName]: datePaid
                        }
                    });
                    console.log("Сделка успешно обновлена");
                }
            }
        } catch (error) {
            console.error(error.message);
        }
        
require_once 'vendor/autoload.php';
        
        use Bitrix24\SDK\Services\ServiceBuilderFactory;
        use Symfony\Component\EventDispatcher\EventDispatcher;
        use Monolog\Logger;
        use Monolog\Handler\StreamHandler;
        
        $logger = new Logger('b24');
        $logger->pushHandler(new StreamHandler('php://stdout'));
        
        $serviceBuilder = (new ServiceBuilderFactory(new EventDispatcher(), $logger))
            ->initFromWebhook('https://your-domain.bitrix24.ru/rest/USER_ID/TOKEN/');
        
        $crm = $serviceBuilder->getCRMScope();
        
        try {
            // Шаг 1: Получение FIELD_NAME для поля с EDIT_FORM_LABEL "Дата оплаты"
            $fields = $crm->dealUserfield()->list(
                [],
                [
                    'LANG' => 'ru',
                    'USER_TYPE_ID' => 'date'
                ]
            )->getUserfields();
        
            $dateField = null;
            foreach ($fields as $field) {
                if ($field->EDIT_FORM_LABEL === "Дата оплаты") {
                    $dateField = $field;
                    break;
                }
            }
        
            if ($dateField) {
                $fieldName = $dateField->FIELD_NAME;
                echo "FIELD_NAME для 'Дата оплаты': " . $fieldName . "\n";
        
                // Шаг 2: Запрос ID сделки у пользователя и получение даты оплаты
                $dealId = readline("Введите ID сделки: ");
                $payments = $serviceBuilder->core->call(
                    'crm.item.payment.list',
                    [
                        'entityId' => $dealId,
                        'entityTypeId' => 2
                    ]
                )->getResponseData()->getResult();
        
                if (count($payments) > 0) {
                    $datePaid = $payments[0]['datePaid'];
                    echo "Дата оплаты: " . $datePaid . "\n";
        
                    // Шаг 3: Изменение сделки
                    $crm->deal()->update(
                        (int)$dealId,
                        [
                            $fieldName => $datePaid
                        ]
                    );
                    echo "Сделка успешно обновлена\n";
                }
            }
        } catch (\Throwable $e) {
            echo "Error: " . $e->getMessage();
        }
        
from b24pysdk import BitrixWebhook, Client
        from b24pysdk.errors import BitrixAPIError
        
        client = Client(
            BitrixWebhook(
                domain="your-domain.bitrix24.com",
                webhook_token="user_id/webhook_key",
            )
        )
        
        try:
            user_fields = client.crm.deal.userfield.list(
                filter={
                    "LANG": "ru",
                    "USER_TYPE_ID": "date",
                }
            ).response.result
        except BitrixAPIError as error:
            print(f"Ошибка: {error}")
        else:
            date_field = next(
                (
                    field
                    for field in user_fields
                    if field.get("EDIT_FORM_LABEL") == "Дата оплаты"
                ),
                None,
            )
        
            if date_field:
                print("FIELD_NAME для 'Дата оплаты':", date_field["FIELD_NAME"])
        
                deal_id = int(input("Введите ID сделки: "))
        
                try:
                    payments = client.crm.item.payment.list(
                        entity_type_id=2,
                        entity_id=deal_id,
                    ).response.result
                except BitrixAPIError as error:
                    print(f"Ошибка: {error}")
                else:
                    if payments:
                        date_paid = payments[0]["datePaid"]
                        print("Дата оплаты:", date_paid)
        
                        try:
                            client.crm.deal.update(
                                bitrix_id=deal_id,
                                fields={
                                    date_field["FIELD_NAME"]: date_paid,
                                },
                            ).response
                        except BitrixAPIError as error:
                            print(f"Ошибка: {error}")
                        else:
                            print("Сделка успешно обновлена")