Перейти к основному содержимому

Subtask 1-3: Research - Authentication, Rate Limits, and Model Descriptions

Overview​

This document summarizes research findings from official Yandex Market Partner API documentation regarding authentication methods, rate limits, and business model descriptions (FBY/FBS/DBS/Express).

Research Date: 2025-02-10 Sources: Official Yandex Market Partner API Documentation

1. Authentication​

Current Status (2025)​

API-Key is the RECOMMENDED and CURRENT authentication method

According to official Yandex Market documentation:

"Чтобы работать с Маркетом по API, нужно получить API-Key-токен. Мы не рекомендуем использовать OAuth-токен, так как этот способ авторизации устарел."

Translation: "To work with Market through API, you need to obtain an API-Key token. We do not recommend using OAuth-token, as this authorization method is deprecated."

Authentication Methods Comparison​

FeatureAPI-Key (Recommended)OAuth (Deprecated)
BindingBound to the cabinet where token was createdBound to the user who created the token
How to GetIn the seller cabinet on MarketVia OAuth application
Access to ShopsAll shops in the cabinetOnly shops the user has access to
Granular Access Control✅ Yes - can restrict to specific method groups❌ No
HeaderApi-KeyAuthorization
Token LifetimeUnlimited1 year
Status✅ Current (2025)❌ Deprecated since Oct 2024

How to Transmit API-Key​

Header: Api-Key

Example:

Api-Key: your-api-key-here

Migration Timeline​

  • October 2024: Yandex Market switched from OAuth 2.0 to API-Key based authorization
  • 2025: OAuth is considered deprecated; all new integrations should use API-Key

2. Rate Limits​

Types of Limits​

According to official limits documentation, there are three types of rate limits:

A. Global Limits (Глобальные ограничения)​

  • Limit: Maximum 2 parallel requests per login
  • Response on Exceed: HTTP 420 Enhance Your Calm
  • Message: "Hit rate limit of 2 parallel requests"

B. Resource Limits (Ресурсные ограничения)​

  • Scope: Limits on request volume to the same resource over a prolonged period (e.g., daily)
  • Calculation: Based on:
    • Number of requests (for most resources)
    • Total data transferred/returned (for some resources, calculated individually per shop/partner)
  • Recalculation: With a delay of 2-8 hours
  • Response Headers:
    • X-RateLimit-Resource-Limit: Numeric limit value
    • X-RateLimit-Resource-Until: Date until limit applies (RFC822 format)
    • X-RateLimit-Resource-Remaining: Remaining request volume
  • Response on Exceed: HTTP 420 Enhance Your Calm with message like: 
    Hit rate limit of 10 000 points per 1 day for resource /regions/{regionId}.json

C. Functional Limits (Функциональные ограничения)​

  • Scope: Limits on data transmitted or returned per single request
  • Common Limit: Maximum request body size = 512 KB
  • Response on Exceed: HTTP 400 Bad Request

Specific Limits Known​

Based on web research and official docs:

Resource TypeLimit
Products per minuteUp to 100,000 products per minute (updated March 1, 2024)
Products per requestMaximum 500 products per single request
Daily requests (FBS/FBY/Express)Up to 100,000 requests per day
Affiliate Network APINot exceed 5 requests per second

Best Practices​

  1. Plan batch calls and task queues
  2. Implement retry logic (exponential backoff)
  3. Monitor headers (X-RateLimit-*) to track quota usage
  4. Split large requests if body exceeds 512 KB
  5. Use monitoring dashboards for synchronization tracking

3. Business Models (FBY, FBS, DBS, Express)​

Model Overview​

Yandex Market supports four main fulfillment models. Some API methods work across all models, while others are model-specific.

3.1 FBY (Fulfillment by Yandex)​

Description: Yandex Market handles most of the work: stores products, assembles orders, packages them, and delivers to customers.

Key Features:

  • Full logistics management by Yandex
  • Maximum convenience for sellers
  • Quick growth potential
  • Minimum routine work
  • Seller focuses on product selection and marketing

API Method Categories for FBY:

  • Campaigns & Shops (Basic)
  • Offers Management
  • Stocks & Turnover (READ-ONLY - Yandex manages stock)
  • Prices
  • Orders (READ-ONLY view)
  • Returns
  • Reports (includes FBY-specific reports)
  • Yandex Warehouses

FBY-Specific Methods:

  • GET warehouses - Returns list of Yandex Market warehouses with IDs
  • POST reports/goods-movement/generate - Goods movement report (FBY only)
  • POST reports/goods-turnover/generate - Turnover report (FBY only)
  • POST reports/goods-realization/generate - Realization report

Stocks: Managed by Yandex (read-only via API)

3.2 FBS (Fulfillment by Seller)​

Description: Seller stores goods themselves, but delivery is handled through Yandex's partners.

Key Features:

  • Balance between costs and control
  • Seller maintains inventory control
  • Yandex handles delivery logistics
  • Potentially higher product ranking in search results

API Method Categories for FBS:

  • Campaigns & Shops (Basic)
  • Offers Management
  • Stocks & Turnover (READ/WRITE - seller manages stock)
  • Prices
  • Orders (full lifecycle management)
  • Returns
  • FBS Shipments (extensive shipment management)
  • FBS Labels
  • Geography (regions)

FBS-Specific Methods:

  • All Shipment management methods:
    • GET campaigns/{campaignId}/first-mile/shipments/{shipmentId} - Shipment info
    • PUT campaigns/{campaignId}/first-mile/shipments - Shipments list
    • POST campaigns/{campaignId}/first-mile/shipments/{shipmentId}/confirm - Confirm shipment
    • PUT campaigns/{campaignId}/first-mile/shipments/{shipmentId}/pallets - Pallet count
    • GET campaigns/{campaignId}/first-mile/shipments/{shipmentId}/pallet/labels - Pallet labels
    • GET campaigns/{campaignId}/first-mile/shipments/{shipmentId}/act - Transfer act
    • GET campaigns/{campaignId}/first-mile/shipments/{shipmentId}/transportation-waybill - Waybill
    • GET campaigns/{campaignId}/first-mile/shipments/{shipmentId}/discrepancy-act - Discrepancy act
  • Order box management:
    • PUT campaigns/{campaignId}/orders/{orderId}/boxes - Box layout + marking codes

Stocks: Fully managed by seller (read/write via API)

3.3 Express (Экспресс)​

Description: Fast delivery model with delivery times of 1-2 days.

Key Features:

  • Priority fast delivery
  • Enhanced customer experience
  • Competitive advantage for time-sensitive products

API Method Categories for Express:

  • Campaigns & Shops
  • Offers Management
  • Stocks & Turnover (READ/WRITE)
  • Prices
  • Orders (full lifecycle management)
  • Labels (FBS/DBS labels)
  • Returns
  • Reports
  • Quality Index
  • Warehouses

Express-Specific Aspects:

  • Similar to FBS but optimized for ultra-fast delivery
  • Warehouse status management:
    • POST campaigns/{campaignId}/warehouse/status - Change warehouse status
  • Order preparation with EAC confirmation:
    • PUT campaigns/{campaignId}/orders/{orderId}/verifyEac - Submit confirmation code

Stocks: Managed by seller (read/write via API)

3.4 DBS (Delivery by Seller)​

Description: Seller handles all aspects including storage, packaging, and direct delivery to the customer.

Key Features:

  • Maximum control over the entire process
  • Seller delivers directly to the customer
  • Higher operational requirements for the seller
  • Suitable for sellers with established logistics

API Method Categories for DBS:

  • Campaigns & Shops
  • Offers Management
  • Stocks & Turnover (READ/WRITE)
  • Prices
  • Orders (extensive management including delivery)
  • DBS Labels
  • DBS Delivery (outlet management)
  • Returns
  • Reports
  • Quality Index
  • Product Models
  • Directories

DBS-Specific Methods:

  • Outlets (Points of Sale) Management:
    • GET campaigns/{campaignId}/outlets/{outletId} - Outlet info
    • GET campaigns/{campaignId}/outlets - List outlets
    • POST campaigns/{campaignId}/outlets - Create outlet
    • PUT campaigns/{campaignId}/outlets/{outletId} - Update outlet
    • DELETE campaigns/{campaignId}/outlets/{outletId} - Delete outlet
    • GET campaigns/{campaignId}/outlets/licenses - License info
    • POST campaigns/{campaignId}/outlets/licenses - Create/update licenses
    • DELETE campaigns/{campaignId}/outlets/licenses - Delete licenses
  • Advanced Order Management:
    • PUT campaigns/{campaignId}/orders/{orderId}/identifiers - Marking codes
    • PUT campaigns/{campaignId}/orders/{orderId}/delivery/shipments/{shipmentId}/boxes - Box count
    • PUT campaigns/{campaignId}/orders/{orderId}/items - Remove items/reduce quantity
    • POST campaigns/{campaignId}/orders/{orderId}/delivery/track - Submit tracking number
    • PUT campaigns/{campaignId}/orders/{orderId}/delivery/date - Change delivery date
    • PUT campaigns/{campaignId}/orders/{orderId}/delivery/storage-limit - Extend storage
    • GET campaigns/{campaignId}/orders/{orderId}/buyer - Buyer info (individual)
    • PUT campaigns/{campaignId}/orders/{orderId}/cancellation/accept - Accept cancellation
    • POST campaigns/{campaignId}/orders/{orderId}/deliverDigitalGoods - Digital goods keys
  • Return Decisions:
    • POST campaigns/{campaignId}/orders/{orderId}/returns/{returnId}/decision - Make decision
    • POST campaigns/{campaignId}/orders/{orderId}/returns/{returnId}/decision/submit - Confirm decision
  • Product Models:
    • GET models/{modelId} - Model info
    • POST models - Multiple models info
    • GET models/{modelId}/offers - Offers for model
    • POST models/offers - Offers for multiple models
    • GET models - Search models

Stocks: Fully managed by seller (read/write via API)

4. Method Availability by Model​

Common Methods (All Models: FBY, FBS, Express, DBS)​

Campaigns & Shops:

  • GET campaigns - List of shops
  • GET campaigns/{campaignId} - Shop information
  • GET campaigns/{campaignId}/settings - Shop settings

Offers:

  • POST campaigns/{campaignId}/offers/update - Update offer parameters
  • POST campaigns/{campaignId}/offers - View offers
  • POST campaigns/{campaignId}/offers/delete - Delete offers
  • GET campaigns/{campaignId}/hidden-offers - View hidden offers
  • POST campaigns/{campaignId}/hidden-offers - Hide offers
  • POST campaigns/{campaignId}/hidden-offers/delete - Show hidden offers

Prices:

  • POST campaigns/{campaignId}/offer-prices/updates - Set prices
  • POST campaigns/{campaignId}/offer-prices - View prices
  • POST campaigns/{campaignId}/price-quarantine - View quarantine
  • POST campaigns/{campaignId}/price-quarantine/confirm - Confirm quarantine

Orders (Basic):

  • GET campaigns/{campaignId}/orders - List orders
  • GET campaigns/{campaignId}/orders/{orderId} - Order details
  • POST campaigns/{campaignId}/orders/{orderId}/business-buyer - Legal entity buyer info
  • POST campaigns/{campaignId}/orders/{orderId}/documents - Documents info

Returns:

  • GET campaigns/{campaignId}/returns - Returns list
  • GET campaigns/{campaignId}/orders/{orderId}/returns/{returnId} - Return details
  • GET campaigns/{campaignId}/orders/{orderId}/returns/{returnId}/application - Return application
  • GET campaigns/{campaignId}/orders/{orderId}/returns/{returnId}/decision/{itemId}/image/{imageHash} - Return photos

Reports:

  • POST campaigns/{campaignId}/stats/orders - Orders report
  • POST campaigns/{campaignId}/stats/skus - Products report

Directories:

  • GET delivery/services - Delivery services directory

Model-Specific Methods​

Method/FeatureFBYFBSExpressDBS
Stocks (Write)❌✅✅✅
Order Status Change❌✅✅✅
Order Box Layout❌✅✅✅
FBS Shipments❌✅❌❌
Warehouse Status❌❌✅❌
EAC Confirmation❌❌✅❌
Outlets Management❌❌❌✅
Delivery Management❌❌❌✅
Return Decisions❌❌❌✅
Product Models❌❌❌✅
FBY Reports✅❌❌❌
Yandex Warehouses✅❌❌❌

5. Key Takeaways for Documentation​

  1. Authentication:

    • Use API-Key (OAuth is deprecated)
    • Header: Api-Key
    • Unlimited lifetime, granular access control

  2. Rate Limits:

    • Global: 2 parallel requests max
    • Resource-based limits vary by endpoint
    • Functional limit: 512 KB max request body
    • Monitor X-RateLimit-* headers

  3. Models:

    • FBY: Yandex fulfills everything (logistics by Yandex)
    • FBS: Seller stores, Yandex delivers
    • Express: Ultra-fast delivery (1-2 days)
    • DBS: Seller does everything (full control)

  4. Method Selection:

    • Check model-specific method lists before implementation
    • Some resources work at cabinet level (all models)
    • Some resources require campaignId (model-specific)

Sources​

Official Documentation​

Additional Resources​

Document Status: ✅ Complete Next Steps: Use this research to create comprehensive Russian markdown documentation (Subtask 2-1)