Создание заказа в курьерской службе

Метод предназначен для создания заказа на доставку товаров в информационной системе курьерской службы. Когда заказ готов к отправке на стороне Золотого Яблока, ИС отправляет запрос с информацией об отправителе, получателе, параметрах доставки и содержимом отправления. В качестве будущего трек-номера используется уникальный номер заказа, который также передаётся. Трек-номер обеспечивает возможность отслеживания заказа и получения связанных состояний. Статусная модель представлена в соответствующем справочнике, см. Приложение: Справочник статусов заказа. Эндпоинт должен быть опубликован по защищенному протоколу HTTPS.

Основная информация

Тип метода запроса	POST
Путь/URL	/api/v1/orders
Описание	Метод для отправки заказа от ИС Золотого Яблока в ИС курьерской службы
Направление	Запрос выполняется ИС Золотого Яблока. Ответ предоставляется курьерской службой.

Запрос

Параметры заголовка

Параметр	Тип данных	Обязательность	Описание	Комментарий
Authorization	string	1	Access token, полученный при авторизации. Передаётся в формате `Bearer <access_token>`	Формат передаёт курьерская служба (см. Авторизация в сервисе ВКС)
content-type	string	1	Тип содержимого запроса	Заполняется "application/json"

Параметры запроса

№	Параметр			Тип данных	Обязательность	Описание	Комментарий
1	orderNumber			string	1	Номер заказа ЗЯ	Внутренний номер заказа в ИС Золотого Яблока. Трек-номер.
2	deliveryServiceCode			string	1	Код курьерской службы	Оговаривается при интеграции с системой.
3	courierTariffCode			string	1	Код тарифа ВКС	Оговаривается при интеграции с системой.
4	isOrderFirstSend			boolean	1	Признак первой отправки	Правило заполнения: Если заказ создается в первый раз, заполнять значением "true" Если заказ был скорректирован или выгружен повторно (даже без корректировок), заполнять значением "false"
5	isOrderModified			boolean	1	Признак изменения состава заказа	Правило заполнения: Если isFirstSend = false И состав заказа был изменен, заполнять значением "true" Если isFirstSend = false И состав заказа НЕ был изменен, заполнять значением "false" Если isFirstSend = true, поле не отправлять
6	needCustomerNotification			boolean	1	Флаг отправки уведомлений со стороны ВКС.	Правило заполнения: Если флаг включен - тогда передаём уведомления клиенту любым способом доступным ИС ВКС; Если флаг выключен - тогда не передаём никаких, то есть уведомления от ВКС вообще не передаются.
7	senderName			string	1	Наименование отправителя	Например: ООО "Екатеринбург Яблоко"
8	shippingWarehouse			object	1
9		code		string	1	Внутренний код склада ЗЯ	Код склада Золотого Яблока. Например: "225"
10		manager		string	0	Управляющий склада, менеджер	Ф.И.О. в свободной строковой форме.
11		phone		string	0	Телефон управляющего складом	Без спецсимволов, только цифры (код страны и федеральный код)
12	locationFrom			object	1	Объект адреса отправителя посылки
13		Address object type		object	1	Объект, содержащий адресную информацию.	Адресный объект (см. Приложение: Адресные типы данных)
14	recipient			object	1	Объект с информацией о получателе
15		name		string	1	Ф.И.О. получателя в свободной строковой форме	Например: Иванов Иван Иванович
16		phone		string	1	Телефон получателя	Без спецсимволов, только цифры (код страны и федеральный код)
17		email		string	0	Email получателя	В формате email согласно обощённому "ISO 27000"
18	pickpointId			string	1 - если доставка до ПВЗ 0 - если доставка до двери	Код ПВЗ курьерской службы	Передаётся, если доставка осуществляется в пункт выдачи (ПВЗ)
19	locationTo			object	1 - если доставка до двери 0 - если доставка до ПВЗ	Адрес получателя посылки	Передаётся, если доставка осуществляется курьером на адрес клиента
20		Address object type		object	1	Объект, содержащий адресную информацию.	Адресный объект (см. Приложение: Адресные типы данных)
21	package			array of objects	1	Массив объектов отправления
22		barcode		string	1	Штрихкод посылки	Например: "M-095359727A"
23		weight		integer	1	Общий вес посылки (в граммах)	Например: "1000"
24		length		decimal	1	Габариты упаковки. Длина (в см)	Например: "20"
25		width		decimal	1	Габариты упаковки. Ширина (в см)	Например: "15"
26		height		decimal	1	Габариты упаковки. Высота (в см)	Например: "18"
27		isPartialBuy		boolean	1	Признак частичного выкупа для посылки	Заполняется истинно, если может быть выкуплена не полностью (частично)
28		isTryOnAllowed		boolean	1	Признак примерки для посылки	Заполняется истинно, если может быть выдана на примерку
29		totalAmount		decimal	1	Цена товаров посылки (доставка не включена)	Например: "222.43"
30		declaredAmount		decimal	1	Объявленная ценность посылки (доставка не включена)	Например: "252.43"
31		paymentAmount		decimal	1	Сумма к оплате за товары посылки
32		courierComment		string	0	Комментарий или уточнение по посылке	Частичная доставка запрещена! Вскрытие запрещено!
33		items		array of objects	1	Массив объектов товаров посылки
34			name	string	1	Наименование товара	Например: "DARLING Маска тканевая, увлажняющая, восстанавливающая"
35			warekey	string	1	Артикул товара	Например: "19000181104"
36			quantity	integer	1	Количество единиц одноименного товара (шт)	Например: 3
37			weight	number	1	Вес товара (в граммах)	Например: 200
38			isPartialBuy	boolean	1	Признак частичного выкупа для товара	Заполняется истинно, если может быть выкуплена только часть партии
39			isTryOnAllowed	boolean	1	Признак необходимости примерки для заказа	Заполняется истинно, если товар может быть выдан на примерку
40			priceAmount	decimal	1	Общая стоимость единицы товара	Цена одной единицы товара. Например: 562.1
41			declaredAmount	decimal	1	Объявленная стоимость единицы товара	Объявленная стоимость одной единицы товара. Например: 564.5
42			paymentAmount	decimal	1	Сумма к оплате за единицу товара Если заказ предоплачен, значение = 0 Если заказ НЕ оплачен, значение > 0	2449.67
43			vatRate	integer	1	Ставка НДС, включенная в стоимость товара	Ставка указывается за 1 единицу товара. Например: 20
44			vatSum	decimal	1	Сумма НДС при постоплате заказа (за штуку)	112.4
45	shipmentDate			date	1	Дата отгрузки	Согласно стандарту "ISO 8601". Формат: YYYY-MM-DDTHH:mm:ssZ
46	shipmentTimeIntervalFrom			date	0	Начало интервала отгрузки	Согласно стандарту "ISO 8601". Формат: HH:mm
47	shipmentTimeIntervalTo			date	0	Конец интервала отгрузки	Согласно стандарту "ISO 8601". Формат: HH:mm
48	deliveryDate			date	1	Дата доставки	Согласно стандарту "ISO 8601". Формат: YYYY-MM-DDTHH:mm:ssZ
49	deliveryTimeIntervalFrom			date	1	Начало интервала доставки	Согласно стандарту "ISO 8601". Формат: HH:mm
50	deliveryTimeIntervalTo			date	1	Конец интервала доставки	Согласно стандарту "ISO 8601". Формат: HH:mm
51	deliveryPaymentAmount			object	1	Объект стоимости услуги доставки
52		declaredAmount		decimal	1	Объявленная ценность доставки	Объявленная ценность доставки передаваемая от ИС ЗЯ
53		paymentAmount		decimal	1	Сумма к оплате за услуги доставки
54		vatRate		integer	0	Ставка НДС за услугу доставки
55		vatSum		decimal	1	Сумма НДС за услугу доставки
56		displayedAmount		decimal	1	Стоимость доставки для клиента	Стоимость доставки для конечного пользователя, транслируемая на чекауте
57	orderPaymentAmount			object	1	Объект стоимости заказа
58		declaredAmount		decimal	1	Объявленная ценность заказа	Указывается сумма ОЦ за весь заказ. Например: 1200
59		totalAmount		decimal	1	Общая стоимость заказа	Указывается стоимость всего заказа. Например: 1000
60		amountToCollect		decimal	1	Сумма оплаты с клиента	Например: 500, если оплата не взимается, то 0. Для определения точной суммы постоплаты необходимо использовать значение данного поля
61		currency		string	1	Валюта	Согласно стандарту "ISO 4217"
62	returnWarehouse			object	0	Объект адреса возвратного склада
63		code		string	0	Внутренний код склада ЗЯ	Код склада Золотого Яблока. Например: "225"
64		Address object type		object	0	Объект, содержащий адресную информацию.	Адресный объект (см. Приложение: Адресные типы данных)

Пример запроса

{
  "orderNumber": "IAQ-126543",
  "deliveryServiceCode": "EXAMPLE_CS",
  "courierTariffCode": "123",
  "isOrderFirstSend": true,
  "isOrderModified": false,
  "needCustomerNotification": false,
  "senderName": "Общество с ограниченной ответственностью Екатеринбург Яблоко",
  "shippingWarehouse": {
    "code": "225",
    "manager": "Иванов Иван Иванович",
    "phone": "79123456780"
  },
  "locationFrom": {
    "addressType": "gar",
    "fullAddress": "214014, г  Смоленск, ул. Мира, д 7",
    "regionFias": "ed36085a-b2f5-454f-b9a9-1c9a678ee618",
    "cityFias": "2763c110-cb8b-416a-9dac-ad28a55b4402",
    "houseFias": "395bc31a-9fda-4804-a01b-13d79c15e3cb",
    "flat": "54",
    "latitude": 58.0167,
    "longitude": 56.235,
    "addressComment": "Распределительный центр, отгрузка"
  },
  "recipient": {
    "name": "Пётр Петров",
    "phone": "79999999999",
    "email": "petr.petrov@gmail.com"
  },
  "pickpointId": null,
  "locationTo": {
    "addressType": "coord",
    "fullAddress": "614054, г. Пермь, ул. Еловская 1-я, д. 5.",
    "cityFias": "2763c110-cb8b-416a-9dac-ad28a55b4402",
    "latitude": 58.0167,
    "longitude": 56.235,
    "flat": "5",
    "addressComment": "Домофон не работает"
  },
  "package": [
    {
      "barcode": "M-095359727A",
      "weight": 438,
      "length": 20,
      "width": 15,
      "height": 18,
      "isPartialBuy": true,
      "isTryOnAllowed": false,
      "totalAmount": 540.0,
      "declaredAmount": 600.0,
      "courierComment": "Частичная доставка запрещена! Вскрытие запрещено!",
      "items": [
        {
          "name": "DARLING",
          "warekey": "19000314269",
          "quantity": 3,
          "weight": 200,
          "isPartialBuy": false,
          "isTryOnAllowed": true,
          "priceAmount": 180.0,
          "declaredAmount": 200.0,
          "vatRate": 20,
          "vatSum": 10.0
        }
      ]
    }
  ],
  "shipmentDate": "2025-04-06T00:00:00Z",
  "shipmentTimeIntervalFrom": "08:00",
  "shipmentTimeIntervalTo": "10:00",
  "deliveryDate": "2025-04-07T00:00:00Z",
  "deliveryTimeIntervalFrom": "10:00",
  "deliveryTimeIntervalTo": "18:00",
  "deliveryPaymentAmount": {
    "declaredAmount": 45.0,
    "displayedAmount": 39.9
  },
  "orderPaymentAmount": {
    "declaredAmount": 645.00,
    "totalAmount": 579.90,
    "amountToCollect": 0.00,
    "vatSum": 100.00,
    "currency": "RUB"
  },
  "returnWarehouse": {
    "code": "333",
    "addressType": "coord",
    "fullAddress": "191014, г Санкт-Петербург, ул. Мира, д 7",
    "cityFias": "2763c110-cb8b-416a-9dac-ad28a55b4402",
    "latitude": 59.791517,
    "longitude": 30.120332,
    "flat": null,
    "addressComment": "Разгрузка со стороны главных ворот территории"
  }
}

Ответ

Коды ответов и сообщений

Код	Статус	Сообщение	Причина
200	ОК	Order has been created	Все прошло успешно. Заказ создан в ИС курьерской службы
400	Bad Request	Missing or inappropriate required parameters	Не переданы или некорректно заполнены обязательные поля. В теле ответа должны быть указаны наименования полей, не прошедших валидацию, в произвольном формате строкой.
401	Unauthorized	Token is invalid	Ошибка аутентификации в КС
403	Forbidden	Has no permission	Запрещено в текущем контексте
500	Internal Server Error	Server unavailable	Сервер недоступен

Параметры успешного ответа

Параметр	Тип данных	Обязательность	Описание	Комментарий
ecsOrderNumber	string	1	Идентификатор заказа в КС	Номер заказа на доставку, назначенный в ИС курьерской службы.
orderNumber	string	1	Номер заказа ЗЯ, отправленный в запросе	Внутренний номер заказа в ИС Золотого Яблока. Трек-номер
createdAt	date	1	Дата и время регистрации заказа	Согласно стандарту "ISO 8601", UTC0 (YYYY-MM-DDThh:mm:ssZ)

Пример успешного ответа

{
    "ecsOrderNumber": "f91ae5a4-3b1c-4e7a-8c29-72b1db2025a1",
    "orderNumber": "IAQ-126543",
    "createdAt": "2025-05-10T10:41:22Z"
}

Параметры неуспешного ответа

Параметр	Тип данных	Обязательность	Описание
errorMessage	string	1	Человекочитаемое сообщение об ошибке
errorCode	string	0	см. Приложение: Справочник кодов ошибок

Пример неуспешного ответа

{
  "errorMessage": "Missing or inappropriate required parameters",
  "errorCode": "Addr_01"
}

Основная информация​

Запрос​

Параметры заголовка​

Параметры запроса​

Пример запроса​

Ответ​

Коды ответов и сообщений​

Параметры успешного ответа​

Пример успешного ответа​

Параметры неуспешного ответа​

Пример неуспешного ответа​