food-market/docs/mobile-api.md

API для мобильного «FM Склад»

Серверные возможности, добавленные для iOS-приложения (стенд api/*). Авторизация — OpenIddict password/refresh grant, client_id=food-market-web, Bearer-токен. Все ответы и ошибки — JSON; бизнес-ошибки отдают { error, field?, code? }.

1. Остатки по группе товаров (с вложенными)

GET /api/inventory/stock?groupId={guid}&storeId=&search=&includeZero=&page=&pageSize=&sort=&order=

• groupId — фильтр по группе товаров включая все вложенные подгруппы (по денормализованному Path). Комбинируется с storeId, search, сортировкой.
• Ответ: PagedResult<StockRow> — { items:[{ productId, productName, article, unitSymbol, storeId, storeName, quantity, reservedQuantity, available }], total, page, pageSize }.

2. Добавить штрихкод к товару

POST /api/catalog/products/{id}/barcodes — право ProductsEdit.

Тело: { "code": "4870001112223", "kind": "ean13" }. kind ∈ ean13|ean8|code128|code39|upca|upce|other (регистр не важен); если не задан — тип определяется по длине/цифрам кода.

Ответы:

• 201 Created → { id, productId, code, type, isPrimary } (первый штрихкод товара становится primary).
• 200 OK — тот же код уже у этого товара (идемпотентно), тело как у 201.
• 409 Conflict → { error:"Штрихкод уже у товара «…».", code:"barcode-duplicate", conflictProduct:"…", field:"code" } — код занят другим товаром организации.
• 400 — пустой/слишком длинный код; 404 — товар не найден.

Уникальность проверяется в пределах организации ((OrganizationId, Code)).

3. Права текущего пользователя

GET /api/me теперь возвращает permissions — эффективные права (имя флага → bool) с учётом роли и простого/расширенного режима. Мобильное приложение и веб гейтят UI по одному источнику (скрывают одно и то же).

{
  "sub":"…","name":"…","email":"…","roles":["Admin"],"orgId":"…",
  "hasLiveOrg":true,"hasActiveEmployee":true,"advancedMode":false,
  "permissions":{ "ProductsView":true,"ProductsEdit":true,"StocksView":true,
                  "DemandsView":false,"TransferEdit":false, … }
}

Правила: SuperAdmin — все права без ограничений; Admin — все, но в простом режиме advanced-only скрыты; обычная роль — её флаги (в простом режиме advanced-only тоже обнуляются). Advanced-only: DemandsView/Edit/Post, TransferEdit, LoyaltyManage, PromotionsManage, PriceTypesManage (зеркалит серверный [RequiresAdvancedMode]). Имена флагов — из RolePermissions. Веб использует тот же источник (useCan()).

4. Весовой признак в офлайн-каталоге

GET /api/pos/v1/sync (каталог для сканирования/офлайна) в ProductSyncDto отдаёт:

• packaging (1=штучный, 2=весовой, 3=разливной) и isWeighed (явный bool packaging==2),
• unitCode — единица измерения (шт/кг/л…).

5. Весовые этикетки (внутримагазинные EAN-13)

Как в МойСкладе: внутримагазинные EAN-13 с префиксом из диапазона 20–29, где зашиты «код товара» (PLU, N цифр) и величина (вес в граммах → кг, либо цена).

Настройка организации — GET/PUT /api/organization/settings (PUT — право Admin):

• weightBarcodeEnabled (bool, по умолчанию true),
• weightBarcodeWeightPrefixes (CSV префиксов веса, null → 20,21,22,23,24),
• weightBarcodePricePrefixes (CSV префиксов цены, null → 25,26,27,28,29),
• weightBarcodeCodeDigits (длина PLU, по умолчанию 5). Блок применяется, только если в PUT передан weightBarcodeEnabled (иначе настройки не трогаются).

Разбор при поиске — GET /api/catalog/products/by-barcode/{value}:

• Обычный штрихкод → товар (или { items:[…] } при нескольких совпадениях), 404 если нет.
• Весовая этикетка (префикс весовой/ценовой) → { product:{…}, weighted:true, valueKind:"WeightKg"|"Price", quantity:1.5, embeddedPrice:null }. Товар ищется по встроенному PLU (как короткий штрихкод товара либо как артикул); quantity — вес (кг), embeddedPrice — зашитая цена (для ценовых этикеток).

Пример: этикетка 2112345015007 при дефолтных настройках → PLU 12345, вес 1.500 кг.

Разбор единый для сервера и кассы — foodmarket.Shared.Barcodes.WeightedBarcode.

Инвентаризация: post/unpost (временная совместимость)

С переходом на модель МойСклада инвентаризация сама остатки не двигает (см. docs/inventory-moysklad-reference.md). Веб использует: complete → create-enter / create-loss, затем проводит документы.

Мобильное приложение «FM Склад» исторически вызывает post/unpost инвентаризации. Чтобы не ломать установленные приложения, эндпоинты оставлены как совместимые:

• POST /api/inventory/inventories/{id}/post — = завершить + создать и ПРОВЕСТИ Оприходование (излишки) и Списание (недостача) одним вызовом. Идемпотентно: если связанные документы уже созданы — не дублирует.
• POST /api/inventory/inventories/{id}/unpost — вернуть в черновик. Поведение изменено (08.10): если по инвентаризации есть проведённые связанные Оприходование/ Списание — возвращает 409 с текстом «По инвентаризации проведены Оприходование О-… и Списание С-…. Сначала отмените результаты» и полями enters/losses (id+номер). Больше НЕ удаляет проведённые документы молча. Если связанные документы только черновики (или их нет) — удаляет черновики (они не влияли на остатки) и возвращает инвентаризацию в черновик (204).
• POST /api/inventory/inventories/{id}/cancel-results — отменить результаты: снимает проведённые связанные Оприходование/Списание с проведения (остатки возвращаются), НЕ удаляя их — они становятся черновиками и остаются в «Связанных документах», истории и аудите. Право: InventoryEdit + EnterEdit (если есть проведённые Оприходования) и/или LossEdit (если есть Списания). 409, если снятие Оприходования уведёт остаток в минус (часть излишка уже продана) — с полем lines. После отмены результатов инвентаризацию можно вернуть в черновик (unpost) или снова провести документы (enters/{id}/post, losses/{id}/post).

Статус: временное. Рекомендуемый путь для новых версий мобильного приложения — complete + create-enter/create-loss (как в вебе), а для отмены — cancel-results вместо удаления, чтобы история и аудит сохранялись. post/unpost будут помечены deprecated после обновления iOS (iOS обновит Mac-Claude).