# Как ИИ-агенту работать с ПронерАвто

## Что можно сделать сейчас

- Прочитать открытый каталог услуг и условия работ.
- Сопоставить услугу с автомобилем по VIN, если доступен официальный каталог.
- После подтверждения клиента подготовить ему ссылку на заявку.
- Если готовой услуги не нашлось, точно назвать, что именно запрошено, и оставить это в обычной заявке только с согласия клиента.
- С согласия владельца прочитать его автомобили, обращения, сметы и историю обслуживания через кабинет.

Доступные посетителю услуги находятся в [каталоге](/услуги.html). Программный интерфейс для каталога описан в [OpenAPI](/api/openapi.json).

## Каталог и цены

Используйте:

- `GET /api/услуги/` для списка категорий и услуг.
- `GET /api/услуги/{slug}/` для состава одной услуги.
- `POST /api/поиск-услуг/` для сопоставления короткого названия работы с каталогом. Отправляйте JSON вида `{"query":"замена масла в МКПП"}`. Ответ `matched` содержит услугу-кандидат, `planned` показывает шины/балансировку/развал-схождение, а `needs_clarification` просит выбрать или уточнить запрос. Запрос формулируйте коротко, без вопросительного текста, цифр и клиентских данных.

Совпадение означает только то, что в каталоге есть подходящая карточка. Поле `state: draft` обозначает черновик; карточка и цена не гарантируют, что мастерская уже подтвердила услугу, единицу расчёта, цену или возможность записи. Planned означает, что услуга пока готовится.

Запрос без совпадения записывается только как короткая безопасная нормализованная фраза, без IP-адреса, cookie, сессии или идентификатора посетителя. Нечёткий незнакомый текст сворачивается в общую категорию. VIN, цифры, телефоны, email, URL и текст беседы API не принимает. Сотрудник-администратор может прочитать агрегаты командой `php bin/console app:agent-service-gaps --actor=kedmans`.

В ответе каталога `preview: true` означает, что это предпросмотр и в выдаче могут быть редакционные черновики. Не описывайте черновую услугу как подтверждённую к выполнению.

`price_minor` — целое число копеек BYN. Например, `12000` означает 120 BYN. `null` означает, что утверждённой стартовой цены нет. Цена работы не включает запчасти и расходники. Поле `duration_minutes` может отсутствовать или быть `null`, когда длительность не установлена.

Для посетителя используйте каноническую страницу услуги `/услуги/{slug}.html`. Отправить заявку можно через `/запись.html?услуга={slug}`, открыв стандартную форму в браузере.

## Подбор автомобиля

На странице услуги посетитель может указать VIN или выбрать марку, модель, год, двигатель и рынок вручную. Передавать VIN и технические поля следует только в штатную форму подбора на сайте. После поиска выбор сохраняется в браузере посетителя. Пользователь сам выбирает результат или меняет автомобиль.

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

Если автомобиль уже выбран в этом браузере, данные одной услуги доступны через `GET /услуги/{slug}/контекст/`. Контракт опубликован в [OpenAPI контекста](/api/service-context-openapi.json) и обнаруживается через HTTP `Link: rel="service-desc"`. Ответ привязан к браузерной сессии, помечен `private, no-store` и `noindex`. Без выбранного автомобиля ответ имеет `status: no_vehicle`. При несовместимом типе коробки используется `different_service`; для неприменимых дизелю свечей зажигания — `not_applicable`. Это состояние не подменяйте общей ценой другой услуги.

Страницы комплектаций и персональные результаты не выводятся из произвольного VIN или текста формы. Ссылка на комплектацию появляется только при точном совпадении с проверенной редакционной записью. Случайный идентификатор браузера, VIN и выбранная машина не должны попадать в SEO-адрес, заголовок или сообщение публичного API.

## Заявка и запись

После того как клиент подтвердил состав, можно открыть стандартную форму `/запись.html?услуга={slug}`. Перенесите его запрос и автомобиль в форму так, чтобы клиент проверил данные и сам отправил её. Для перехода из черновика ассистента сайт выдаёт одноразовый токен передачи. Используйте кнопку передачи на сайте, а не создавайте этот токен самостоятельно.

Отправка формы создаёт обращение со статусом `requested`. Она не подтверждает время, визит, наличие детали или заказ запчастей. Время согласует сотрудник. Не сообщайте, что визит оформлен или подтверждён, до появления такого статуса.

Не отправляйте VIN, личный номер клиента, имя, телефон, описание обращения или другие данные в GET-параметрах URL. Не включайте их в аналитику. Сообщения сайта передаются в «СТО Лиды» как рабочие уведомления.

## Данные кабинета

Если клиент вошёл в свой кабинет и прямо попросил проверить его данные, доступны только read-only endpoints из [OpenAPI кабинета](/кабинет/api/openapi.json):

- `GET /кабинет/api/гараж/` — собственные автомобили, обращения и история обслуживания.
- `GET /кабинет/api/автомобили/{id}/` — сведения об автомобиле, принадлежащем этому кабинету.
- `GET /кабинет/api/наряды/{id}/` — собственный наряд и версии сметы.

Используется обычная авторизованная браузерная сессия. Отдельных bearer-токенов или автоматического доступа по одному VIN нет. Ответы `private, no-store` и `noindex`. Не пытайтесь подбирать чужие ID. Эти endpoints только читают данные. Согласие со сметой, перенос визита или его отмену выполняют через кабинет или сотрудник.

## Если нужной услуги нет

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

Передайте короткое название отсутствующей работы в `POST /api/поиск-услуг/`. Сайт учтёт запрос в статистике спроса без данных клиента. Шиномонтаж, балансировка колёс и развал-схождение сейчас готовятся. По другим работам без совпадения попросите конкретизировать задачу и предложите обычную заявку, если клиент хочет уточнить возможность у мастера.

## Возможности для клиентских агентов в будущем

Для подключённых клиентом агентов планируется MCP или другой авторизованный шлюз. После отдельного проектирования доступа он сможет прочитать собственный автомобиль и историю, начать заявку на работу, получить статус подтверждения времени и подготовить предварительный список деталей с источниками и уровнем применимости. Заказ или покупка деталей будет происходить только после явного согласия клиента.

Сейчас MCP-сервера и API для создания визита, управления кабинетом, оценки ДТП по VIN и заказа деталей нет. Государственную историю из «Е-Паслугі» сайт автоматически по VIN не получает: нужные сведения клиент должен заказать через официальный портал и предоставить для осмотра.