API управления заказами

1. URL

https://api.onstor.ru/common/merchant/1.0/

2. Аутентификация

Запрос должен содержать действительный token в строке запроса, данных формы или JSON-теле. Токен определяет авторизованную сессию продавца.

Получение токена:

Получить или обновить токен API можно в панели управления:

Продавцы → Выберите продавца → Настройки → Поле Token

Передача параметров

Параметры передаются через GET, POST или RAW JSON в теле запроса. Допускается любой из способов и их сочетание.

3. Справочник полей

Поле	Тип	Обязательное	Описание
order_id	int	Нет	Идентификатор заказа
external_id	string	Нет	Внешний идентификатор заказа
user	object	Да*	Объект клиента
type	int	Нет	1 — доставка, 2 — самовывоз
destination_address	multilang	Да*	Адрес доставки на нескольких языках
destination_coordinates	object	Да**	Координаты доставки: { "lat": -58.3816, "lon":-34.6037 }
destination_info	string	Нет	Дополнительные сведения об адресе доставки
comment	string	Нет	Комментарий к заказу
cost	decimal	Нет	Стоимость товаров
discount	decimal	Нет	Сумма скидки
bonus	decimal	Нет	Сумма бонусов
promocode_amount	decimal	Нет	Сумма скидки по промокоду
tips	decimal	Нет	Сумма чаевых
fee	decimal	Нет	Сервисный сбор
vat	decimal	Нет	Сумма налога
delivery	decimal	Нет	Стоимость доставки
payment_commission	decimal	Нет	Комиссия за оплату
reserve	decimal	Нет	Сумма резерва
refund	decimal	Нет	Сумма возврата
total	decimal	Нет	Итоговая сумма
order_status	object / int	Нет	Статус заказа
time_create	datetime	Нет	Дата и время создания заказа
time_finish	datetime	Нет	Планируемая дата и время завершения
time_delivery	datetime	Нет	Фактическая дата и время доставки
courier	object	Нет	Объект курьера
asap	bool / int	Нет	1 — как можно скорее, 0 — по расписанию / предзаказ
cutlery	int	Нет	Число персон / комплектов приборов
paid	bool	Нет	Признак завершённой оплаты
paid_refund	bool	Нет	Признак выполненного возврата
pay_type	object / int	Нет	Способ оплаты
pay_link	string	Нет	URL оплаты
currency	string	Нет	Код валюты
cart	array	Да*	Корзина заказа / список позиций

Поле user

Поле	Тип	Обязательное	Описание
user	object	Да	Данные клиента, связанного с заказом.
user.phone	string	Да	Номер телефона клиента.
user.name	string	Да	Полное имя клиента.
user.email	string	Нет	Электронная почта клиента.

Поле cart

Поле	Тип	Обязательное	Описание
cart	array	Да	Список позиций в заказе.
cart[].item	object	Да	Объект товара.
cart[].item.name	multilang object	Да	Название товара на нескольких языках.
cart[].item.description	multilang object	Нет	Описание товара на нескольких языках.
cart[].item.img	string	Нет	URL изображения товара.
cart[].qty	decimal	Да	Количество товара.
cart[].price	decimal	Да	Цена единицы товара.
cart[].discount	decimal	Нет	Сумма скидки на позицию корзины.

* Обязательно для создания заказа в типовом сценарии доставки. Точные правила проверки зависят от бизнес-логики и настроек продавца.

** Для создания заказа обязательно передать точные координаты места назначения.

Значение многоязычного поля

Строка применяется ко всем языкам компании. В объекте значения назначаются соответствующим языкам; отсутствующие заполняются последним переданным значением. Коды языков, не включённых в настройках компании, игнорируются.

 "destination_address": {
      "es": "Buenos Aires, Calle Falsa 123",
      "en": "Fake Street 123, Buenos Aires"
    }

4. Структура ответа

{
  "auth": {
    "status": "OK",
    "merchant": {
      "id": 427,
      "company": 228,
      "country": {
        "currency_code": "ILS"
      }
    },
    "languages": [
      {
        "code": "ES",
        "name": "Español"
      },
      {
        "code": "EN",
        "name": "English"
      },
      {
        "code": "RU",
        "name": "Русский"
      }
    ]
  },
  "payload": {
    "status": "OK",
    "error": "",
    "data": [...]
  }
}

auth.status — статус аутентификации, например OK
auth.error — описание ошибки аутентификации, если auth.status равен ERROR
auth.merchant — данные авторизованного продавца
auth.languages — доступные языки продавца / компании
payload.status — результат операции: OK или ERROR
payload.error — описание ошибки операции, если payload.status равен ERROR
payload.request_id — идентификатор запроса API, например для отслеживания webhook
payload.data — объект или массив данных в зависимости от метода

5. Выбор возвращаемых полей

По умолчанию API возвращает все доступные поля. Передайте fields — массив публичных имён полей, чтобы ограничить ответ.

Пример запроса

{
  "api": "order",
  "method": "get-all",
  "token": "...",
  "limit": 100,
  "offset": 0,
  "fields": ["order_id", "external_id", "order_status"]
}

Примечания

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

6. Получить заказы

Возвращает плоский список заказов продавца.

Запрос

Методы:GET / POST / тело RAW JSON
URL: https://api.onstor.ru/common/merchant/1.0/

Параметры

Название	Тип	Описание	Обязательное
api	string	`order`	Да
method	string	`get-all`	Да
token	string	Токен аутентификации	Да
limit	integer	Максимальное число заказов (по умолчанию: 20)	Нет
offset	integer	Смещение пагинации (по умолчанию: 0)	Нет
fields	array	Список возвращаемых полей	Нет
filter	object	Правила фильтрации. См. раздел 7 «Фильтрация результатов»	Нет

Пример запроса

{
  "api": "order",
  "method": "get-all",
  "token": "...",
  "limit": 50,
  "offset": 0,
  "fields": ["order_id", "external_id", "cart"],
  "filter": {
    "external_id": { "eq": "ext-1003" }
  }
}

Пример ответа

{
  "auth": {
    "status": "OK"
  },
  "payload": {
    "status": "OK",
    "error": "",
    "data": [
      {
        "order_id": 2289,
        "external_id": "ext-1003",
        "cart": [
          {
            "qty": 2,
            "price": 10.50,
            "total": 21.00
          }
        ]
      }
    ],
    "total": 1,
    "offset": false
  }
}

Примечания:

offset = false означает отсутствие следующей страницы.
fields ограничивает возвращаемые поля.

7. Фильтрация результатов

Метод get-all поддерживает универсальный объект filter для фильтрации по правилам SQL.

Внутри filter используются публичные имена полей.

Поддерживаемые операторы

Оператор	Описание	Пример
eq	Равно	`"order_id":{"eq":10}`
ne	Не равно	`"paid":{"ne":1}`
gt	Больше	`"total":{"gt":100}`
gte	Больше или равно	`"total":{"gte":100}`
lt	Меньше	`"total":{"lt":100}`
lte	Меньше или равно	`"total":{"lte":100}`
like	SQL LIKE (символ % указывается вручную)	`"external_id":{"like":"%1003%"}`
in	Входит в список	`"order_id":{"in":[1,2,3]}`
nin	Не входит в список	`"order_id":{"nin":[1,2,3]}`
between	Диапазон	`"total":{"between":[10,50]}`
is_null	Проверка NULL	`"external_id":{"is_null":true}`

Простой фильтр AND

{
  "filter": {
    "paid": { "eq": 1 },
    "total": { "gte": 10 }
  }
}

Результат:

paid = 1 AND total >= 10

Группы AND / OR

{
  "filter": {
    "and": [
      { "paid": { "eq": 1 } },
      { "type": { "eq": 1 } }
    ],
    "or": [
      { "external_id": { "like": "%web%" } },
      { "comment": { "like": "%web%" } }
    ]
  }
}

Только OR

{
  "filter": {
    "or": [
      { "order_status": { "eq": 1 } },
      { "order_status": { "eq": 2 } }
    ]
  }
}

Полный пример

{
  "api": "order",
  "method": "get-all",
  "token": "...",
  "limit": 50,
  "offset": 0,
  "fields": ["order_id", "external_id", "total", "paid"],
  "filter": {
    "and": [
      { "paid": { "eq": 1 } },
      { "total": { "between": [10, 50] } }
    ],
    "or": [
      { "external_id": { "is_null": false } },
      { "comment": { "like": "%promo%" } }
    ]
  }
}

Важные замечания

Указывайте % в выражениях LIKE вручную.
in: [] всегда даёт ложное условие.
nin: [] всегда даёт истинное условие.
Для логических значений рекомендуется использовать 0 / 1.

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

Создаёт новый заказ для авторизованного продавца.

Запрос

Методы:POST / тело RAW JSON
URL: https://api.onstor.ru/common/merchant/1.0/

Параметры

Название	Тип	Описание	Обязательное
api	string	`order`	Да
method	string	`create`	Да
token	string	Токен аутентификации	Да
fields	array	Список возвращаемых полей	Нет
payload	array	Данные тела запроса	Да

Пример запроса

{
  "api": "order",
  "method": "create",
  "token": "...",
  "payload": {
    "external_id": "ext-1004",
    "user": {
      "phone": "+54 (911) 1234-5678",
      "name": "Juan Perez",
      "email": "juan@example.com"
    },
    "type": 1,
    "destination_address": {
      "es": "Buenos Aires, Calle Falsa 123",
      "en": "Fake Street 123, Buenos Aires"
    },
    "destination_coordinates": { "lat": -58.3816, "lon":-34.6037 },
    "destination_info": "Depto 4B, timbre Perez",
    "comment": "Sin cebolla por favor",
    "bonus": 10,
    "promocode_amount": 5,
    "tips": 2,
    "fee": 1.5,
    "vat": 3,
    "delivery": 4,
    "payment_commission": 0.5,
    "odd": 0,
    "promocode": "WELCOME",
    "tips_percent": 5,
    "order_status": null,
    "time_finish": "2026-03-19 20:00:00",
    "time_delivery": null,
    "delivery_time": 0,
    "asap": 1,
    "cutlery": 2,
    "platform": "ios",
    "ver": "1.0.0",
    "promocode_type": 1,
    "promocode_discount": 5,
    "currency": "ARS",
    "cart": [
      {
        "item": {
          "name": {
            "es": "Hamburguesa",
            "en": "Burger"
          },
          "description": {
            "es": "Carne con queso",
            "en": "Beef with cheese"
          },
          "img": "https://example.com/burger.jpg"
        },
        "qty": 2,
        "price": 10.5,
        "discount": 1.5
      },
      {
        "item": {
          "name": {
            "es": "Papas fritas",
            "en": "Fries"
          },
          "description": {
            "es": "Papas crujientes",
            "en": "Crispy fries"
          },
          "img": "https://example.com/fries.jpg"
        },
        "qty": 1,
        "price": 5,
        "discount": 0
      }
    ]
  }
                }

Примечания

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

9. Изменить заказ

Обновляет существующий заказ.

Запрос

Методы:POST / тело RAW JSON
URL: https://api.onstor.ru/common/merchant/1.0/

Параметры

Название	Тип	Описание	Обязательное
api	string	`order`	Да
method	string	`edit`	Да
token	string	Токен аутентификации	Да
fields	array	Список возвращаемых полей	Нет
payload	array	Данные тела запроса	Да

* Обычно нужен хотя бы один идентификатор заказа: order_id или external_id, в зависимости от реализации.

Пример запроса

{
  "api": "order",
  "method": "edit",
  "token": "5486e371-631d-11f0-a416-fa163eed394d",
  "fields": ["order_status"],
  "payload": {
     "external_id": "ext-1003",
     "order_status": 4
  }
}

Примечания

Обновляются только переданные поля.
Доступные для изменения поля зависят от бизнес-логики, статуса заказа и ограничений интеграции.
Если заказ не найден или не может быть изменён, API возвращает payload.status = "ERROR".