Frequently Asked Questions (FAQ)

Quick Navigation: Getting Started | Authentication | API Usage | Error Handling | Rate Limiting | Advanced | Troubleshooting

---

Getting Started

1. How do I install the Wildberries SDK?

Install via npm:

npm install daytona-wildberries-typescript-sdk

For TypeScript projects, ensure you have TypeScript ≥5.0 installed:

npm install --save-dev typescript@^5.0.0

See also: Quickstart Guide

---

2. What are the minimum requirements to use the SDK?

• Node.js: 18.x, 20.x, or 22.x LTS
• TypeScript: 5.0+ (for TypeScript projects)
• Wildberries API Key: Required for authentication

Compatibility: Works with both ESM and CommonJS module systems.

---

3. How do I get a Wildberries API key?

1. Log in to your Wildberries Seller account
2. Navigate to Settings → API Access
3. Generate a new API key with required permissions
4. Copy and securely store your API key

⚠️ Security: Never commit API keys to version control. Use environment variables or secure vaults.

See also: Authentication Guide

---

4. How do I initialize the SDK?

import { WildberriesSDK } from 'daytona-wildberries-typescript-sdk';

const sdk = new WildberriesSDK({
  apiKey: process.env.WB_API_KEY // or your API key
});

// Test connection
const ping = await sdk.general.ping();
console.log(ping); // { Status: 'OK', TS: '2024-12-03T15:22:47Z' }

Best Practice: Store API keys in environment variables, not source code.

See also: Quickstart Guide

---

5. Can I use the SDK with JavaScript (without TypeScript)?

Yes! The SDK works with plain JavaScript:

const { WildberriesSDK } = require('daytona-wildberries-typescript-sdk');

const sdk = new WildberriesSDK({
  apiKey: process.env.WB_API_KEY
});

Note: You'll lose TypeScript autocomplete and type safety, but all functionality works.

---

Authentication & Configuration

6. How do I configure custom timeouts?

Global timeout — applies to all requests:

const sdk = new WildberriesSDK({
  apiKey: process.env.WB_API_KEY,
  timeout: 60000 // 60 seconds (default: 30000)
});

Per-request timeout — the SDK's BaseClient supports per-request timeout via RequestOptions. Module methods use the global timeout by default. For operations that may take longer, increase the global timeout:

// For long-running operations, use a higher global timeout
const sdkWithLongTimeout = new WildberriesSDK({
  apiKey: process.env.WB_API_KEY,
  timeout: 120000 // 2 minutes for slow report generation
});

// Quick health check uses the default timeout
const ping = await sdk.general.ping();

Each retry attempt uses the configured timeout individually (not cumulative).

See also: Configuration Guide — Timeout Configuration

---

7. Can I override base URLs for different environments?

Yes, you can override base URLs per module:

const sdk = new WildberriesSDK({
  apiKey: process.env.WB_API_KEY,
  baseUrls: {
    products: 'https://staging-content-api.wildberries.ru',
    ordersFBS: 'https://staging-marketplace-api.wildberries.ru'
  }
});

Use Case: Testing with sandbox/staging environments.

---

8. How do I configure retry logic?

const sdk = new WildberriesSDK({
  apiKey: process.env.WB_API_KEY,
  retryConfig: {
    maxRetries: 5,          // Default: 3
    retryDelay: 2000,       // Default: 1000ms
    exponentialBackoff: true // Default: true
  }
});

See also: Error Handling Guide

---

9. How do I enable debug logging?

const sdk = new WildberriesSDK({
  apiKey: process.env.WB_API_KEY,
  logLevel: 'debug' // 'debug' | 'info' | 'warn' | 'error'
});

Production: Use 'warn' or 'error' to reduce noise.

See also: Troubleshooting Guide

---

10. Can I use multiple API keys for different modules?

No, the SDK uses a single API key for all modules. If you need multiple accounts, create separate SDK instances:

const sellerAccount1 = new WildberriesSDK({ apiKey: KEY_1 });
const sellerAccount2 = new WildberriesSDK({ apiKey: KEY_2 });

---

API Usage

11. How do I fetch product categories?

const categories = await sdk.products.getParentAll();
console.log(categories.data); // Array of category objects

See also: Product Management Example

---

12. How do I create a new product?

import type { CreateProductRequest } from 'daytona-wildberries-typescript-sdk';

const newProduct: CreateProductRequest = {
  brandName: 'MyBrand',
  categoryId: '12345',
  title: 'Product Name',
  description: 'Product description',
  characteristics: [
    { id: 'size', value: 'L' },
    { id: 'color', value: 'Red' }
  ]
};

const result = await sdk.products.createCardsUpload(newProduct);
console.log(result.nmId); // New product ID

Note: Product creation has strict rate limits (1 request per 10 seconds).

See also: Complete Product Workflow

---

13. How do I fetch new orders (FBS)?

const result = await sdk.ordersFBS.getOrdersNew();

for (const order of result.orders ?? []) {
  console.log(`Order ${order.id}: article ${order.article}, nmId ${order.nmId}`);
}

See also: Order Fulfillment Example

---

14. How do I check order statuses?

const result = await sdk.ordersFBS.getOrderStatuses({ orders: [12345, 67890] });

result.orders?.forEach(order => {
  console.log(`Order ${order.id}: ${order.supplierStatus} / ${order.wbStatus}`);
});

Supplier statuses: new → confirm → complete (or cancel)

See also: Order Status Workflow

---

15. How do I check my account balance?

const balance = await sdk.finances.getAccountBalance();
console.log(`Current balance: ${balance.amount} RUB`);

See also: Financial Operations Example

---

16. How do I fetch sales analytics?

// v3 Sales Funnel API (SDK v2.7.0+)
const result = await sdk.analytics.getSalesFunnelProducts({
  selectedPeriod: { start: '2026-01-01', end: '2026-01-31' },
  orderBy: { field: 'orderCount', mode: 'desc' },
  limit: 10,
  offset: 0,
});

result.products?.forEach(p => {
  console.log(`Product ${p.product.nmId}: ${p.statistic.selected.orderCount} orders`);
});

Note: Prior to v2.7.0, the SDK used createNmReportDetail() which called the v2 endpoint. That endpoint now returns 404. See the Analytics v3 Migration Guide for details.

See also: Analytics Dashboard Tutorial

---

17. How do I generate and download reports?

Reports use an async pattern (request → poll → download). Here is an example using the warehouse remains report:

// Step 1: Request report generation
const task = await sdk.reports.warehouseRemains({
  groupByBrand: true,
  groupBySubject: true
});
const taskId = task.data?.taskId;

// Step 2: Poll for completion
let status = await sdk.reports.getWarehouseRemainsTaskStatus(taskId);
while (status.data?.status === 'new') {
  await new Promise(resolve => setTimeout(resolve, 5000)); // Wait 5s
  status = await sdk.reports.getWarehouseRemainsTaskStatus(taskId);
}

// Step 3: Download completed report
if (status.data?.status === 'done') {
  const data = await sdk.reports.downloadWarehouseRemainsReport(taskId);
  console.log(data); // Array of warehouse remain items
}

See also: Reports Example

---

18. How do I work with customer communications (reviews, Q&A)?

// Fetch unanswered questions
const questions = await sdk.communications.questions({
  isAnswered: false,
  take: 10,
  skip: 0
});

// Answer a question
await sdk.communications.updateQuestion({
  id: '12345',
  answer: { text: 'Thank you for your question...' },
  state: 'wbRu'
});

// Fetch reviews
const reviews = await sdk.communications.feedbacks({
  isAnswered: false,
  take: 10,
  skip: 0
});

See also: Customer Engagement Example

---

19. Can I use the SDK with async/await or Promises?

Yes, all SDK methods return Promises and work with async/await:

// Async/await (recommended)
const balance = await sdk.finances.getAccountBalance();

// Promise chains
sdk.finances.getAccountBalance()
  .then(balance => console.log(balance))
  .catch(error => console.error(error));

---

20. How do I handle pagination?

Different APIs use different pagination methods:

Cursor-based (products):

const products = await sdk.products.getCardsList({
  settings: {
    cursor: { limit: 100 },
    sort: { ascending: false }
  }
});

console.log(`Total: ${products.cursor?.total}`);

Cursor-based:

const result = await sdk.ordersFBS.orders({
  limit: 100,
  next: previousResponse.next ?? 0 // From previous response
});

See also: Pagination Patterns

---

Error Handling

21. How do I handle errors in the SDK?

Use TypeScript error classes with instanceof:

import {
  AuthenticationError,
  RateLimitError,
  ValidationError,
  NetworkError
} from 'daytona-wildberries-typescript-sdk';

try {
  await sdk.products.createCardsUpload(data);
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key:', error.message);
  } else if (error instanceof ValidationError) {
    console.error('Invalid data:', error.fieldErrors);
  } else if (error instanceof RateLimitError) {
    console.error(`Rate limited. Retry after ${error.retryAfter}ms`);
  } else if (error instanceof NetworkError) {
    console.error('Network error:', error.message);
  }
}

See also: Error Handling Guide

---

22. What does "AuthenticationError: Invalid API key" mean?

Causes:

• API key is incorrect or expired
• API key doesn't have required permissions
• API key is not properly formatted

Solutions:

1. Verify API key in Wildberries Seller portal
2. Check environment variables are loaded correctly
3. Ensure API key has required scopes
4. Regenerate API key if expired

See also: Authentication Troubleshooting

---

23. How do I debug "ValidationError: Missing required field"?

Check the fieldErrors property for specific field issues:

try {
  await sdk.products.createCardsUpload(data);
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Field errors:', error.fieldErrors);
    // Example: { brandName: 'Required field missing' }
  }
}

See also: Validation Error Guide

---

24. What happens when I hit rate limits?

The SDK automatically handles rate limits:

1. Detection: SDK detects 429 response
2. Wait: Automatically waits for retry period
3. Retry: Retries request after delay
4. Throw: If max retries exceeded, throws RateLimitError

Manual Handling:

try {
  await sdk.products.createCardsUpload(data);
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(`Wait ${error.retryAfter}ms before retrying`);
  }
}

See also: Rate Limiting Guide

---

Rate Limiting & Performance

25. What are the rate limits for different APIs?

Rate limits vary by endpoint:

API Module	Typical Limit	Notes
Products (create)	1 req/10s	Strictest limit
Products (read)	3 req/min	Category queries
Orders	5 req/min	FBS/FBW order fetching
Finances	10 req/min	Balance, transactions
Analytics	5 req/min	Performance queries
Reports (CSV export)	1 req/2min	Large data exports

See also: Performance Guide

---

26. How can I optimize SDK performance?

Best Practices:

1. Batch Operations: Group multiple operations where possible
2. Caching: Cache frequently accessed data (categories, tariffs)
3. Pagination: Use appropriate page sizes (50-100 items)
4. Concurrent Requests: Use Promise.all() for independent calls
5. Connection Pooling: Reuse SDK instance across requests

Example:

// ❌ Bad: Sequential requests
const categories = await sdk.products.getParentAll();
const balance = await sdk.finances.getAccountBalance();

// ✅ Good: Parallel requests
const [categories, balance] = await Promise.all([
  sdk.products.getParentAll(),
  sdk.finances.getAccountBalance()
]);

See also: Performance Tuning Guide

---

27. Does the SDK support connection pooling?

Yes, the SDK reuses HTTP connections automatically via Axios's built-in connection pooling. Simply reuse the same SDK instance:

// ✅ Good: Reuse instance
const sdk = new WildberriesSDK({ apiKey });

for (const orderId of orderIds) {
  await sdk.ordersFBS.updateOrdersCancel(orderId);
}

// ❌ Bad: Creating new instance per request
for (const orderId of orderIds) {
  const sdk = new WildberriesSDK({ apiKey }); // Don't do this!
  await sdk.ordersFBS.updateOrdersCancel(orderId);
}

---

Advanced Topics

28. Can I use the SDK in serverless environments (AWS Lambda, Vercel)?

Yes! The SDK works in serverless environments:

// AWS Lambda handler
export const handler = async (event) => {
  const sdk = new WildberriesSDK({
    apiKey: process.env.WB_API_KEY,
    timeout: 25000 // Lambda timeout - 5s buffer
  });

  const orders = await sdk.ordersFBS.getOrdersNew();
  return { statusCode: 200, body: JSON.stringify(orders) };
};

Tip: Warm up connections by initializing SDK outside handler for better performance.

---

29. How do I mock the SDK for testing?

Use dependency injection and mock the SDK instance:

// jest.mock() or Vitest mock
import { vi } from 'vitest';

const mockSDK = {
  products: {
    getCardsList: vi.fn().mockResolvedValue({ data: [], total: 0 })
  }
};

// In your test
const result = await mockSDK.products.getCardsList();
expect(result.data).toEqual([]);

See also: Testing Best Practices

---

30. Can I extend the SDK with custom functionality?

Yes, you can extend modules or wrap the SDK:

class CustomProductsService {
  constructor(private sdk: WildberriesSDK) {}

  async createProductWithRetry(data: CreateProductRequest, maxAttempts = 3) {
    for (let i = 0; i < maxAttempts; i++) {
      try {
        return await this.sdk.products.createCardsUpload(data);
      } catch (error) {
        if (i === maxAttempts - 1) throw error;
        await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)));
      }
    }
  }
}

---

31. How do I handle webhook events from Wildberries?

The SDK doesn't include webhook handling (it's HTTP request-based). For webhooks, use a web framework:

import express from 'express';

const app = express();

app.post('/webhooks/wildberries', async (req, res) => {
  const event = req.body;

  // Verify webhook signature (implement based on WB docs)
  // Process event
  if (event.type === 'order.created') {
    const sdk = new WildberriesSDK({ apiKey: process.env.WB_API_KEY });
    // Process the new order - check statuses, add to supply, etc.
    const result = await sdk.ordersFBS.getOrderStatuses({ orders: [event.orderId] });
  }

  res.status(200).send('OK');
});

---

Troubleshooting

32. Why am I getting "Network timeout" or ETIMEDOUT errors?

Causes:

• Slow network connection
• Wildberries API experiencing high load
• Timeout configured too low (default is 30 seconds)

Solutions:

1. Increase global timeout:

   const sdk = new WildberriesSDK({
     apiKey: process.env.WB_API_KEY,
     timeout: 60000 // 60 seconds
   });

2. Create a separate SDK instance for slow operations:

   const sdkSlow = new WildberriesSDK({
     apiKey: process.env.WB_API_KEY,
     timeout: 120000 // 2 minutes for slow report calls
   });
   const report = await sdkSlow.analytics.getNmReportDownloads();

3. Enable info-level logging to see retry attempts:

   const sdk = new WildberriesSDK({
     apiKey: process.env.WB_API_KEY,
     logLevel: 'info' // Shows retry attempts and timeout warnings
   });

4. Check network connectivity

5. Retry with exponential backoff (SDK handles this automatically)

See also: Configuration Guide — Timeout Configuration | Network Errors

---

33. My requests are very slow. How can I diagnose the issue?

Enable debug logging to see request/response timing:

const sdk = new WildberriesSDK({
  apiKey: process.env.WB_API_KEY,
  logLevel: 'debug'
});

await sdk.products.getCardsList(); // Check console for timing logs

Common Causes:

• Rate limiting (SDK waiting for slots)
• Large response payloads
• Network latency
• Server-side processing time

See also: Performance Diagnostics

---

34. How do I report bugs or request features?

1. Check existing issues: GitHub Issues
2. Create new issue: Use issue templates
3. Provide details:
   • SDK version
   • Node.js version
   • Code snippet reproducing issue
   • Error messages and stack traces

See also: Contributing Guide

---

35. Where can I find complete code examples?

• Examples Directory: examples/
• Quickstart: getting-started/quickstart.md
• Integration Examples:
  • Product CRUD
  • Order Fulfillment
  • Financial Operations
  • Customer Communications

---

Additional Resources

• Quickstart Guide - Get started in 5 minutes
• API Reference - Complete TypeDoc documentation
• Best Practices - Production-ready patterns
• Troubleshooting Guide - Common issues and solutions
• Performance Guide - Optimization techniques
• Glossary - Wildberries and SDK terminology

---

Need more help?

• 📖 Documentation
• 🐛 Report an Issue
• 💬 Discussions