Digikala

Integrate with Digikala Marketplace API to authenticate sellers, manage products, upload images, search categories, handle orders, and automate seller workfl...

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:

Operation	Impact	Confirmation Required
save-product	Creates/updates live product visible to customers	✅ Yes (script prompts)
assign	Adds product to your seller inventory	✅ Yes (script prompts)
brand-request	Submits brand registration for manual review	✅ Yes (script prompts)
save-title	Updates product title on marketplace	⚠️ Review before running
upload-*	Uploads images to Digikala servers	⚠️ Review files before upload

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:

text

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)

Method	Endpoint	Description
GET	/categories/tree	Get category tree (filter by parent_id)

Product (28 endpoints)

Method	Endpoint	Type	Description
GET	/product-creation/search/v2	READ	Search existing products by keyword/filters
GET	/product-creation/search/suggestion/v2	READ	Suggest products to sell
GET	/product-creation/be-seller/{product_id}	READ	Check if can sell a product, get commission
GET	/product-creation/search/category/v2/{keyword}	READ	Find categories by keyword
GET	/product-creation/category/{category_id}/validation	READ	Validate category & get required attributes
POST	/product-creation/product/detail/validation	READ	Validate product details
GET	/product-creation/draft-product/count	READ	Count draft products
GET	/product-creation/draft-product/{id}	READ	Get draft product details
GET	/product-creation/{id}/auto-title	READ	Get AI title suggestion
POST	/product-creation/auto-title/save	WRITE	Save/validate title
GET	/product-creation/attributes/{category_id}	READ	Get category attributes
POST	/product-creation/attributes	READ	Validate attributes
POST	/product-creation/images/upload	WRITE	Upload product image to temp
POST	/product-creation/images/requests/upload	WRITE	Upload content request image
POST	/product-creation/images/requests/brand-logo/upload	WRITE	Upload brand logo
POST	/product-creation/images/ai	READ	AI image quality check
POST	/product-creation/save	STATE-CHANGING	Save/create LIVE product
POST	/product-creation/assign	STATE-CHANGING	Assign product to seller
POST	/product-creation/brand/request	STATE-CHANGING	Request new brand

---

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

Usage

bash

# 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:

Script	Commands	Description
product-create.sh	search, validate-category, save-title, save-product, assign, brand-request	Full product pipeline
category.sh	tree, search, validate	Category navigation
image.sh	upload-product, upload-request, upload-brand, ai-check	Image operations

Examples:

bash

# 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:

json

{
  "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:

text

## 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
{...}

text

## 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 `[e-mail]`
- **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)