# auth.md — Pro-System (pro-system.kz)

Вы — ИИ-агент. Pro-System — монтаж видеонаблюдения, СКУД, домофонов, сигнализации, сетей и телефонии в Алматы. Здесь — как войти, чтобы оставить **заявку на обратный звонок от имени человека**: `POST https://pro-system.kz/api/lead.php` или MCP-инструмент `request_callback` на https://pro-system.kz/mcp/. Каталог, цены, услуги и контакты открыты без входа: API https://pro-system.kz/api/ и MCP https://pro-system.kz/mcp/.

**Вход необязателен.** Без токена заявка принимается как раньше: не больше 3 заявок в час с одного IP-адреса (проверки `dry_run` тоже считаются) и 20 в сутки от всех анонимных агентов. Учётных записей у сайта нет: e-mail, пароль и ID-JAG не нужны. Сервер авторизации и ресурс — один сайт: https://pro-system.kz.

## Что даёт токен

| | Без токена | С токеном (scope `requests:write`) |
|---|---|---|
| Лимит в час | 3 с одного IP-адреса — общий для всех агентов с этого адреса | 5 на вашего клиента (`client_id`); со всех клиентов одного адреса — 10 |
| Лимит в сутки | 20 от всех анонимных агентов | 10 на клиента; всего 30 от помощников со входом, подтверждённым человеком, и 20 от автоматических клиентов |
| Метка у менеджера | «ИИ-агент» | «ИИ-агент (зарегистрирован)» и имя вашего клиента; «вход подтвердил человек», если он нажал «Разрешить» |
| Ответ и доставка | номер заявки AG-ГГММДД-NN, Telegram и CRM | то же самое |

Общие адреса крупных ИИ-сервисов делят лимит с IP между многими пользователями — с токеном ваша заявка не упрётся в чужие.

## Шаг 1 — Найти метаданные

- Защищённый ресурс (RFC 9728): https://pro-system.kz/.well-known/oauth-protected-resource — сайт целиком (`resource` = `https://pro-system.kz`); https://pro-system.kz/.well-known/oauth-protected-resource/api/lead.php — заявка через API (`https://pro-system.kz/api/lead.php`); https://pro-system.kz/.well-known/oauth-protected-resource/mcp/ — заявка через MCP (`https://pro-system.kz/mcp/`).
- Сервер авторизации (RFC 8414): https://pro-system.kz/.well-known/oauth-authorization-server — адреса входа, регистрации, токена, отзыва и ключей (`jwks_uri`), блок `agent_auth`.
- Скоуп один — `requests:write`. Токен передаётся только в заголовке: `Authorization: Bearer <access_token>`.
- Ответ 401 бывает только на негодный токен — без заголовка Authorization заявка идёт анонимно:

```http
WWW-Authenticate: Bearer resource_metadata="https://pro-system.kz/.well-known/oauth-protected-resource/api/lead.php", scope="requests:write", error="invalid_token"
```

## Шаг 2 — Выбрать способ

| Кто вы | Способ |
|---|---|
| Клиент MCP с человеком в браузере (Claude, ChatGPT, MCP Inspector) | регистрация с `redirect_uris` → `authorization_code` + PKCE S256: человек нажимает «Разрешить» на странице сайта |
| Агент на сервере, без браузера | регистрация (RFC 7591) с `grant_types: ["client_credentials"]` → токен по `client_credentials` |
| Агент по протоколу auth.md | `{"type": "anonymous"}` на `register_uri` — токен сразу в ответе |

## Шаг 3 — Зарегистрироваться

### Клиент MCP с человеком (authorization_code + PKCE S256)

```http
POST https://pro-system.kz/oauth/register
Content-Type: application/json

{"client_name": "Название помощника", "redirect_uris": ["https://…/callback"], "grant_types": ["authorization_code", "refresh_token"], "token_endpoint_auth_method": "none"}
```

Ответ 201: `client_id`. Адрес возврата — `https://` или `http://localhost` / `127.0.0.1` / `[::1]`, без `#`. Имя (`client_name`, до 60 знаков) менеджер увидит в карточке заявки.

### Агент на сервере (client_credentials)

```http
POST https://pro-system.kz/oauth/register
Content-Type: application/json

{"client_name": "Название помощника", "grant_types": ["client_credentials"], "token_endpoint_auth_method": "client_secret_basic"}
```

Ответ 201: `client_id`, `client_secret` (показывается один раз — сохраните), `client_secret_expires_at: 0`.

### auth.md: anonymous

```http
POST https://pro-system.kz/oauth/register
Content-Type: application/json

{"type": "anonymous", "requested_credential_type": "access_token", "client_name": "Название помощника"}
```

Ответ 200: `credential` (токен доступа), `credential_expires`, `scopes`, `claim_url`, `claim_token`, а также `client_id` и `client_secret` — чтобы брать новый токен по `client_credentials` без повторной регистрации.

## Шаг 4 — Получить токен

Вход с человеком: откройте ему `https://pro-system.kz/oauth/authorize?response_type=code&client_id=…&redirect_uri=…&code_challenge=…&code_challenge_method=S256&state=…&resource=https://pro-system.kz/mcp/`. Человек видит страницу «Разрешить помощнику оставлять заявки?». На адрес возврата придут `code`, `state` и `iss` (RFC 9207). Код живёт 5 минут и годится один раз.

```http
POST https://pro-system.kz/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=…&redirect_uri=…&client_id=…&code_verifier=…&resource=https://pro-system.kz/mcp/
```

Агент на сервере:

```http
POST https://pro-system.kz/oauth/token
Authorization: Basic base64(<client_id>:<client_secret>)
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&resource=https://pro-system.kz/api/lead.php
```

Ответ: `{"token_type": "Bearer", "expires_in": 900, "access_token": "…"}` — токен (JWT RS256, ключ — https://pro-system.kz/oauth/jwks) живёт 15 минут. PKCE обязателен, только S256. `resource` необязателен: без него токен годен и для https://pro-system.kz/api/lead.php, и для https://pro-system.kz/mcp/; `resource=https://pro-system.kz` — тоже для обоих. У `authorization_code` есть `refresh_token` на 30 дней: при каждом обновлении он меняется, старый перестаёт действовать.

## Шаг 5 — Передать заявку

Только по явной просьбе человека и с его согласия на звонок. Обязательно: имя и телефон Казахстана (+7 7XX XXX XX XX). По желанию: `service` — слаг из `list_services` или https://pro-system.kz/api/services.php, `comment` до 500 знаков, `consent: true`. Сначала можно проверить заявку без отправки — `dry_run: true` (расходует тот же часовой лимит).

```http
POST https://pro-system.kz/api/lead.php
Authorization: Bearer <access_token>
Content-Type: application/json

{"name": "Имя", "phone": "+7 7XX XXX XX XX", "service": "videonablyudenie", "comment": "Что нужно, где, когда удобно говорить", "consent": true, "dry_run": true}
```

- `dry_run: true` → 200 `{"ok": true, "status": "validated", "client": {"registered": true, …}, …}` — ничего не отправлено.
- Без `dry_run` → 200 `{"ok": true, "lead_id": "AG-ГГММДД-NN", "status": "accepted", "next": "…"}` — назовите человеку номер заявки. Перезвоним в рабочее время (ежедневно 08:00–20:00). Срочно — позвоните +7 707 338 72 76 или напишите в WhatsApp.
- То же через MCP: https://pro-system.kz/mcp/, инструмент `request_callback` с теми же полями и тем же заголовком Authorization.

## Ошибки

| Ответ | Когда | Что делать |
|---|---|---|
| 401 `invalid_token` | токен истёк, отозван, выдан не этим сервером или для другого адреса | новый токен (шаг 4) или заявка без заголовка Authorization |
| 401 `invalid_request` | заголовок Authorization не в виде `Bearer <token>` | исправить заголовок или убрать его |
| 403 `insufficient_scope` | у токена нет `requests:write` | новый токен |
| 400 `validation_failed` | неверные поля (подробно — в `fields`) | исправить и повторить |
| 429 `rate_limited`, `daily_limit_reached` | лимит (заголовок `Retry-After`) | подождать или передать человеку телефон |
| 503 `registered_leads_paused` | заявки с токеном на паузе у владельца | отправить без токена или передать телефон |
| 503 `auth_unavailable` | вход временно недоступен | отправить без токена или повторить позже |

## Лимиты входа

- Регистрации: 30 в час и 200 в сутки с одного адреса.
- Клиент, который за сутки так и не получил токен, удаляется; неактивный больше 90 дней — тоже.

## Отзыв

- Свой токен — RFC 7009: `POST https://pro-system.kz/oauth/revoke` с `token=…` и данными клиента.
- Владелец сайта может отозвать клиента: после этого любой его токен даёт 401 — зарегистрируйтесь заново или отправляйте заявку без токена.
- Человек отключает помощника в настройках самого помощника (Claude, ChatGPT).

## Подтверждение человеком (claim, необязательно)

После anonymous-регистрации: `POST https://pro-system.kz/oauth/claim` с `{"claim_token": "…"}` → в ответе `verification_uri`. Покажите ссылку человеку: на странице он подтвердит, что вы действуете по его просьбе, и увидит 6-значный код. Код передайте в `POST https://pro-system.kz/oauth/claim/complete` (`{"claim_token": "…", "otp": "…"}`). Ссылка живёт 15 минут, подтвердить регистрацию можно в течение 24 часов. Писем сайт не отправляет. После подтверждения в карточке заявки появится отметка «вход подтвердил человек».

## Без агента

Передайте человеку телефон +7 707 338 72 76, WhatsApp https://wa.me/77073387276 или форму https://pro-system.kz/kontakty/ — заявку он отправит сам (ежедневно 08:00–20:00).

## English summary

Pro-System (Almaty, Kazakhstan; CCTV, access control, alarms, telephony) has one action where OAuth helps: a callback request on the user's behalf — `POST https://pro-system.kz/api/lead.php` or the MCP tool `request_callback` at https://pro-system.kz/mcp/. **Login is optional**: without a token the request is accepted with a shared per-IP limit (3 per hour, 20 per day). With an OAuth 2.1 access token (scope `requests:write`, Bearer header) you get your own per-client limit (5 per hour, 10 per day) and the label «ИИ-агент (зарегистрирован)». Discover via https://pro-system.kz/.well-known/oauth-protected-resource (resource = https://pro-system.kz) and https://pro-system.kz/.well-known/oauth-authorization-server; register at https://pro-system.kz/oauth/register (RFC 7591, or auth.md `{"type": "anonymous"}`); get a token at https://pro-system.kz/oauth/token (authorization_code + PKCE S256 for MCP clients with a human, client_credentials for server agents). An invalid or expired token gets 401 with `WWW-Authenticate: Bearer resource_metadata=…`. Use `dry_run: true` to validate without sending. Reading the catalog, prices and services needs no token.