В CRMservice нет отдельного API для мобилки — мобильное приложение использует тот же REST API, что и веб-CRM (/api/v1/*). Это упрощает разработку: один бэкенд, одна логика, общий аудит.
Авторизация
JWT Bearer token. Получается через /api/v1/auth/login (email+пароль или phone+OTP-код).
Заголовок
``` Authorization: BearerАльтернатива (query param)
``` GET /api/v1/orders?token=Это fallback для случаев когда невозможно использовать заголовок (например, прямые ссылки на скачивание файлов). Используйте только для GET, не для мутаций.
Жизненный цикл токенов
| Токен | Срок жизни | Как обновляется |
|---|---|---|
| Access token | 15 минут | Через refresh_token |
| Refresh token | 30 дней | Не обновляется, нужен новый login |
После истечения access — мобилка делает POST /api/v1/auth/refresh с refresh-токеном и получает свежий access.
Что нужно мобильному приложению
| Сценарий | Endpoint | Примечание |
|---|---|---|
| Список заказов | GET /api/v1/orders | Фильтр по статусу/дате/клиенту |
| Карточка заказа | GET /api/v1/orders/{id} | Полный детальный объект |
| Смена статуса | PUT /api/v1/orders/{id}/status | Проверка required_role_ids |
| Список задач | GET /api/v1/tasks | Только мои |
| Отметить чек-лист | PATCH /api/v1/tasks/{id}/checklist/{itemID}/toggle | |
| Открыть смену | POST /api/v1/shifts/open | На вашей локации |
| Список клиентов | GET /api/v1/clients | Поиск по имени/телефону |
| веб-сокет уведомлений | wss://crm.../api/v1/chat/ws | Real-time |
| Профиль | GET /api/v1/auth/me |
Permissions
При запросе бэкенд проверяет права через RBAC v2. У мобильного сотрудника обычно роль «Мастер» или «Менеджер», которая открывает только его задачи / заказы / клиентов.
Если право не дано — 403 permission_denied. Мобильное приложение должно корректно обрабатывать.
Маскирование полей
Если ваша роль не даёт смотреть financial.cost или personal.salary — в ответе API таких полей не будет (маскирующий промежуточный обработчик удаляет их из JSON). Это нужно учитывать на стороне мобилки — поле может прийти null или отсутствовать.
Лимит запросовs
Глобально CRM держит 300 RPS с burst 600. На один токен — мягкий лимит, конкретные числа в разработке. При превышении — 429 rate_limit_exceeded с Retry-After в секундах.
Push-уведомления
В roadmap: интеграция с FCM (Android) и APNS (iOS) для пуш-уведомлений на мобильное устройство о новой задаче / звонке / лиде. Пока недоступно — мобилка должна опрашивать /api/v1/notifications или держать веб-сокет.
Что готовим заранее (для разработчика мобилки)
- Получите тестовый тенант — через регистрацию или попросите у нас sandbox.
- Тестовый юзер с ролью — у нас можете создать через супер-админа.
- Список endpoints — пишите в поддержку, дадим Postman-коллекцию.
Возможные проблемы
- «401 (не авторизован) после 15 минут» — access истёк. Обновите через refresh.
- «Все эндпоинты 403» — у токена нет нужных permissions. Проверьте роль юзера.
- «веб-сокет падает каждые N минут» — переподключайтесь автоматически (стандарт для веб-сокет-клиента).