Общая схема API

REST API PTNL Rating позволяет интегрировать платформу с внутренними системами: вести справочники, загружать продукты, готовить дегустации и выгружать результаты.

Всё, что делает интерфейс, доступно и через API — интерфейс работает поверх того же набора методов.

Принципы

• REST + JSON — предсказуемые ресурсы и коды ответов.
• HTTP или HTTPS — HTTPS и сетевой доступ к экземпляру настраивает администратор, выполняющий установку, см. Инструкцию по установке.
• Версионирование в пути — рабочие методы находятся под префиксом /api/v1.
• Права от роли — токен действует от имени пользователя и ограничен правами его роли, см. Авторизация.

Служебные методы

Метод	Назначение
GET /api/health-check	Проверка доступности сервиса
GET /api/info/version	Версия сервиса

Оба метода удобны для мониторинга и проверки связности после развёртывания.

Основные группы ресурсов

Группа	Назначение
categories	Категории и их атрибуты
products	Карточки продуктов, изображения, статистика
batches	Производственные партии
imports	Сессии импорта из Excel
degustations	Дегустации, шаблоны, ответы, экспорт
degustations-experts	Прохождение дегустации экспертом
users, groups, roles	Учётные записи, комиссии и права
licenses	Лицензия и лимиты
action-logs	Журнал действий

Формат списков

Методы получения списков возвращают массив строк и общее количество:

{
  "rows": [],
  "total": 0
}

Поле total содержит число записей до применения постраничности — по нему считается количество страниц.

Общие параметры запроса

Параметр	Назначение
limit	Размер страницы
offset	Смещение от начала выборки
order_by	Поле сортировки
order_direction	Направление сортировки
search	Поиск по строковым полям ресурса

К ним добавляются фильтры конкретного ресурса. У продуктов это category_id, status, rating_from и rating_to.

Формат ошибки

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

{
  "code": "unauthorized",
  "http_code": 401,
  "message": "",
  "errors": {
    "field_name": { "key": "not exists", "condition": "" }
  }
}

Поле	Содержание
code	Машиночитаемый код ошибки
http_code	Код состояния HTTP
message	Текстовое описание
errors	Разбор по полям при ошибке валидации

Разбирайте ответ по полю code, а не по тексту message: текст может измениться.

Типовые сценарии

• Импорт продуктов из Excel перед подготовкой дегустации.
• Выгрузка результатов после завершения дегустации.

Полная спецификация

Здесь описаны схема обмена и группы ресурсов. Полный перечень методов с параметрами и моделями доступен в Swagger вашего экземпляра по адресу /api/v1/swagger/index.html. Вопросы по интеграции — на support@ptnlrating.ru.