---
slug: "iiko"
name: "iikoCloud API"
vendor: "iiko"
industry: "retail"
docsUrl: "https://api-ru.iiko.services/docs"
version: 2
updatedAt: "2026-10-24"
---

# iikoCloud API

Отрасль: Ритейл и e-commerce. Актуально на 2026-10-24.

Облачный API ресторанной системы iiko для внешних интеграций: организации и терминальные группы, внешние меню и стоп-листы, заказы на доставку и заказы в зале, банкеты и резервы, курьеры, программа лояльности iikoCard, складские и финансовые документы, номенклатура, сотрудники и OLAP-отчёты. Почти все методы — `POST` с JSON-телом; в спецификации около 350 путей, здесь — основные для доставки и меню.

## Сценарии

### Подключиться и найти свои рестораны

Первый шаг любой интеграции: токен, организации и терминальные группы, куда будут уходить заказы.

1. Создай приложение на портале разработчика public-api.iikoweb.ru — получишь appId и clientSecret (показывается один раз). В iikoWeb → «Интеграции» → «API-ключи» сгенерируй apiKey: он определяет, к каким организациям будет доступ.
2. Получи токен: POST /api/v2/access_token с apiKey, appId и clientSecret. Токен живёт час, refresh-токена нет — запрашивай новый заранее, например каждые 50 минут, и передавай в заголовке Authorization: Bearer <token>.
3. Получи организации: POST /api/1/organizations (пустой organizationIds — все доступные). returnAdditionalInfo = true добавит адрес и версию RMS.
4. Получи терминальные группы доставки: POST /api/1/terminal_groups с organizationIds. Их ID понадобятся при создании заказа.

```bash
TOKEN=$(curl -s -X POST https://api-ru.iiko.services/api/v2/access_token \
  -H 'Content-Type: application/json' \
  -d '{"apiKey": "<apiKey>", "appId": "<appId>", "clientSecret": "<clientSecret>"}' | jq -r .token)

curl -s -X POST https://api-ru.iiko.services/api/1/organizations \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"organizationIds": [], "returnAdditionalInfo": true}'

curl -s -X POST https://api-ru.iiko.services/api/1/terminal_groups \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"organizationIds": ["<organizationId>"]}'
```

### Выгрузить меню на сайт с учётом стоп-листа

Меню сайта или приложения доставки всегда совпадает с кассой: цены, позиции и то, что сейчас закончилось.

1. Получи список внешних меню и ценовых категорий: POST /api/2/menu (тело пустое). В ответе externalMenus и priceCategories.
2. Загрузи нужное меню: POST /api/menu/v3/by_id с externalMenuId, organizationId и при необходимости priceCategoryId. Старые /api/1/nomenclature и /api/2/menu/by_id устарели — не используй их.
3. Получи стоп-листы: POST /api/1/stop_lists с organizationIds (и terminalGroupsIds, если нужен конкретный ресторан). Скрывай или помечай позиции из стопа.
4. Меню обновляй по расписанию, а стоп-лист — часто: он меняется в течение дня.

```bash
H=(-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json')

curl -s -X POST https://api-ru.iiko.services/api/2/menu "${H[@]}" -d '{}'

curl -s -X POST https://api-ru.iiko.services/api/menu/v3/by_id "${H[@]}" \
  -d '{"externalMenuId": "<externalMenuId>", "organizationId": "<organizationId>", "priceCategoryId": null}'

curl -s -X POST https://api-ru.iiko.services/api/1/stop_lists "${H[@]}" \
  -d '{"organizationIds": ["<organizationId>"], "returnSize": true}'
```

### Передать заказ доставки с сайта на кассу

Заказ с сайта сразу появляется на кухне и у курьеров — без ручного переноса оператором.

1. Получи типы оплат: POST /api/1/payment_types с organizationIds — нужен ID типа оплаты для order.payments.
2. Создай заказ: POST /api/1/deliveries/create с organizationId, terminalGroupId и order — phone (с +), orderServiceType (DeliveryByCourier или DeliveryByClient для самовывоза), deliveryPoint.address, items (тип, productId, amount; productSizeId — если у блюда есть размеры), payments. Передай свой order.id (UUID) — он защитит от дублей при повторе.
3. createOrderSettings.checkStopList = true не даст создать заказ с позицией из стоп-листа.
4. Создание асинхронное: в ответе correlationId. Проверяй POST /api/1/commands/status с organizationId и correlationId, пока state не станет Success или Error.
5. Текущий статус и детали заказа — POST /api/1/deliveries/by_id с organizationId и orderIds. Время в iiko — локальное время терминала, без часового пояса.

```python
import time, uuid, requests

API = "https://api-ru.iiko.services/api/1"
H = {"Authorization": f"Bearer {token}"}
org, tg = "<organizationId>", "<terminalGroupId>"
order_id = str(uuid.uuid4())

resp = requests.post(f"{API}/deliveries/create", headers=H, json={
    "organizationId": org,
    "terminalGroupId": tg,
    "createOrderSettings": {"checkStopList": True},
    "order": {
        "id": order_id,
        "externalNumber": "SITE-1042",
        "phone": "+79990001122",
        "orderServiceType": "DeliveryByCourier",
        "deliveryPoint": {"address": {"street": {"name": "Ленина", "city": "Екатеринбург"}, "house": "10"},
                          "comment": "Домофон 45"},
        "items": [{"type": "Product", "productId": "<productId>", "amount": 2}],
        "payments": [{"paymentTypeKind": "Card", "paymentTypeId": "<paymentTypeId>", "sum": 1580}],
        "comment": "Без лука",
    },
}).json()

while True:
    st = requests.post(f"{API}/commands/status", headers=H,
                       json={"organizationId": org, "correlationId": resp["correlationId"]}).json()
    if st["state"] != "InProgress":
        break
    time.sleep(2)
print(st["state"])
```

### Отменить заказ и получать статусы вебхуками

Гость отменил заказ на сайте — отмена доходит до кассы; статусы заказов приходят к тебе сами, без опроса.

1. Отмени заказ: POST /api/1/deliveries/cancel с organizationId, orderId и, при необходимости, cancelCauseId и cancelComment. Это тоже команда — итог проверяй через POST /api/1/commands/status. Ответ 410 значит, что correlationId устарел.
2. Чтобы не опрашивать заказы, настрой вебхуки: POST /api/1/webhooks/update_settings с organizationId, webHooksUri (твой HTTPS-обработчик), authToken (iiko передаст его обработчику — проверяй его) и webHooksFilter.
3. Обработчик должен быстро отвечать 200 и обрабатывать событие асинхронно; по ID заказа из события сверяйся через POST /api/1/deliveries/by_id.

```bash
H=(-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json')

curl -s -X POST https://api-ru.iiko.services/api/1/deliveries/cancel "${H[@]}" \
  -d '{"organizationId": "<organizationId>", "orderId": "<orderId>", "cancelComment": "Гость отменил на сайте"}'

curl -s -X POST https://api-ru.iiko.services/api/1/webhooks/update_settings "${H[@]}" \
  -d '{"organizationId": "<organizationId>", "webHooksUri": "https://example.ru/iiko/webhook", "authToken": "<секрет>"}'
```

## Базовые URL

- Боевой: `https://api-ru.iiko.services`

## Авторизация

Тип: Bearer-токен

- Зарегистрируйтесь на портале разработчика `https://public-api.iikoweb.ru/portal` и создайте приложение — получите `appId` и одноразово показываемый `clientSecret`.
- В iikoWeb → «Интеграции» → «API-ключи» сгенерируйте `apiKey`.
- Получите токен методом `POST /api/v2/access_token` и передавайте его во всех запросах: `Authorization: Bearer {token}`.

Токен (JWT) действует 1 час; refresh-токена нет — запрашивайте новый до истечения срока. Старый метод `POST /api/1/access_token` с `apiLogin` устарел.

## Методы

### POST /api/v2/access_token — Получение токена

В ответе: `correlationId` и `token`.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `apiKey` | body | string | да | API-ключ из iikoWeb; определяет доступные организации |
| `appId` | body | string | да | ID приложения с портала разработчика (uuid) |
| `clientSecret` | body | string | да | Секрет приложения с портала разработчика |
| `Timeout` | header | integer | нет | Таймаут в секундах, по умолчанию 15 |

### POST /api/1/organizations — Организации

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `organizationIds` | body | array | нет | ID организаций; по умолчанию — все доступные |
| `returnAdditionalInfo` | body | boolean | нет | Вернуть доп. информацию (версия RMS, страна, адрес) |
| `includeDisabled` | body | boolean | нет | Включить отключённые организации |
| `returnExternalData` | body | array | нет | Ключи внешних данных |

### POST /api/1/terminal_groups — Группы терминалов доставки

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `organizationIds` | body | array | да | ID организаций |
| `includeDisabled` | body | boolean | нет | Включить отключённые группы |
| `returnExternalData` | body | array | нет | Ключи внешних данных |

### POST /api/2/menu — Внешние меню и ценовые категории

Без параметров. В ответе: `correlationId`, `externalMenus`, `priceCategories`.

### POST /api/menu/v3/by_id — Внешнее меню по ID

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `externalMenuId` | body | string | да | ID внешнего меню из /api/2/menu |
| `organizationId` | body | string | да | ID организации (uuid) |
| `priceCategoryId` | body | string | нет | Ценовая категория из /api/2/menu |

### POST /api/1/stop_lists — Стоп-листы

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `organizationIds` | body | array | да | ID организаций |
| `terminalGroupsIds` | body | array | нет | ID терминальных групп |
| `returnSize` | body | boolean | нет | Возвращать размеры блюд |

### POST /api/1/payment_types — Типы оплат

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `organizationIds` | body | array | да | ID организаций |

### POST /api/1/deliveries/create — Создание заказа на доставку

Команда: статус выполнения проверяется через `/api/1/commands/status`.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `organizationId` | body | string | да | ID организации (uuid) |
| `terminalGroupId` | body | string | нет | ID терминальной группы, куда отправить заказ |
| `createOrderSettings.transportToFrontTimeout` | body | integer | нет | Сколько секунд даётся на доставку заказа в iikoFront |
| `createOrderSettings.checkStopList` | body | boolean | нет | Проверять позиции по стоп-листу |
| `order` | body | object | да | Заказ |
| `order.id` | body | string | нет | ID заказа (уникальный uuid); если не передан — генерируется |
| `order.externalNumber` | body | string | нет | Внешний номер заказа |
| `order.completeBefore` | body | string | нет | Время выполнения yyyy-MM-dd HH:mm:ss.fff, локальное для терминала |
| `order.phone` | body | string | да | Телефон: начинается с +, не меньше 8 цифр |
| `order.orderTypeId` | body | string | нет | Тип заказа; указывается он или orderServiceType |
| `order.orderServiceType` | body | string | нет | Тип обслуживания; указывается он или orderTypeId |
| `order.deliveryPoint.address` | body | object | нет | Адрес доставки (не нужен для самовывоза) |
| `order.deliveryPoint.coordinates` | body | object | нет | Координаты адреса |
| `order.deliveryPoint.comment` | body | string | нет | Доп. информация |
| `order.comment` | body | string | нет | Комментарий к заказу |
| `order.customer.type` | body | string | да | Тип клиента (если передаётся customer) |
| `order.guests.count` | body | integer | да | Число персон — определяет число приборов (если передаётся guests) |
| `order.items` | body | array | да | Позиции заказа |
| `order.items[].type` | body | string | да | Тип позиции |
| `order.items[].amount` | body | number | да | Количество |
| `order.items[].productSizeId` | body | string | нет | Размер; обязателен, если у позиции есть шкала размеров |
| `order.items[].comment` | body | string | нет | Комментарий |
| `order.combos` | body | array | нет | Комбо: id, name, amount, price, sourceId |
| `order.payments` | body | array | нет | Оплаты заказа |
| `order.marketingSourceId` | body | string | нет | Рекламный источник |
| `order.priceCategoryId` | body | string | нет | Ценовая категория |

### POST /api/1/deliveries/by_id — Заказы доставки по ID

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `organizationId` | body | string | да | ID организации |
| `orderIds` | body | array | нет | ID заказов; обязательно, если нет posOrderIds |
| `posOrderIds` | body | array | нет | ID заказов в POS; обязательно, если нет orderIds |
| `sourceKeys` | body | array | нет | Ключи источников |
| `returnExternalDataKeys` | body | array | нет | Ключи внешних данных |

### POST /api/1/deliveries/cancel — Отмена заказа доставки

Команда; статус — через `/api/1/commands/status`.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `organizationId` | body | string | да | ID организации |
| `orderId` | body | string | да | ID заказа |
| `cancelCauseId` | body | string | нет | Причина отмены из /api/1/cancel_causes |
| `cancelComment` | body | string | нет | Комментарий к отмене |
| `removalTypeId` | body | string | нет | Тип удаления для напечатанных позиций |
| `movedOrderId` | body | string | нет | ID нового заказа, если заказ перенесён |

### POST /api/1/order/create — Создание заказа в зале

Команда; статус — через `/api/1/commands/status`.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `organizationId` | body | string | да | ID организации |
| `terminalGroupId` | body | string | да | ID терминальной группы |
| `order.items` | body | array | да | Позиции заказа |
| `order.tableIds` | body | array | нет | ID столов |
| `order.phone` | body | string | нет | Телефон гостя |
| `order.guestCount` | body | integer | нет | Число гостей |
| `order.payments` | body | array | нет | Оплаты |
| `createOrderSettings.servicePrint` | body | boolean | нет | Автоматическая сервисная печать |

### POST /api/1/commands/status — Статус команды

Код ответа `410` — `correlationId` больше не поддерживается.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `organizationId` | body | string | да | ID организации |
| `correlationId` | body | string | да | ID операции из ответа команды |

### POST /api/1/webhooks/update_settings — Настройка вебхуков

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `organizationId` | body | string | да | ID организации |
| `webHooksUri` | body | string | да | URL обработчика вебхуков |
| `authToken` | body | string | нет | Токен авторизации, передаваемый обработчику |
| `webHooksFilter` | body | object | нет | Фильтр событий |

### POST /api/1/loyalty/iiko/customer/info — Информация о госте (лояльность)

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `type` | body | string | да | Критерий поиска гостя |
| `organizationId` | body | string | нет | ID организации |

## Нюансы

- Все запросы, кроме получения токена, требуют заголовок `Authorization`; в каждом можно передать заголовок `Timeout` (секунды).
- Методы-команды (создание, отмена, изменение заказов) выполняются асинхронно: в ответе `correlationId`, итог — через `/api/1/commands/status`.
- Форматы: uuid — строка UUID; дата-время — `yyyy-MM-dd HH:mm:ss.fff` без часового пояса, локальное время терминала.
- Методы сгруппированы по группам ограничений (`Data: dictionaries`, `Data: menu`, `Orders: creating` и др.) — права API-ключа настраиваются по этим группам.
- Часть полей доступна только с определённой версии iikoRMS (в документации — пометки «Allowed from version»).
- Устаревшие методы: `/api/1/access_token`, `/api/1/nomenclature`, `/api/2/menu/by_id` — используйте `/api/v2/access_token` и `/api/menu/v3/by_id`.

## Ошибки

| Код | Описание |
|---|---|
| `400` | Некорректный запрос |
| `401` | Нет авторизации или токен истёк |
| `408` | Таймаут запроса |
| `410` | correlationId больше не поддерживается (commands/status) |
| `500` | Внутренняя ошибка |

## Источники

- [iikoCloud API](https://api-ru.iiko.services/docs)
- [Спецификация OpenAPI](https://api-ru.iiko.services/api-docs/docs)
- [Портал разработчика iiko](https://public-api.iikoweb.ru/portal)

---

Если этого недостаточно — официальная документация: https://api-ru.iiko.services/docs
JSON: https://mcp-everything.ru/api/integrations/iiko. MCP: https://mcp-everything.ru/mcp