### API Error Response Example (JSON) Source: https://dev.wildberries.ru/openapi/api-information An example of a typical error response from the Wildberries API. This JSON structure includes details about the error, such as the title, a detailed message, status code, status text, and timestamp. ```json { "title": "path not found", "detail": "Please consult the https://dev.wildberries.ru/openapi/api-information", "status": 404, "statusText": "Not Found", "timestamp": "2025-04-24T07:25:28Z" } ``` -------------------------------- ### API Connectivity Check Example (curl) Source: https://dev.wildberries.ru/openapi/api-information This snippet demonstrates how to check API connectivity using curl. It requires a valid API token for authentication. The output indicates successful or failed connection. ```shell curl -X GET "https://api.wildberries.ru/general/health" \ -H "Authorization: Bearer YOUR_API_TOKEN" ``` -------------------------------- ### Getting seller portal news /api/communications/v2/news Source: https://dev.wildberries.ru/openapi/api-information This endpoint allows you to retrieve news from the seller portal. You need to specify either the 'from' or 'fromID' parameter to get news. A maximum of 100 news items can be retrieved per request. ```APIDOC ## GET /api/communications/v2/news ### Description Retrieves news from the seller portal. Requires either the 'from' or 'fromID' parameter. Allows fetching up to 100 news items per request. ### Method GET ### Endpoint `https://common-api.wildberries.ru/api/communications/v2/news` ### Parameters #### Query Parameters - **from** (string) - Optional - Date from which to get news (e.g., `from=2025-02-06`). - **fromID** (integer) - Optional - The news ID, starting from which (including it) you need to get the list of news (e.g., `fromID=7369`). ### Request Example ``` GET https://common-api.wildberries.ru/api/communications/v2/news?from=2025-02-06 GET https://common-api.wildberries.ru/api/communications/v2/news?fromID=7369 ``` ### Response #### Success Response (200) This endpoint returns a list of news items. The exact structure of a news item is not detailed in the provided text, but it is expected to be a JSON array of objects. #### Response Example (Example not provided in source text) #### Error Responses - **400** Bad request - **401** Unauthorized - **429** Too many requests ``` -------------------------------- ### Token Creation and Management Source: https://dev.wildberries.ru/openapi/api-information Detailed steps on how to generate an API token from your seller account, including selecting the appropriate scope (Test/Read only) and API categories. ```APIDOC ## Token Creation Steps ### Description Follow these steps to create a new API token for your Wildberries seller account. ### Method N/A (UI-driven process) ### Endpoint N/A (UI-driven process) ### Parameters N/A (UI-driven process) ### Request Example N/A ### Response N/A ### Process 1. Navigate to your seller account profile. 2. Select 'Settings' -> 'API Integrations'. 3. Choose the desired scope: - **Test scope (Sandbox)**: For testing purposes only. - **Read only**: For read-only access to real and test data. 4. Select specific API categories you intend to use (e.g., Content, Analytics, Marketplace). 5. Click 'Create a token'. 6. Copy and securely store the generated token. Tokens cannot be viewed after creation; generate a new one if lost. **Note:** Create separate tokens for different services to manage access and security effectively. ``` -------------------------------- ### Rate Limits Source: https://dev.wildberries.ru/openapi/api-information The WB API employs a token bucket algorithm for rate limiting to ensure even load distribution. Specific limits for API methods are detailed within their respective documentation. ```APIDOC ## Rate Limits The WB API has request rate limits implemented using the `token bucket` algorithm. ### General Limits (Marketplace Category Example) | Period | Limit | Interval | Burst | |----------|---------------|--------------------|--------------| | 1 minute | 300 requests | 200 milliseconds | 20 requests | **Note:** A request resulting in a `409` response code counts as 5 requests. ### Parameter Definitions: * **Period**: The time interval during which the maximum number of requests can be sent. * **Limit**: The maximum number of requests allowed per period. Requests should be evenly distributed. * **Interval**: The recommended time gap between requests to ensure even distribution (e.g., `60 seconds / 300 requests = 200 milliseconds`). * **Burst**: The maximum number of requests that can be sent simultaneously without interval pauses. This is also indicated by the `X-Ratelimit-Remaining` header. ### Response Headers: * `X-Ratelimit-Remaining` (integer): The number of requests that can currently be sent without pauses. Decreases by one per request. A value of `0` without a delay will result in a `429` error. * `X-Ratelimit-Retry` (integer): The number of seconds to wait before retrying a request after a `429` error. * `X-Ratelimit-Limit` (integer): The maximum allowable burst of requests. * `X-Ratelimit-Reset` (integer): The number of seconds after which the allowable burst of requests will be restored to the maximum value. ### Error Codes: * **429 Too Many Requests**: Indicates that the request rate limit has been exceeded. Use `X-Ratelimit-Retry` to determine wait time. ``` -------------------------------- ### General API Information Source: https://dev.wildberries.ru/openapi/api-information Provides general information about the API, including authorization, rate limits, error codes, and connectivity checks. ```APIDOC ## General API Information ### Description This section covers general API details such as authorization mechanisms, rate limiting policies, common error responses, and methods for checking API connectivity. It also provides access to seller portal news and seller information. ### Method N/A (Informational) ### Endpoint N/A (Informational) ### Parameters N/A ### Request Example N/A ### Response N/A ## HTTP Status Codes ### Description This table outlines the main HTTP status codes used in the Wildberries API responses, their descriptions, and guidance on how to resolve issues. ### Status Codes - **200** (Success) - Request was successful. - **204** (Deleted/Updated/Confirmed) - Indicates a successful deletion, update, or confirmation. - **400** (Bad Request) - The request syntax is incorrect. Check the request syntax. - **401** (Unauthorized) - Check the authorization token. Ensure the token is valid, not expired, not missing, and its category matches the API category. - **403** (Access Denied) - The token must be generated by an active user, and access to the method must not be blocked. Check your subscription for Jam methods. - **404** (Not Found) - The requested URL was not found. Check the request URL. - **409** (Status Update Error/Error Adding Label/etc.) - Check the request data. It must meet service requirements and limitations. - **413** (Request Body Too Large) - The request body size exceeds the given limit. Reduce the number of objects in the request. - **422** (Error Processing Request Parameters/Unexpected Result/etc.) - Check the request data. The data must not contradict itself. - **429** (Too Many Requests) - Rate limits for the method have been exceeded. Retry the request later. - **5XX** (Internal Service Error) - The service is unavailable. Retry the request later or contact support. **Note**: Pay attention to the `details` field in `404` and `429` errors for more specific information. ### Error Example ```json { "title": "path not found", "detail": "Please consult the https://dev.wildberries.ru/openapi/api-information", "status": 404, "statusText": "Not Found", "timestamp": "2025-04-24T07:25:28Z" } ``` ``` -------------------------------- ### Understanding API Token Properties Source: https://dev.wildberries.ru/openapi/api-information An explanation of the JWT token structure and its public fields, including their types and meanings, as well as the interpretation of the 's' (bitmask) field. ```APIDOC ## API Token Structure and Fields ### Description Wildberries API tokens are JWTs (JSON Web Tokens) conforming to RFC 7519. This section details the public fields within the token and the meaning of the `s` field (bitmask). ### Method N/A ### Endpoint N/A ### Parameters N/A ### Request Example N/A ### Response N/A ### Public Token Fields | Field | Type | Description | |--------|--------|---------------------------------------------------| | **id** | UUIDv4 | Unique token identifier. | | **s** | uint | Token properties bitmask. | | **sid**| UUIDv4 | Wildberries seller ID. | | **exp**| uint | Token lifetime (Unix timestamp), complies with RFC 7519. | | **t** | boolean| Indicates if the token is for test scope (sandbox). | ### The `s` Field (Bitmask) The `s` field is an integer where each bit represents a specific permission or access right. **Bit Values:** | Bit Position | Property (if bit is 1) | |--------------|-------------------------------| | 1 | Access to **Content** | | 2 | Access to **Analytics** | | 3 | Access to **Prices and discounts** | | 4 | Access to **Marketplace** | | 5 | Access to **Statistics** | | 6 | Access to **Promotion** | | 7 | Access to **Feedbacks and Questions** | | 9 | Access to **Buyers chat** | | 10 | Access to **Supplies** | | 11 | Access to **Buyers returns** | | 12 | Access to **Documents** | | 13 | Access to **Finance** | | 30 | Read only token | ``` -------------------------------- ### Token Decoding and Validation Source: https://dev.wildberries.ru/openapi/api-information Information on how to decode your API token to verify its validity and the API methods accessible with it. ```APIDOC ## Token Decoding ### Description Token decoding allows you to verify the validity of your API token and determine which API method categories are accessible with it. It is recommended to avoid using online decoding tools to prevent token interception. ### Method N/A (Separate page/tool provided) ### Endpoint N/A ### Parameters N/A ### Request Example N/A ### Response N/A ### Process Access the dedicated token decoding page provided by Wildberries to input your token and review its details. This process confirms the token's validity and lists the permissions granted by its associated bitmask. ``` -------------------------------- ### Authorization Source: https://dev.wildberries.ru/openapi/api-information Authentication for the WB API is handled via an API token, valid for 180 days. This token must be included in the `Authorization` request header. ```APIDOC ## Authorization ### Authentication Method Requests to the WB API must be authenticated using an API token. ### Token Validity API tokens are valid for 180 days from their creation date. ### Request Header Include the API token in the `Authorization` request header: ``` Authorization: Bearer YOUR_API_TOKEN ``` ### Integration Restriction Integration with the seller portal without using the public API is prohibited, as per clause 9.9.6 of the offer. ``` -------------------------------- ### Understanding Rate Limit Headers in HTTP Responses Source: https://dev.wildberries.ru/openapi/api-information This snippet illustrates the typical HTTP response headers related to API rate limiting. It shows headers that indicate remaining requests, retry intervals, the request limit, and when the limit resets. These headers are crucial for managing API call frequency and avoiding errors. ```http HTTP/1.1 429 Too Many Requests ... X-Ratelimit-Reset: 29 X-Ratelimit-Retry: 2 ... X-Ratelimit-Limit: 10 ``` -------------------------------- ### Connection Check /ping Source: https://dev.wildberries.ru/openapi/api-information This endpoint checks the connection to the Wildberries API, validates the authorization token and request URL, and ensures the token category matches the service. It is not intended for checking service availability. ```APIDOC ## GET /ping ### Description Checks if the request successfully reaches the WB API, verifies the validity of the authorization token and request URL, and ensures the token category matches the service. This method is not intended to check the availability of WB services. ### Method GET ### Endpoint `https://common-api.wildberries.ru/ping` ### Parameters This endpoint does not have any path, query, or request body parameters. ### Request Example This endpoint does not require a request body. ### Response #### Success Response (200) - **TS** (string) - Timestamp of the response. - **Status** (string) - Status of the connection check, typically 'OK'. #### Response Example ```json { "TS": "2024-08-16T11:19:05+03:00", "Status": "OK" } ``` #### Error Responses - **401** Unauthorized - **429** Too many requests ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.