Содержит описание методов, которые могут быть использованы из программного кода конфигурации 1С для программного взаимодействия с модулем доставки
API Модуля доставки «API-1C»
Версия модуля 2.29
API Модуля доставки «API-1C»
Оглавление
API Модуля доставки «API-1C» 1
Функция РассчитатьИОтправитьВнешниеДанные 2
Функция ДанныеДляОтправкиПоЗаказу 8
Процедура СформироватьПечатныеФормыПоЗаказам 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. Для остальных игнорируется, формируются все возможные печатные формы. |
Процедура УстановитьТихийРежим
Устанавливает признак тихого режима. В этом режиме информационные сообщения, не влияющие на работу модуля, не отображаются.
Параметры:
Имя | Тип | Описание |
Признак | Булево | Включить или выключить тихий режим |