Для AI-агентов: markdown этой страницы — /docs-content/entities/shipments/fields.md индекс документации — /llms.txt

Поля отгрузки

GET /v1/shipments/fields

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

Примеры

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/shipments/fields" \
  -H "X-Api-Key: YOUR_API_KEY"

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/shipments/fields" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/shipments/fields', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { data } = await res.json()
console.log('Поля отгрузки:', Object.keys(data.fields))

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/shipments/fields', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { data } = await res.json()

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data.fields object Схема полей. Ключ — имя поля, значение — описание поля
data.fields.<поле>.type string Тип значения: number, string, boolean, datetime, array
data.fields.<поле>.readonly boolean true — поле заполняется системой, запись отклоняется с 400 READONLY_FIELD
data.fields.<поле>.required boolean Приходит со значением true и только у полей, обязательных при создании
data.fields.<поле>.readonlyOnUpdate boolean Приходит со значением true и только у полей, которые задаются при создании и не меняются при изменении
data.fields.<поле>.itemSchema object Приходит только у массивов — схема элемента массива
data.fields.<поле>.label string Короткое название поля
data.fields.<поле>.description string Пояснение к полю
data.aggregatable array Поля, по которым разрешена группировка groupBy в агрегации отгрузок
data.batch array Операции, доступные в пакетных вызовах. У отгрузок массив пустой

Поля отгрузки

Полный набор полей, который возвращает GET /v1/shipments/fields. Колонка RO — поле только для чтения.

Поле Тип RO Описание
id number да ID отгрузки
orderId number нет ID заказа. Список: GET /v1/orders. Обязательно при создании. Задаётся только при создании: при изменении отклоняется с 400 READONLY_FIELD, в схеме помечено readonlyOnUpdate
accountNumber string да Номер отгрузки: номер заказа и порядковый номер отгрузки через /, например 1027/2
deliveryId number нет ID службы доставки. Список: GET /v1/delivery-services. Обязательно при создании
deliveryName string да Название службы доставки
deliveryXmlId string да Внешний код службы доставки. null, если не задан
statusId string нет Статус доставки. Список: GET /v1/order-statuses?filter[type]=D
statusXmlId string да Внешний код статуса доставки. null, если не задан
allowDelivery boolean нет Доставка разрешена
dateAllowDelivery datetime да Дата разрешения доставки. null, пока доставка не разрешена
empAllowDeliveryId number да ID сотрудника, разрешившего доставку. null, пока доставка не разрешена
deducted boolean да Отметка «отгружено». Ставится через POST /v1/shipments/:id/ship, снимается через POST /v1/shipments/:id/unship
dateDeducted datetime да Дата последней смены отметки «отгружено» — когда её поставили или сняли. null, пока отметку не ставили
empDeductedId number да ID сотрудника, последним менявшего отметку «отгружено». null, пока отметку не ставили
reasonUndoDeducted string да Причина снятия отметки «отгружено». При снятии через unship остаётся null
canceled boolean да Отменена ли отгрузка
dateCanceled datetime да Дата отмены. null, если отгрузка не отменена
empCanceledId number да ID сотрудника, отменившего отгрузку. null, если отгрузка не отменена
marked boolean да Отмечена ли отгрузка как проблемная
dateMarked datetime да Дата пометки. null, если пометки нет
empMarkedId number да ID сотрудника, поставившего пометку. null, если пометки нет
reasonMarked string да Причина пометки. null, если пометки нет
responsibleId number нет Ответственный сотрудник. Список: GET /v1/users
dateResponsibleId datetime да Дата назначения ответственного
empResponsibleId number да ID сотрудника, назначившего ответственного
priceDelivery number нет Стоимость доставки
basePriceDelivery number нет Базовая стоимость доставки
discountPrice number да Скидка на доставку
customPriceDelivery boolean да Стоимость доставки задана вручную
currency string да Валюта отгрузки, например RUB
companyId number нет ID компании CRM из GET /v1/companies. null, если компания не задана
deliveryDocNum string нет Номер документа отгрузки. null, если не задан
deliveryDocDate datetime нет Дата документа отгрузки. null, если не задана
trackingNumber string нет Трек-номер
trackingStatus string да Статус отслеживания посылки. null, если отслеживания нет
trackingDescription string да Описание статуса отслеживания. null, если отслеживания нет
trackingLastCheck string да Время последней проверки статуса отслеживания. null, если проверки не было
externalDelivery boolean да Признак внешней доставки
system boolean да Системная отгрузка заказа. Подробнее — Отгрузки
comments string нет Комментарий к отгрузке
xmlId string нет Внешний код отгрузки
id1c string да Идентификатор в 1С. null, если отгрузка не синхронизирована с 1С
version1c string да Версия в 1С. null, если отгрузка не синхронизирована с 1С
updated1c boolean да Обновлена ли отгрузка через 1С
dateInsert datetime да Дата создания
shipmentItems array да Позиции отгрузки. Приходят в ответе GET /v1/shipments/:id, меняются через позиции отгрузок

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

JSON 
{
  "success": true,
  "data": {
    "fields": {
      "accountNumber": {
        "type": "string",
        "readonly": true,
        "label": "accountNumber",
        "description": "Поле Битрикс24 accountNumber."
      },
      "allowDelivery": {
        "type": "boolean",
        "readonly": false,
        "label": "Доставка разрешена",
        "description": "Доставка разрешена."
      },
      "basePriceDelivery": {
        "type": "number",
        "readonly": false,
        "label": "Базовая стоимость доставки",
        "description": "Базовая стоимость доставки."
      },
      "canceled": {
        "type": "boolean",
        "readonly": true,
        "label": "canceled",
        "description": "Поле Битрикс24 canceled."
      },
      "comments": {
        "type": "string",
        "readonly": false,
        "label": "Комментарий",
        "description": "Комментарий."
      },
      "companyId": {
        "type": "number",
        "readonly": false,
        "label": "ID компании",
        "description": "ID компании."
      },
      "currency": {
        "type": "string",
        "readonly": true,
        "label": "currency",
        "description": "Поле Битрикс24 currency."
      },
      "customPriceDelivery": {
        "type": "boolean",
        "readonly": true,
        "label": "Ручная стоимость доставки",
        "description": "Ручная стоимость доставки."
      },
      "dateAllowDelivery": {
        "type": "datetime",
        "readonly": true,
        "label": "dateAllowDelivery",
        "description": "Поле Битрикс24 dateAllowDelivery."
      },
      "dateCanceled": {
        "type": "datetime",
        "readonly": true,
        "label": "dateCanceled",
        "description": "Поле Битрикс24 dateCanceled."
      },
      "dateDeducted": {
        "type": "datetime",
        "readonly": true,
        "label": "dateDeducted",
        "description": "Поле Битрикс24 dateDeducted."
      },
      "dateInsert": {
        "type": "datetime",
        "readonly": true,
        "label": "Дата создания",
        "description": "Дата создания."
      },
      "dateMarked": {
        "type": "datetime",
        "readonly": true,
        "label": "dateMarked",
        "description": "Поле Битрикс24 dateMarked."
      },
      "dateResponsibleId": {
        "type": "datetime",
        "readonly": true,
        "label": "dateResponsibleId",
        "description": "Поле Битрикс24 dateResponsibleId."
      },
      "deducted": {
        "type": "boolean",
        "readonly": true,
        "label": "Отгружено",
        "description": "Отметка об отгрузке; используйте POST /v1/shipments/:id/ship или /unship. Складской учёт может списать остатки."
      },
      "deliveryDocDate": {
        "type": "datetime",
        "readonly": false,
        "label": "Дата документа отгрузки",
        "description": "Дата документа отгрузки."
      },
      "deliveryDocNum": {
        "type": "string",
        "readonly": false,
        "label": "Номер документа отгрузки",
        "description": "Номер документа отгрузки."
      },
      "deliveryId": {
        "type": "number",
        "readonly": false,
        "required": true,
        "label": "ID службы доставки",
        "description": "ID службы доставки из GET /v1/delivery-services; см. /docs/entities/delivery-services."
      },
      "deliveryName": {
        "type": "string",
        "readonly": true,
        "label": "deliveryName",
        "description": "Поле Битрикс24 deliveryName."
      },
      "deliveryXmlId": {
        "type": "string",
        "readonly": true,
        "label": "deliveryXmlId",
        "description": "Поле Битрикс24 deliveryXmlId."
      },
      "discountPrice": {
        "type": "number",
        "readonly": true,
        "label": "discountPrice",
        "description": "Поле Битрикс24 discountPrice."
      },
      "empAllowDeliveryId": {
        "type": "number",
        "readonly": true,
        "label": "empAllowDeliveryId",
        "description": "Поле Битрикс24 empAllowDeliveryId."
      },
      "empCanceledId": {
        "type": "number",
        "readonly": true,
        "label": "empCanceledId",
        "description": "Поле Битрикс24 empCanceledId."
      },
      "empDeductedId": {
        "type": "number",
        "readonly": true,
        "label": "empDeductedId",
        "description": "Поле Битрикс24 empDeductedId."
      },
      "empMarkedId": {
        "type": "number",
        "readonly": true,
        "label": "empMarkedId",
        "description": "Поле Битрикс24 empMarkedId."
      },
      "empResponsibleId": {
        "type": "number",
        "readonly": true,
        "label": "empResponsibleId",
        "description": "Поле Битрикс24 empResponsibleId."
      },
      "externalDelivery": {
        "type": "boolean",
        "readonly": true,
        "label": "externalDelivery",
        "description": "Поле Битрикс24 externalDelivery."
      },
      "id": {
        "type": "number",
        "readonly": true,
        "label": "ID отгрузки",
        "description": "ID отгрузки."
      },
      "id1c": {
        "type": "string",
        "readonly": true,
        "label": "id1c",
        "description": "Поле Битрикс24 id1c."
      },
      "marked": {
        "type": "boolean",
        "readonly": true,
        "label": "marked",
        "description": "Поле Битрикс24 marked."
      },
      "orderId": {
        "type": "number",
        "readonly": false,
        "readonlyOnUpdate": true,
        "required": true,
        "label": "ID заказа",
        "description": "ID заказа. Поиск: GET /v1/orders."
      },
      "priceDelivery": {
        "type": "number",
        "readonly": false,
        "label": "Стоимость доставки",
        "description": "Стоимость доставки."
      },
      "reasonMarked": {
        "type": "string",
        "readonly": true,
        "label": "reasonMarked",
        "description": "Поле Битрикс24 reasonMarked."
      },
      "reasonUndoDeducted": {
        "type": "string",
        "readonly": true,
        "label": "reasonUndoDeducted",
        "description": "Поле Битрикс24 reasonUndoDeducted."
      },
      "responsibleId": {
        "type": "number",
        "readonly": false,
        "label": "ID ответственного",
        "description": "ID ответственного."
      },
      "statusId": {
        "type": "string",
        "readonly": false,
        "label": "statusId",
        "description": "Поле Битрикс24 statusId."
      },
      "statusXmlId": {
        "type": "string",
        "readonly": true,
        "label": "statusXmlId",
        "description": "Поле Битрикс24 statusXmlId."
      },
      "system": {
        "type": "boolean",
        "readonly": true,
        "label": "Системная отгрузка",
        "description": "Системная отгрузка."
      },
      "trackingDescription": {
        "type": "string",
        "readonly": true,
        "label": "trackingDescription",
        "description": "Поле Битрикс24 trackingDescription."
      },
      "trackingLastCheck": {
        "type": "string",
        "readonly": true,
        "label": "trackingLastCheck",
        "description": "Поле Битрикс24 trackingLastCheck."
      },
      "trackingNumber": {
        "type": "string",
        "readonly": false,
        "label": "Трек-номер",
        "description": "Трек-номер."
      },
      "trackingStatus": {
        "type": "string",
        "readonly": true,
        "label": "trackingStatus",
        "description": "Поле Битрикс24 trackingStatus."
      },
      "updated1c": {
        "type": "boolean",
        "readonly": true,
        "label": "updated1c",
        "description": "Поле Битрикс24 updated1c."
      },
      "version1c": {
        "type": "string",
        "readonly": true,
        "label": "version1c",
        "description": "Поле Битрикс24 version1c."
      },
      "xmlId": {
        "type": "string",
        "readonly": false,
        "label": "Внешний код",
        "description": "Внешний код."
      },
      "shipmentItems": {
        "type": "array",
        "readonly": true,
        "label": "Позиции отгрузки",
        "description": "Позиции в ответе get; управление через /v1/shipment-items.",
        "itemSchema": {
          "type": "object"
        }
      }
    },
    "aggregatable": [
      "orderId",
      "priceDelivery",
      "deliveryId"
    ],
    "batch": []
  }
}

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

401 — не передан API-ключ:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key required. Pass via X-Api-Key header."
  }
}

Ошибки

HTTP Код Описание
403 SCOPE_DENIED API-ключ не имеет скоупа sale
401 MISSING_API_KEY Не передан заголовок X-Api-Key
401 TOKEN_MISSING API-ключ не имеет настроенных токенов
429 RATE_LIMITED Превышен лимит запросов: 300 в минуту на портал, все API-ключи портала делят один лимит. Точное значение — в заголовке x-ratelimit-limit (потолок делится на реплики). Повторите после срока из заголовка Retry-After

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

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