API интеграции с сайтом/приложением

Сейчас работает с Delivery.MB (MainBrain) и кастомными сайтами/приложениями.

Взаимодействие сайта и Юпитера происходит посредством обмена сообщениями.

Передача информации из Юпитера на сайт:

1. Через GET-запросы к серверу ЮПИТЕР на URL: https://<ip-address>/<org id>/<filename> 
   <org id> - уникальный идентификатор организации
   Имена файлов <filename>:
   • MENU.JSON
   • RESTAURANT_ZONES.XML
   • STOP_LIST.XML
     Ссылки доступны в любое время и выдают актуальные на текущий момент данные.
2. Файлами через фтп сервер сайта. На сервере, где расположен сайт создаются локальные папки, которые доступны Юпитеру через 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 - при удалении заказа