marketplaces/docs/architecture/backend/Backend-Platform-API-Spec.md

# Backend Platform API Specification

Status: Draft for implementation handoff
Date: 2026-07-03
Scope: Marketplace Platform (Website + Builder + Backoffice)

## 1. Tenant Resolution

### Mechanism
- Backend resolves tenant from HTTP Host header.
- Frontend never sends tenant id or project key.
- Tenant resolution occurs before authorization and route handling.

### Resolution Rules
1. Exact host match in tenant registry.
2. Alias host fallback.
3. Unknown host returns 404 tenant_not_found.

### Validation
- Host must be present.
- Host must map to active tenant.
- Suspended tenant returns 403 tenant_suspended.

## 2. Bootstrap API

### Endpoint
- Method: GET
- Path: /bootstrap

### Purpose
- Return complete tenant runtime configuration for frontend bootstrap.

### Authorization
- Public for website runtime.
- Optional authenticated extensions for builder/backoffice context may be included via claims.

### Request
- Headers: Host (required)
- Query: locale (optional)

### Response
- 200 with BootstrapConfig payload.

### Validation
- Schema version required.
- Required segments: tenant, branding, theme, featureFlags, navigation, pages.

### Example Response
```json
{
  "schemaVersion": "1.0.0",
  "generatedAt": "2026-07-03T00:00:00Z",
  "tenant": { "id": "tenant-default-001", "slug": "default", "host": "default.local" },
  "branding": { "brandName": "Marketplace", "logoUrl": "/icons/icon-192x192.png", "faviconUrl": "/icons/icon-192x192.png" },
  "theme": { "themeId": "default-light", "mode": "light", "palette": { "primary": "#497671" }, "typography": { "primaryFontFamily": "DM Sans, sans-serif", "baseFontSize": 16 }, "spacing": { "unit": 4, "scale": [0,4,8] }, "borderRadiusScale": { "md": "12px" }, "shadows": { "md": "0 4px 12px rgba(0,0,0,0.15)" }, "iconSet": "default" },
  "featureFlags": { "wishlist": true, "reviews": true },
  "navigation": { "header": [], "footer": [] },
  "pages": []
}
```

## 3. Configuration API

### Endpoint
- Method: GET
- Path: /configuration

### Purpose
- Return complete editable configuration model for Builder.

### Authorization
- Required: builder.read

### Request
- Headers: Authorization bearer token

### Response
- 200 configuration aggregate for tenant.

### Validation
- Caller must belong to tenant context.
- Caller role must include builder permissions.

### Example Response
```json
{
  "tenantId": "tenant-default-001",
  "branding": { "brandName": "Marketplace" },
  "theme": { "themeId": "default-light" },
  "navigation": { "header": [], "footer": [] },
  "pages": []
}
```

## 4. Website API

### Endpoint
- Method: GET
- Path: /website/pages/{pageKey}

### Purpose
- Return website page composition for runtime rendering.

### Authorization
- Public.

### Request
- Path: pageKey required

### Response
- 200 PageConfig with sections/widgets.

### Validation
- pageKey must exist for tenant.
- hidden pages return 404.

### Example Response
```json
{
  "id": "page-home",
  "key": "home",
  "layout": "default-public",
  "sections": [
    {
      "id": "section-hero",
      "type": "hero",
      "order": 1,
      "widgets": [
        { "id": "widget-hero-main", "type": "hero", "version": "1.0.0", "props": { "title": "Welcome" } }
      ]
    }
  ]
}
```

## 5. Builder API

### Endpoint
- Method: PUT
- Path: /builder/configuration

### Purpose
- Save tenant configuration from Builder Sandbox.

### Authorization
- Required: builder.write

### Request
- Body: full or partial configuration document.

### Response
- 200 updated configuration metadata.

### Validation
- JSON schema validation.
- Widget types must be registered and supported.
- Route/path uniqueness checks.

### Example Request
```json
{
  "branding": { "brandName": "Updated Brand" },
  "featureFlags": { "chat": true },
  "pages": []
}
```

### Example Response
```json
{
  "version": 42,
  "updatedAt": "2026-07-03T12:00:00Z",
  "updatedBy": "user-100"
}
```

## 6. Backoffice API

### Endpoint
- Method: GET
- Path: /backoffice/dashboard

### Purpose
- Return dashboard aggregates for backoffice operations.

### Authorization
- Required: backoffice.read

### Request
- Optional query filters by date range.

### Response
- KPIs and entity counts.

### Validation
- Caller must belong to tenant.

### Example Response
```json
{
  "ordersToday": 14,
  "openOrders": 38,
  "products": 1024,
  "customers": 5600,
  "inventoryAlerts": 12
}
```

## 7. Products API

### Endpoint
- GET /products
- GET /products/{id}
- POST /products
- PUT /products/{id}
- DELETE /products/{id}

### Purpose
- Product catalog management for backoffice.

### Authorization
- Read: backoffice.products.read
- Write: backoffice.products.write

### Request
- Supports paging/filter/sort on GET /products.

### Response
- Product entities aligned to UI contracts.

### Validation
- SKU unique per tenant.
- Price and currency required.
- Visibility and status must be valid enum values.

### Example Product
```json
{
  "id": "prod-001",
  "sku": "SKU-001",
  "title": "Wireless Headphones",
  "price": { "amount": 149990, "currency": "RUB" },
  "stockStatus": "in_stock",
  "visible": true
}
```

## 8. Categories API

### Endpoint
- GET /categories
- POST /categories
- PUT /categories/{id}
- DELETE /categories/{id}

### Purpose
- Category tree management.

### Authorization
- Read: backoffice.categories.read
- Write: backoffice.categories.write

### Validation
- Category id unique.
- Parent relation must not create cycles.

### Example Category
```json
{
  "id": "cat-001",
  "title": "Electronics",
  "parentId": null,
  "itemsCount": 120,
  "visible": true
}
```

## 9. Orders API

### Endpoint
- GET /orders
- GET /orders/{id}
- PATCH /orders/{id}/status

### Purpose
- Order lifecycle tracking and updates.

### Authorization
- Read: backoffice.orders.read
- Write: backoffice.orders.write

### Validation
- Status transition must be legal according to state machine.

### Example Response
```json
{
  "id": "ord-1001",
  "status": "processing",
  "total": { "amount": 9900, "currency": "RUB" },
  "createdAt": "2026-07-03T10:20:00Z"
}
```

## 10. Media API

### Endpoint
- POST /media/upload
- GET /media/{id}
- DELETE /media/{id}

### Purpose
- Media asset management for products/widgets/pages.

### Authorization
- Required: backoffice.media.write for upload/delete.

### Validation
- File size/type constraints.
- Malware scan required before publish.

### Example Response
```json
{
  "id": "media-001",
  "url": "https://cdn.example.com/tenant-default/media-001.jpg",
  "mimeType": "image/jpeg"
}
```

## 11. Localization API

### Endpoint
- GET /localization/dictionaries/{locale}
- PUT /localization/dictionaries/{locale}

### Purpose
- Localization dictionary retrieval and updates.

### Authorization
- Read: builder.localization.read
- Write: builder.localization.write

### Validation
- Locale must be supported by tenant.
- Keys must be unique.

### Example Response
```json
{
  "locale": "ru",
  "version": "1.0.3",
  "entries": {
    "nav.home": "Главная",
    "nav.cart": "Корзина"
  }
}
```

## 12. Permissions API

### Endpoint
- GET /permissions
- GET /roles
- PUT /roles/{role}

### Purpose
- Permission definitions and role bindings.

### Authorization
- Required: security.admin

### Validation
- Role names unique.
- Permission keys must exist in definitions.

### Example Response
```json
{
  "definitions": [
    { "key": "builder.pages.edit" },
    { "key": "backoffice.products.read" }
  ],
  "roles": [
    { "role": "builder_admin", "permissions": ["builder.pages.edit"] }
  ]
}
```

## 13. Feature Flags API

### Endpoint
- GET /feature-flags
- PUT /feature-flags

### Purpose
- Tenant capability toggles for optional modules.

### Authorization
- Read: builder.features.read
- Write: builder.features.write

### Validation
- Flag keys must be from allowed registry.
- Non-boolean values rejected.

### Example Response
```json
{
  "wishlist": true,
  "compare": true,
  "reviews": true,
  "blog": false,
  "chat": false,
  "analytics": true,
  "notifications": true,
  "coupons": true,
  "loyalty": false,
  "giftCards": false,
  "invoices": true
}
```

## Error Model (Common)

### Structure
```json
{
  "code": "validation_error",
  "message": "Validation failed",
  "details": [
    { "field": "pages[0].route.path", "message": "Path already exists" }
  ],
  "traceId": "trc-123"
}
```

### Common Codes
- tenant_not_found
- tenant_suspended
- unauthorized
- forbidden
- validation_error
- conflict
- not_found
- internal_error

## Contract Compatibility Note

Authentication, payment, and authorization behavior and contracts in the current system are preserved as-is.
This document defines platform APIs around those stable integrations without changing their existing payload contracts.