chat/docs/MOBILE_API.md

Инструкция по интеграции мобильного API календарного сервиса

Обзор

Этот документ содержит информацию о том, как интегрировать мобильное приложение с API календарного сервиса. Календарный сервис предоставляет эндпоинты для создания, получения и удаления записей в календаре женского здоровья.

Базовый URL

http://[domain]/api/v1/calendar/

Аутентификация

Все запросы к API должны включать токен аутентификации в заголовке Authorization:

Authorization: Bearer [token]

Для получения токена аутентификации используйте сервис аутентификации:

POST /api/v1/auth/token
Content-Type: application/x-www-form-urlencoded

username=user@example.com&password=userpassword

Эндпоинты для мобильного приложения

1. Создание записи в календаре

POST /api/v1/calendar/entries/mobile
Content-Type: application/json
Authorization: Bearer [token]

Формат запроса

{
  "date": "2025-09-26",
  "type": "MENSTRUATION",
  "flow_intensity": 3,
  "symptoms": ["CRAMPS", "HEADACHE"],
  "mood": "NORMAL",
  "notes": "Пример записи"
}

Параметры

Параметр	Тип	Обязательный	Описание
date	string	Да	Дата записи в формате YYYY-MM-DD
type	string	Да	Тип записи: MENSTRUATION, OVULATION, SPOTTING, DISCHARGE, PAIN, MOOD
flow_intensity	integer	Нет	Интенсивность выделений по шкале 1-5 (только для MENSTRUATION и SPOTTING)
symptoms	array[string]	Нет	Массив симптомов: CRAMPS, HEADACHE, BLOATING, FATIGUE, и т.д.
mood	string	Нет	Настроение: HAPPY, SAD, NORMAL, STRESSED, ANXIOUS, IRRITATED
notes	string	Нет	Текстовая заметка

Пример успешного ответа

{
  "id": 123,
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "entry_date": "2025-09-26",
  "entry_type": "period",
  "flow_intensity": "medium",
  "period_symptoms": "",
  "mood": "happy",
  "energy_level": 1,
  "sleep_hours": 0,
  "symptoms": "CRAMPS, HEADACHE",
  "medications": "",
  "notes": "Пример записи",
  "is_predicted": false,
  "confidence_score": null,
  "created_at": "2023-09-26T14:30:00.000Z"
}

2. Получение записей календаря

GET /api/v1/calendar/entries
Authorization: Bearer [token]

Параметры запроса (в URL)

Параметр	Тип	Обязательный	Описание
start_date	string	Нет	Начальная дата в формате YYYY-MM-DD
end_date	string	Нет	Конечная дата в формате YYYY-MM-DD
entry_type	string	Нет	Тип записи (period, ovulation, symptoms)
limit	integer	Нет	Ограничение количества возвращаемых записей (по умолчанию 100)

Пример успешного ответа

[
  {
    "id": 123,
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "entry_date": "2025-09-26",
    "entry_type": "period",
    "flow_intensity": "medium",
    "period_symptoms": "",
    "mood": "happy",
    "energy_level": 1,
    "sleep_hours": 0,
    "symptoms": "CRAMPS, HEADACHE",
    "medications": "",
    "notes": "Пример записи",
    "is_predicted": false,
    "confidence_score": null,
    "created_at": "2023-09-26T14:30:00.000Z"
  },
  {
    "id": 124,
    "uuid": "550e8400-e29b-41d4-a716-446655440001",
    "entry_date": "2025-09-30",
    "entry_type": "ovulation",
    "flow_intensity": null,
    "period_symptoms": "",
    "mood": "happy",
    "energy_level": 1,
    "sleep_hours": 0,
    "symptoms": "BREAST_TENDERNESS",
    "medications": "",
    "notes": "Пример записи об овуляции",
    "is_predicted": false,
    "confidence_score": null,
    "created_at": "2023-09-26T14:30:00.000Z"
  }
]

3. Удаление записи календаря

DELETE /api/v1/entries/{entry_id}
Authorization: Bearer [token]

Параметры

Параметр	Тип	Обязательный	Описание
entry_id	integer	Да	ID записи для удаления

Пример успешного ответа

{
  "message": "Entry deleted successfully"
}

4. Получение обзора цикла

GET /api/v1/cycle-overview
Authorization: Bearer [token]

Пример успешного ответа

{
  "current_cycle_day": 14,
  "current_phase": "ovulation",
  "next_period_date": "2023-10-15",
  "days_until_period": 12,
  "cycle_regularity": "regular",
  "avg_cycle_length": 28
}

Маппинг типов данных

Типы записей

Мобильное приложение	Сервер
MENSTRUATION	period
OVULATION	ovulation
SPOTTING	symptoms
DISCHARGE	symptoms
PAIN	symptoms
MOOD	mood

Интенсивность выделений

Мобильное приложение	Сервер
1	light
2	light
3	medium
4	heavy
5	heavy

Настроение

Мобильное приложение	Сервер
HAPPY	happy
SAD	sad
NORMAL	happy
STRESSED	anxious
ANXIOUS	anxious
IRRITATED	irritated

Тестирование API

Для тестирования API можно использовать скрипты:

1. setup_mobile_test.py - создание токена для тестирования
2. mobile_format_test.py - тестирование преобразования форматов данных
3. test_mobile_api.py - полное тестирование мобильного API

Пример запроса с curl

curl -X POST http://localhost:8004/api/v1/calendar/entries/mobile \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(cat auth_token.txt)" \
  -d '{
    "date": "2025-09-26", 
    "type": "MENSTRUATION", 
    "flow_intensity": 3, 
    "symptoms": ["CRAMPS", "HEADACHE"], 
    "mood": "NORMAL", 
    "notes": "Тестовая запись"
  }'

Коды ошибок

Код	Описание
400	Неверный запрос или данные
401	Ошибка аутентификации
404	Запись не найдена
422	Ошибка валидации данных
500	Внутренняя ошибка сервера

Контактная информация

При возникновении вопросов или проблем с интеграцией, пожалуйста, свяжитесь с командой разработки.