marketplaces/docs/backend/FRONTEND-API-SURFACE-COMPLETE.md

Complete Frontend API Surface — Master Endpoint List

Generated 2026-08-18 directly from source (every this.http.get/post/patch/put/delete call across src/app/core/, src/app/features/admin/, src/app/services/api.service.ts). This is not a design document — it is a census: every endpoint this codebase currently calls or will call once its gateway swap goes live, in one place, cross-referenced against the contracts that already exist.

Why this exists. The individual Phase/Track contracts in this directory each cover one domain well. Nothing until now listed the entire surface in one pass, so a backend dev building against these docs had no way to see what's fully specified, what's inferred-and-needs-confirmation, and what has no contract at all. This closes that gap.

Status legend

Status	Meaning
✅ Specified	Exact shape exists in a Phase/Track contract doc. Build as written.
⚠️ Inferred	Endpoint follows this codebase's own REST conventions (path pattern, verb) but no contract doc states it explicitly. Flagged in source with a comment at the call site. Confirm or correct before building — do not treat as final.
❌ Undocumented	Legacy endpoint, no contract anywhere, still called by api.service.ts. Will be replaced when the corresponding /api/v2 migration lands (Track N) — do not invest in these long-term, but they are live today.

---

1. Legacy surface (still called today, no /api/v2 contract)

These come from BACKEND-API-REFERENCE.md, not docs/backend/. Base URL is environment.localhostApiUrl / tenant-resolved; qrBaseUrl is a separate provider base for QR-specific calls.

Method	Path	Called from	Status
GET	/ping	api.service.ts	❌ Undocumented — health check
GET	/category	api.service.ts, api-category.repository.ts	❌ Undocumented — full category tree
GET	/category/{categoryID}	api.service.ts	❌ Undocumented — one category + its items
GET	/items/{itemID}	api.service.ts	❌ Undocumented — single item detail
GET	/searchitems	api.service.ts	❌ Undocumented — search
GET	/items/randomitems	api.service.ts	❌ Undocumented — related/random items
POST	/websession/{sessionId}	api.service.ts	❌ Undocumented — sync cart to a Telegram web session
POST	/items/{itemID}/callback	api.service.ts	❌ Undocumented — "call me back" request
POST	/items/{itemID}/questiion	api.service.ts	❌ Undocumented — product Q&A (note: questiion typo is load-bearing, do not silently "fix" without checking the live backend uses the same typo)
POST	/items/{itemID}/notify-me	api.service.ts	❌ Undocumented — back-in-stock subscription
POST	/purchase-email	api.service.ts	❌ Undocumented — post-purchase email collection
POST	{qrBaseUrl}/qr	api.service.ts	❌ Undocumented — direct QR payment creation
POST	/cart	api.service.ts	❌ Undocumented — legacy payment creation, client-sent amount (superseded by §2 below for new checkout flow; still live for any caller not yet migrated)
GET	{qrBaseUrl}/qr/dynamic/{partnerId}/{qrId}	api.service.ts	❌ Undocumented — QR payment status poll
GET	{qrBaseUrl}/card/{partnerId}/{orderId}	api.service.ts	❌ Undocumented — card payment status poll
POST	/orders	api.service.ts	❌ Undocumented — records a paid cart as a backoffice order, fire-and-forget

Recommendation: these 15 need their own contract doc if they are staying, or a deprecation timeline if /api/v2/storefront/* replaces them. Right now they are simply undocumented and live — the single biggest gap in docs/backend/.

---

2. Storefront checkout & cart — ✅ Specified

Contract: PHASE-1-MONEY-FX-PAYMENTS-CONTRACT.md §5.2, PHASE-6-CART-CHECKOUT-CONTRACT.md §3, §5.

Method	Path	Called from
GET	/api/v2/storefront/cart	server-cart-api.gateway.ts
POST	/api/v2/storefront/cart/lines	server-cart-api.gateway.ts
PATCH	/api/v2/storefront/cart/lines/{lineId}	server-cart-api.gateway.ts
DELETE	/api/v2/storefront/cart/lines/{lineId}	server-cart-api.gateway.ts
POST	/api/v2/storefront/checkout	server-cart-api.gateway.ts, api.service.ts (two different callers, same contract)
POST	/api/v2/storefront/payments/intents	api.service.ts

3. Pricing — ✅ Specified

Contract: PHASE-1-MONEY-FX-PAYMENTS-CONTRACT.md §3.1.

Method	Path	Called from
GET	/api/v2/pricing/fx-quote?base=&quote=	fx-quote-api.gateway.ts

4. Identity & permissions — ✅ Specified

Contracts: PHASE-8-IDENTITY-MESSAGING-CONTRACT.md §2, TRACK-S-SECURITY-RBAC-CONTRACT.md §2.

Method	Path	Called from
GET	/api/identity/v1/vk/authorize	vk-id-api.gateway.ts
POST	/api/identity/v1/vk/callback	vk-id-api.gateway.ts
GET	/api/identity/v1/session/permissions	permission-api.gateway.ts

5. Team / RBAC — mixed

Contract: TRACK-S-SECURITY-RBAC-CONTRACT.md §8.

Method	Path	Called from	Status
GET	/api/admin/v2/audit	permission-api.gateway.ts, admin-users-api.gateway.ts?actor=	✅ Specified
POST	/api/admin/v2/team/invite	admin-users-api.gateway.ts	✅ Specified
GET	/api/admin/v2/team?marketplaceId=	admin-users-api.gateway.ts	✅ Specified
PATCH	/api/admin/v2/team/{userId}	admin-users-api.gateway.ts	✅ Specified
DELETE	/api/admin/v2/team/{userId}	(interface exists, not yet called)	✅ Specified
GET	/api/admin/v2/team/roles	admin-users-api.gateway.ts	⚠️ Inferred
GET	/api/admin/v2/team/invitations	admin-users-api.gateway.ts	⚠️ Inferred
GET	/api/admin/v2/team/{userId}/sessions	admin-users-api.gateway.ts	⚠️ Inferred
PATCH	/api/admin/v2/team/{userId}/status	admin-users-api.gateway.ts	⚠️ Inferred
DELETE	/api/admin/v2/team/invitations/{id}	admin-users-api.gateway.ts	⚠️ Inferred
DELETE	/api/admin/v2/team/sessions/{sessionId}	admin-users-api.gateway.ts	⚠️ Inferred

6. Orders & notifications — ✅ Specified

Contract: PHASE-2-ORDERS-NOTIFICATIONS-CONTRACT.md.

Method	Path	Called from
GET	/api/admin/v2/orders?marketplaceId=&status=&source=&page=&pageSize=	admin-orders-api.gateway.ts
GET	/api/admin/v2/orders/{id}	admin-orders-api.gateway.ts
PATCH	/api/admin/v2/orders/{id}/status	admin-orders-api.gateway.ts
POST	/api/admin/v2/orders/{id}/refund-request	admin-orders-api.gateway.ts (note: gateway calls this refund-request; interface method is named requestRefund — same endpoint)
POST	/api/admin/v2/orders/{id}/notes	admin-orders-api.gateway.ts
POST	/api/admin/v2/orders/{id}/archive	admin-orders-api.gateway.ts
POST	/api/admin/v2/orders/{id}/restore	admin-orders-api.gateway.ts
DELETE	/api/admin/v2/orders/{id}	admin-orders-api.gateway.ts
GET	/api/admin/v2/notifications?marketplaceId=&unreadOnly=&eventType=	admin-notifications-api.gateway.ts
PATCH	/api/admin/v2/notifications/{id}/read	admin-notifications-api.gateway.ts
PATCH	/api/admin/v2/notifications/read-all	admin-notifications-api.gateway.ts

7. Catalog / offers — ✅ Specified + ⚠️ Inferred

Contract: PHASE-3-CATALOG-OFFER-FULFILLMENT-CONTRACT.md §7.

Method	Path	Called from	Status
GET	/api/admin/v2/products?marketplaceId=&status=&search=&page=&pageSize=	admin-products-api.gateway.ts	✅ Specified
GET	/api/admin/v2/products/{id}	admin-products-api.gateway.ts	✅ Specified
POST	/api/admin/v2/products	admin-products-api.gateway.ts	✅ Specified
PATCH	/api/admin/v2/products/{id}	admin-products-api.gateway.ts	✅ Specified
GET	/api/admin/v2/offers?productId=&sellerId=&status=	offer-api.gateway.ts	✅ Specified
POST	/api/admin/v2/offers/{id}/publish	offer-api.gateway.ts	✅ Specified — 422 + details[] on executability failure
GET	/api/admin/v2/offers/lookup?sku=&sellerSku=&externalId=	offer-api.gateway.ts	✅ Specified
GET	/api/admin/v2/products/categories	admin-products-api.gateway.ts	⚠️ Inferred
DELETE	/api/admin/v2/products/{id}	admin-products-api.gateway.ts	⚠️ Inferred
POST	/api/admin/v2/products/{id}/duplicate	admin-products-api.gateway.ts	⚠️ Inferred
POST	/api/admin/v2/products/{id}/archive	admin-products-api.gateway.ts	⚠️ Inferred
POST	/api/admin/v2/products/{id}/restore	admin-products-api.gateway.ts	⚠️ Inferred
GET	/api/admin/v2/offers/{offerId}/inventory	offer-api.gateway.ts	⚠️ Inferred

8. Categories — ✅ Specified (pre-existing, F29 done before this session)

Method	Path	Called from
GET	{baseUrl} (categories collection)	admin-categories-api.gateway.ts
GET	{baseUrl}/{id}	admin-categories-api.gateway.ts
POST	{baseUrl}	admin-categories-api.gateway.ts
PUT	{baseUrl}/{id}	admin-categories-api.gateway.ts
DELETE	{baseUrl}/{id}	admin-categories-api.gateway.ts
POST	{baseUrl}/{id}/restore	admin-categories-api.gateway.ts
GET	{baseUrl}/slug-taken	admin-categories-api.gateway.ts

9. Seller portal — mixed

Contract: PHASE-5-SELLER-PORTAL-CONTRACT.md §3.

Method	Path	Called from	Status
GET	/api/seller/v1/finance/settlements	(contract-only, no current caller)	✅ Specified
GET	/api/admin/v2/sellers	seller-api.gateway.ts	⚠️ Inferred — contract only specifies the caller's own GET /api/seller/v1/profile, not an admin list-all
GET	/api/admin/v2/sellers/{sellerId}/team	seller-api.gateway.ts	⚠️ Inferred — contract's GET /api/seller/v1/team is session-scoped, not parameterized

10. Payments, refunds, reconciliation, settlements — ✅ Specified

Contract: PHASE-7-PAYMENTS-RECONCILIATION-CONTRACT.md.

Method	Path	Called from
GET	/api/admin/v2/orders/{orderId}/refunds	finance-api.gateway.ts
GET	/api/admin/v2/reconciliation/queue	finance-api.gateway.ts
POST	/api/admin/v2/reconciliation/{id}/resolve	finance-api.gateway.ts
GET	/api/admin/v2/finance/settlements?sellerId=	finance-api.gateway.ts

11. Tenant registry — mixed

Contract: PHASE-9-TENANT-REGISTRY-DOMAINS-CONTRACT.md.

Method	Path	Called from	Status
GET	/api/admin/v2/marketplaces/{id}/lifecycle	marketplace-api.gateway.ts	✅ Specified
GET	/api/admin/v2/marketplaces (list)	marketplace-api.gateway.ts	⚠️ Inferred — contract specifies POST for creation, not the list GET
GET	/api/admin/v2/marketplaces/{id}/domains	marketplace-api.gateway.ts	⚠️ Inferred

12. Connector framework — mixed

Contract: PHASE-4-CONNECTOR-FRAMEWORK-CONTRACT.md §7-8.

Method	Path	Called from	Status
GET	/api/admin/v2/integrations	connector-api.gateway.ts	✅ Specified
PATCH	/api/admin/v2/integrations/{id}	connector-api.gateway.ts (pause/resume via status field)	✅ Specified
GET	/api/admin/v2/integrations/{connectorId}/dead-letter	connector-api.gateway.ts	⚠️ Inferred — contract specifies replay, not the list
POST	/api/admin/v2/integrations/{connectorId}/dead-letter/{id}/replay	connector-api.gateway.ts	✅ Specified — path corrected 2026-08-18; the gateway initially omitted connectorId, caught while writing this doc, fixed in the same pass

13. Content modules (Gorbushka-class) — ⚠️ Mostly inferred

Contract: PHASE-10-CONTENT-MODULES-CONTRACT.md §2.

Method	Path	Called from	Status
POST	/api/admin/v2/content/rent-listings/{id}/leads	mall-content-api.gateway.ts	✅ Specified
GET	/api/admin/v2/content/shops	mall-content-api.gateway.ts	⚠️ Inferred
GET	/api/admin/v2/content/shop-categories	mall-content-api.gateway.ts	⚠️ Inferred
GET	/api/admin/v2/content/floors	mall-content-api.gateway.ts	⚠️ Inferred
GET	/api/admin/v2/content/floors/{floorId}/pins	mall-content-api.gateway.ts	⚠️ Inferred
GET	/api/admin/v2/content/rent-listings	mall-content-api.gateway.ts	⚠️ Inferred

14. Analytics — ✅ Specified

Contract: TRACK-A-ANALYTICS-CONTRACT.md §1.

Method	Path	Called from
POST	/api/v2/storefront/analytics/events	analytics-api.gateway.ts

15. Transactions, monitoring, moderation — ❌ No contract doc exists

These three domains have gateways calling /api/admin/v2/{resource} by convention only. No Phase/Track doc covers any of them.

Method	Path	Called from
GET	/api/admin/v2/transactions	admin-transactions-api.gateway.ts
POST	/api/admin/v2/transactions/{id}/retry	admin-transactions-api.gateway.ts
PATCH	/api/admin/v2/transactions/{id}	admin-transactions-api.gateway.ts
GET	/api/admin/v2/monitoring/events	admin-monitoring-api.gateway.ts
GET	/api/admin/v2/monitoring/queues	admin-monitoring-api.gateway.ts
GET	/api/admin/v2/monitoring/webhooks	admin-monitoring-api.gateway.ts
GET	/api/admin/v2/moderation/reviews	admin-moderation-api.gateway.ts
GET	/api/admin/v2/moderation/reviews/{id}	admin-moderation-api.gateway.ts
PATCH	/api/admin/v2/moderation/reviews/{id}	admin-moderation-api.gateway.ts (status/visible/pinned/featured — 4 different PATCH bodies, same endpoint)
POST	/api/admin/v2/moderation/reviews/{id}/notes	admin-moderation-api.gateway.ts
DELETE	/api/admin/v2/moderation/reviews/{id}	admin-moderation-api.gateway.ts
GET	/api/admin/v2/moderation/reports	admin-moderation-api.gateway.ts
PATCH	/api/admin/v2/moderation/reports/{id}	admin-moderation-api.gateway.ts
GET	/api/admin/v2/dashboard/metrics	admin-dashboard-metrics-api.gateway.ts

Recommendation: these are the highest-priority gap. Three full admin domains with real UI and real gateways, zero backend contract. Whoever picks up Phase 5/7 next should write these as proper contract docs — the endpoint shapes above are a starting point, not a spec.

16. Partner provisioning API — ✅ Specified

Contract: PARTNER-PROVISIONING-API-CONTRACT.md §4, §6. This is the one domain where the frontend gateway was built from the contract, not the other way around — no drift to reconcile.

Method	Path	Called from
GET	/api/partner/v1/companies/{companyId}/hierarchy?environment=	partner-hierarchy-api.gateway.ts
GET	/api/partner/v1/nodes/{nodeId}	partner-hierarchy-api.gateway.ts
GET	/api/partner/v1/nodes/lookup?externalReference=&environment=	partner-hierarchy-api.gateway.ts
POST	/api/partner/v1/companies/{companyId}/projects	partner-hierarchy-api.gateway.ts
POST	/api/partner/v1/projects/{projectId}/stores	partner-hierarchy-api.gateway.ts
POST	/api/partner/v1/stores/{storeId}/payment-points	partner-hierarchy-api.gateway.ts
PATCH	/api/partner/v1/nodes/{nodeId}/status	partner-hierarchy-api.gateway.ts
POST	/api/partner/v1/nodes/{nodeId}/disable	partner-hierarchy-api.gateway.ts
GET	/api/partner/v1/credentials?companyId=	partner-hierarchy-api.gateway.ts
POST	/api/partner/v1/credentials	partner-hierarchy-api.gateway.ts
POST	/api/partner/v1/credentials/{keyId}/rotate	partner-hierarchy-api.gateway.ts
DELETE	/api/partner/v1/credentials/{keyId}	partner-hierarchy-api.gateway.ts

17. Backoffice data & bootstrap — ✅ Specified elsewhere (not a Phase/Track doc, but stable)

Method	Path	Called from
GET	/api/backoffice/products	api-backoffice-data.provider.ts
GET	/api/backoffice/categories	api-backoffice-data.provider.ts
GET	(tenant bootstrap URL)	api-bootstrap.provider.ts — see BACKEND-HANDOFF.md §1a

---

Summary counts

Status	Count
✅ Specified	47
⚠️ Inferred (needs confirmation)	24
❌ Undocumented (legacy)	15
Total distinct endpoints called	86

What backend needs to do with this

1. Build the ✅ rows as written — they match an existing contract doc exactly.
2. Confirm or correct every ⚠️ row — each one has a comment at its call site in source explaining the inference. Search the codebase for Inferred to find all 24 in place, with the reasoning right next to the code.
3. Write a contract for §15 (transactions, monitoring, moderation) — real UI, real gateways, zero spec. Highest-priority gap in this whole list.
4. Decide the fate of §1 — 15 legacy endpoints with no contract at all, still live. Either document them as a stable, permanent surface, or set a Track N migration date.