Изменить заказ sale.order.update

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

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

Scope: sale

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

Метод sale.order.update изменяет поля заказа и возвращает заказ после изменения.

Позиции корзины, оплаты и отгрузки метод не меняет — для них есть методы sale.basketitem.*, sale.payment.* и sale.shipment.*.

Поля, которые нельзя изменить, метод пропускает без ошибки: ответ будет успешным, но значения останутся прежними. Таких полей две группы:

  • lid, personTypeId, currency, userId — задаются только при создании заказа
  • id, accountNumber, payed, deducted и другие поля только для чтения — их формирует Битрикс24

Какие поля можно изменить, показывают признаки isImmutable и isReadOnly в ответе sale.order.getFields.

Параметры метода

Обязательные параметры отмечены *

Название
тип

Описание

id*
sale_order.id

Идентификатор заказа. Его возвращают методы sale.order.add и sale.order.list

fields*
object

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

Параметр fields

Название
тип

Описание

price
double

Сумма заказа с учетом доставки

discountValue
double

Значение скидки

statusId
sale_status.id

Идентификатор статуса заказа. Список статусов возвращает метод sale.status.list

empStatusId
user.id

Идентификатор пользователя, изменившего статус заказа

dateInsert
datetime

Дата создания заказа

marked
string

Признак того, что заказ отмечен как проблемный. Битрикс24 ставит Y автоматически, если при сохранении заказа возникло предупреждение. Причину Битрикс24 записывает в поле reasonMarked.

  • Y — да
  • N — нет

empMarkedId
user.id

Идентификатор пользователя, поставившего маркировку

reasonMarked
string

Причина, по которой заказ был промаркирован

userDescription
string

Комментарий покупателя к заказу

additionalInfo
string

Устаревший.

Дополнительная информация

comments
string

Комментарий менеджера к заказу

companyId
integer

Идентификатор компании из модуля «Интернет-магазин»

responsibleId
user.id

Идентификатор пользователя, ответственного за заказ

recurringId
string

Идентификатор продления подписки

lockedBy
string

Актуально только для коробочной версии.

Идентификатор пользователя, заблокировавшего заказ. Заказ блокируется в административной панели, когда пользователь открывает детальную карточку заказа

recountFlag
string

Устаревший.

Флаг пересчета.

  • Y — да
  • N — нет

affiliateId
integer

Актуально только для коробочной версии.

Идентификатор аффилиата

updated1c
string

Обновлен ли заказ через 1С.

  • Y — да
  • N — нет

orderTopic
string

Устаревший.

Тема заказа

xmlId
string

Внешний идентификатор

id1c
string

Идентификатор в 1С

version1c
string

Версия в 1С

externalOrder
string

Заказ из внешней системы или нет.

  • Y — да
  • N — нет

canceled
string

Был ли отменен заказ.

  • Y — да
  • N — нет

empCanceledId
user.id

Идентификатор пользователя, отменившего заказ

reasonCanceled
string

Причина отмены

Примеры кода

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

curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"id":300,"fields":{"statusId":"P","responsibleId":1,"comments":"Оплата получена, заказ передан на сборку"}}' \
https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/sale.order.update
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"id":300,"fields":{"statusId":"P","responsibleId":1,"comments":"Оплата получена, заказ передан на сборку"},"auth":"**put_access_token_here**"}' \
https://**put_your_bitrix24_address**/rest/sale.order.update

// 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, ISODate } from '@bitrix24/b24jssdk'

declare const $b24: B24Frame

// Shape of the payload returned in result (match the "response handling" section of the page)
type OrderUpdateResult = {
  order: {
    accountNumber: string
    additionalInfo: string
    affiliateId: number | null
    canceled: string
    clients: Record<string, unknown>[]
    comments: string
    companyId: number | null
    currency: string
    dateCanceled: ISODate | null
    dateInsert: ISODate | null
    dateLock: ISODate | null
    dateMarked: ISODate | null
    dateStatus: ISODate | null
    dateUpdate: ISODate | null
    deducted: string
    discountValue: number
    empCanceledId: number | null
    empMarkedId: number | null
    empStatusId: number
    externalOrder: string
    id: number
    id1c: string
    lid: string
    lockedBy: string
    marked: string
    orderTopic: string
    payed: string
    personTypeId: number
    personTypeXmlId: string
    price: number
    propertyValues: Record<string, unknown>[]
    reasonCanceled: string
    reasonMarked: string
    recountFlag: string
    recurringId: string
    requisiteLink: Record<string, number>
    responsibleId: number
    statusId: string
    statusXmlId: string
    taxValue: number
    updated1c: string
    userDescription: string
    userId: number
    version: number
    version1c: string
    xmlId: string
  }
}

try {
  const response = await $b24.actions.v2.call.make<OrderUpdateResult>({
    method: 'sale.order.update',
    params: {
      id: 300,
      fields: {
        statusId: 'P',
        responsibleId: 1,
        comments: 'Оплата получена, заказ передан на сборку',
      },
    },
    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(result.order.id, result.order.statusId, result.order.price)
  }
} 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 updateOrder() {
    try {
      // Initialize the SDK inside a Bitrix24 frame
      const $b24 = await B24Js.initializeB24Frame()

      const response = await $b24.actions.v2.call.make({
        method: 'sale.order.update',
        params: {
          id: 300,
          fields: {
            statusId: 'P',
            responsibleId: 1,
            comments: 'Оплата получена, заказ передан на сборку',
          },
        },
        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(result.order.id, result.order.statusId, result.order.price)
    } catch (error) {
      // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
      console.error(error)
    }
  }

  document.addEventListener('DOMContentLoaded', updateOrder)
</script>
from b24pysdk.errors import BitrixAPIError, BitrixSDKException

fields = {
    "statusId": "P",
    "responsibleId": 1,
    "comments": "Оплата получена, заказ передан на сборку",
}

try:
    bitrix_response = client.sale.order.update(
        bitrix_id=300,
        fields=fields,
    ).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}")
try {
    $response = $b24Service
        ->core
        ->call(
            'sale.order.update',
            [
                'id' => 300,
                'fields' => [
                    'statusId'      => 'P',
                    'responsibleId' => 1,
                    'comments'      => 'Оплата получена, заказ передан на сборку',
                ],
            ]
        );

    $result = $response
        ->getResponseData()
        ->getResult();

    echo 'Success: ' . print_r($result, true);

} catch (Throwable $e) {
    error_log($e->getMessage());
    echo 'Error updating sale order: ' . $e->getMessage();
}
BX24.callMethod(
    'sale.order.update',
    {
        id: 300,
        fields: {
            statusId: 'P',
            responsibleId: 1,
            comments: 'Оплата получена, заказ передан на сборку',
        }
    },
    function(result)
    {
        if(result.error())
            console.error(result.error());
        else
            console.log(result.data());
    }
);
require_once('crest.php');

$result = CRest::call(
    'sale.order.update',
    [
        'id' => 300,
        'fields' => [
            'statusId' => 'P',
            'responsibleId' => 1,
            'comments' => 'Оплата получена, заказ передан на сборку',
        ]
    ]
);

echo '<PRE>';
print_r($result);
echo '</PRE>';
// client и ctx уже созданы — см. раздел «SDK для Go»
res, err := client.Core().Call(ctx, "sale.order.update", b24.Params{
	"id": 300,
	"fields": b24.Params{
		"statusId":      "P",
		"responsibleId": 1,
		"comments":      "Оплата получена, заказ передан на сборку",
	},
})
if err != nil {
	return fmt.Errorf("sale.order.update: %w", err)
}

// Метод заворачивает ответ в объект с ключом "order".
raw, ok := b24.Unwrap(res.Result, "order")
if !ok {
	return fmt.Errorf("в ответе нет ключа order")
}

var item struct {
	ID            b24.ID `json:"id"`
	AccountNumber string `json:"accountNumber"`
	StatusID      string `json:"statusId"`
	Comments      string `json:"comments"`
}
if err := json.Unmarshal(raw, &item); err != nil {
	return fmt.Errorf("разбор ответа: %w", err)
}
fmt.Println(item.ID, item.AccountNumber, item.StatusID, item.Comments)

Обработка ответа

HTTP-статус: 200

{
    "result": {
        "order": {
            "accountNumber": "300",
            "additionalInfo": "",
            "affiliateId": null,
            "canceled": "N",
            "clients": [
                {
                    "entityId": 2819,
                    "entityTypeId": 3,
                    "id": 1717,
                    "isPrimary": "Y",
                    "orderId": 300,
                    "roleId": 0,
                    "sort": 0
                }
            ],
            "comments": "Оплата получена, заказ передан на сборку",
            "companyId": null,
            "currency": "RUB",
            "dateCanceled": null,
            "dateInsert": "2026-09-28T08:02:16+03:00",
            "dateLock": null,
            "dateMarked": null,
            "dateStatus": "2026-09-28T08:02:16+03:00",
            "dateUpdate": "2026-09-28T08:02:16+03:00",
            "deducted": "N",
            "discountValue": 0,
            "empCanceledId": null,
            "empMarkedId": null,
            "empStatusId": 1,
            "externalOrder": "N",
            "id": 300,
            "id1c": "",
            "lid": "s1",
            "lockedBy": "",
            "marked": "N",
            "orderTopic": "",
            "payed": "N",
            "personTypeId": 1,
            "personTypeXmlId": "",
            "price": 0,
            "propertyValues": [
                {
                    "code": "EMAIL",
                    "id": 11287,
                    "name": "E-Mail",
                    "orderPropsId": 41,
                    "orderPropsXmlId": "bx_60b605ba1d082",
                    "value": null
                },
                {
                    "code": "FIO",
                    "id": 11289,
                    "name": "Ф.И.О.",
                    "orderPropsId": 39,
                    "orderPropsXmlId": "bx_609bec7cc794c",
                    "value": null
                }
            ],
            "reasonCanceled": "",
            "reasonMarked": "",
            "recountFlag": "Y",
            "recurringId": "",
            "requisiteLink": {
                "bankDetailId": 0,
                "mcBankDetailId": 0,
                "mcRequisiteId": 0,
                "requisiteId": 467
            },
            "responsibleId": 1,
            "statusId": "P",
            "statusXmlId": "",
            "taxValue": 0,
            "updated1c": "N",
            "userDescription": "Позвоните перед доставкой",
            "userId": 1,
            "version": 1,
            "version1c": "",
            "xmlId": "bx_6aba02e7a86af"
        }
    },
    "time": {
        "start": 1790575336,
        "finish": 1790575336.994123,
        "duration": 0.9941229820251465,
        "processing": 0,
        "date_start": "2026-09-28T09:02:16+03:00",
        "date_finish": "2026-09-28T09:02:16+03:00",
        "operating_reset_at": 1790575936,
        "operating": 0.22028803825378418
    }
}

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

Название
тип

Описание

result
object

Корневой элемент ответа (подробное описание)

time
time

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

Объект result

Название
тип

Описание

order
sale_order

Заказ после изменения. Кроме полей заказа содержит clients, requisiteLink, propertyValues, а если они есть у заказа — basketItems и shipments. Связанные объекты описаны на странице sale.order.get

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

HTTP-статус: 400

{
    "error": "200540400001",
    "error_description": "order is not exists"
}

Название
тип

Описание

error
string

Строковый код ошибки. Состоит из цифр, латинских букв и знака подчеркивания. Может прийти пустым — тогда причину показывает только error_description

error_description
string

Текст ошибки для разработчика. Не показывайте его конечному пользователю без обработки

Возможные коды ошибок

Статус

Код

Описание

Значение

400

200540400001

order is not exists

Заказа с таким id нет

400

100

Could not find value for parameter {fields}

Не передан параметр fields

400

100

Bitrix\Sale\Order constructor must be is public

Не передан параметр id

400

200040300020

Access Denied

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

400

0

Текст ошибки сохранения

Заказ не сохранен по другой причине, она указана в error_description

Статусы и коды системных ошибок

HTTP-статус: 4xx, 5xx

Описанные ниже ошибки возвращает сам REST API, а не логика конкретного метода. Они могут прийти в ответ на любой метод.

Статус

Код
Текст ошибки

Описание

500

INTERNAL_SERVER_ERROR
Internal server error

Возникла внутренняя ошибка сервера. Повторите вызов, а если ошибка сохраняется, обратитесь к администратору сервера или в техническую поддержку Битрикс24

500

ERROR_UNEXPECTED_ANSWER
Server returned an unexpected response

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

503

QUERY_LIMIT_EXCEEDED
Too many requests

Превышен лимит на интенсивность запросов

429

OPERATION_TIME_LIMIT
Method is blocked due to operation time limit

Метод заблокирован из-за превышения лимита на ресурсоемкость запросов. Блокировка снимается автоматически, когда накопленное время выполнения метода перестает превышать лимит

401

NO_AUTH_FOUND
Wrong authorization data

В запросе нет авторизационных данных: не передан ни access-токен, ни код вебхука

401

INVALID_REQUEST
Https required

Методы вызываются только по протоколу HTTPS

401

OVERLOAD_LIMIT
REST API is blocked due to overload

REST API заблокирован из-за перегрузки. Это ручная индивидуальная блокировка. Чтобы ее снять, обратитесь в техническую поддержку Битрикс24

401

ACCESS_DENIED
REST is available only on commercial plans

REST API доступен только на коммерческих тарифах. У вебхука текст ошибки другой — REST is available only by subscription

401

INVALID_CREDENTIALS
Invalid request credentials

Не найден активный вебхук с указанным идентификатором пользователя и секретным кодом

404

ERROR_METHOD_NOT_FOUND
Method not found!

Метод с таким именем не найден. Имя написано с ошибкой, метода нет в REST API или он недоступен без нужного скоупа

401

insufficient_scope
The request requires higher privileges than provided by the webhook token

Запрос требует более широких прав, чем есть у токена: у вебхука это выданные ему права, у приложения — скоуп. У приложения текст ошибки заканчивается на provided by the access token

401

expired_token
The access token provided has expired

Срок действия access-токена истек

401

user_access_error
The user does not have access to the application

Приложение установлено, но администратор Битрикс24 открыл доступ к нему только конкретным пользователям

403

PORTAL_DELETED
Portal was deleted

Публичная часть сайта закрыта. Чтобы открыть ее на коробочной установке, отключите опцию «Временное закрытие публичной части сайта». Путь к настройке: Рабочий стол > Настройки > Настройки продукта > Настройки модулей > Главный модуль > Временное закрытие публичной части сайта

Продолжите изучение