Интеграция с сайтом HTTP API

Общая информация

URL API: https://jupiter.report/site-api/

Авторизация

Передайте токен авторизации в заголовке запроса X-Jup-Api-Key

Для получения API-Key обратитесь в техподдержку

Результаты обработки запроса

Если запрос успешно обработан, сервер вернет ответ с статусом 200.

Если при обработке запроса были ошибки, сервер вернет ответ со статусом ошибки (400, 401, 500) и описание ошибки.

{
    "error": "Некорректный Api-Key" // Описание ошибки
}

Концепции

Ресторан может одновременно работать с разными концепциями, например "Лучшая пицца" и "Вкусные суши". Каждая концепция может иметь свои зоны доставки и меню. Товары в разных концепциях могут пересекаться, но иметь разные цены.

Зоны доставки

Сайт может работать как с зонами доставки так и без них.

Определив зону доставки, сайт получает информацию какой ресторан будет выполнять заказ, минимальную стоимость заказа, время доставки, стоп-лист, юридическое лицо для приема онлайн платежей.

Если сайт работает без зон доставки, то он может просто передавать координаты адреса доставки. Юпитер сам определит зону доставки и ресторан, который будет выполнять заказ.

Справочник товаров

Для корректной работы интеграции необходимо выполнить сопоставление справочника товаров между Юпитером и сайтом.

Стоп-лист

Стоп-лист представляет собой список товаров, которые не доступны в данный момент для заказа в ресторане

Настройки интеграции в Юпитере

Вызовы

Получить список ресторанов

Адрес: /restaurants

Метод: GET

Параметры:

  • restaurant_id - Не обязательный. Идентификатор ресторана

Тело ответа:

{
    "places": [ // Список ресторанов
        {
            "id": "000127", // Идентификатор ресторана, используется для передачи в заказе restaurant_id 
            "name": "ТЗ Судостроительная, д. 3", // Название
            "address": "г. Москва, ул. Судостроительная, д. 3, к. 2; м. Коломенская", // Адрес
            "email": "email@ya.ru", // Email
            "start_time": 32400, // Время начала работы в секундах, 9:00
            "end_time": 82800, // Время завершения работы в секундах, 23:00
            "phone": "88005552211", // Телефон для отображения на сайте
            "self_delivery": false, // Есть самовывоз. false - нет, true - есть
            "ul": { // Информация о юридическом лице
                "name": "ООО Быстрая доставка", // Название юр. лица
                "inn": "7711111111", // ИНН юр. лица
                "kpp": "770000001" // КПП юр. лица
            },
            "concepts": [ // Список концепций с которыми работает ресторан
                {
                    "id": "7", // Идентификатор концепции
                    "name": "Вкусные суши" // Название
                }
            ]
        }
    ]
}

 

Получить список зон доставки

Адрес: /delivery_zones

Метод: GET

Параметры:

  • restaurant_id - Обязательный. Идентификатор ресторана
  • concept_id - Обязательно если ресторан работает с концепциями. Идентификатор концепции. Если не задан, то список зон возвращаются для концепции default

Тело ответа:

{
    "restaurant_id": "002040", // Идентификатор ресторана
    "concept_id": "7", // Идентификатор концепции
    "lastChange": "2024-05-21T16:19:13.000+03:00", // Дата последнего изменения зон доставки
    "zones": [ // Список концепций
        {
            "id": "028270", // Идентификатор зоны доставки, передается в параметре заказа zone_id
            "name": "Москва Зона 1 Сумма минимального заказа 600 руб. Стоимость доставки 125 руб. При заказе от 1200 р. ДОСТАВКА ОСУЩЕСТВЛЯЕТСЯ БЕСПЛАТНО. Время ожидания заказ 75 минут.",
            "sum_min": 600, // Минимальная сумма заказа, в рублях
            "time_min": 75, // Время доставки от, в минутах
            "time_max": 75, // Время доставки до, в минутах
            "delivery_price": 125, // Стоимость доставки, в рублях
            "sum_for_free": 1200, // Сумма заказа для бесплатной доставки, в рублях
            "lastChange": "2024-05-21T16:19:13.000+03:00", // Дата последнего изменения зоны доставки
            "coordinates": [ // Координаты вершин полигона
                [
                    "37.52371234879848", // Долгота
                    "55.84410641903395" // Широта
                ],
                [
                    "37.514442634443014",
                    "55.753211478836405"
                ],
                [
                    "37.75142603657669",
                    "55.77257777343632"
                ],
                [
                    "37.745595187258395",
                    "55.83994903702488"
                ],
                [
                    "37.52371234879848",
                    "55.84410641903395"
                ]
            ]
        }
    ],
    "deleted_zones": [ // Список удалённых зон доставки
        {
            "id": "111", // Идентификатор удаленённой зоны доставки
            "name": "Зона доставки № 3", // Название
            "lastChange": "2023-04-19T20:00:00.000+03:00" // Дата последнего изменения (удаления)
        }
    ]
}

Получить меню

Адрес: /menu

Метод: GET

Параметры:

  • restaurant_id - Обязательный. Идентификатор ресторана
  • concept_id - Обязательно если ресторан работает с концепциями. Идентификатор концепции. Если не задан, то будет передано меню по концепции default
{
    "restaurant_id": "000127", // Идентификатор ресторана
    "concept_id": "7", // Идентификатор концепции
    "menu": { // Меню ресторана по концепции
        "lastChange": "2024-05-21T16:19:13.000+03:00", // Дата последнего изменения меню, в формате RFC3339
        "categories": [ // Список категорий меню
            {
                "id": "5:3:0:832141", // Идентификатор категории
                "name": "Роллы", // Название категории
                "sortOrder": 0, // Порядок сортировки от меньшего к большему
                "images": [ // Изображение категории
                    {
                        "url": "string", // Ссылка на изображение для скачивания
                        "updatedAt": "2024-05-21T16:19:13.000+03:00" // Дата обновления изображения, в формате RFC3339
                    }
                ]
            }
        ],
        "items": [ // Список товаров
            {
                "id": "T20231", // Идентификатор товара
                "categoryId": "5:3:0:832141", // Идентификатор категории к которой относится товар
                "name": "Филадельфия Гранд", // Название
                "description": "Рис, нори, сыр сливочный, огурец, лосось. Подается с соевым соусом (30 г), имбирём (30 г), васаби (10 г).", // Описание для меню
                "price": 500, // Цена
                "vat": 0, // НДС, включенный в стоимость, в процентах, если не указан, считается за 0
                "measure": 240, // Вес или объем
                "measureUnit": "г", // Единица измерения. Допустимые значения - граммы (г) и миллилитры (мл)
                "sortOrder": 0, // Порядок сортировки от меньшего к большему
                "nutrients": [ // Параметры КБЖУ на 100г. Необязательный параметр
                    {
                        "calories": 142, // Калории
                        "proteins": 10, // Белки
                        "fat": 7, // Жиры
                        "carbohydrates": 11, // Углеводы
                        "is_deactivated": false // Неиспользуется, всегда false
                    }
                ],
                "modifiers": [ // Группы модификаторов для товара. Необязательный параметр
                    {
                        "id": "5:3:0:11821", // Идентификатор группы модификаторов
                        "name": "Доп. гарниры", // Название группы модификаторов
                        "minSelectedModifiers": 0, // Минимальное количество модификаторов, которые необходимо выбрать для данной группы
                        "maxSelectedModifiers": 3, // Максимальное количество модификаторов, которые можно выбрать для данной группы
                        "sortOrder": 0, // Порядок сортировки от меньшего к большему
                        "modifiers": [ // Список модификаторов
                            {
                                "id": "6021", // Идентификатор товара-модификатора
                                "name": "Соевый соус (30 г)", // Название
                                "price": 50, // Цена
                                "vat": 0, // НДС, включенный в стоимость, в процентах, если не указан, считается за 0
                                "minAmount": 0, // Минимальное количество указанного модификатора для блюда в заказе
                                "maxAmount": 3, // Максимальное количество указанного модификатора для блюда в заказе
                                "sortOrder": 0 // Порядок сортировки от меньшего к большему
                            },
                            {
                                "id": "6042",
                                "name": "Имбирь (30 г)",
                                "price": 50,
                                "vat": 0,
                                "minAmount": 0,
                                "maxAmount": 3,
                                "sortOrder": 1
                            }
                        ]
                    }
                ],
                "images": [ // Изображение товара
                    {
                        "url": "https://url.url", // Ссылка на изображение для скачивания
                        "hash": "55247fb2135f11ef8a4fd00db080bd69" // SHA1-хэш от содержимого файла изображения. Служит признаком уникальности. В случае если он меняется, сайт перезагружает картинку
                    }
                ],
                "tags": [ // Список тегов товара. Необязательный параметр
                    {
                        "name": "Хит" // Название тега
                    }
                ]
            }
        ]
    }
}

Параметр "description": "", // Описание для меню задается в настройках ТМЦ->вкладка "Касса"->поле "Описание для меню"

Получить стоп-лист

Адрес: /stop_list

Метод: GET

Параметры:

  • restaurant_id - Не обязательный. Идентификатор ресторана
  • date_change - Не обязательный. Дата последнего изменения в формате ДДММГГГГЧЧММСС. В ответе будут переданы только те стоп-листы, которые изменялись после указанной даты

Тело ответа:

{
    "stop_lists": [ // Список стоп-листов
        {
            "restaurant_id": "000017", // Идентификатор ресторана
            "lastChange": "2024-06-10T22:02:27.000+03:00", // Дата последнего обновления стоп-листа, в формате RFC3339
            "items": [ // Список товаров находящихся в стоп-листе
                {
                    "id": "T20231" // Идентификатор товара
                }
            ]
        }
    ]
}

Создать заказ

Адрес: /order

Метод: POST

Тело запроса:

{
  "action": "new_order", // Всегда new_order
  "body": { // Объект заказа
    "number": "9400001", // Номер заказа на сайте
    "restaurant_id": "000127", // Идентификатор ресторана, который будет выполнять заказ. Игнорируется если заданы коордианты или зона доставки
    "concept_id": "7", // Идентификатор концепции. Обязательно, если ресторан работает с концепциями
    "date": "2024-04-08 15:21:03", // Дата\время оформления заказа
    "delivery_method": "courier", // courier - доставка, pickup - самовывоз
    "persons": 2, // Количество персон
    "comment": "Всё без лука", // Комментарий к заказу
    "date_preorder": "2024-04-08 17:00", // Дата\время к котрому нужно доставить\приготовить заказ
    "status_url": "https://you-url?order_id=9400001", // Ссылка для обновления статуса заказа на сайте
    "cart": { // Содержимое заказа
      "items": [ // Товарная часть
        { 
          "id": "T20231", // Идентификатор товара
          "name": "Филадельфия Гранд", // Название товара
          "count": 1, // Количество
          "cost": 500.00 // Цена
        },
        {
          "id": "555333111",
          "name": "Калифорния Гранд",
          "count": 3,
          "cost": 700.00,
          "modifiers": [ // Массив вложенных модификаторов к этому товару
            {
              "id": "6021", // Идентификатор товара
              "name": "Соевый соус (30 г)", // Название товара
              "count": 1, // Количество
              "cost": 30.00 // Цена
            },
            {
              "id": "6042",
              "name": "Имбирь (30 г)",
              "count": 1,
              "cost": 50.00
            }
          ]
        }
      ],
      "delivery": 100.00, // Стоимость доставки. 0 если доставка бесплатная
      "total": 2940.00 // Итоговая сумма заказа с учётом стоимости доставки
    },
    "client": { // Информация о клиенте
      "name": "Пётр", // Имя клиента
      "phone": "+7(922)988-33-22" // Телефон клиента, в любом формате
    },
    "recipient_name": { // Информация о получателе заказа. Заполнять если заказывает один человек, а получает другой
      "name": "Иван", // Имя получателя 
      "phone": "+7(987)654-32-10" // Телефон получателя, в любом формате
    },
    "address": { // Информация о адресе. Если заказ на вынос, то не заполнять
      "name": "г. Москва, ул. Большая Садовая, д. 10, кв. 50", // Адрес одной строкой
      "comment": "Стучать, звонок не работает", // Комметарий к адресу
      "coords": { // Координаты дома. Если заданы, то имеют приоритет перед restaurant_id
        "latitude": "55.767210", // Широта
        "longitude": "37.593390" // Долгота 
      },
      "zone_id": "028270" // Идентификатор зоны доставки. Если задан, то имеет приоритет перед coords и restaurant_id
    },
    "payment": { // Информация об оплате заказа
      "method": "cash", // cash - наличные, card - картой курьеру, online - онлайн через приложение или сайт
      "sum": 2940.00, // Сумма оплаты. Итоговая сумма заказа с учётом всех скидок и стоимости доставки
      "change": 5000.00 // Сумма с которой приготовить сдачу
    }
  }
}

Если запрос успешно обработан, сервер вернет ответ с статусом 200. В теле ответа будет передан номер заказа.

 

{
  "order_id": "S9400001" // Номер заказа в Юпитере
}

Номер заказа может быть модифицирован и отличаться от номера заказа на сайте.

Успешное выполнение запроса не означает, что заказ окончательно принят. Результатом выполнения запроса является постановка заказа в очередь на загрузку. Гарантированный индикатор приёма заказа является получение запроса с изменением статуса заказа на "Новый"

 

Получить информацию по клиенту

Адрес: /client

Метод: GET

Параметры:

  • phone - Обязательный. Номер телефона клиента, только цифры

Тело ответа:

{
    "id": "665F52E5-8CFF-2174-12FB-C2AAAF55D803", // Идентификатор клиента
    "name": "Петр Иванов", // Имя клиента
    "phone": "89991112233", // Номер телефона
    "email": "test@test.ru", // Email
    "birthday": "1990-02-10", // День рожения в формате ГГГГ-ММ-ДД
    "gender": "Мужской", // Пол, Мужской\Женский
    "discounts_active": true, // Признак "Может пользоваться скидками\бонусами"
    "blacklist": false, // Признак "Чёрный список"
    "block_sms": false // Признак "Запретить отправку SMS"
}

Обратные вызовы

Обновить статус заказа на сайте

При изменении статуса заказов, Юпитер отправляет GET запрос на URL переданный сайтом в параметре status_url при создании заказа.

К status_url добавляется параметр status, в котором передается код нового статуса

https://you-url?order_id=9400001&status=0

Возможные значения параметра status:

Значение Название статуса Когда отправляется
0 Новый При получении заказа с сайта\приложения, при ручном создании заказа в Юпитере
10 В работе (Готовится) При печати заказа на кухню
20 Доставляется При назначении курьера
30 Доставлен При смене статуса на "Заказ доставлен" и при закрытии заказа
5 Отменён При удалении заказа

 

Результат запроса не контролируется, но протоколируется для решения возможных инцидентов. Предполагается, что сайт отвечает пустой страницей с статусом 200

 

 


Система JUPITER                                 www.jupiter.systems                                 (с) 2024г.