docs: add comprehensive createCardsList() guide and fix common validation errors

salacoste · claude · salacoste · commit aefb50dc09fa · 2025-12-28T03:25:45.000+03:00
Added new guide to prevent user confusion with createCardsList() pagination. ## Added - **New Guide**: Working with Product Cards (`docs/guides/working-with-product-cards.md`) - Complete createCardsList() usage with 8+ code examples - First request vs pagination explained in detail - Common Mistakes section (empty cursor fields, missing settings wrapper) - Comprehensive troubleshooting for validation errors - All filtering options documented with examples - Best practices for rate limiting and error handling ## Changed - **Troubleshooting Guide**: Added Issue 13a for createCardsList() validation errors - **Method Reference**: Updated Products table with correct createCardsList() method - **Product Catalog Examples**: Fixed all code to use correct API methods - **Guides Index**: Added Working with Product Cards to navigation ## Fixed - Removed references to non-existent getAllProducts() and listProducts() helpers - Corrected pagination examples to use proper cursor structure - Documented that empty updatedAt/nmID cause validation failures - Clarified settings wrapper requirement in all examples Resolves common user issue where empty cursor fields cause "Validation failed" errors. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,46 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+#### Documentation
+- **NEW: Working with Product Cards Guide** (`docs/guides/working-with-product-cards.md`)
+  - Complete guide to `createCardsList()` method with cursor pagination
+  - First request vs pagination requests explained with examples
+  - All filtering options documented (photos, brands, tags, categories)
+  - Common mistakes section preventing validation errors
+  - Comprehensive troubleshooting with real-world solutions
+  - Complete pagination example with rate limiting
+  - Response structure documentation with TypeScript types
+  - 8 code examples covering all use cases
+- **Troubleshooting Updates** (`docs/guides/troubleshooting.md`)
+  - New Issue 13a: `createCardsList()` validation errors (most common issue)
+  - Updated Method Reference table with correct `createCardsList()` method
+  - Quick reference links to detailed product cards guide
+- **Example Updates** (`docs/examples/use-cases/product-catalog.md`)
+  - Fixed all examples to use correct `createCardsList()` API
+  - Removed references to non-existent `getAllProducts()` helper
+  - Added proper pagination implementation in all examples
+  - Cross-reference to detailed product cards guide
+
+### Changed
+
+#### Documentation Structure
+- **Guides Index** - Added "Working with Product Cards" to Product Management section
+- **Method Reference** - Corrected product listing method name from `listProducts()`/`getAllProducts()` to `createCardsList()`
+
+### Fixed
+
+#### User Confusion Prevention
+- **Common Validation Error**: Documented that empty `updatedAt: ""` and `nmID: 0` cause validation failures
+- **Cursor Structure**: Clarified first request (only `limit`) vs pagination (with `updatedAt`/`nmID`)
+- **Settings Wrapper**: Highlighted requirement to wrap all parameters in `settings` object
+- **Limit Maximum**: Documented 1000 max limit with 100 recommended
+
+---
+
 ## [2.4.0] - 2025-12-25
 
 ### ⚠️ CRITICAL - Wildberries API Deprecation Notice
diff --git a/docs/examples/use-cases/product-catalog.md b/docs/examples/use-cases/product-catalog.md
@@ -6,6 +6,8 @@ Synchronize your product catalog with Wildberries.
 
 This use case demonstrates how to manage your product catalog on Wildberries, including listing products, updating information, and syncing with external systems.
 
+> **📖 For detailed guide on fetching product cards, see [Working with Product Cards Guide](/guides/working-with-product-cards)**
+
 ## Get All Products
 
 ```typescript
@@ -15,15 +17,38 @@ const sdk = new WildberriesSDK({
   apiKey: process.env.WB_API_KEY!
 });
 
-// Get all products using the helper method (handles pagination automatically)
+// Get all products with pagination
 async function getAllProducts() {
-  const products = await sdk.products.getAllProducts({
-    locale: 'ru',
-    withPhoto: 1  // Include photo URLs
-  });
+  const allCards = [];
+  let cursor: any = { limit: 100 };
+
+  while (true) {
+    const response = await sdk.products.createCardsList({
+      settings: {
+        filter: { withPhoto: -1 },  // All cards
+        cursor
+      }
+    }, { locale: 'ru' });
+
+    if (response.cards) {
+      allCards.push(...response.cards);
+    }
+
+    if ((response.cards?.length ?? 0) < 100 || !response.cursor?.updatedAt) {
+      break;
+    }
 
-  console.log(`Total products: ${products.length}`);
-  return products;
+    cursor = {
+      limit: 100,
+      updatedAt: response.cursor.updatedAt,
+      nmID: response.cursor.nmID
+    };
+
+    await new Promise(resolve => setTimeout(resolve, 650));
+  }
+
+  console.log(`Total products: ${allCards.length}`);
+  return allCards;
 }
 
 const products = await getAllProducts();
@@ -32,21 +57,19 @@ const products = await getAllProducts();
 ## Get Products with Filtering
 
 ```typescript
-// Get products with specific settings
+// Get products with specific filters
 async function getProductsFiltered() {
-  const response = await sdk.products.listProducts({
-    limit: 100,
-    offset: 0,
-    locale: 'ru',
-    withPhoto: 1
-  });
-
-  // Filter by specific criteria
-  const activeProducts = response.cards?.filter(
-    card => card.nmID && !card.trash
-  );
+  const response = await sdk.products.createCardsList({
+    settings: {
+      filter: {
+        withPhoto: 1,  // Only with photos
+        brands: ['MyBrand']
+      },
+      cursor: { limit: 100 }
+    }
+  }, { locale: 'ru' });
 
-  return activeProducts;
+  return response.cards ?? [];
 }
 ```
 
@@ -117,8 +140,8 @@ interface ExternalProduct {
 }
 
 async function syncFromExternalSystem(externalProducts: ExternalProduct[]) {
-  // 1. Get existing WB products
-  const wbProducts = await sdk.products.getAllProducts({ locale: 'ru' });
+  // 1. Get existing WB products (using getAllProducts helper from above)
+  const wbProducts = await getAllProducts();
 
   // 2. Create lookup map
   const wbProductMap = new Map(
@@ -176,11 +199,8 @@ interface CatalogExport {
 }
 
 async function exportCatalog(): Promise<CatalogExport[]> {
-  // Get all products
-  const products = await sdk.products.getAllProducts({
-    locale: 'ru',
-    withPhoto: 1
-  });
+  // Get all products (using getAllProducts helper from above)
+  const products = await getAllProducts();
 
   // Get stock levels
   const stocks = await sdk.reports.getStocks(
@@ -219,7 +239,8 @@ writeFileSync('catalog.json', JSON.stringify(catalog, null, 2));
 
 ```typescript
 async function checkProductHealth() {
-  const products = await sdk.products.getAllProducts({ locale: 'ru' });
+  // Get all products (using getAllProducts helper from above)
+  const products = await getAllProducts();
   const stocks = await sdk.reports.getStocks(
     new Date().toISOString().split('T')[0]
   );
@@ -263,6 +284,7 @@ async function checkProductHealth() {
 
 ## Related Materials
 
+- **[Working with Product Cards Guide](/guides/working-with-product-cards)** - Complete guide to `createCardsList()` with troubleshooting
 - [API Reference: ProductsModule](/api/classes/ProductsModule)
 - [Pricing Updates](pricing-updates.md)
 - [Stock Management](stock-management.md)
diff --git a/docs/guides/index.md b/docs/guides/index.md
@@ -20,6 +20,7 @@ In-depth guides for production deployment and advanced SDK usage.
 ## Module Guides
 
 ### Product Management
+- **[Working with Product Cards](/guides/working-with-product-cards)** - Complete guide to fetching, filtering, and paginating product cards
 - **[Product Card Merging & Analytics](/guides/product-card-merging)** - Merged cards (склейки), advertising traffic distribution, and cross-variant analytics
 
 ### Advertising & Marketing
diff --git a/docs/guides/troubleshooting.md b/docs/guides/troubleshooting.md
@@ -41,6 +41,7 @@ Quick solutions for common Wildberries SDK issues. This guide helps you diagnose
 - [Rate limit exceeded](#issue-6-429-too-many-requests)
 - [Connection timeout](#issue-11-etimedout)
 - [Validation error](#issue-13-validation-error)
+- [**createCardsList() validation errors**](#issue-13a-createcardslist-validation-errors--common-issue) ⭐ **NEW**
 - [Module not found](#issue-17-module-not-found)
 
 ---
@@ -53,10 +54,11 @@ Quick lookup table for common operations and their actual SDK methods. Copy thes
 
 ### Products & Catalog
 
+> **📖 For detailed guide on product cards, see [Working with Product Cards](/guides/working-with-product-cards)**
+
 | Operation | Actual SDK Method | Notes |
 |-----------|-------------------|-------|
-| List all products | `sdk.products.listProducts(filters?)` | Returns first page only (up to 100 products). Use `getAllProducts()` for automatic pagination |
-| Get all products | `sdk.products.getAllProducts(filters?, options?)` | Automatically paginates through all products. Use for large catalogs (10,000+ products) |
+| List product cards | `sdk.products.createCardsList({ settings })` | **Main method** - Returns cards with cursor pagination. See [detailed guide](/guides/working-with-product-cards) |
 | Create new product | `sdk.products.createProduct(data)` | Single product creation |
 | Update product | `sdk.products.updateProduct(data[])` | Accepts array of updates |
 | Delete product | `sdk.products.deleteProduct(nmIDs[])` | Permanently removes products |
@@ -1135,6 +1137,134 @@ Field: categoryId - Must be a valid category ID
 
 ---
 
+### Issue 13a: createCardsList() Validation Errors ⚠️ COMMON ISSUE
+
+> **📖 For complete troubleshooting guide, see [Working with Product Cards](/guides/working-with-product-cards#troubleshooting)**
+
+**Error Message:**
+```
+ValidationError: Validation failed
+```
+
+**Cause:** Incorrect request structure for `createCardsList()` method.
+
+**What Went Wrong:**
+
+This is **the most common mistake** with `createCardsList()`:
+
+❌ **Mistake 1: Empty cursor fields in first request**
+```typescript
+// ❌ WRONG - Causes validation error
+await sdk.products.createCardsList({
+  settings: {
+    cursor: {
+      limit: 100,
+      updatedAt: "",  // Empty string causes validation error!
+      nmID: 0         // Zero causes validation error!
+    }
+  }
+});
+```
+
+❌ **Mistake 2: Missing `settings` wrapper**
+```typescript
+// ❌ WRONG - Missing settings wrapper
+await sdk.products.createCardsList({
+  cursor: { limit: 100 },
+  filter: { withPhoto: -1 }
+});
+```
+
+❌ **Mistake 3: Limit exceeds maximum**
+```typescript
+// ❌ WRONG - Max limit is 1000
+await sdk.products.createCardsList({
+  settings: {
+    cursor: { limit: 5000 }
+  }
+});
+```
+
+**Solution:**
+
+**For FIRST request:**
+```typescript
+// ✅ CORRECT - Only include limit
+const response = await sdk.products.createCardsList({
+  settings: {
+    cursor: {
+      limit: 100  // ONLY limit, omit updatedAt and nmID
+    },
+    filter: {
+      withPhoto: -1  // -1 = all cards
+    }
+  }
+});
+```
+
+**For PAGINATION requests:**
+```typescript
+// ✅ CORRECT - Copy cursor from previous response
+const nextResponse = await sdk.products.createCardsList({
+  settings: {
+    cursor: {
+      limit: 100,
+      updatedAt: response.cursor.updatedAt,  // From previous response
+      nmID: response.cursor.nmID              // From previous response
+    },
+    filter: {
+      withPhoto: -1
+    }
+  }
+});
+```
+
+**Complete Working Example:**
+```typescript
+async function getAllCards() {
+  const allCards = [];
+  let cursor: any = { limit: 100 };  // Start with only limit
+
+  while (true) {
+    const response = await sdk.products.createCardsList({
+      settings: {
+        filter: { withPhoto: -1 },
+        cursor
+      }
+    });
+
+    if (response.cards) {
+      allCards.push(...response.cards);
+    }
+
+    // Check if more data available
+    if ((response.cards?.length ?? 0) < 100 || !response.cursor?.updatedAt) {
+      break;
+    }
+
+    // Update cursor for next request
+    cursor = {
+      limit: 100,
+      updatedAt: response.cursor.updatedAt,
+      nmID: response.cursor.nmID
+    };
+
+    await new Promise(resolve => setTimeout(resolve, 650));
+  }
+
+  return allCards;
+}
+```
+
+**How to Prevent:**
+- ✅ First request: Only `limit` in cursor
+- ✅ Pagination: Copy `updatedAt` and `nmID` from response
+- ✅ Always wrap in `settings` object
+- ✅ Use `limit: 100` (max 1000)
+- ✅ See [Complete Guide](/guides/working-with-product-cards) for all details
+
+---
+
 ### Issue 14: Missing Required Field
 
 **Error Message:**
diff --git a/docs/guides/working-with-product-cards.md b/docs/guides/working-with-product-cards.md
