Интеграция с сайтом/приложением FTP API
Общие сведения
Сейчас работает с Delivery.MB (MainBrain), thapl.com и кастомными сайтами/приложениями.
Основное взаимодействие сайта и Юпитера происходит через обмен XML файлами. Обмен происходит через FTP сервер сайта. На фтп сервере создаются каталоги FROM_JUPITER - для файлов из Юпитера на сайт и FROM_SITE - для файлов от сайта к Юпитеру. Сайт предоставляет доступ Юпитеру к FTP серверу с этими каталогами.
Обновление статуса заказов на сайте происходит через callback запрос. При изменении статуса Юпитер отправляет GET запрос на сайт.
Передача меню на сайт происходит через GET запрос сайтом по статичной ссылке https://<ip-address>/<org id>/ menu.json. Файл с меню обновляется пользователем из Юпитера по мере необходимости.
Отдельные справочники (виды оплаты, источники заказа, торговые точки) сопоставляются вручную. Техподдержка Юпитера передает представителям сайта справочники в удобном формате (например Excel)
Сайт передает заказы в Юпитер
После полного завершения оформления заказа клиентом, сайт формирует XML файл и публикует его на фтп сервере в заранее оговоренной директории TO_JUPITER. Юпитер забирает файл заказа с фтп сервера и загружает заказ к себе в БД.
Имя файла должно иметь вид ORDER_<Номер-заказа>.XML
Если заказ оплачивается онлайн (кредитной картой или электронными деньгами), то файл заказа должен выгружаться только в случае успешной оплаты
Пример файла с заказом (ORDER_TPL383_1056443.XML):
<?xml version="1.0" encoding="utf-8"?>
<service action="orders" id="TPL383_1056443" source="3" order_source="TPL383_3"> <!--id - номер заказа. source - код источника заказа. order_source - тоже код источника заказа, не обязательный. Коды источников обговариваются отдельно -->
<order>
<concept>77</concept> <!--Код концепции по мультибренду, если не используется <concept/>-->
<client_id>287189</client_id> <!--Код клиента на сайте. Не обязательно-->
<client_full_name>Александр Столба</client_full_name> <!--Полное имя клиента-->
<client_address> <!--Информация об адресе доставки-->
<city>Подольск</city> <!--Город-->
<street>Академика Доллежаля</street> <!--Улица-->
<house>36</house> <!--Дом-->
<room>146</room> <!--Квартира-->
<entrance>3</entrance> <!--Подъезд-->
<intercom>146</intercom> <!--Код домофона-->
<floor>9</floor> <!--Этаж-->
<comment/> <!--Комментарий клиента к адресу -->
<map_latitude/> <!--Координаты широты (Обязательно, если сайт не определяет зоны доставки)-->
<map_longitude/> <!--Координаты долготы (Обязательно, если сайт не определяет зоны доставки)-->
<corp/>
</client_address>
<delivery_at>21.09.2022 16:39:18</delivery_at> <!--отложенный заказ, формат даты и времени-->
<pickup>0</pickup> <!--Статус самовывоза (1 - Самовывоз, 0 - Доставка)-->
<persons>5</persons> <!--кол-во гостей/персон в заказе.-->
<promocode_nouse/> <!--промокод, который был применен на сайте и его не нужно обрабатывать в программе, сохраняем для статистики.-->
<promocode/> <!--промокод, который нужно применить в программе, при загрузке заказа в программу.-->
<other_name>Руслан</other_name><!--Имя клиента, если клиент указал как к нему обращаться.-->
<phone>89096583529</phone><!--Номер телефона клиента. Начиная с 8 без пробелов.-->
<email>email@mail.ru</email> <!--почта клиента-->
<client_data_confirmed>1</client_data_confirmed> <!--На случай если данные клиента нужно обновить в Юпитере.-->
<client_comment/> <!--Комментарий клиента к заказу -->
<sum>810</sum> <!--Сумма заказа -->
<restaurant_id>36</restaurant_id> <!--Код ресторана, который будет выполнять заказ (Определяется сайтом по зоне доставки. Если сайт работает без зон доставки, то обязательно заполнить координаты широты и долготы адреса)-->
<promo/>
<restaurant_zone_id>210</restaurant_zone_id> <!--Код зоны доставки, зона доставки определяется сайтом (Если сайт работает без зон доставки, то обязательно заполнить координаты широты и долготы адреса)-->
</order>
<payment> <!--Параметры оплаты заказа-->
<payment_id>1</payment_id> <!--Код вида оплаты. Коды видов оплат обговариваются отдельно-->
<payment_title>Наличные</payment_title>
<payment_status>1</payment_status> <!--Статус оплаты (1 - Не проведена, 2 - Проведена)-->
<payment_sum>710</payment_sum> <!--Сумма оплаты-->
<change_sum>1000</change_sum> <!--Сумма с которой нужна сдача-->
<bonus_payment>100</bonus_payment><!--Сумма оплаты бонусами-->
</payment>
<items> <!--Товарная часть заказа. В этом разделе перечисляются товарные строки заказа.-->
<item> <!--Базовая строка заказа-->
<product_id>20001</product_id> <!--Код товара-->
<product_parent_id/> <!--Код товара родителя. Для базовой строки всегда пустое-->
<price>670</price> <!--Цена товара-->
<quantity>1</quantity> <!--Кол-во товара-->
<name>Мясной Пир (открытая)</name> <!--Название товара-->
</item>
<item> <!--Базовая строка заказа-->
<product_id>2055</product_id> <!--Код товара-->
<product_parent_id/> <!--Код товара родителя, для модификатора-->
<price>670</price> <!--Цена товара-->
<quantity>1</quantity> <!--Кол-во товара-->
<name>Мясной Пир (закрытая)</name> <!--Название товара-->
</item>
<!--Если к товару добавили модификаторы (доп. ингредиенты), то перечисляются строки модификатора. Строки модификатора должны обязательно быть указаны после базовой строки к которой принадлежат.-->
<item> <!--Строка модификатора-->
<product_id>935</product_id> <!--Код модификатора-->
<product_parent_id>2055</product_parent_id> <!--Код товара родителя-->
<product_price>70</product_price> <!--Цена модификатора-->
<quantity>2</quantity> <!--Кол-во модификатора. Умножается на кол-во базовой строки-->
<name>Помидоры (60г)</name> <!--Название модификатора-->
</item>
<item> <!--Строка модификатора-->
<product_id>914</product_id> <!--Код модификатора-->
<product_parent_id>2055</product_parent_id> <!--Код товара родителя-->
<product_price>70</product_price> <!--Цена модификатора-->
<quantity>2</quantity> <!--Кол-во модификатора. Умножается на кол-во из базовой строки.-->
<name>Сыр Моцарелла (60г)</name> <!--Название модификатора-->
</item>
</items>
</service>
Юпитер передает на сайт стоп-листы
Стоп-лист представляет собой список товаров, которые не доступны в данный момент для заказа на указанных торговых точках.
Выгрузка стоп-листа происходит автоматически после каждого его изменения.
Имя файла имеет вид STOP_LIST_<restaurant_id>.XML
Пример файла с стоп-листом (STOP_LIST_17.XML):
<?xml version="1.0" encoding="utf-8"?>
<service action="menuStopList">
<items>
<item id="2152" restaurant_id="17"/> <!--Код товара, который находится в стоп-листе-->
<item id="1340" restaurant_id="17"/>
<item id="10173" restaurant_id="17"/>
<item id="20177" restaurant_id="17"/>
<item id="10174" restaurant_id="17"/>
<item id="88700" restaurant_id="17"/>
<item id="10172" restaurant_id="17"/>
<item id="10176" restaurant_id="17"/>
<item id="10175" restaurant_id="17"/>
<item id="407000" restaurant_id="17"/>
<item id="691" restaurant_id="17"/>
<item id="364" restaurant_id="17"/>
<item id="1173" restaurant_id="17"/>
<item id="613" restaurant_id="17"/>
<item id="2599" restaurant_id="17"/>
<item id="20176" restaurant_id="17"/>
<item id="931" restaurant_id="17"/>
<item id="10235" restaurant_id="17"/>
<item id="2530" restaurant_id="17"/>
<item id="2608" restaurant_id="17"/>
<item id="2605" restaurant_id="17"/>
<item id="1294" restaurant_id="17"/>
<item id="2378" restaurant_id="17"/>
</items>
<restaurant id="17"/> <!--Код ресторана к которому относится стоп-лист -->
</service>
Стоп-лист для агрегаторов
Реализовано специально для интеграции с thapl.com
Данный стоп-лист нужен исключительно для выгрузки стоп-листа в модуль интеграции с последующем применением его ко всем агрегаторам (Деливери, Яндекс и т.п.). Стоп-лист для агрегаторов не влияет на заказы с сайта\приложения и КЦ - логика на стороне сайта/приложения. Стоп-лист для агрегаторов заполняется отдельно в кассовом интерфейсе через меню "Функции - Товары". Доступ включается в правах должности "Есть доступ к стоп-листу для агрегаторов".
Отличается от обычного стоп-листа, только названием файла, к нему добавляется префикс "A_". Например A_STOP_LIST_17.XML
Юпитер передает на сайт зоны доставки
Файл с зонами доставки обновляется пользователем из Юпитера по мере необходимости. Имя файла имеет вид RESTAURANT_ZONES.XML
Сайт может работать как с зонами доставки так и без них. По зонам доставки сайт может определить какой ресторан будет выполнять заказ, а вместе с ним минимальную стоимость заказа, время доставки, стоп-лист, организовать прием онлайн платежей на нужное юр. лицо. В файле с зонами доставки Юпитер передает код ресторана к которому относится данная зона доставки (restaurant_id), код самой зоны доставки (id) и список вершин полигона (широта, долгота). Получив координаты адреса доставки (координаты точки) сайту нужно определить входит ли эта точка в один из этих полигонов.
Юпитер загружает xml файл с зонами на фтп сервер сайта в заранее оговоренную директорию (например FROM_JUPITER). Сайт принимает и обрабатывает файл. После обработки файл обязательно удаляется с фтп сервера.
Если сайт будет работать без зон доставки, то в ORDER.XML передаются координаты адреса доставки и Юпитер сам по ним определит зону. В таком случае, для определения стоп-листа и других свойств ресторана, сайту необходимо организовать альтернативный способ определения ресторана-исполнителя.
Юпитер передает на сайт меню (MENU.JSON)
Формат выгрузки аналогичен формату выгрузки меню в JPOS (смотреть тут). Формат отличается только параметрами первого уровня:
{
"restaurant_id": "03",
"menu": {
// Выгрузка в формате JPOS
}
}
Обновить данные клиента в бонусной системе Юпитер
Реализовано специально для интеграции с thapl.com
Чтобы обновить данные клиента в бонусной системе, нужно сгенерировать и передать в Юпитер XML файл:
<?xml version="1.0" encoding="utf-8"?>
<!-- action всегда "customer", id внутренний код клиента на сайте\приложении -->
<service action="customer" id="123">
<!-- Признак, что номер телефона клиента подтвержден через SMS. Обязтальное поле -->
<client_data_confirmed>1</client_data_confirmed>
<!-- Уникальный идентификатор клиента в бонусной системе, передавать только если есть -->
<client_guid>4799FF1A-06E2-C625-15FF-D8AC38E8925E</client_guid>
<!-- Номер телефона в формате 89998887766. Обязтальное поле -->
<phone>89060760573</phone>
<!-- Имя клиента. Обязтальное поле -->
<name>Олег</name>
<!-- Email -->
<email>email@mail.ru</email>
<!-- День рождения в формате гггг-мм-дд -->
<birth>1990-12-30</birth>
<!-- Согласие на получение SMS. 1 - согласен, 0 - не согласен -->
<sms_sub>1</sms_sub>
<!-- Согласие на получение email. 1 - согласен, 0 - не согласен -->
<email_sub>1</email_sub>
<!-- Признак наличия детей. 1 - есть дети, 0 - детей нет -->
<has_kids>1</has_kids>
<!-- Пол. Может принимать значения "Муж" или "Жен" -->
<sex>Муж</sex>
</service>Имя файла должно соответствовать маске: CUSTOMER_*.XML, где * это внутренний код клиента на сайте\приложении.
Передача файла в Юпитер осуществляется следующим образом:
Сайт\приложение предоставляет Юпитеру доступ к своему FTP серверу (передает техподдержке адрес, порт, логин, пароль)
Сайт\приложение формирует файл, и публикует его на своем FTP сервере в отдельную директорию
Юпитер мониторит эту директорию и при появлении в ней файлов, забирает их к себе
Юпитер передаёт статусы заказов на сайт
Статусы передаются по ВСЕМ заказам, а не только по тем, которые были загружены с сайта\приложения. Чтобы статусы передавались на сайт нужно задать "Ссылку для обновления статуса заказов на сайте". Задается в холдинге на вкладке "Доставка" (пример https://www.pronto24.ru/order/set-status.htm). Статус передается через GET запрос, например: https://www.pronto24.ru/order/set-status.html?order_id=9-1-25-23&status=10, где:
-
order_id- код заказа в Юпитере. Для заказов, загруженных с внешних источников, из кода будет удаляться префикс (например код заказа S270073, будет передан как 270073). Для заказов созданных через Юпитер, код остается как есть (например 9-1-25-23). -
status- id нового статуса
Возможные статусу статусы:
- Новый (0) - при поступлении заказа с внешнего источника (сайт, приложение, агрегаторы), при ручном создании нового заказа на доставку или самовывоз на точке или в КЦ.
- В работе (10) - вместе с печатью на кухню. Если включен режим авто печати заказов при поступлении на точку, то статус также отправляется при поступлении заказа на точку.
- Доставляется (20) - при назначении курьера на заказа.
- Доставлен (30) - при смене статуса на "Заказ доставлен". При закрытии заказа, вместе с печатью чека (т.к. не все точки используют статус "Заказ доставлен").
- Отменён (5) - при удалении заказа.
Дополнительные возможности:
- Можно отключить передачу статуса отмены на сайт при удалении заказа. Для этого в причину удаления заказа добавлен параметр "Не передавать отмену на сайт"
- Сайт может передать ссылку для обновления статуса заказа в XML файле через узел "status_url".
Ссылка должна иметь вид: https://адрес-сервера?order_id=номер_заказа. (В том числе можно прислать свой номер заказа не из Юпитера)
Ссылка сохраняется в заказе и используется для обновления статусов. Юпитер автоматически добавляет к ссылке &status=код_статуса.
Если ссылка в заказе не передана, то используется ссылка для обновления статусов по умолчанию (задается в холдинге).
Юпитер будет обновлять статусы только если в холдинге задана ссылка по умолчанию. - Добавлена роль "Передавать подтверждение заказа сразу при получении" (КАССА - Опции настройки - Интеграция с сайтом).
Если роль включена, то вместо статуса 0 (Новый) на сайт будет передаваться статус 10 (В работу).
Это нужно для тех случаев, когда Delivery Club автоматически отменяет заказ если в течении 5 минут не получил подтверждение о начале приготовления.
Если сайт/приложение уже настроены на работу с другой учетной системой
Предусмотрены "дополнительные коды" по которым будут приниматься заказы с внешних систем (сайт, приложение).
Добавляются через контекстное меню ТМЦ пункт "Дополнительные коды (штрихкоды)"
Предусмотрены служебные процедуры, которые:
- Создает доп. коды по всем ТМЦ у которых в качестве кода задан GUID (длина кода > 30 символов)
- Назначает новый, короткий код (по текущему значению нумератора)
Система JUPITER www.jupiter.systems (с) 2024г.
Нет комментариев