Реализация/пример обменов API и Http сервисов 1С с 3pl ART Logistik

Реализация\пример обменов API и Http сервисов 1С с 3pl ART Logistik

Данный пример значительно ускорит написание обмена интеграции 1С с 3pl ART Logistik.

Для отправки данных о поставке в систему ART Logistik и отслеживания статуса поставки используется HTTP API ART Logistik.

Документация API ART Logistik:
https://api-prod.arvato.ru/index.html

Документация OpenAPI:
https://api-prod.arvato.ru/resources/openapi/openapi.json

• 1. Аутентификация
• Доступ к API точкам осуществляется с использованием JWT токена.
• Время жизни JWT токена: 24 часа (API отдает значение «3600»)
• Получение и обновление токена выполняется через API точку /account/login.
• Для аутентификации требуется передача логина и пароля в теле запроса.

Документация API точки аутентификации:
https://api-prod.arvato.ru/index.html?lang=ru#/login/login

В теле запроса передаются логин и пароль. В заголовках ответа приходит JWT токен (заголовок authorization) и время жизни токена в секундах (заголовок expires).

Для аутентификации при использовании API точек ART Logistik необходимо передавать JWT токен (вместе со схемой Bearer) в заголовке запроса Authorization.

При разработке этапа B2B использовался следующий подход:
«Токен хранится в параметрах сеанса. На данный момент токен обновляется при срабатывании регламентного задания.»

1. 2. API Content Type

API ART Logistik поддерживает обмен данными в формате JSON (application/json) и XML (application/xml). Согласование типа формата происходит посредствам использования заголовков запроса:

• Content-Type заголовок для указания передаваемого типа;
• Accept заголовок для указания ожидаемого типа.

1. 3. Входящие интерфейсы (исходящие для 1С)

Входящие интерфейсы – это набор API точек для передачи данных или заданий в систему ART Logistik.

Используемые HTTP методы, типы данных параметров запросов и статусы ответов от этих точек описаны в OpenAPI документации. Внимание на эти детали при описании точек уделяться не будет.

• Отправка данных о заказах 050325

API точка: /order/import

Данная точка используется для отправки заказа клиента. Точка принимает POST-запрос с данными клиента и заказа из документа 1С «ЗаказКлиента» (маппинг полей описан ниже по ссылке на таблицу 1). Результатом вызова точки является загрузка заказа клиента в систему и последующее выполнение этого заказа (сборка и отгрузка).

Запрос с параметром «CREATE» отправляется в Арвато в двух случаях:

1. 1. Отправка нового заказа
   2. Отправка измененного заказа

Запрос с параметром «CANCEL» отправляется в Арвато в случае отмены заказа.
Условия отправки отмены заказа будут описаны в другом ТЗ.

При отправке запроса на создание, изменение или отмену заказа в Арвато, создается запись в РС «Arvato_ОтправкаЗаказаЛог», в которой записывается номер заказа, текст запроса, текст ответа, время получения ответа, параметр (“CREATE” или “CANCEL”), статус отправки заказа (“OK” или “ERROR”).

Структура РС «Arvato_ОтправкаЗаказаЛог» описана ниже.

Детали по работе метода:

• На каждый физический товар необходимо передавать отдельную строку в запросе заказа. Это значит одном в массиве <order-row> на каждый уникальный КМ и везде <amount> будет 1.
• До наступления статуса заказа «FULFILLMENT_STARTED» можно обновить заказ. Для этого отсылается новый заказ полностью. При обновлении можно убирать позиции и менять адрес доставки.
• После наступления «FULFILLMENT_STARTED» и до наступления статуса заказа «SHIPPED» можно отменить заказ полностью. Важно: отменить можно не системно, а только сообщением менеджеру.
• Если способ доставки «Самовывоз», то для таких заказов в необходимо передавать адрес ТЦ/ адрес склада ТЦ.
• Для передачи индекса, региона, города, адреса и ID ПВЗ для курьерских заказов в Арвато, необходимо доработать парсинг/получение адреса из Битрикса в 1С. Данная доработка будет выделена в отдельную задачу.

Документация API точки:
https://api-prod.arvato.ru/index.html?lang=ru#/customer%20orders/importOrders

Внешняя таблица № 1. Подробное описание полей API, описание входных данных точки отправки данных о заказах:
https://docs.google.com/spreadsheets/d/1BzKaYMxqXkHB-_i-_tPCCIroQ0V_8zarg8MtwdY_MEs/edit?gid=269908384#gid=269908384

При формировании запроса необходимо передавать следующие параметры:

• <order date=""> - ЗаказКлиента.Дата
• <nr="string"> - ЗаказКлиента.Номер
• <type><link href=""> - ID из спр «Arvato_ТипЗаказа»
• <action><link href=""> - ID из спр «Arvato_ДействияСЗаказом»; зависит от действия с заказом
• <customer nr=""> - Партнер.Код/Контрагент.Код
• <customer nr=""><index> - Индекс адреса доставки
• <customer nr=""><person><lastname> - ЗаказКлиента.Клиент (ФИО или Фамилия получателя)
• <customer nr=""><phone> - ЗаказКлиента.СК_ТелефонПолучателя
• <customer nr=""><region> - Регион адреса доставки
• <customer nr=""><settlement> - Город адреса доставки
• <customer nr=""><street> - Остаточная информация в адресе (улица, дом, квартира)
• <shipping-cost> - Стоимость доставки, которую должен заплатить клиент из ТЧ ЗаказКлиента.Товары.Сумма
• <doc-parameter>"" - ЗаказКлиента.СК_ТрекНомер
• <doc-parameter param-name=""> – передаем строку: "tracking-number"
• <doc-parameter param-type=""> - передаем строку: "2"
• <shipping-method><link href=""> - сопоставляем ЗаказКлиента.Склад со спр «Arvato_СпособОтгрузки», передаем ID из спр «Arvato_СпособОтгрузки»
• <shipping-method><postamat-nr> - ID ПВЗ
• <order-row><amount> - ЗаказКлиента.Товары.КоличествоУпаковок (На каждый товар в заказе передавать отдельную строку)
• <order-row><nds-sum> - ЗаказКлиента.Товары.СуммаНДС (Сумма НДС по каждой строке с товаром)
• <order-row> <product nr=""> - сопоставляем ЗаказКлиента.Товары.Характеристика с РС ШтрихкодыНоменклатуры, передаем значение Штрихкода из РС
• <order-row><sum> - ЗаказКлиента.Товары.СуммаСНДС (Сумма, которую человек должен заплатить за товар, На каждый товар в заказе передавать отдельную строку)