Заказы

Управление заказами интернет-магазина: создание, получение, обновление, удаление, поиск, агрегация. Заказ — корневая сущность интернет-магазина: с него начинается путь покупателя, к нему привязываются позиции корзины, оплаты, отгрузки и статусы.

Битрикс24 API: sale.order.* Скоуп: sale

Создать заказ

POST /v1/orders

Создаёт новый заказ интернет-магазина. Тело запроса плоское — без обёртки fields.

Поля запроса (body)

Поле Тип Обяз. Описание
lid string да Идентификатор сайта-источника. Для облачных порталов всегда "s1"
personTypeId number да Идентификатор типа плательщика. На каждом портале свой набор типов (юр. лицо, физ. лицо и т. п.). ID можно увидеть в существующих заказах через `GET /v1/orders` или `POST /v1/orders/aggregate` с groupBy: "personTypeId"
currency string да Валюта заказа. Список: `GET /v1/currencies`
price number нет Общая сумма заказа
statusId string нет Статус заказа. По умолчанию — "N" (новый). Список: `GET /v1/order-statuses?filter[type]=O`
userId number нет Идентификатор пользователя Битрикс24 — покупателя в интернет-магазине. Источник: `GET /v1/users`. Если не передать — Битрикс24 проставит пользователя по умолчанию
companyId number нет Идентификатор CRM-компании, связанной с заказом. Источник: `GET /v1/companies`
responsibleId number нет Ответственный сотрудник. Источник: `GET /v1/users`
comments string нет Комментарий менеджера к заказу
userDescription string нет Комментарий покупателя к заказу
xmlId string нет Внешний идентификатор для синхронизации с внешними системами
canceled boolean нет Отменён ли заказ
reasonCanceled string нет Причина отмены
discountValue number нет Значение скидки

Полный список полей — `GET /v1/orders/fields`.

Примеры

curl — личный ключ

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/orders" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "lid": "s1",
    "personTypeId": 5,
    "currency": "RUB",
    "price": 12500,
    "statusId": "N",
    "userId": 1,
    "comments": "Заказ из мобильного приложения"
  }'

curl — OAuth-приложение

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/orders" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "lid": "s1",
    "personTypeId": 5,
    "currency": "RUB",
    "price": 12500,
    "statusId": "N",
    "userId": 1,
    "comments": "Заказ из мобильного приложения"
  }'

JavaScript — личный ключ

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/orders', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    lid: 's1',
    personTypeId: 5,
    currency: 'RUB',
    price: 12500,
    statusId: 'N',
    userId: 1,
    comments: 'Заказ из мобильного приложения',
  }),
})

const { success, data } = await res.json()
console.log('Order ID:', data.id)

JavaScript — OAuth-приложение

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/orders', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    lid: 's1',
    personTypeId: 5,
    currency: 'RUB',
    price: 12500,
    statusId: 'N',
    userId: 1,
    comments: 'Заказ из мобильного приложения',
  }),
})

const { success, data } = await res.json()

Поля ответа

Возвращается полный объект созданного заказа со всеми полями.

Поле Тип Описание
id number Идентификатор созданного заказа
accountNumber string Порядковый номер заказа на портале (генерируется автоматически)
dateInsert datetime Дата создания
dateStatus datetime Дата установки текущего статуса

Остальные поля — см. Поля заказа.

URL заказа в Битрикс24 строится из id:

https://<portal>.bitrix24.ru/shop/orders/details/<id>/

<portal> — домен портала. Доступ ограничен правами сотрудника в Битрикс24.

Пример ответа

JSON 
{
  "success": true,
  "data": {
    "id": 859,
    "accountNumber": "450",
    "lid": "s1",
    "personTypeId": 5,
    "currency": "RUB",
    "price": 12500,
    "discountValue": 0,
    "taxValue": 0,
    "statusId": "N",
    "dateInsert": "2026-05-13T11:42:18.000Z",
    "dateUpdate": "2026-05-13T11:42:18.000Z",
    "dateStatus": "2026-05-13T11:42:18.000Z",
    "payed": false,
    "canceled": false,
    "marked": false,
    "responsibleId": 1,
    "userId": 1,
    "companyId": null,
    "clients": [
      { "entityTypeId": 3, "entityId": 2471, "isPrimary": true, "roleId": 0, "sort": 0 }
    ],
    "comments": "Заказ из мобильного приложения",
    "xmlId": "",
    "externalOrder": false
  }
}

Пример ответа при ошибке

422 — не переданы обязательные поля:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Required fields: personTypeId, currency, lid"
  }
}

Ошибки

HTTP Код Описание
422 BITRIX_ERROR Не переданы обязательные поля — сообщение содержит их список (Required fields: ...)
400 READONLY_FIELD Передано поле только для чтения — accountNumber, payed, даты оплаты и статуса и другие
403 SCOPE_DENIED API-ключ не имеет скоупа sale
401 TOKEN_MISSING API-ключ не имеет настроенных токенов

Полный список общих ошибок API — Ошибки.

Известные особенности

Ссылки на справочники не проверяются. Существование statusId, userId, personTypeId, companyId при создании не проверяется — несуществующие значения принимаются без ошибки. Заказ создаётся с переданными значениями, целостность ссылок остаётся на стороне приложения.

statusId усекается до 2 символов. Значение длиннее двух символов сохраняется обрезанным без ошибки: statusId: "ZZZ" сохранится как "ZZ". Используйте только реальные двухсимвольные коды статусов из `GET /v1/order-statuses`.

Поля только для создания. price, marked и reasonMarked применяются при создании заказа, но на обновлении `PATCH /v1/orders/:id` игнорируются. Чтобы изменить сумму после создания, меняйте позиции корзины через `/v1/basket-items`.

payed нельзя установить. Поле «оплачен» управляется подсистемой оплат — при создании и обновлении оно игнорируется и возвращает false. Попытка передать payed отклоняется с 400 READONLY_FIELD. Оплату регистрируйте через `POST /v1/payments`.

Номер счёта генерируется автоматически. Поле accountNumber присваивается при создании. Передавать его в запросе нельзя — попытка отклоняется с 400 READONLY_FIELD.

Позиции корзины и оплаты добавляются отдельно. Заказ — это контейнер. После POST /v1/orders для добавления товаров вызовите `POST /v1/basket-items` с orderId, для регистрации оплаты — `POST /v1/payments`.

Смотрите также