Эта страница фиксирует клиентский контракт API. Детальные backend flows остаются в backend-flows.md, а runtime URLs и ports - в Environment And Runtime.
| Компонент | Routes |
|---|---|
| Django API | /api/v1/* |
| OpenAPI schema | /api/schema/ |
| Swagger UI | /api/v1/schema/swagger-ui/ |
| Redoc | /api/v1/schema/redoc/ |
| Billing API | /api/v1/billing/* |
| Push API | /api/v1/push/* |
| Reviews API | /api/v1/reviews/* |
| Feedback API | /api/v1/feedback/ |
| Go chat HTTP | /api/v1/chats, /api/v1/chats/{chatID}/messages |
| Go chat WebSocket | /ws/chats |
Production nginx проксирует /api/v1/chats и /ws/chats в Go chat service. Остальной /api/v1/* обслуживается Django.
HTTP auth:
Authorization: Bearer <access-token>
Auth endpoints:
POST /api/v1/auth/registerPOST /api/v1/auth/loginPOST /api/v1/auth/verify-codePOST /api/v1/auth/resend-otpPOST /api/v1/auth/refreshPOST /api/v1/auth/logoutGET /api/v1/auth/users/me/PATCH /api/v1/auth/users/me/PATCH /api/v1/auth/users/me/address/GET /api/v1/auth/users/me/sheets/Register/login возвращают OTP в message. В default/dev mode при MOBIZON_ENABLED=0 OTP равен 0000.
Verify code возвращает:
{
"access": "...",
"refresh": "...",
"token_type": "Bearer",
"user": {}
}
Access token живет 60 минут, refresh token - 14 дней. Refresh rotation и blacklist включены.
Успешные responses зависят от serializer/viewset. Для list endpoints обычно используется массив или объект с items.
Validation errors обрабатываются глобальным exception handler. Для DRF validation ожидается HTTP 422 и тело с message/detail. Domain exceptions могут возвращать 400 с error_code.
Auth failures возвращают 401. Owner/participant restrictions могут проявляться как 403 или 404, в зависимости от конкретного сервиса и lookup.
Multipart/form-data используется для:
PATCH /api/v1/auth/users/me/ с avatar.BasePhotoSerializer требует file на create. На PATCH файл optional. Фото поддерживают is_primary, crop fields, original_name, url.
Шаблоны времени принадлежат текущему пользователю:
GET /api/v1/schedule/templates/ — все шаблоны;GET /api/v1/schedule/templates/?template_type=<type> — фильтрация по назначению;POST /api/v1/schedule/templates/ — создание;GET/PATCH/DELETE /api/v1/schedule/templates/{id}/ — чтение, изменение и удаление своего шаблона.template_type |
Назначение | Поля |
|---|---|---|
job |
Услуги | Рабочий интервал, base_after_client_break_time, breaks |
bringing |
Привоз | Рабочие границы обозначают окно продаж; order_closing_minutes задаёт срок закрытия заявок |
storage_contract |
Склад и контракт | Начало и конец рабочего дня |
Пример шаблона привоза:
{
"id": 12,
"template_type": "bringing",
"name": "Вечерний привоз",
"color": "purple",
"working_start_time": "16:00:00",
"working_end_time": "20:00:00",
"base_after_client_break_time": 0,
"order_closing_minutes": 1440,
"breaks": []
}
order_closing_minutes измеряется в минутах: 60 — час, 1440 — сутки. Для остальных типов передаётся null. Шаблоны, существовавшие до типизации, мигрируются как job.
При применении шаблона клиент создаёт или обновляет /api/v1/schedule/days/, копируя рабочие границы и breaks. order_closing_minutes остаётся свойством шаблона привоза и в CalendarDay не копируется.
Frontend flow:
job использует job;product_bringing использует bringing;product_storage и product_contract используют storage_contract.Sheet endpoints expose additional client-facing state:
status, rating, review_count, preview_photo_url and is_favorite;POST /api/v1/<domain-sheets>/{id}/archive/ archives provider-owned sheets;POST /api/v1/<domain-sheets>/{id}/unarchive/ returns provider-owned sheets to active state;GET /api/v1/sheets/favorites/ lists the current user's favorite sheets;POST /api/v1/sheets/{id}/favorite/ adds a sheet to favorites;DELETE /api/v1/sheets/{id}/favorite/ removes a sheet from favorites.Авторизованный пользователь может пожаловаться на чужую анкету:
POST /api/v1/sheets/{id}/report/
Authorization: Bearer <access-token>
Content-Type: application/json
Request body:
{
"reason": "Описание анкеты вводит в заблуждение"
}
reason — обязательная непустая строка. Пробелы в начале и конце удаляются перед сохранением.
Успешный ответ — HTTP 201 Created:
{
"id": 42,
"user": 15,
"sheet": 73,
"reason": "Описание анкеты вводит в заблуждение",
"created_at": "2026-07-20T12:34:56.000000+04:00"
}
Ограничения и ошибки:
401;422 с ошибкой в поле sheet;reason возвращает HTTP 422 с ошибкой в поле reason;id анкеты возвращает 404.Пример validation response для собственной анкеты:
{
"message": "Validation error",
"error_code": "M10000",
"success": true,
"detail": [
{
"sheet": "You cannot report your own sheet."
}
]
}
Каждая жалоба создаёт отдельный SheetReport, связанный с автором (user) и анкетой (sheet). Причина хранится в текстовом поле reason; жалобы доступны сотрудникам в Django admin. На клиенте меню ⋯ → Пожаловаться показывается на карточке и странице анкеты только если текущий пользователь не является её владельцем.
Reviews:
GET /api/v1/reviews/?base_sheet=<id> lists reviews and can be filtered by sheet;POST /api/v1/reviews/ creates a review with base_sheet, author_name, rating from 1 to 5 and text;PATCH/DELETE /api/v1/reviews/{id}/ update or delete a review and recalculate sheet rating and review_count.Feedback:
POST /api/v1/feedback/ stores authenticated user feedback with text;UserFeedbackService throttles feedback to one request per user every 5 minutes via cache.Push:
GET /api/v1/push/status checks that the notifications module is available;GET /api/v1/push/devices lists active push devices for the current user;POST /api/v1/push/devices/register registers or updates a device token with platform, optional device_id, app_version, locale;POST /api/v1/push/devices/unregister deactivates devices by token or device_id.GET /api/v1/notifications?read=true|false lists persisted user notifications;POST /api/v1/notifications/{id}/read marks one notification as read;POST /api/v1/notifications/read-all marks all current-user notifications as read;POST /api/v1/internal/chat/message-sent is called by chat-service and requires X-Chat-Notification-Token.Полная матрица кодов, триггеров, payload и Celery Beat расписаний описана в
Уведомления и Firebase Push.
Chat HTTP endpoints требуют Bearer access token:
GET /healthz - без auth, возвращает {"status":"ok"}.GET /api/v1/chats - возвращает { "items": [...] }.POST /api/v1/chats с { "peer_user_id": <db_user_id> }.GET /api/v1/chats/{chatID}/messages?limit=&before_id=.Важно: peer_user_id - числовой database id пользователя, не uuid из public user serializer.
WebSocket:
/ws/chats.Authorization: Bearer <access-token> или query token=<access-token>.last_event_id.ping, chat.create, message.send, message.ack, message.read.last_event_id replay отправляет sync.replayed только если найдены сообщения после указанного id.
CHAT_OPENAPI_FRAGMENT документирует POST /api/v1/uploads/photos, но в Go router handler для этого endpoint сейчас отсутствует. До реализации handler-а или удаления из schema этот route считается documented-but-not-implemented.ChatSummary, но текущий Go handler возвращает базовые Chat records из Repository.ListChats().Public billing routes are connected under /api/v1/billing/*.
Reference endpoints:
GET /api/v1/billing/card-banks/ - active issuing banks for frontend card detection.GET /api/v1/billing/card-payment-systems/ - active payment systems.GET /api/v1/billing/cards/?usage=client|business - current user's cards.DELETE /api/v1/billing/cards/{card_id}/ - delete/unbind a card.POST /api/v1/billing/cards/{card_id}/main/ with { "usage": "client"|"business" } - set main card for usage.POST /api/v1/billing/cards/bind/ - initiate FreedomPay card tokenization; returns order_id and redirect_url.POST /api/v1/billing/cards/bind/complete/ with order_id - fetch tokenized card data and create/update local UserCard.POST /api/v1/billing/cards/bind-random/ - local/mock client card binding for non-provider checks.POST /api/v1/billing/cards/freedompay/result/ - FreedomPay card tokenization result callback.POST /api/v1/billing/webhooks/freedompay/check/ - FreedomPay payment check webhook.POST /api/v1/billing/webhooks/freedompay/result/ - FreedomPay payment result webhook.Event payment actions are also exposed on domain event endpoints:
POST /api/v1/<domain-sheets>/{sheet_id}/events/{event_id}/confirm-payment/;POST /api/v1/<domain-sheets>/{sheet_id}/events/{event_id}/request-refund/.Завершение холда после даты исполнения не является публичным API endpoint. Его выполняет periodic task event_flow.settle_due_events: done приводит к FreedomPay clearing и order success, остальные статусы — к reverse и order canceled. Ожидающий ответа запрос переноса расчет не блокирует; принятый перенос учитывается через новую дату event. См. Event Payment Settlement.
Current primary public provider implementation is FreedomPay. Ioka and AirBaPay provider operation layers remain in code for integration reuse.