Содержит описание методов, которые могут быть использованы из программного кода конфигурации 1С для программного взаимодействия с модулем доставки

API Модуля доставки «API-1C»

Версия модуля 2.29

API Модуля доставки «API-1C»

Оглавление

API Модуля доставки «API-1C» 1

Изменения 1

Поддерживаемые документы 1

Функция РассчитатьИОтправитьВнешниеДанные 2

Функция ДанныеДляОтправкиПоЗаказу 8

Функция СлужбыДоставки 9

Функция Тарифы 9

Функция ДопУслуги 9

Функция ПВЗ 10

Функция ОбновлениеСтатусов 10

Процедура ПересчитатьМеста 11

Процедура СформироватьПечатныеФормыПоЗаказам 12

Процедура УстановитьТихийРежим 12

Изменения

11.09.2024 – в. 2.29:

+ Описание функции СформироватьПечатныеФормыПоЗаказам

+ Добавлено понятие Поддерживаемые документы для указания в методах

01.10.2023 – в. 2.24.0:

+ Описание функции УстановитьТихийРежим

01.11.2023 – в. 2.25.0:

+ добавлен параметр ЭтоРасчётТарифа в функцию ДанныеДляОтправкиПоЗаказу

Поддерживаемые документы

Модуль работает с документами «Заказ клиента» (в УНФ – «Заказ покупателя»), «Заказ поставщику», «Реализация товаров и услуг». Далее в методах эти документы будут указываться как «Поддерживаемые документы».

Функция РассчитатьИОтправитьВнешниеДанные

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

Параметры:

Имя параметра Тип параметра Описание
Данные Структура. Содержит поля, описанные ниже. Полностью готовую структуру нужного формата можно получить по документу, передав его в функцию «ДанныеДляОтправкиПоЗаказу».

Поля структуры:

Заказ – Поддерживаемые документы, документ, который нужно отправить в службу доставки

Тариф — Число, Необязательный, ID тарифа. Передаётся только если нужно сразу отправить данные в службу доставки без предварительного расчёта тарифа.

ТарифНаРасчёт — Число, Необязательный, ID тарифа. Нужен для того, чтобы в калькуляторе рассчитать только стоимость этого тарифа.

Номер – Строка, Необязательный, номер заказа. Если не передан – будет использован номер заказа из параметра «Заказ».

Штрихкод — Строка, Необязательный, Штрих-код заказа

Комментарий — Строка, Необязательный, Комментарий для службы доставки

Высота — Число, Необязательный, Высота заказа в сантиметрaх

Длина — Число, Необязательный, Длина заказа в сантиметрaх

Ширина — Число, Необязательный, Ширина заказа в сантиметрах

Вес — Число, Вес всего заказа в граммах

БезСтраховки — Булево, Необязательный, Если Истина – страхование отправления не требуется. По умолчанию – Ложь.

СлужбаДоставки — Строка, Код службы доставки

ТипОтправки — Число, Тип отправки груза (1 — от двери, 2 — от ПВЗ)

ТипДоставки — Число, Тип доставки (1 — до двери, 2 — до ПВЗ)

ИДПВЗОтправки — Число, Необязательный, ID пункта отправки, если предполагается доставка до ПВЗ. Если не передано, то будет произведена попытка распознать ПВЗ по адресу доставки, переданному в поле «Отправитель». Если заполнено – Адрес доставки отправителя не обрабатывается (необязателен к передаче).

ИДПВЗДоставки — Число, Необязательный, ID пункта доставки, если предполагается доставка до ПВЗ. Если не передано, то будет произведена попытка распознать ПВЗ по адресу доставки, переданному в поле «Получатель». Если заполнено – Адрес доставки получателя не обрабатывается (необязателен к передаче).

ДатаОтправки — Дата, Необязательный, Предполагаемая дата передачи груза в службу доставки

ДатаДоставки — Дата, Необязательный, Дата доставки

ВремяОтправкиНачало — Дата, Необязательный, Начальное время забора груза

ВремяОтправкиОкончание — Дата, Необязательный, Конечное время забора груза

ВремяДоставкиНачало — Дата, Необязательный, Начальное время доставки

ВремяДоставкиОкончание — Дата, Необязательный, Конечное время доставки

ОбъявленнаяСтоимость — Число, Объявленная оценочная стоимость / сумма страховки (в рублях)

СтоимостьОтправления — Число, Необязательный, Стоимость отправления с учетом НДС (в рублях)

НДС — Число, Необязательный, Процентная ставка НДС. Для «БезНДС» нужно передавать -1, для «НДС0» 0.

СуммаНаложенногоПлатежа — Число, Сумма наложенного платежа с учетом НДС (в рублях). Состоит из СуммаДоставкиДляКлиента + сумма, которую должен оплатить клиент за сам заказ.

СуммаДоставкиДляКлиента — Число, Необязательный, Сумма, которую платит клиент именно за услугу доставки. Входит в сумму наложенного платежа и не может быть больше неё.

Отправитель — Структура, поля: Данные отправителя

Адрес — Строка, Полный адрес отправителя одной строкой

АдресЗначенияПолей — Строка, Значения полей адреса в формате ФИАС. Возможно пустое, если в Модуле подключена интеграция с Дадатой. Должно быть передано либо это поле, либо «АдресДанные». Для отправки от ПВЗ данные берутся из метода получения данных о ПВЗ из модуля.

АдресДанные — Структура, поля: Значения полей адреса с разбивкой. Должно быть передано либо это поле, либо «АдресОтправкиЗначенияПолей».

Индекс — Строка, Необязательный, Почтовый индекс

КодСтраны — Строка, Код страны в соответствии с ISO 3166-1 alpha-2

Страна — Строка, Название страны

Регион — Строка, Область или республика или край

Район — Строка, Необязательный, Район

Город — Строка, Город или населенный пункт

ГородGuid — Строка, Необязательный, ID города в базе ФИАС

Улица — Строка, Улица, с наименованием адресного объекта. Например, «ул. Ленина», «Новорижское шоссе», «б-р Симферопольский»

КодКЛАДРУлицы — Строка, Необязательный, Только для Деловых линий. Код КЛАДР для выбранной улицы. Увеличивает точность определения адреса.

Дом — Строка, Дом

Корпус — Строка, Необязательный, Строение/Корпус

Квартира — Строка, Необязательный, Офис/Квартира

ИмяОрганизации — Строка, Необязательный, Название компании

ИННОрганизации — Строка, Необязательный, ИНН организации-отправителя

КонтактноеЛицо — Строка, ФИО контактного лица

Телефон — Строка, Контактный телефон

Email — Строка, Необязательный, Контактный email адрес

Получатель — Структура, поля:, Данные получателя

Адрес — Строка, Полный адрес отправителя одной строкой

АдресЗначенияПолей — Строка, Значения полей адреса в формате ФИАС. Возможно пустое, если в Модуле подключена интеграция с Дадатой. Должно быть передано либо это поле, либо «АдресДанные». Для доставки до ПВЗ данные берутся из метода получения данных о ПВЗ из модуля.

АдресДанные — Структура, поля: Значения полей адреса с разбивкой. Должно быть передано либо это поле, либо «АдресЗначенияПолей». Если передано это поле, правильность заполнения его элементов не проверяется.

Индекс — Строка, Необязательный, Почтовый индекс

КодСтраны — Строка, Код страны в соответствии с ISO 3166-1 alpha-2

Страна — Строка, Название страны

Регион — Строка, Область или республика или край

Район — Строка, Необязательный, Район

Город — Строка, Город или населенный пункт

ГородGuid — Строка, Необязательный, ID города в базе ФИАС

Улица — Строка, Улица, с наименованием адресного объекта. Например, «ул. Ленина», «Новорижское шоссе», «б-р Симферопольский»

КодКЛАДРУлицы — Строка, Необязательный, Только для Деловых линий. Код КЛАДР для выбранной улицы. Сильно увеличивает точность определения адреса.

Дом — Строка, Дом

Корпус — Строка, Необязательный, Строение/Корпус

Квартира — Строка, Необязательный, Офис/Квартира

ОПФ — Число, Организационно-правовая форма. 1 – ООО, 2 – ИП, 3 — ФизЛицо

ИмяОрганизации — Строка, Необязательный, Название компании

КонтактноеЛицо — Строка, ФИО контактного лица

Телефон — Строка, Контактный телефон

Email — Строка, Необязательный, Контактный email адрес

ИННОрганизации — Строка, Необязательный, ИНН компании-получателя

Места — Массив, строка = Структура, поля:

Место — Строка, Необязательный, Номер места в информационной системе клиента

Штрихкод — Строка, Необязательный, Штрихкод места

Высота — Число, Необязательный, Высота места в сантиметрaх

Длина — Число, Необязательный, Длина места в сантиметрaх

Ширина — Число, Необязательный, Ширина места в сантиметрах

Вес — Число, Вес места в граммах

Товары — Массив, строка = Структура, поля:

Артикул — Строка, Необязательный, Артикул товара

Маркировка — Строка, Необязательный, Код маркировки (UTF-8)

Наименование — Строка, Наименование товара

Количество — Число, Кол-во товара. Если указан Маркировка, то кол-во не может быть > 1

Высота — Число, Необязательный, Высота единицы товара в сантиметрах

Длина — Число, Необязательный, Длина единицы товара в сантиметрах

Ширина — Число, Необязательный, Ширина единицы товара в сантиметрах

Вес — Число, Необязательный, Вес единицы товара в граммах

ОбъявленнаяСтоимость — Число, Необязательный, Оценочная стоимость единицы товара в рублях

Цена — Число, Необязательный, Стоимость единицы товара с учетом НДС в рублях

НДС — Число, Необязательный, Процентная ставка НДС. Для «БезНДС» нужно передавать -1, для «НДС0» 0.

Штрихкод — Строка, Необязательный, Штрихкод на товаре

ДополнительныеУслуги — Соответствие:

Ключ — Строка, Идентификатор дополнительной услуги. Перечень возможных значений получается из соответствующего метода Модуля.

Значение — Строка, Булево, Дата, Число, Значение дополнительной услуги. Перечень возможных значений получается из соответствующего метода Модуля.

Рассчитать Булево, Необязательный нужно ли выполнять расчёт тарифа, по умолчанию — Истина
Отправить Булево, Необязательный нужно ли выполнять отправку заказа в службу доставки, по умолчанию — Истина
СохранитьРезультат Булево, Необязательный нужно ли сохранять результат отправки типовым механизмом модуля, по умолчанию — Истина
ВызыватьИсключение Булево, Необязательный Нужно ли вызывать исключение при ошибках или только вернуть Ложь. По умолчанию — Истина

Возвращает – Истина, если все операции выполнены без ошибок. В случае ошибок – генерируются исключения. Подробности ошибок можно получить из очереди сообщений 1С. В процессе работы, если ошибок не было, в параметр Данные дописываются поля «Тариф» (в случае расчёта тарифа) и «ИдентификаторЗаказа» (в случае успешной отправки заказа). Т.к. заказы отправляются в асинхронном режиме, рекомендуется через какое-то время (от 30 сек) вызвать функцию «ОбновлениеСтатусов» для заказа, который был отправлен.

Функция ДанныеДляОтправкиПоЗаказу

Формирует по заказу данные, которые затем можно передать в функцию РассчитатьИОтправитьВнешниеДанные. Функция может вызываться только для заказов, у которых ещё нет идентификатора заказа (неотправленные заказы). Обычно идентификатор хранится в доп.сведении заказа «(Api-1C) Идентификатор заказа», если это не было перенастроено (https://api-1c.ru/rukovodstvo-polzovatelya-modulya-dostavki-api-1s/#nastroyki-modulya).

Параметры:

Имя Тип Описание
Документ Поддерживаемые документы Ссылка на документ, по которому нужно получить данные.
ЭтоРасчётТарифа Необязательный, Булево, по умолчанию Ложь Позволяет более точно получить данные для расчёта тарифа. При этом, в подавляющем большинстве случаев данные с этим параметром и без него, отличаться не будут. Имеет смысл для редких случаев, например, отправка заказа в СДЭК по тарифу Посылка склад-дверь с указанием адреса как от двери.

Возвращает – Структура, поля соответствуют описанию входящего параметра функции РассчитатьИОтправитьВнешниеДанные.

Функция СлужбыДоставки

Определяет и возвращает перечень подключённых служб доставки.

Параметры отсутствуют.

Возвращает – ТаблицаЗначений, колонки:

  • ИД – строка, идентификатор службы доставки. Например, «cdek», «ext_Dellin»
  • СлужбаДоставки – строка, представление службы доставки. Например, «СДЭК», «Деловые линии»

Функция Тарифы

Определяет и возвращает перечень подключённых служб доставки.

Параметры отсутствуют.

Возвращает – ТаблицаЗначений, колонки:

  • ИД – строка, идентификатор службы доставки. Например, «cdek», «ext_Dellin»
  • Тариф – строка, представление тарифа. Например, «Посылка склад-дверь»
  • СлужбаДоставкиИД – строка, идентификатор службы доставки. Например, «cdek», «ext_Dellin»
  • СлужбаДоставки – строка, представление службы доставки. Например, «СДЭК», «Деловые линии»

Функция ДопУслуги

Определяет и возвращает перечень дополнительных услуг, возможных для определённой службы доставки. Понятие «дополнительные услуги» очень широко и разнообразно трактуется службами доставки, поэтому в перечне могут быть самые разные пункты – от примерки до плательщика за услугу страховки и т.п.

Параметры:

Имя Тип Описание
ИДСлужбыДоставки Строка Идентификатор службы доставки в модуле. Может быть получен из функции «СлужбыДоставки».

Возвращает – Массив, элементы – Структуры, поля:

  • Услуга – Строка, представление услуги
  • Описание – Строка, произвольное описание услуги от службы доставки. Может быть пустым.
  • ИДУслуги – Строка, уникальный идентификатор услуги
  • ТипСтрокой – Строка, строковое представление типа
  • ЗначенияВыбора – Строка, возможные значения для выбора. Может быть пустым

Функция ПВЗ

Возвращает перечень пунктов приёма-выдачи заказов (в т.ч. постаматы, терминалы и т.п.) для заданной службы доставки в заданном городе (населённом пункте).

Параметры:

Имя Тип Описание
ИДСлужбыДоставки Строка Идентификатор службы доставки в модуле. Может быть получен из функции «СлужбыДоставки».
GUIDГорода Строка, Необязательный GUID города согласно ФИАС. Если заполнен параметр «ИмяГорода», то может быть пустым. Рекомендуется передавать именно этот параметр для большей точности определения.
ИмяГорода Строка, Необязательный Наименование города. Если заполнен параметр «GUIDГорода», то может быть пустым. Рекомендуется передавать этот параметр только в том случае, если нет возможности определить GUID города согласно ФИАС, т.к. нет гарантии правильного определения населённого пункта по его имени.

Возвращает – ТаблицаЗначений, колонки:

  • ИД – Строка, идентификатор ПВЗ
  • СлужбаДоставкиИД – Строка, идентификатор службы доставки
  • СлужбаДоставки – Строка, представление службы доставки
  • ТипПВЗ – Строка, тип ПВЗ (постамат, терминал и т.п.)
  • ТипОперации – Строка, возможность отправки и/или выдачи отправлений
  • АдресПВЗ — Строка
  • ГрафикРаботы — Строка
  • Телефоны — Строка
  • ПараметрыПВЗ – Строка в формате JSON, данные о ПВЗ как они приходят в ответе от службы доставки. Содержат всю возможную информацию о ПВЗ
  • ТипПВЗИД – Число, идентификатор типа ПВЗ
  • МожетПриниматьОплату — Булево
  • МожетПриниматьОплатуКартой – Булево

Функция ОбновлениеСтатусов

Возвращает информацию о результате обновления статусов.

Параметры:

Имя Тип Описание
МассивЗаказов Массив, Необязательный, элемент – Поддерживаемые документы Документы, для которых нужно обновить статусы. Если не передан – статусы будут обновлены для всех заказов в базе, которые находятся в работе.

Возвращает – Строка, сообщения об ошибках или успешном выполнении.

Процедура ПересчитатьМеста

Принимает массив мест и пересчитывает нужные места. Массив может быть как сформирован с нуля по указанной структуре, так и получен из сохранённых модулем доп.сведений для заказа.

Параметры:

Имя Тип Описание
МассивМест Массив МассивМест — Массив, на первом уровне — один элемент, описывает Документ, на втором уровне — Места, на третьем — Товары.

Элемент массив — Структура:

«Наименование»: «Заказ …», или «Место 1» или «Товар такой-то»

«НомерСтроки»: 0 — нужен только для уровня Товар, номер строки в таблице товаров в Заказе,

«ЭтоУслуга»: Булево,

«Коды»: Артикул для уровня Товар, Штрихкод для остальных

«Количество»: 3 — количество единиц для уровня Товар, количество позиций для уровня Место, количество мест для уровня Заказ,

«Вес»: 26 — граммы, вес единицы

«Высота»: 20 — сантиметры, высота единицы

«Длина»: 4 — сантиметры, длина единицы

«Ширина»: 30 — сантиметры, ширина единицы

«Объём»: 0.0024 — кубометры, объём единицы

«Цена»: 0,

«СтавкаНДС»: 0 — число, процент ставки, для БезНДС нужно передать -1

«Уровень»: 1 — Заказ, 2 — Место, 3 — Товар, Необязательный

«Картинка»: 1, Необязательный

«УИД»: «1b54e4da-d5d4-448d-bca2-0c2a919c2f9d», Необязательный

«Пересчитать»: Булево, нужно ли пересчитать это место по подчинённым товарам

«Строки»: — Массив, такой же, как вышестоящий

Процедура СформироватьПечатныеФормыПоЗаказам

Формирует печатные формы по документам и сохраняет их в доп.сведения модуля.

Параметры:

Имя Тип Описание
МассивДокументов Массив, элемент = Поддерживаемые документы Документы, для которых нужно получить печатные формы
Акты Булево, Необязательный, по умолчанию = Истина Нужно ли формировать Акты. Работает только для служб ApiShip. Для остальных игнорируется, формируются все возможные печатные формы.
Ярлыки Булево, Необязательный, по умолчанию = Истина Нужно ли формировать Ярлыки (этикетки, наклейки). Работает только для служб ApiShip. Для остальных игнорируется, формируются все возможные печатные формы.

Процедура УстановитьТихийРежим

Устанавливает признак тихого режима. В этом режиме информационные сообщения, не влияющие на работу модуля, не отображаются.

Параметры:

Имя Тип Описание
Признак Булево Включить или выключить тихий режим