marketplaces/docs/API_CHANGES_REQUIRED.md

API Changes Required for Backend

Overview

Frontend has been updated with two new features:

1. Region/Location system — catalog filtering by region
2. Auth/Login system — Telegram-based authentication required before payment

Base URLs:

• Dexar: https://api.dexarmarket.ru:445
• Novo: https://api.novo.market:444

---

1. Region / Location Endpoints

1.1 GET /regions — List available regions

Returns the list of regions where the marketplace operates.

Response 200 OK

[
  {
    "id": "moscow",
    "city": "Москва",
    "country": "Россия",
    "countryCode": "RU",
    "timezone": "Europe/Moscow"
  },
  {
    "id": "spb",
    "city": "Санкт-Петербург",
    "country": "Россия",
    "countryCode": "RU",
    "timezone": "Europe/Moscow"
  },
  {
    "id": "yerevan",
    "city": "Ереван",
    "country": "Армения",
    "countryCode": "AM",
    "timezone": "Asia/Yerevan"
  }
]

Region object:

Field	Type	Required	Description
id	string	yes	Unique region identifier
city	string	yes	City name (display)
country	string	yes	Country name (display)
countryCode	string	yes	ISO 3166-1 alpha-2 code
timezone	string	no	IANA timezone string

If this endpoint is unavailable, the frontend falls back to 6 hardcoded regions (Moscow, SPB, Yerevan, Minsk, Almaty, Tbilisi).

---

1.2 Region Query Parameter on Existing Endpoints

The following existing endpoints now accept an optional ?region= query parameter:

Endpoint	Example
GET /category	GET /category?region=moscow
GET /category/:id	GET /category/5?count=50&skip=0&region=spb
GET /item/:id	GET /item/123?region=yerevan
GET /searchitems	GET /searchitems?search=phone&region=moscow
GET /randomitems	GET /randomitems?count=5&region=almaty

Behavior:

• If region param is present → return only items/categories available in that region
• If region param is absent → return all items globally (current behavior, no change)
• The region value matches the id field from the /regions response

---

2. Auth / Login Endpoints

Authentication is Telegram-based with cookie sessions (HttpOnly, Secure, SameSite=None).

All auth endpoints must support CORS with credentials: true.

2.1 GET /auth/session — Check current session

Called on every page load to check if the user has an active session.

Request:

• Cookies: session cookie (set by backend)
• CORS: withCredentials: true

Response 200 OK (authenticated):

{
  "sessionId": "sess_abc123",
  "telegramUserId": 123456789,
  "username": "john_doe",
  "displayName": "John Doe",
  "active": true,
  "expiresAt": "2026-03-01T12:00:00Z"
}

Response 200 OK (expired session):

{
  "sessionId": "sess_abc123",
  "telegramUserId": 123456789,
  "username": "john_doe",
  "displayName": "John Doe",
  "active": false,
  "expiresAt": "2026-02-27T12:00:00Z"
}

Response 401 Unauthorized (no session / invalid cookie):

{
  "error": "No active session"
}

AuthSession object:

Field	Type	Required	Description
sessionId	string	yes	Unique session ID
telegramUserId	number	yes	Telegram user ID
username	string?	no	Telegram @username (can be null)
displayName	string	yes	User display name (first_name + last_name)
active	boolean	yes	Whether session is currently valid
expiresAt	string	yes	ISO 8601 expiration datetime

---

2.2 GET /auth/telegram/callback — Telegram bot auth callback

This is the URL the Telegram bot redirects to after the user starts the bot.

Flow:

1. Frontend generates link: https://t.me/{botUsername}?start=auth_{encodedCallbackUrl}
2. User clicks → opens Telegram → starts the bot
3. Bot sends user data to this callback endpoint
4. Backend creates session, sets Set-Cookie header
5. Frontend polls GET /auth/session every 3 seconds to detect when session becomes active

Request (from Telegram bot / webhook):

{
  "id": 123456789,
  "first_name": "John",
  "last_name": "Doe",
  "username": "john_doe",
  "photo_url": "https://t.me/i/userpic/...",
  "auth_date": 1709100000,
  "hash": "abc123def456..."
}

Response: Should set a session cookie and return:

{
  "sessionId": "sess_abc123",
  "message": "Authenticated successfully"
}

Cookie requirements:

Attribute	Value	Notes
HttpOnly	true	Not accessible via JS
Secure	true	HTTPS only
SameSite	None	Required for cross-origin (API ≠ frontend)
Path	/
Max-Age	86400 (24h)	Or as needed
Domain	API domain

Important: Since the API domain differs from the frontend domain, SameSite=None + Secure=true is required for the cookie to be sent cross-origin.

---

2.3 POST /auth/logout — End session

Request:

• Cookies: session cookie
• CORS: withCredentials: true
• Body: {} (empty)

Response 200 OK:

{
  "message": "Logged out"
}

Should clear/invalidate the session cookie.

---

3. CORS Configuration

For auth cookies to work cross-origin, the backend CORS config must include:

Access-Control-Allow-Origin: https://dexarmarket.ru   (NOT *)
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Allow-Methods: GET, POST, PATCH, DELETE, OPTIONS

Access-Control-Allow-Origin cannot be * when Allow-Credentials: true. Must be the exact frontend origin.

For Novo, also allow https://novo.market.

---

4. Session Refresh Behavior

The frontend automatically re-checks the session 60 seconds before expiresAt. If the backend supports session extension (sliding expiration), it can re-set the cookie with a fresh Max-Age on every GET /auth/session call.

---

5. Auth Gate — Checkout Flow

The checkout button (POST /cart payment) now requires authentication:

• If the user is not logged in → frontend shows a Telegram login dialog instead of proceeding
• If the user is logged in → checkout proceeds normally
• The session cookie is sent automatically with the payment request

No backend changes needed for the payment endpoint itself — just ensure it reads the session cookie if needed for order association.

---

Summary of New Endpoints

Method	Path	Purpose	Auth Required
GET	/regions	List available regions	No
GET	/auth/session	Check current session	Cookie
GET	/auth/telegram/callback	Telegram bot auth callback	No (from bot)
POST	/auth/logout	End session	Cookie

Summary of Modified Endpoints

Method	Path	Change
GET	/category	Added optional ?region= param
GET	/category/:id	Added optional ?region= param
GET	/item/:id	Added optional ?region= param
GET	/searchitems	Added optional ?region= param
GET	/randomitems	Added optional ?region= param

---

Telegram Bot Setup

Each brand needs its own bot:

• Dexar: @dexarmarket_bot
• Novo: @novomarket_bot

The bot should:

1. Listen for /start auth_{callbackUrl} command
2. Extract the callback URL
3. Send the user's Telegram data (id, first_name, username, etc.) to that callback URL
4. The callback URL is {apiUrl}/auth/telegram/callback