Интеграция: получение списка заказов (get_order_list)

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

1. Общие сведения

Параметр	Значение
Адрес	POST https://<домен>/index.php
Формат	JSON, кодировка UTF-8
Заголовки	Content-Type: application/json
Авторизация	JWT в заголовке Authorization: Bearer <token>
Срок жизни токена	15 минут (expires_in: 900)

Все запросы выполняются только по HTTPS.

2. Авторизация

Авторизация выполняется в два шага.

Шаг 1. Получение токена

Вам выдаётся ключ интеграции (строка из 32 символов). Он используется только для получения токена.

curl -X POST "https://<домен>/index.php" \
  -H "Content-Type: application/json" \
  -d '{"type":"auth_token","key":"<ваш ключ интеграции>"}'

Ответ:

{
  "status": "ok",
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImsxIn0....",
  "token_type": "Bearer",
  "expires_in": 900
}

Шаг 2. Запросы с токеном

Токен передаётся в заголовке Authorization. Ключ интеграции в теле запроса больше не нужен и не должен передаваться.

Authorization: Bearer <access_token>

Обновление токена

Токен действует 15 минут. Когда срок истекает, сервер возвращает ошибку NO_AUTH (HTTP 401). В этом случае нужно заново выполнить шаг 1 и повторить запрос.

Рекомендуемая схема: получать новый токен за 1–2 минуты до истечения expires_in, либо получать его при каждой ошибке 401.

Важно

• Ключ интеграции является секретом. Не передавайте его в URL, не храните в открытом виде в коде и не отправляйте в логи.
• Не используйте ключ интеграции для запросов данных, только для auth_token. Запрос get_order_list с ключом в теле вернёт ошибку прав.
• Токен нельзя использовать для получения нового токена.
• Если ключ скомпрометирован, сообщите нам. Ключ будет перевыпущен, старый перестанет работать.

3. Запрос get_order_list

Параметры

Поле	Тип	Обязательное	Описание
type	string	да	Всегда "get_order_list"
from_data_date	string	да	Начало периода, дата YYYY-MM-DD (включительно)
to_data_date	string	да	Конец периода, дата YYYY-MM-DD (включительно)
data_tt	string	нет	ID торговой точки или несколько ID через запятую, например "12,15". Если не указано, возвращаются заказы всех торговых точек, доступных вашей учётке
order_list	array of string	нет	Список order_uid конкретных заказов. Передавайте значения в том виде, в котором получили их в ответе

Сопоставление периода с заказом выполняется по полю date заказа.

Пример: заказы за день

curl -X POST "https://<домен>/index.php" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
    "type": "get_order_list",
    "from_data_date": "2026-11-01",
    "to_data_date": "2026-11-01"
  }'

Пример: несколько торговых точек

{
  "type": "get_order_list",
  "from_data_date": "2026-11-01",
  "to_data_date": "2026-11-02",
  "data_tt": "12,15"
}

Торговые точки в data_tt должны быть доступны вашей учётке. Иначе вернётся ошибка.

Пример: конкретные заказы

{
  "type": "get_order_list",
  "from_data_date": "2026-10-24",
  "to_data_date": "2026-10-24",
  "order_list": ["5-872-0-9982839"]
}

4. Ответ

При успехе возвращается HTTP 200 и JSON-массив заказов. Если заказов нет, возвращается пустой массив [].

Заказы идут по времени открытия (open) по возрастанию. Удалённые заказы (deleted: 1) по порядку в ответе не выделяются.

Пример: доставка (канал «Новое Приложение»)

[
  {
    "order_id": "64131187",
    "order_uid": "5-872-0-9982839",
    "tt_id": "672",
    "tt_name": "(Ф) г. Зарайск, ул. Мерецкова, д. 27/19",
    "num": "NP3343042",
    "date": "2026-10-24",
    "hour": "11",
    "open": "2026-10-24 11:31:12",
    "close": "2026-10-24 13:15:48",
    "type": "Заказ",
    "vid": "Доставка",
    "name": "NP3343042",
    "source": "Новое Приложение",
    "waiter": "Официант 1",
    "cashier": "Официант 1",
    "client_name": "Имя Клиента",
    "client_phone": "8 (900) 000-00-00",
    "summ_fakt": 1693,
    "summ_rozn": 1693,
    "summ_skidki": 0,
    "address": "г Зарайск ул. Примерная д. 5 под. 4 дмф. 1234 эт. 1 кв. 49",
    "deleted": 0,
    "overtime": 0,
    "timeline": "Создан: 11:31 → Пришёл на точку: 11:32 → Отправлен в работу: 11:34",
    "aggregator_id": "",
    "courier_uid": "",
    "courier_name": "",
    "payment": [{"name": "КРЕД КАРТА КУРЬЕРУ", "summ": 1693}],
    "discounts": [],
    "goods": [
      {
        "product_name": "СЕТ \"ТОП ЗАПЕЧЕННЫЙ\"",
        "deleted": 0,
        "quantity": 1,
        "summ_fakt": 1619,
        "summ_rozn": 1619,
        "price_fakt": 1619,
        "price_rozn": 1619
      },
      {
        "product_name": "СОУС ЯКИ",
        "deleted": 0,
        "quantity": 1,
        "summ_fakt": 49,
        "summ_rozn": 49,
        "price_fakt": 49,
        "price_rozn": 49
      },
      {
        "product_name": "Сервисный сбор",
        "deleted": 0,
        "quantity": 1,
        "summ_fakt": 25,
        "summ_rozn": 25,
        "price_fakt": 25,
        "price_rozn": 25
      },
      {
        "product_name": "Бокс Большой Желтый 210х145х50 СУШИСЕТ *140",
        "deleted": 0,
        "quantity": 2,
        "summ_fakt": 0,
        "summ_rozn": 0,
        "price_fakt": 0,
        "price_rozn": 0
      }
    ]
  }
]

Пример: удалённая позиция

{
  "product_name": "ФИШ ЭНД ЧИПС 280 Г",
  "deleted": 1,
  "quantity": 1,
  "summ_fakt": 680,
  "summ_rozn": 680,
  "price_fakt": 680,
  "price_rozn": 680,
  "why_deleted": "Отказ гостя без списания продуктов",
  "who_deleted": "Сотрудник 1",
  "deleted_type": "2"
}

Описание полей заказа

Поле	Тип	Описание
order_id	string	Внутренний ID заказа. Числовая строка, например "64131187" или "25469250"
order_uid	string	Уникальный ID заказа вида 5-872-0-9982839. Используется в order_list
tt_id	string	ID торговой точки, числовая строка ("672", "28", "294")
tt_name	string	Название торговой точки.
num	string	Номер заказа
date	string	Дата рабочего дня заказа, YYYY-MM-DD.
hour	string	Час открытия заказа ("11").
open	string	Время открытия, YYYY-MM-DD HH:MM:SS
close	string	Время закрытия, YYYY-MM-DD HH:MM:SS. Для незакрытого заказа значение 0000-00-00 00:00:00
type	string	Тип документа, Заказ или Возврат
vid	string	Вид заказа: Обычный заказ (зал, касса), На вынос, Доставка
name	string	Название заказа в кассе. Для зала: номер стола или бара (Стол № 17, Бар 6). Для самовывоза: номер в очереди (1, 2, 3). Для онлайн-заказов совпадает с num
source	string	Имя источника заказа
waiter	string	Имя официанта (сотрудник который открыл заказ)
cashier	string	Имя кассира (сотрудник, который закрыл заказ)
client_name	string	Имя клиента
client_phone	string	Телефон клиента в формате 8 (XXX) XXX-XX-XX.
summ_fakt	number	Фактическая сумма заказа, после скидок
summ_rozn	number	Сумма заказа по розничным ценам, до скидок
summ_skidki	number	Сумма скидок.
address	string	Адрес доставки в свободной форме. Сокращения: под. — подъезд, дмф. — домофон, эт. — этаж, кв. — квартира. Для зала, самовывоза и заказов на вынос пустая строка
deleted	number	0 — заказ действителен, 1 — заказ удалён.
overtime	number	Просрочка доставки, в минутах.
timeline	string	Хронология статусов в формате Статус: HH:MM → Статус: HH:MM. Встречаются статусы: Создан, Пришёл на точку, Отправлен в работу, Приготовлен и собран, Назначен курьеру. Для зала — только Создан и Отправлен в работу. Время без даты, поэтому возможен переход через полночь (например, Создан: 12:42 → Отправлен в работу: 00:43)
aggregator_id	string	ID заказа в системе агрегатора формата YYMMDD-NNNNNNN (например, 261024-6371662).
courier_uid	string	ID курьера, например 4:98:0:9241.
courier_name	string	Имя курьера
payment	array	Оплаты заказа: name — тип оплаты, summ — сумма. Пустой массив [] для незакрытых заказов и заказов, полностью оплаченных скидкой или бонусами
discounts	array	Скидки и бонусные операции: name, summ. Значение summ может быть отрицательным
goods	array	Позиции заказа

 

Описание позиции (goods)

Поле	Тип	Описание
product_name	string	Название товара или набора. Чаще в верхнем регистре
price_rozn	number	Розничная цена (до скидок)
price_fakt	number	Фактическая цена (после скидок)
quantity	number	Количество
summ_fakt	number	Фактическая сумма позиции. 0 для позиций, входящих в набор
summ_rozn	number	Сумма позиции по розничным ценам
deleted	number	0 — позиция в заказе, 1 — удалённая позиция. Сумма удалённой позиции не входит в итог заказа
why_deleted	string	Причина удаления. Только у deleted: 1, например Отказ гостя без списания продуктов
who_deleted	string	Сотрудник, удаливший позицию. Только у deleted: 1
deleted_type	string	Код типа удаления, числовая строка (в примерах "2"). Не текстовое описание

Одинаковые позиции в заказе объединяются в одну строку с суммарным количеством. Удалённые позиции передаются отдельными строками. В выборке они идут после неудалённых.

Важные особенности разбора ответа

• Суммы и количества приходят числами.
• Пустые строки вместо null. Отсутствующие значения (aggregator_id, courier_uid, courier_name, address, client_name) передаются как "". Не полагайтесь на null.
• Отрицательные скидки. В discounts могут быть записи с отрицательным summ. Таким образом передаются наценки.
• Новые поля могут появиться в будущих версиях. Игнорируйте неизвестные поля.

5. Ограничения

• Не более 200 заказов за один ответ. Лимит общий для открытых, закрытых и удалённых заказов. Признака «ответ обрезан» и общего количества в ответе нет. Если за период заказов больше, часть из них не попадёт в ответ.
  
  • Запрашивайте данные по одному дню или по конкретным торговым точкам.
  • Для выборки конкретных заказов используйте order_list.
• Пагинации нет.
• Период. Укажите разумный период: большие диапазоны выполняются дольше.
• Частота запросов. Не запрашивайте одни и те же данные чаще, чем нужно. Лимиты частоты сейчас не настроены, но могут быть введены.

6. Ошибки

Ошибка возвращается в JSON:

{
  "status": "error",
  "message": "GDD93 Не получена дата",
  "error": "Не получена дата",
  "error_num": "GDD93"
}

Поле error_num содержит код ошибки. Поле message начинается с этого же кода.

HTTP	Код	Причина	Что делать
401	NO_AUTH	Токен истёк, отозван или неверен	Получить новый токен (шаг 1) и повторить запрос
400	AS…	Операция не разрешена для вашей учётки	Проверьте type. Для вашей учётки разрешён только get_order_list
400	CA…	Не получен ключ запроса	Проверьте заголовок Authorization
400	GDD… Не получена дата	Не передан from_data_date или to_data_date	Передайте оба параметра
400	GDD… Выбранная торговая точка … не доступна	data_tt содержит ТТ, недоступную вашей учётке	Уточните список торговых точек
400	GOL… Ошибка при выполнении запроса	Ошибка на стороне сервера	Повторите запрос позже. Если ошибка повторяется, сообщите код

Пример ошибки прав

Запрос с ключом интеграции в теле вместо токена:

{
  "status": "error",
  "message": "AS1234 Недостаточно прав для выполнения операции",
  "error": "Недостаточно прав для выполнения операции",
  "error_num": "AS1234"
}

7. Пример клиента (псевдокод)

token = None
token_expires_at = 0

def get_token():
    response = post({"type": "auth_token", "key": API_KEY})
    return response["access_token"], time() + response["expires_in"]

def get_orders(date_from, date_to, data_tt=None):
    global token, token_expires_at
    if token is None or time() > token_expires_at - 60:
        token, token_expires_at = get_token()

    body = {"type": "get_order_list", "from_data_date": date_from, "to_data_date": date_to}
    if data_tt:
        body["data_tt"] = data_tt

    response = post(body, headers={"Authorization": f"Bearer {token}"})
    if response.status_code == 401:
        token, token_expires_at = get_token()
        response = post(body, headers={"Authorization": f"Bearer {token}"})
    return response.json()