Авторизация в iiko API

Эта статья — продолжение инструкций по началу работы с iiko API:

После того как вы зарегистрировались на портале разработчика и создали приложение, у вас есть всё необходимое для авторизации. Здесь описано, как получить токен доступа и использовать его в запросах к Cloud API.

Быстрый старт

Соберите три значения: appId, clientSecret, apiKey (см. ниже).
Обменяйте их на токен — POST /api/v2/access_token.
Передавайте токен в каждом запросе: Authorization: Bearer {token}.
Токен живёт 1 час, refresh-токена нет — по истечении запросите новый.

Что нужно для авторизации

Для запроса токена нужны три значения, полученные на предыдущих шагах:

Значение	Откуда взять	Особенность
`appId`	Карточка приложения на портале разработчика — api.iiko.help/portal	Не меняется в течение жизни приложения
`clientSecret`	Показывается один раз при создании приложения	При утрате — сбросить в карточке приложения
`apiKey`	iikoWeb → Настройки Cloud API → Добавить интеграцию (в части версий кабинета — Интеграции → API-ключи)	Определяет, к каким ресторанам токен даёт доступ

Про название ключа. В старых инструкциях и в устаревшем методе v1 API-ключ называется apiLogin. Это один и тот же ключ, сгенерированный в iikoWeb: в запросе /api/1/access_token поле называется apiLogin, а в /api/v2/access_token — apiKey.

Полный цикл авторизации:

Получение токена доступа

Токен — короткоживущий ключ сессии. Его запрашивают один раз, а затем передают в заголовке каждого запроса.

Эндпоинт: POST https://api-ru.iiko.services/api/v2/access_token

Заголовки:

Заголовок	Значение
`Content-Type`	`application/json`
`Timeout` (необязательный)	Таймаут запроса в секундах (по умолчанию 15)

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

{
  "appId": "ВАШ_APP_ID",
  "clientSecret": "ВАШ_CLIENT_SECRET",
  "apiKey": "ВАШ_API_КЛЮЧ"
}

Поле	Описание
`appId`	Уникальный идентификатор приложения, выданный порталом разработчика
`clientSecret`	Секретный ключ приложения. Показывается один раз при создании
`apiKey`	API-ключ из iikoWeb. Определяет перечень ресторанов, к которым будет доступ

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

curl

curl -X POST "https://api-ru.iiko.services/api/v2/access_token" \
  -H "Content-Type: application/json" \
  -d '{"appId":"ВАШ_APP_ID","clientSecret":"ВАШ_CLIENT_SECRET","apiKey":"ВАШ_API_КЛЮЧ"}'

Python

import requests

resp = requests.post(
    "https://api-ru.iiko.services/api/v2/access_token",
    json={
        "appId": "ВАШ_APP_ID",
        "clientSecret": "ВАШ_CLIENT_SECRET",
        "apiKey": "ВАШ_API_КЛЮЧ",
    },
)
resp.raise_for_status()
token = resp.json()["token"]
print(token)

JavaScript (Node.js / браузер)

async function getToken() {
  const resp = await fetch("https://api-ru.iiko.services/api/v2/access_token", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      appId: "ВАШ_APP_ID",
      clientSecret: "ВАШ_CLIENT_SECRET",
      apiKey: "ВАШ_API_КЛЮЧ",
    }),
  });
  if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
  const { token } = await resp.json();
  return token;
}

Успешный ответ (HTTP 200)

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "correlationId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
}

Поле	Описание
`token`	JWT-токен. Передавайте его в последующих запросах как`Bearer {token}`
`correlationId`	UUID запроса. Указывайте его при обращении в поддержку`api@iiko.ru`

Использование токена

Токен передаётся в заголовке Authorization каждого запроса. Пример — получение списка ресторанов (организаций):

curl -X POST "https://api-ru.iiko.services/api/1/organizations" \
  -H "Authorization: Bearer ВАШ_ТОКЕН" \
  -H "Content-Type: application/json" \
  -d '{}'

Ответ:

{
  "organizations": [
    { "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "name": "Мой ресторан" }
  ],
  "correlationId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
}

organizations[].id — UUID ресторана, который подставляется в остальные методы.

Время жизни токена и его обновление

Токен действителен 1 час. Точное время истечения закодировано в JWT-поле exp (Unix-секунды). Refresh-токена нет — по истечении срока просто запросите новый токен тем же способом.

Посмотреть payload токена и срок действия:

echo "ВАШ_ТОКЕН" | cut -d. -f2 | python3 -c "import sys,base64,json; p=sys.stdin.read().strip(); p+='='*(-len(p)%4); print(json.loads(base64.urlsafe_b64decode(p)))"

Ошибки и их устранение

HTTP-код	Причина	Решение
`400`	Неверный формат тела запроса	Проверьте`Content-Type: application/json` и валидность JSON
`401`	Неверный`appId`, `clientSecret` или `apiKey`; либо истёкший токен	Проверьте значения на портале разработчика и в iikoWeb; получите новый токен
`403`	Нет доступа к ресурсу или IP не в allow-list	Проверьте настройки приложения и список разрешённых IP
`500`	Ошибка на стороне сервера	Повторите запрос; обратитесь в поддержку, указав `correlationId`

Безопасность

clientSecret и apiKey сохраните в хранилище секретов например: Vault.
Не храните секреты в коде и не коммитьте в Git. Добавьте .env в .gitignore.
Периодически ротируйте ключи (рекомендуется раз в 90 дней).

Что дальше

Справочник по API — интерактивный Swagger UI со всеми методами.
Получение списка ресторанов, доступных API-ключу — POST /api/1/organizations.

Быстрый старт​

Что нужно для авторизации​

Получение токена доступа​

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

Успешный ответ (HTTP 200)​

Использование токена​

Время жизни токена и его обновление​

Ошибки и их устранение​

Безопасность​

Что дальше​