API

API
Методы
Аутентификация и авторизация
Получить маркер доступа
Проверка маркера доступа
Организации (2.6.1)
Получение списка организаций
Получение информации о заданной организации
Номенклатура (меню)
Получить дерево номенклатуры
Получить картинку (изображение продукта)
Заказы
Создание заказа
Информация о заказе
Акции (2.6.1)
Получение списка акций в заданной организации
Ответы и коды ошибок
Внутренние ошибки сервера
Данные
Простые типы
DateTime
Date
Time
TimeSpan
Составные типы
Group
Product
Modifer
Address
OrderRequest
Order
OrderItem
OrderItemModifier
Customer
OrderInfo
OrganizationInfo (2.6.1)
SpecialInfo (2.6.1)
ContactInfo (2.6.1)
API
Методы
Ответы и коды ошибок
Данные
Версия API
Базовый адрес протокола https
0
https://api.iiko.net:9900
Методы
Последняя колонка указывает особые условия для поля:
* - обязательное поле
Аутентификация и авторизация
Базовый адрес сервиса: /api/0/auth
Все методы данного сервиса работают по протоколу https.
Получить маркер доступа
Проверка маркера доступа
Получить маркер доступа
Маркер доступа выдается на фиксированный интервал времени. По умолчанию это - 15
минут.
Логин и пароль на доступ к платформе и ее сервисам выдаются компанией iiko в ручном
режиме. Впоследствии эта процедура будет автоматизирована.
/api/0/auth/access_token?user_id={user_id}&user_secret={user_secret}
Метод HTTP
GET
Параметры
user_id
string
Идентификатор клиента
*
user_secret
string
Пароль клиента
*
Ответ
string
Маркер доступа, используемый для авторизации в службах iikoNet
Пример
https://iiko.net/api/0/auth/access_token?user_id=client&user_secret=secret
Проверка маркера доступа
Внимание: использовать только при разработке. Нельзя использовать в поставляемой
версии, так как метод может быть удален в любой момент.
/api/0/auth/echo?msg={msg}&access_token={accessToken}
Параметры
msg
string
Сообщение
*
accessToken
string
Маркер доступа
*
Ответ
string
Сообщение, или “Wrong access token”, если маркер доступа не прошел проверку.
Организации (2.6.1)
Все методы этого сервиса работают по протоколу https.
Интерфейс предназначен для получения списка организаций с названиями, описаниями,
логотипами, контактной информацией, адресом. Предполагаемый сценарий использования интеграция с внешними системами, отображающими организации с доп. информацией на
картах, в списках и т.п.
Получение списка организаций
/api/0/organization/list?access_token={accessToken}&request_timeout={requestTimeout}
Метод HTTP
GET
Аутентификация
обязательная
Параметры
accessToken
string
Маркер доступа
*
requestTimeout TimeSpan Таймаут для выполнения запроса. Указывает на время
обработки запроса на серверный стороне, не учитывая
транспортные задержки.
Ответ
OrganizationInfo[]
Информация о организациях.
Пример
{
{ "organizationId":"1721531da-7ed5-4cf8-3ad1f-370031d2e6b1",
“name”:”ArteFAQ”, … },
{ "organizationId":"1721531da-7ed5-4cf8-3ad1f-370031d2e6b2",
“name”:”DeFAQto”, … }
}
Получение информации о заданной организации
Возвращает поля-описатели организации
/api/0/organization/organizationId?access_token={accessToken}&request_timeout={requestTime
out}
Метод HTTP
GET
Аутентификация
обязательная
Параметры
accessToken
string
Маркер доступа
*
organizationId
Guid
Идентификатор организации
*
requestTimeout TimeSpan Таймаут для выполнения запроса. Указывает на время
обработки запроса на серверный стороне, не учитывая
транспортные задержки.
Ответ
OrganizationInfo
Информация о организации
Пример
{
"organizationId":"1721531da-7ed5-4cf8-3ad1f-370031d2e6b1",
“name”:”ArteFAQ”,
“description”:”Greate place to socialize and meet with ladies”,
“location”:”Moscow-somewhere (ask google for geolocation and route)”
}
Номенклатура (меню)
Все методы этого сервиса работают по протоколу https.
Получить дерево номенклатуры
Получить картинку (изображение продукта)
Получить дерево номенклатуры
/api/0/nomenclature/organizationId?revision={revision}
Один запрос возвращает информацию как о группах, так и о продуктах. Ревизия одна на все
дерево продуктов. Метод возвращает:
1. полное дерево продуктов, если в нем были изменения,
2. null, если переданная ревизия является актуальной.
Метод HTTP
GET
Аутентификация
обязательная
Параметры
accessToken
string
Маркер доступа
*
organizationId
Guid
Идентификатор организации
*
revision
long
Ревизия
Ответ
groups
Group[]
Группы
products
Product[]
Продукты
revision
long
Ревизия
Пример
{
"groups": [
{
"code": null,
"description": null,
"id": "9fa0dd9a-03f3-4d27-b74a-500000000002",
"name": "Закуски",
"order": 0,
"parentGroup": "9fa0dd9a-03f3-4d27-b74a-500000000001",
"imageId": null
},
{
"code": null,
"description": null,
"id": "9fa0dd9a-03f3-4d27-b74a-500000000001",
"name": "Основное меню",
"order": 0,
"parentGroup": null,
"imageId": null
}
],
"products": [
{
"code": null,
"description": null,
"id": "9fa0dd9a-03f3-4d27-b74a-000000000003",
"name": "Рыба в кляре",
"carbohydrateAmount": null,
"energyAmount": null,
"fatAmount": null,
"fiberAmount": null,
"groupdId": null,
"groupModifiers": [
],
"modifiers": [
],
"price": 0.00000,
"type": "dish",
"weight": null,
"imageId": null,
"isIncludedInMenu": true,
"order": 1,
"parentGroup": null
},
{
"code": null,
"description": null,
"id": "9fa0dd9a-03f3-4d27-b74a-000000000001",
"name": "bread",
"carbohydrateAmount": null,
"energyAmount": null,
"fatAmount": null,
"fiberAmount": null,
"groupModifiers": [
],
"modifiers": [
{
"maxAmount": 1,
"minAmount": 0,
"modifierId": "9fa0dd9a-03f3-4d27-b74a-000000000002"
}
],
"price": 10.00000,
"type": "good",
"weight": null,
"imageId": null,
"isIncludedInMenu": true,
"order": 0,
"parentGroup": "9fa0dd9a-03f3-4d27-b74a-500000000002"
},
{
"code": null,
"description": null,
"id": "9fa0dd9a-03f3-4d27-b74a-000000000002",
"name": "butter",
"carbohydrateAmount": null,
"energyAmount": null,
"fatAmount": null,
"fiberAmount": null,
"groupModifiers": [
],
"modifiers": [
],
"price": 0.00000,
"type": "modifier",
"weight": null,
"imageId": null,
"isIncludedInMenu": false,
"order": 0,
"parentGroup": null
}
],
"revision": 13985090
}
Получить картинку (изображение продукта)
/api/0/images/imageId.jpg
Возвращает картинку по ее идентификатору.
Метод HTTP
GET
Аутентификация
обязательная
Параметры
accessToken
string
Маркер доступа
*
imageId
Guid
Идентификатор картинки
*
Ответ
Картинка.
Заказы
Создание\редактирование заказа
Информация о заказе
Создание/Изменение заказа
/api/0/orders/add?access_token={accessToken}&request_timeout={requestTimeout}
При создании заказа предполагается, что идентификатор задается клиентом. Если
идентификатор корректен, то заказ создается с ним. Если идентификатор не корректен, то
возвращается ошибка.
Идентификатор пользователя позволяет выбрать уже зарегистрированного пользователя или
создать нового. Если идентификатор не корректен, то возвращается ошибка.
Метод HTTP
POST
Аутентификация
обязательная
Параметры
Маркер доступа
accessToken
string
orderRequest
OrderRequest Запрос на создание заказа
requestTimeout TimeSpan
Таймаут для выполнения запроса. Указывает на время
обработки запроса на серверный стороне, не учитывая
транспортные задержки.
Ответ
orderInfo
OrderInfo
Информация о заказе
Пример
{
"restaurantId":"1721531da-7ed5-4cf8-3ad1f-370031d2e6b1",
"customer":{"id":"88529d26-efa5-48e2-af5e-96c245f62d26", "name":"Client", "phone":"Phone"},
"order":
{
"id":"76da34ed-7952-49e3-a2fa-4a0283d510b8",
"phone":"Phone",
"address":{"street":"Street-1", "home":"1"},
"date":"2011-09-20 18:30:00",
"items": [
{
"id":"040adebb-695a-4687-93bc-4ad30b370b83",
"name":"Пицца",
"amount":"1",
"modifiers":[
{
*
*
"id": "8a5b6dce-c5d1-4932-9c61-073b3dd57645",
"name":"Топпинг",
"amount":"3",
"groupId":"35e3d0c0-cb19-4bf1-b760-fe8c0061f4d1",
"groupName":"Топпинги для пиццы"
}
]
}
]
}
}
Информация о заказе
/api/0/orders/info?access_token={accessToken}&restaurant={restaurantId}&order={orderId}&
request_timeout={requestTimeout}
Получение информации о предварительно созданном заказе.
Метод HTTP
GET
Аутентификация
обязательная
Параметры
accessToken
string
Маркер доступа
*
restaurantId
string
Идентификатор ресторана
*
orderId
string
Идентификатор заказа
*
requestTimeout TimeSpan Таймаут для выполнения запроса. Указывает на время
обработки запроса на серверный стороне, не учитывая
транспортные задержки.
Ответ
orderInfo
OrderInfo
Информация о заказе
Акции (2.6.1)
Все методы этого сервиса работают по протоколу https.
Получение списка акций в заданной организации
/api/0/organization/organizationId/specials?access_token={accessToken}&request_timeout={requ
estTimeout}
Метод HTTP
GET
Аутентификация
обязательная
Параметры
accessToken
string
Маркер доступа
*
organizationtId
Guid
Идентификатор организации
*
requestTimeout TimeSpan Таймаут для выполнения запроса. Указывает на время
обработки запроса на серверной стороне, не учитывая
транспортные задержки.
Ответ
orderInfo SpecialInfo[] Информация об электронных флаерах и суммовых скидках,
действующих в данной организации
Пример
Ответы и коды ошибок
Для индикации результата запроса используется HTTP статус. Частые статусы:
200 (OK)
Выполнено без ошибок
400 (Bad Request)
Ошибка в параметрах запроса
401 (Unauthorized)
Ошибка авторизации
403 (Forbidden)
Запрошенная информация недоступна с указанными данными
авторизации
404 (Not Found)
Указанный URI или ресурс не существует
408 (Request Timeout)
Время ожидания для выполнения запроса истекло
500 (Internal Server
Error)
Внутренняя ошибка сервера.
Дополнительные данные об ошибке могут указываться в параметре errorType.
Внутренние ошибки сервера
В качестве внутренних ошибок сервера с кодом 500 (Internal Server Error) в параметре
errorType могут возвращаться следующие значения.
Что
проверяем
Суть проблемы
Код
ошибки
iiko
Сообщение.
id ресторана
Ресторан должен быть
зарегистрирован.
101
Неизвестный код ресторана
ХХХХХХХХХХ.
Точка
приготовления
У заказа уже назначена
точка приготовления.
102
Заказ уже обрабатывается на точке.
Имя клиента
Задано пустое имя
клиента или имя клиента
состоит только из
пробелов.
103
Задано пустое имя клиента.
Блюдо
Отсутствует в продаже
104
Блюдо ХХХХХХХХХХ запрещено к
продаже.
Блюдо
Неизвестный GUID
105
Неизвестный код блюда
ХХХХХХХХХ.
Блюдо
К блюду не применены
обязательные
модификаторы
106
К блюду ХХХХХХХХХХХ применены
не все обязательные модификаторы.
Модификатор
Отсутствует в продаже
107
Модификатор ХХХХХХХХХХ
запрещен к продаже.
Модификатор
Неизвестный GUID
108
Неизвестный код модификатора
ХХХХХХХХХ
Модификатор
Не применим к
указанному основному
блюду
109
Модификатор ХХХХХХХХХХХ не
может продаваться с блюдом
YYYYYYYYYY.
Модификатор
Не соблюдаются min/max
настройки для
одиночного
модификатора.
110
Количество модификатора
XXXXXXXXXX не соответствует
настройкам минимума/максимума
(XX/YY).
Модификатор
Не соблюдаются min/max
настройки группы для
группового
модификатора.
111
Количество группового
модификатора ХХХХХХХХХХ не
соответствует настройкам
минимума/максимума для группы
ZZZZZZZZZ (XX/YY).
Модификатор
Для группового
модификатора не задана
группа или задана
несуществующая.
112
У группового модификатора
ХХХХХХХХХХХХ некорректно задана
группа.
Концепция
Указана несуществующая 113
концепция
Концепция ХХХХХХХ не определена.
Состав заказа
Пустой заказ
203
Невозможно создать/изменить заказ
без позиций.
Телефон
клиента
Пустой номер телефона
206
Невозможно создать/изменить заказ,
телефонный номер клиента пуст.
Данные
Простые типы
DateTime
Дата и время.
Строка в формате “YYYY-MM-DD hh:mm:ss”, где
YYYY - год;
MM - месяц (начиная с 1 - январь);
DD - день;
hh - час (от 00 до 23);
mm - минута (от 00 до 59);
ss - секунда (от 00 до 59).
Date
Дата.
Строка в формате “YYYY-MM-DD”, где
YYYY - год;
MM - месяц (начиная с 1 - январь);
DD - день.
Time
Время.
Строка в формате “hh:mm:ss”, где
hh - час (от 00 до 23);
mm - минута (от 00 до 59);
ss - секунда (от 00 до 59).
TimeSpan
Период времени.
Строка в формате “hh:mm:ss”, где
hh - часы;
mm - минуты;
ss - секунды.
Составные типы
Последняя колонка указывает особые условия для поля:
* - обязательное поле
Group
Группа
id
Guid
Уникальный идентификатор
name
string
Название
code
string
Артикул
description
string
Описание
order
int
Порядок отображения
parentGroup
Guid
Родительская группа
imageId
Guid
Идентификатор картинки
isIncludedInMenu
bool
Нужно ли группу отображать в дереве номенклатуры
Product
Продукт
id
Guid
Уникальный идентификатор
name
string
Название
code
string
Артикул
description
string
Описание
order
int
Порядок отображения
parentGroup
Guid
Родительская группа
imageId
Guid
Идентификатор картинки
groupId
Guid
Идентификатор группы
price
decimal
Цена
carbohydrateAmount
decimal
Количество углеводов
energyAmount
decimal
Энергетическая ценность
fatAmount
decimal
Количество жиров
fiberAmount
decimal
Количество белков
weight
decimal
Вес одной единицы в кг
type
string
Тип:
●
●
●
dish - блюдо
good - товар
modifier - модификатор
isIncludedInMenu
bool
Нужно ли продукт отображать в дереве номенклатуры
modifiers
Modifer[]
Одиночные модификаторы
groupModifiers
Modifer[]
Групповые модификаторы
Modifer
Модификатор
modifierId
Guid Идентификатор модификатора. Идентификатор продукта для
одиночного модификатора и идентификатор группы - для группового.
maxAmount int
Максимальное количество модификатора
minAmount
Минимальное количество модификатора
int
*
Address
Адрес
street
string
Улица
*
home
string
Дом
*
housing
string
Корпус
apartment
string
Квартира
comment
string
Дополнительная информация
OrderRequest
restaurantId
string
Идентификатор ресторана
*
customer
Customer
Заказчик
*
order
Order
Заказ
*
Order
Заказ
id
Guid
Идентификатор заказа
phone
string
Контактный телефон
address
Address
Адрес доставки заказа
date
DateTime
Дата выполнения заказа
conception
string
Концепция
items
OrderItem[]
Элементы заказа
comment
string
Комментарий к заказу
*
OrderItem
Элемент заказа
id
Guid
Идентификатор продукта
*
name
string
Название продукта
*
amount
decimal
Количество
*
modifiers
OrderItemModifier[]
Модификаторы
OrderItemModifier
Модификатор элемента заказа
id
Guid
Идентификатор продукта
*
name
string
Название продукта
*
amount
decimal
Количество
*
groupId
Guid
Идентификатор группы в случае группового модификатора
groupName
string
Имя группы в случае группового модификатора
Customer
Заказчик
id
Guid
Идентификатор
*
name
string
Имя
phone
string
Телефонный номер
OrderInfo
Описание заказа
orderId
Guid
Идентификатор заказа
customerId
Guid
Идентификатор заказчика
restaurantId string
*
Идентификатор ресторана
sum
decimal Сумма заказа
discount
decimal Сумма скидки
number
string
Понятный номер заказа. Может использоваться для передачи
клиенту. Уникальность не гарантирована (может быть уникальным в
рамках одного обслуживающего сервера).
status
string
Статус заказа. Варианты значения для доставки:
● Новая
● Ждет отправки
● В пути
● Доставлена
● Отменена
OrganizationInfo (2.6.1)
Описание организации (Ресторан, AЗС, Гостиница, ...)
id
Guid
Идентификатор организации
*
name
string
Название организации(не юр. лицо)
*
description
string
Описание органиации данное владельцем
logo
string
Ссылка на изображение с логотипом организации.
contact
ContactInfo
Контактная информация в свободной форме.
homePage
string
Домашняя страница
SpecialInfo (2.6.1)
Описание акции
Идентификатор акции
*
organizationId Guid
Идентификатор организации
*
name
string
Название акции
*
description
string
Подробности акции
*
url
string
Ссылка на акцию для того, чтобы положить ее в “кошелек”.
*
Платформа автоматически добавляет в URL параметр
partner_id=guid равный ИД партнера, запросившего информацию
об акции.1
start
DateTime Начало акции. Не задано - либо отсутствует, либо определяется
другими механизмами.
end
DateTime Окончание акции. Не задано - либо отсутствует, либо
определяется другими механизмами.
imageUrl
string
id
Guid
Ссылка на картинку одного из блюд в акции
ContactInfo (2.6.1)
Контактная информация.
phone
string
Телефон
location
string
Адрес
email
string
Адрес электронной почты
При реализации акции - при оплате заказа, это значение сохраняется в заказ iikoNet.
В текущей реализации - для справки - URL открывает страницу с пользовательским
интерфейсом iikoNet для добавления акции в кошелек пользователя.
1