nns/food-market
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity
food-market/docs/api-reference.md
nns 72d0a71307
Some checks are pending
Auto-tag / Create date-tag (push) Waiting to run
Details
CI / Backend (.NET 8) (push) Waiting to run
Details
CI / Web (React + Vite) (push) Waiting to run
Details
CI / POS (WPF, Windows) (push) Waiting to run
Details
Docker API / Build + push API (push) Waiting to run
Details
Docker API / Deploy API on stage (push) Blocked by required conditions
Details
docs(s24): docs cross-check + auto-gen + onboarding + test gap-fill (8/8 ✓) 
1. Docs cross-check — обновил performance-baseline.md (Sprint 18/20/23
   фиксы), secrets.md (16 новых env-vars из Sprint 20+ — Authentication
   Google/Microsoft, Monitoring, Cleanup, Hangfire:Cron, Telegram,
   Maintenance, App, Storage, PUBLIC_GA_ID/YM_ID).

2. Auto-gen api-reference — ApiReferenceDocsJob (Hangfire weekly вс
   05:30 UTC) + Python-эквивалент `/tmp/gen-api-ref.py` для commit
   actual snapshot. docs/api-reference.md = 195 endpoints, 57 controllers.

3. Coverage gap-fill — Sprint18To23FeaturesTests.cs (16 Facts):
   - bulk-update + cross-tenant isolation
   - UserPresets CRUD
   - inline-edit price PATCH
   - CSV import 2 строки транзакцией
   - OrgExport create + list isolation
   - 1C-CSV import с русскими заголовками
   - audit-log export CSV streaming + BOM check
   - MoySklad sync-status stub
   - SSO providers + 503 unconfigured + 400 unknown provider
   - bug-001 NUL byte → 400
   - bug-004 tiny price → 400
   - export CSV BOM
   Покрывает все новые контроллеры Sprint 18-23 + regression-protect
   для критичных багов.

4. Contract tests — deploy/swagger-diff.sh: pull /swagger/v1/swagger.json
   с двух URL, diff endpoints+schemas через python3. Exit 0/1/2 для
   blue-green safety gate. Multi-path auto-detect.

5. docs/error-codes.md — каталог HTTP-кодов API (200-503) + humanizeError
   pattern для фронта + retry-policy таблица.

6. docs/glossary.md — 50+ доменных терминов (Tenant/Organization/Stock/
   StockMovement/RetailSale/Counterparty/Owner/Employee/Role/Permission/
   advisory lock/Serializable/…) с ссылками на code-сущности.

7. docs/ONBOARDING.md — first 3 days для нового разработчика
   (install → запуск → структура → первый PR + FAQ).

8. README.md — обновил под текущее состояние: React 19, Sprint-history
   1-24, ссылки на ключевые docs, корректный 5-min quick start.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-06-08 02:15:56 +05:00

22 KiB
Raw Blame History

API endpoint reference

Сгенерировано Python-сканером (/tmp/gen-api-ref.py) из src/food-market.api/Controllers/. Идентичный логике runtime-job ApiReferenceDocsJob (Sprint 24); тот пересоздаёт файл еженедельно при cron Hangfire:Cron:ApiReferenceDocs.

Всего endpoint'ов: 195.

Полная OpenAPI-спека: /swagger/v1/swagger.json. Этот reference — human-readable summary.

AbcReportController

Base route: /api/reports/abc

Method Route Permission Summary
GET /api/reports/abc/export —

AdminCleanupController

Base route: /api/admin/cleanup

Method Route Permission Summary
DELETE /api/admin/cleanup/all — Полная очистка данных текущей организации — всё кроме настроек: остаются Organization, пользователи,…
DELETE /api/admin/cleanup/counterparties — Удалить всех контрагентов текущей организации. Чтобы не нарваться на FK, сначала обнуляем ссылки (Pr…
GET /api/admin/cleanup/stats —
POST /api/admin/cleanup/all/async —

AdminJobsController

Base route: /api/admin/jobs

Method Route Permission Summary
GET /api/admin/jobs/{id:guid} —

AuthForgotPasswordController

Base route: /api/auth

Method Route Permission Summary
POST /api/auth/forgot-password —
POST /api/auth/reset-password —

AuthSignupController

Base route: /api/auth

Method Route Permission Summary
POST /api/auth/signup —

AuthorizationController

Method Route Permission Summary
POST /~/connect/token —

CounterpartiesController

Base route: /api/catalog/counterparties

Method Route Permission Summary
DELETE /api/catalog/counterparties/{id:guid} —
GET /api/catalog/counterparties/export — Sprint 19: экспорт списка контрагентов.
GET /api/catalog/counterparties/{id:guid} —
POST /api/catalog/counterparties —
PUT /api/catalog/counterparties/{id:guid} —

CountriesController

Base route: /api/catalog/countries

Method Route Permission Summary
DELETE /api/catalog/countries/{id:guid} —
GET /api/catalog/countries/{id:guid} —
POST /api/catalog/countries —
PUT /api/catalog/countries/{id:guid} —

CurrenciesController

Base route: /api/catalog/currencies

Method Route Permission Summary
GET /api/catalog/currencies/{id:guid} —
POST /api/catalog/currencies —
PUT /api/catalog/currencies/{id:guid} —

DashboardController

Base route: /api/dashboard

Method Route Permission Summary
GET /api/dashboard/margin — Маржа за окно N дней: выручка минус COGS (Sum(qty * UnitCost) по строкам проданных товаров). Использ…

DemandsController

Base route: /api/sales/demands

Method Route Permission Summary
DELETE /api/sales/demands/{id:guid} —
GET /api/sales/demands/{id:guid} —
POST /api/sales/demands —
POST /api/sales/demands/{id:guid}/post —
POST /api/sales/demands/{id:guid}/unpost —
PUT /api/sales/demands/{id:guid} —

DemoSeedController

Base route: /api/admin/seed-demo

Method Route Permission Summary
GET /api/admin/seed-demo/status — Сводка: какие демо-сущности уже наполнены. Дешёвый — только count'ы, не вызывает seed. UI использует…
POST /api/admin/seed-demo — Запустить seed демо-данных. Идемпотентен — если уже наполнено, возвращает existing summary без встав…

DiagnosticController

Base route: /api/admin/diagnostic

Method Route Permission Summary
GET /api/admin/diagnostic/run —

EmployeeRolesController

Base route: /api/organization/employee-roles

Method Route Permission Summary
DELETE /api/organization/employee-roles/{id:guid} —
GET /api/organization/employee-roles/{id:guid} —
POST /api/organization/employee-roles —
PUT /api/organization/employee-roles/{id:guid} —

EmployeesController

Base route: /api/organization/employees

Method Route Permission Summary
DELETE /api/organization/employees/{id:guid} —
GET /api/organization/employees/{id:guid} —
POST /api/organization/employees —
PUT /api/organization/employees/{id:guid} —

EntersController

Base route: /api/inventory/enters

Method Route Permission Summary
DELETE /api/inventory/enters/{id:guid} —
GET /api/inventory/enters/{id:guid} —
POST /api/inventory/enters —
POST /api/inventory/enters/{id:guid}/post —
POST /api/inventory/enters/{id:guid}/unpost —
PUT /api/inventory/enters/{id:guid} —

ExternalAuthController

Base route: /api/auth/external

Method Route Permission Summary
GET /api/auth/external/callback — Callback после успешного OAuth у провайдера. Читает claims и решает, что делать: связать с существую…
GET /api/auth/external/providers — Список доступных SSO-провайдеров. Web-фронт по этому списку решает, какие кнопки рисовать на /login.
GET /api/auth/external/{provider} — Инициирует OAuth challenge на провайдере. Если провайдер не сконфигурирован — 503 с подсказкой.

FeedbackController

Base route: /api/feedback

Method Route Permission Summary
POST /api/feedback —

GlobalSearchController

Base route: /api/search

Method Route Permission Summary
GET /api/search/global —

InventoriesController

Base route: /api/inventory/inventories

Method Route Permission Summary
DELETE /api/inventory/inventories/{id:guid} —
GET /api/inventory/inventories/{id:guid} —
POST /api/inventory/inventories —
POST /api/inventory/inventories/{id:guid}/post —
POST /api/inventory/inventories/{id:guid}/unpost —
PUT /api/inventory/inventories/{id:guid} —

LossesController

Base route: /api/inventory/losses

Method Route Permission Summary
DELETE /api/inventory/losses/{id:guid} —
GET /api/inventory/losses/{id:guid} —
POST /api/inventory/losses —
POST /api/inventory/losses/{id:guid}/post —
POST /api/inventory/losses/{id:guid}/unpost —
PUT /api/inventory/losses/{id:guid} —

LoyaltyCardsController

Base route: /api/loyalty/cards

Method Route Permission Summary
DELETE /api/loyalty/cards/{id:guid} —
GET /api/loyalty/cards/lookup — Lookup по CardNumber — используется кассой при оплате. Возвращает 404 если карты нет, 409 если карта…
POST /api/loyalty/cards/issue —
POST /api/loyalty/cards/{id:guid}/block —
POST /api/loyalty/cards/{id:guid}/unblock —

LoyaltyProgramsController

Base route: /api/loyalty/programs

Method Route Permission Summary
DELETE /api/loyalty/programs/{id:guid} —
GET /api/loyalty/programs/{id:guid} —
POST /api/loyalty/programs —
PUT /api/loyalty/programs/{id:guid} —

MeAccountController

Base route: /api/me

Method Route Permission Summary
POST /api/me/change-password — Сменить пароль текущему юзеру. Требует текущий пароль для защиты от случайного/злонамеренного измене…

MeSessionsController

Base route: /api/me/sessions

Method Route Permission Summary
POST /api/me/sessions/revoke-all — Гасит все refresh-токены текущего юзера. Использовать когда есть подозрение на угон cookies/пароля.

MoySkladImportController

Base route: /api/admin/moysklad

Method Route Permission Summary
GET /api/admin/moysklad/settings —
POST /api/admin/moysklad/import-counterparties —
POST /api/admin/moysklad/import-products —
POST /api/admin/moysklad/test —
PUT /api/admin/moysklad/settings —

MoySkladSyncStatusController

Base route: /api/moysklad

Method Route Permission Summary
GET /api/moysklad/sync-status —

OrgExportController

Base route: /api/org/export

Method Route Permission Summary
GET /api/org/export/download/{token} — Anonymous download по токену. Не требует авторизации — security через 256-битный random token + TTL …
GET /api/org/export/{id:guid} —
POST /api/org/export — Создать новый экспорт. Возвращает 202 + Id; полезно сразу polled'ить GET /api/org/export/{id} до Sta…

OrgFiscalSettingsController

Base route: /api/organization/fiscal

Method Route Permission Summary
GET /api/organization/fiscal —
GET /api/organization/fiscal/providers — Доступные значения провайдера для select'а в UI. Возвращаем массив, потому что enum-значения мы НЕ х…
POST /api/organization/fiscal/test-send — Тестовая отправка: создаёт «фейк-чек» (in-memory, не в БД) и отправляет через выбранного провайдера.…
PUT /api/organization/fiscal —

OrganizationSettingsController

Base route: /api/organization

Method Route Permission Summary
GET /api/organization/settings —
PUT /api/organization/settings —

PlatformSettingsController

Base route: /api/super-admin/platform-settings

Method Route Permission Summary
GET /api/super-admin/platform-settings —
POST /api/super-admin/platform-settings/test-send —
PUT /api/super-admin/platform-settings —

PosController

Base route: /api/pos/v1

Method Route Permission Summary
GET /api/pos/v1/sync —
POST /api/pos/v1/sales —

PriceTypesController

Base route: /api/catalog/price-types

Method Route Permission Summary
DELETE /api/catalog/price-types/{id:guid} —
GET /api/catalog/price-types/{id:guid} —
POST /api/catalog/price-types —
PUT /api/catalog/price-types/{id:guid} —

ProductGroupsController

Base route: /api/catalog/product-groups

Method Route Permission Summary
DELETE /api/catalog/product-groups/{id:guid} —
GET /api/catalog/product-groups/{id:guid} —
POST /api/catalog/product-groups —
PUT /api/catalog/product-groups/{id:guid} —

ProductImagesController

Base route: /api/catalog/products/{productId:guid}/images

Method Route Permission Summary
DELETE /api/catalog/products/{productId:guid}/images/{imageId:guid} —
POST /api/catalog/products/{productId:guid}/images/{imageId:guid}/main —

ProductsController

Base route: /api/catalog/products

Method Route Permission Summary
DELETE /api/catalog/products/{id:guid} —
GET /api/catalog/products/by-barcode/{value} — Точный поиск по штрихкоду (для сканера). 0 → 404, 1 → объект, несколько → { items: [...] } чтобы UI …
GET /api/catalog/products/export — Sprint 19: экспорт списка товаров с теми же фильтрами что и /api/catalog/products. Сервер-side генер…
GET /api/catalog/products/{id:guid} —
PATCH /api/catalog/products/{id:guid}/price —
POST /api/catalog/products —
POST /api/catalog/products/bulk-update —
POST /api/catalog/products/import-csv —
POST /api/catalog/products/{id:guid}/recalc-retail — «Привести розничную к себестоимости»: ставит дефолтную розничную цену = ceil(Cost * (1 + Group.Marku…
PUT /api/catalog/products/{id:guid} —

ProfitReportController

Base route: /api/reports/profit

Method Route Permission Summary
GET /api/reports/profit/export —

PromotionsController

Base route: /api/promotions

Method Route Permission Summary
DELETE /api/promotions/{id:guid} —
GET /api/promotions/{id:guid} —
POST /api/promotions —
PUT /api/promotions/{id:guid} —

RetailPointsController

Base route: /api/catalog/retail-points

Method Route Permission Summary
DELETE /api/catalog/retail-points/{id:guid} —
GET /api/catalog/retail-points/{id:guid} —
POST /api/catalog/retail-points —
PUT /api/catalog/retail-points/{id:guid} —

RetailSalesController

Base route: /api/sales/retail

Method Route Permission Summary
DELETE /api/sales/retail/{id:guid} —
GET /api/sales/retail/export — Sprint 19: экспорт списка чеков с фильтрами status/storeId/from/to.
GET /api/sales/retail/stats — Aggregated sales metrics + daily series for the dashboard. Series buckets are days; defaults to last…
GET /api/sales/retail/{id:guid} —
POST /api/sales/retail —
POST /api/sales/retail/{id:guid}/create-return — POST /create-return — копирует строки проведённого чека в новый Draft с IsReturn=true и ReferenceSal…
POST /api/sales/retail/{id:guid}/post —
POST /api/sales/retail/{id:guid}/unpost —
PUT /api/sales/retail/{id:guid} —

SalesReportController

Base route: /api/reports/sales

Method Route Permission Summary
GET /api/reports/sales/export —

StockController

Base route: /api/inventory

Method Route Permission Summary
GET /api/inventory/stock/export — Sprint 19: экспорт остатков.

StockReportController

Base route: /api/reports/stock

Method Route Permission Summary
GET /api/reports/stock/export —

StoresController

Base route: /api/catalog/stores

Method Route Permission Summary
DELETE /api/catalog/stores/{id:guid} —
GET /api/catalog/stores/{id:guid} —
POST /api/catalog/stores —
PUT /api/catalog/stores/{id:guid} —

SuperAdminController

Base route: /api/super-admin

Method Route Permission Summary
GET /api/super-admin/dashboard —
GET /api/super-admin/settings —
GET /api/super-admin/setup-status —
PUT /api/super-admin/settings —

SuperAdminEmployeesController

Base route: /api/super-admin/organizations/{orgId:guid}/employees

Method Route Permission Summary
DELETE /api/super-admin/organizations/{orgId:guid}/employees/{id:guid} —
GET /api/super-admin/organizations/{orgId:guid}/employees/{id:guid} —
POST /api/super-admin/organizations/{orgId:guid}/employees —
POST /api/super-admin/organizations/{orgId:guid}/employees/{id:guid}/account/toggle-active —
POST /api/super-admin/organizations/{orgId:guid}/employees/{id:guid}/reset-password —
POST /api/super-admin/organizations/{orgId:guid}/employees/{id:guid}/toggle-active —
PUT /api/super-admin/organizations/{orgId:guid}/employees/{id:guid} —

SuperAdminOrganizationsController

Base route: /api/super-admin/organizations

Method Route Permission Summary
DELETE /api/super-admin/organizations/{id:guid} —
GET /api/super-admin/organizations/{id:guid} —
POST /api/super-admin/organizations —
POST /api/super-admin/organizations/{id:guid}/archive —
POST /api/super-admin/organizations/{id:guid}/change-owner —
POST /api/super-admin/organizations/{id:guid}/restore —
PUT /api/super-admin/organizations/{id:guid} —

SuperAdminUnitsOfMeasureController

Base route: /api/super-admin/units-of-measure

Method Route Permission Summary
DELETE /api/super-admin/units-of-measure/{id:guid} — Soft-delete: IsActive=false. Если на единицу ссылаются продукты или активные org-junction'ы — 409 со…
GET /api/super-admin/units-of-measure/{id:guid} —
POST /api/super-admin/units-of-measure —
PUT /api/super-admin/units-of-measure/{id:guid} —

SupplierReturnsController

Base route: /api/purchases/supplier-returns

Method Route Permission Summary
DELETE /api/purchases/supplier-returns/{id:guid} —
GET /api/purchases/supplier-returns/{id:guid} —
POST /api/purchases/supplier-returns —
POST /api/purchases/supplier-returns/{id:guid}/post —
POST /api/purchases/supplier-returns/{id:guid}/unpost —
PUT /api/purchases/supplier-returns/{id:guid} —

SuppliesController

Base route: /api/purchases/supplies

Method Route Permission Summary
DELETE /api/purchases/supplies/{id:guid} —
GET /api/purchases/supplies/export — Sprint 19: экспорт списка приёмок с теми же фильтрами.
GET /api/purchases/supplies/{id:guid} —
POST /api/purchases/supplies —
POST /api/purchases/supplies/{id:guid}/post —
POST /api/purchases/supplies/{id:guid}/unpost —
PUT /api/purchases/supplies/{id:guid} —

TelegramBindingController

Base route: /api/organization/telegram

Method Route Permission Summary
DELETE /api/organization/telegram —
GET /api/organization/telegram/status —
PUT /api/organization/telegram/bind —

TransfersController

Base route: /api/inventory/transfers

Method Route Permission Summary
DELETE /api/inventory/transfers/{id:guid} —
GET /api/inventory/transfers/{id:guid} —
POST /api/inventory/transfers —
POST /api/inventory/transfers/{id:guid}/post —
POST /api/inventory/transfers/{id:guid}/unpost —
PUT /api/inventory/transfers/{id:guid} —

TwoFactorController

Base route: /api/me/2fa

Method Route Permission Summary
GET /api/me/2fa/status —
POST /api/me/2fa/disable —
POST /api/me/2fa/enroll —
POST /api/me/2fa/verify —

UnitsOfMeasureController

Base route: /api/catalog/units-of-measure

Method Route Permission Summary
DELETE /api/catalog/units-of-measure/{id:guid}/enable — Отключить global для текущей орги. Если на эту единицу ссылаются продукты орги — 409 со списком назв…
GET /api/catalog/units-of-measure/{id:guid} —
POST /api/catalog/units-of-measure/{id:guid}/enable — Включить global для текущей орги. Идемпотентно: повторный вызов отдаёт 204 и не плодит дубликатов ju…

UploadsController

Base route: /uploads

Method Route Permission Summary
GET /uploads/{*path} —

UserPresetsController

Base route: /api/user/presets

Method Route Permission Summary
DELETE /api/user/presets/{id:guid} —
POST /api/user/presets —
PUT /api/user/presets/{id:guid} —

WhatsNewController

Base route: /api/whats-new

Method Route Permission Summary
GET /api/whats-new —