Digikala

Digikala Marketplace API Skill

This skill enables Claude to work with the Digikala Marketplace Open API (seller.digikala.com) — Iran's largest e-commerce platform's seller API with 274 endpoints covering product management, categories, orders, shipments, finance, and more.

⚠️ Important Safety Notice

This skill interacts with a LIVE production marketplace. Several operations are state-changing and affect your actual seller account:

Read-only operations (safe to run anytime): search, suggest, be-seller, validate-*, get-*, draft-count, auto-title, get-attributes, tree, ai-check

How It Works

1. Authentication: Provide access token via DIGIKALA_ACCESS_TOKEN env var or ~/.digikala/token file (user-managed)
2. Product Creation Pipeline: Search existing products → validate category/attributes → create draft → upload images → AI image validation → save title → save product → assign to seller
3. Category Navigation: Tree browsing, search by keyword, validation for product creation
4. Image Management: Upload to temp storage → AI quality check → attach to products
5. Scope-Based Access: Each endpoint requires specific scopes (product, order, finance, etc.)

API Reference

Base URL: https://seller.digikala.com/open-api/v1/

Headers Required:

Content-Type: application/json
Authorization: Bearer <access_token>

Rate Limits: 429 response with reset_time header when exceeded

Key Endpoints by Domain

Category (1 endpoint - READ ONLY)

Product (28 endpoints)

Legend: READ = Safe to run | WRITE = Modifies remote data | STATE-CHANGING = Affects live marketplace (scripts prompt for confirmation)

Usage

# Product creation workflow
bash /mnt/skills/user/digikala/scripts/product-create.sh <step> [args]

# Category utilities
bash /mnt/skills/user/digikala/scripts/category.sh <command> [args]

# Image handling
bash /mnt/skills/user/digikala/scripts/image.sh <command> [args]

Script Arguments:

Examples:

# Set token (one time)
export DIGIKALA_ACCESS_TOKEN="your_access_token_here"
# OR: echo "your_access_token_here" > ~/.digikala/token && chmod 600 ~/.digikala/token

# ✅ READ-ONLY: Safe to run anytime
# Search products to sell
bash /mnt/skills/user/digikala/scripts/product-create.sh search "iPhone 15"

# Validate category and get required attributes
bash /mnt/skills/user/digikala/scripts/product-create.sh validate-category 12345

# Upload product image (uploads to Digikala temp storage)
bash /mnt/skills/user/digikala/scripts/image.sh upload-product /path/to/image.jpg

# AI quality check on uploaded image
bash /mnt/skills/user/digikala/scripts/image.sh ai-check "image_id" true

# Save product title (modifies remote data)
bash /mnt/skills/user/digikala/scripts/product-create.sh save-title 123 "گوشی موبایل اپل آیفون 15"

# ⚠️ STATE-CHANGING: These prompt for confirmation before executing
# Save product (CREATES LIVE PRODUCT on marketplace)
bash /mnt/skills/user/digikala/scripts/product-create.sh save-product '{"category_id":123,"draft_product_id":456,...}'

# Assign product to seller (MODIFIES SELLER INVENTORY)
bash /mnt/skills/user/digikala/scripts/product-create.sh assign 789

Output

All scripts output JSON to stdout. Example responses:

Product Search Response:

{
  "status": "ok",
  "data": {
    "items": [
      {
        "id": 12345,
        "name": "iPhone 15 Pro",
        "brand": "Apple",
        "commission": {"canSell": true, "commission": 0.055},
        "referencePrice": 150000000
      }
    ]
  }
}

Present Results to User

When presenting API results to users, format as:

## Digikala API Result: [Operation Name]

**Status**: ✅ Success / ❌ Failed
**Endpoint**: `METHOD /open-api/v1/...`

### Key Data
- **Field**: Value
- **Field**: Value

### Next Steps
1. [Action based on response]
2. [Follow-up if needed]

### Raw Response (if needed)
```json
{...}

## Troubleshooting

| Error | Cause | Solution |
|-------|-------|----------|
| 401 Unauthorized | Invalid/expired token | Update `DIGIKALA_ACCESS_TOKEN` or `~/.digikala/token` |
| 403 Forbidden | Missing scope | Check `/auth/scopes/{client_code}` for available scopes |
| 404 Not Found | Wrong ID or resource doesn't exist | Verify product/category IDs |
| 429 Too Many Requests | Rate limit exceeded | Wait for `reset_time` or implement backoff |
| 500 Server Error | Digikala platform issue | Retry later, contact support if persistent |
| Validation errors | Missing required fields | Check response `errors` object for field-specific messages |

## Important Notes

- **Sandbox Available**: Use `https://github.com/salimousavi/seller_service_sandbox` for development with mock data
- **Persian Content**: Many fields (titles, descriptions, categories) use Persian/Farsi
- **Client Registration**: Must have active client registered with Digikala; contact `Marketplace-API@digikala.com`
- **Scopes Required**: Each endpoint needs specific scope — check `/auth/scopes/{client_code}` for your app's permissions
- **Image URLs**: Temp images expire; use `use_temp_images: true` in product save to reference them
- **Commission Rates**: Vary by category; check `/product-creation/be-seller/{id}` before listing
- **Token Management**: Tokens are NOT stored by scripts. Provide via `DIGIKALA_ACCESS_TOKEN` env var or `~/.digikala/token` file (chmod 600 recommended)