API интеграции с сайтом/приложением
Сейчас работает с Delivery.MB (MainBrain) и кастомными сайтами/приложениями.
Взаимодействие сайта и Юпитера происходит посредством обмена сообщениями.
Передача информации из Юпитера на сайт:
- Через GET-запросы к серверу ЮПИТЕР на URL: https://<ip-address>/<org id>/<filename>
<org id> - уникальный идентификатор организации
Имена файлов <filename>: - Файлами через фтп сервер сайта. На сервере, где расположен сайт создаются локальные папки, которые доступны Юпитеру через FTP. Папка FROM_JUPITER - для файлов из Юпитера на сайт, папка FROM_SITE - для файлов от сайта к Юпитеру. После обработки файлы обязательно удаляются из соответствующей директории.
Статусы заказов всегда передаются сайту через http запросы.
Получение информации с сайта
Информация о заказе передаётся в виде структуры ORDER.XML. Передача возможна либо помещением XML-файла c заказом в локальную папку сайта, доступную через FTP, либо POST-запросом на API-сервер Юпитера:
https://<ip-address>/<org id>/ORDER
POST запрос передает по HTTPS соединению и должен содержать заголовок авторизации:
Authorization: Basic <api_key>
Сайт передает в Юпитер заказы (ORDER*.XML).
Сообщение с заказом передаётся после полного завершения оформления заказа клиентом. Если заказ оплачивается онлайн (кредитной картой или электронными деньгами), сообщение передаётся только в случае успешной оплаты.
Юпитер передает на сайт стоп-листы (STOP_LIST*.XML).
Стоп-лист представляет собой список товаров, которые не доступны в данный момент для заказа на указанных торговых точках. Выгрузка стоп-листа происходит автоматически после каждого его изменения.
Стоп-лист для агрегаторов имеет префикс A_ (A_STOP_LIST.XML).
Данный стоп-лист нужен исключительно для выгрузки стоп-листа в модуль интеграции с последующем применением его ко всем агрегаторам (Деливери, Яндекс и т.п.). Стоп-лист для агрегаторов не влияет на заказы с сайта\приложения и КЦ - логика на стороне сайта/приложения. Стоп-лист для агрегаторов заполняется отдельно в кассовом интерфейсе через меню "Функции - Товары". Доступ включается в правах должности "Есть доступ к стоп-листу для агрегаторов".
Юпитер передает на сайт зоны доставки (RESTAURANT_ZONES.XML).
Сайт может работать как с зонами доставки так и без них. По зонам доставки сайт может определить какой ресторан будет выполнять заказ, а вместе с ним минимальную стоимость заказа, время доставки, стоп-лист, организовать прием онлайн платежей на нужное юр. лицо. В файле с зонами доставки Юпитер передает код ресторана к которому относится данная зона доставки (restaurant_id), код самой зоны доставки (id) и список вершин полигона (широта, долгота). Получив координаты адреса доставки (координаты точки) сайту нужно определить входит ли эта точка в один из этих полигонов.
Юпитер загружает xml файл с зонами на фтп сервер сайта в заранее оговоренную директорию (например FROM_JUPITER). Сайт принимает и обрабатывает файл. После обработки файл обязательно удаляется с фтп сервера.
Если сайт будет работать без зон доставки, то в ORDER.XML передаются координаты адреса доставки и Юпитер сам по ним определит зону. В таком случае, для определения стоп-листа и других свойств ресторана, сайту необходимо организовать альтернативный способ определения ресторана-исполнителя.
Синхронизация видов оплаты, источников заказа и ресторанов происходит по их кодам.
Синхронизация меню происходит также по кодам.
Юпитер передает на сайт меню (MENU.JSON)
Формат выгрузки аналогичен формату выгрузки меню в JPOS (смотреть тут). Формат отличается только параметрами первого уровня:
{
"restaurant_id": "03",
"menu": {
// Выгрузка в формате JPOS
}
}
Обновить данные клиента в бонусной системе Юпитер.
Чтобы обновить данные клиента в бонусной системе, нужно сгенерировать и передать в Юпитер 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 минут не получил подтверждение о начале приготовления.
Набор статусов:
- Новый 0 - при получении заказа с сайта\приложения, при ручном создании заказа в Юпитере
- В работе 10 - при печати заказа на кухню
- Приготовлен 15 - при смене статуса что заказ готов к передаче клиенту/курьеру
- Доставляется 20 - при назначении курьера
- Доставлен 30 - при смене статуса на "Заказ доставлен" и при закрытии заказа
- Отменен 5 - при удалении заказа
Система JUPITER www.jupiter.systems (с) 2023г.
Нет комментариев