# Мои Места (Moi Mesta)

> Программа лояльности для бизнеса. Self-service регистрация компании по API без участия менеджера. Trial-период — 10 дней бесплатно.

## Документация

- Страница документации: https://moimesta.ru/docs
- Инструкция для AI-агентов (сырой markdown): https://moimesta.ru/api/content/docs/ai-agent-registration.md
- Инструкция для человека (сырой markdown): https://moimesta.ru/api/content/docs/human-registration.md

## API

- Базовый URL: https://company.moimesta.ru/api
- OpenAPI спецификация (YAML): https://moimesta.ru/api/openapi.yaml
- OpenAPI спецификация (JSON): https://moimesta.ru/api/openapi.json
- Интерактивный API-референс (Redoc): https://moimesta.ru/api/docs

## Company Management API

API для machine-to-machine интеграций: управление подарками, акциями, статистикой от имени компании.

- Базовый URL: https://company.moimesta.ru/api/v1
- Авторизация: заголовок Authorization: Bearer mm_... (ключ выдаётся в личном кабинете компании / ЛКБ)
- Scopes: gifts:read, gifts:write, promotions:read, promotions:write, stats:read
- Лимиты: 120 запросов в минуту на ключ; не более 4 одновременных запросов на ключ; 600 запросов в минуту на IP
- При превышении лимита — HTTP 429 с заголовком Retry-After и заголовками RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, X-RateLimit-Limit, X-RateLimit-Remaining
- Инструкция для AI-агентов: https://moimesta.ru/api/content/docs/ai-agent-loyalty

## Регистрация компании (кратко)

Регистрация компании выполняется за 4 шага без авторизации:

1. GET /categories — получить справочник категорий, выбрать categoryId
2. GET /auth/checkPhone?phone={10 цифр РФ без +7} — проверить номер телефона
3. POST /auth/singupGetCode — запросить OTP-код (4 цифры, доставка по SMS/звонку/Telegram)
4. POST /auth/singup — создать компанию, получить accessToken и refreshToken

```
curl https://company.moimesta.ru/api/categories
```

```
curl "https://company.moimesta.ru/api/auth/checkPhone?phone=9991234567"
```

```
curl -X POST https://company.moimesta.ru/api/auth/singupGetCode \
  -H "Content-Type: application/json" \
  -d '{"phone": 9991234567}'
```

```
curl -X POST https://company.moimesta.ru/api/auth/singup \
  -H "Content-Type: application/json" \
  -d '{"phone": 9991234567, "confirmCode": "1234", "companyName": "Мой бизнес", "categoryId": 1, "email": "owner@example.ru", "username": "Иван", "userSurname": "Петров", "password": "MyPass123"}'
```

## Важно для агентов

- Бизнес-ошибки эндпоинтов singup, singupGetCode и checkPhone возвращаются с HTTP 200 и полем errorMessage в теле ответа — не через коды 4xx. Агент обязан анализировать тело ответа, а не только HTTP-статус.
- OTP-код — 4 цифры; действует 3 минуты; повторный запрос не чаще 1 раза в 5 минут на номер.
- На OTP-эндпоинтах действует rate-limit: 3 запроса / 10 мин на номер, 20 запросов / 10 мин на IP, 100 запросов / мин глобально. При превышении — HTTP 429.
- Формат телефона: число из 10 цифр без +7 (пример: 9991234567).
- Если checkPhone возвращает companyExist: true — регистрация невозможна, нужно войти или восстановить пароль.

## В разработке

- ai-agent-server с готовыми tool-calls для автоматической регистрации — coming soon, пока недоступно.

_Last updated: 2026-07-15_