Qoo10 QAPI Management

Overview

This skill provides comprehensive management of the Qoo10 (趣天) e-commerce platform API (QAPI). All Qoo10 operations are pre-built as ready-to-run CLI commands — no coding required. A full CLI tool (scripts/qoo10_api.py), a Python SDK (scripts/qoo10_client.py), and a complete API reference are bundled.

Prerequisites

1. Seller Authorization Key (SAK) — Required for all API calls (except cert operations). Obtain via the interactive setup wizard (recommended) or manually.
   - SAK is valid for 1 year and must be renewed before expiry.
   - The skill automatically tracks SAK issue date and warns when nearing expiry.
2. Python 3.8+ with the requests library installed (pip install requests).
3. Qoo10 Seller Account with API access approved.

Quick Start: account setup (推荐入口)

For new users, the account setup command provides a full interactive wizard that guides you through obtaining your SAK from scratch:

python scripts/qoo10_api.py account setup

The wizard will:
1. Ask for a profile name and target site (JP/INTL/SG)
2. Guide you through entering your Qoo10 login ID, password, and Certification Key
3. Show exactly where to find each piece of information
4. Automatically call CertificationAPI.GetCertificationKey to obtain your SAK
5. Save everything (including cert-key and user-id for future renewal) to your profile

After setup, all commands work without --sak — the saved profile is used automatically.

Getting Your SAK Manually

If you prefer the CLI approach or already have your credentials ready:

# Option A: Provide all fields directly
python scripts/qoo10_api.py cert create-key \
  --user-id YOUR_QSM_LOGIN_ID \
  --pwd YOUR_QSM_PASSWORD \
  --cert-key YOUR_CERTIFICATION_KEY_FROM_QOO10 \
  --profile-name myshop

# Option B: Interactive wizard (omit any field to be prompted)
python scripts/qoo10_api.py cert create-key
# → Will ask for user-id, password, and cert-key interactively

SAK Expiry & Renewal

SAK is valid for 365 days. The skill tracks when each SAK was issued and:
- Auto-warns when SAK is within 35 days of expiry (⏰ warning on every command)
- Blocks with a clear error when SAK has expired (❌ with renewal instructions)

To renew a SAK (using stored cert-key and user-id):

# Renew the current account (just needs password re-entry)
python scripts/qoo10_api.py cert renew

# Renew a specific account
python scripts/qoo10_api.py cert renew --profile myshop

> Note: Passwords are NEVER stored. Renewal requires re-entering the password, but the cert-key and user-id are saved so you don't need to find them again.

Dangerous Operations — Confirmation Required

All operations that modify platform state or delete data require explicit user confirmation before execution. This is enforced at the CLI level.

Destructive (irreversible, high impact)

These operations trigger payment/refund flows or remove data. The agent MUST show the user what will happen and get a "yes" confirmation:

Write operations (reversible but impactful)

These modify live product listings or order workflows. Buyer-visible notifications may be triggered:

Local operations

How confirmation works

$ python qoo10_api.py shipping send --order 12345 --corp Yamato --tracking ABC

  ⚠ WRITE: Register shipping for OrderNo=12345
    Corp: Yamato, Tracking: ABC
    Buyer will receive tracking notification.
  Proceed? [y/N]

For the agent (AI assistant): When executing any of the above commands on behalf of the user, you MUST:
1. Clearly explain what the command will do
2. Show the exact parameters (order number, item code, price, etc.)
3. Wait for explicit user confirmation ("yes", "确认", "OK") before running
4. Use --yes / -y flag only after the user has confirmed

Skip confirmation with -y / --yes:

python qoo10_api.py -y shipping send --order 12345 --corp Yamato --tracking ABC

Non-interactive mode (piped/automated): Dangerous operations are skipped by default unless --yes is provided. This prevents accidental execution in scripts.

How to Use

Step 1: Configure Your Accounts (one-time setup)

Recommended for new users — interactive wizard:

python scripts/qoo10_api.py account setup
# → Guides you through everything: name, site, credentials, SAK generation

For users who already have a SAK:

# Add accounts
python scripts/qoo10_api.py account add shop_japan --sak YOUR_JP_SAK --site JP --note "Japan main shop" --current
python scripts/qoo10_api.py account add shop_intl --sak YOUR_INTL_SAK --site INTL --note "International shop"

# List saved accounts
python scripts/qoo10_api.py account list

# Switch active account
python scripts/qoo10_api.py account use shop_intl

# Show current account (includes SAK validity status)
python scripts/qoo10_api.py account show

Step 2: Run API Commands

After configuring, just run commands — the current profile is used automatically:

# Register a new product (uses current account automatically)
python scripts/qoo10_api.py goods register \
  --title "Wireless Earbuds Pro" --cat 300000113 \
  --image https://example.com/product.jpg --detail "Great sound" \
  --price 4500 --qty 100 --expire 2027-12-31 --ship-no 0 --adult N --tax-rate 10

# List orders requesting shipping (within 90 days!)
python scripts/qoo10_api.py orders list --status 4 --start-date 20260604 --end-date 20260803

# Use a specific profile for one command without switching
python scripts/qoo10_api.py --profile shop_japan orders list --status 4

# Or pass SAK directly (bypasses config)
python scripts/qoo10_api.py --sak YOUR_KEY orders list --status 4

Global options (place before the command name):
- --sak KEY — SAK key directly (highest priority)
- --profile NAME / --use-account NAME — Use a specific saved profile
- --site JP|INTL|SG — Target site (overrides profile site)
- -y / --yes — Skip confirmation prompts for dangerous operations
- --json — Output raw JSON
- --csv FILE — Export list results to CSV
- --verbose — Debug logging

SAK resolution priority: --sak > --profile > current account > QOO10_SAK env var

Full command reference: See references/cli_commands.md for every command with all parameters.

CLI Command Categories

0. account — Multi-Account Management (7 commands)

account setup     🚀 交互式配置向导（推荐新用户首次使用，从零完成授权）
account add       Add or update a saved account profile (name, sak, site, note)
account list      List all saved accounts with masked SAKs
account use       Switch the current active account
account show      Show current account details (includes SAK validity)
account remove    Remove an account
account update    Update an account's sak/site/note

Config file: ~/.qoo10/accounts.json (auto-created, permissions 600)

0.5. cert — SAK 生命周期管理 (2 commands)

cert create-key   获取 SAK（可交互向导，不需要现有 SAK）
cert renew        续期 SAK（使用已保存的 cert-key + user-id，只需重新输入密码）

1. goods — Product Management (ItemsBasic.*, v1.1)

goods register          Register a new product
goods update            Update an existing product
goods get               Get product detail
goods list              List products (filter by status)
goods update-image      Update standard image
goods update-images     Update enlarged images (up to 11)
goods update-addinfo    Update additional attributes

2. price-inventory — Price & Inventory (ItemsBasic.UpdateGoods)

price-inventory set                Update price and/or qty (single)
price-inventory set-bulk           Bulk update (string or CSV file)
price-inventory update-inventory   Update qty only
price-inventory update-status      Update sales status (S0/S1/S2)
price-inventory update-discount    Update discount info

3. options — Inventory Variants (ItemsBasic.*, v1.1)

options list           List inventory options
options add            Add an inventory option
options delete         Delete an inventory option
options update         Update option price/qty
options update-qty     Update option qty only

4. orders — Order Query (ShippingBasic.GetShippingInfo_v3)

orders list            Search orders by shipping status
orders shipping-list   Search shipping info

5. shipping — Shipping & Delivery (ShippingBasic.*)

shipping check         Confirm order (ShippingBasic.SetSellerCheckYN)
shipping send          Register shipping (ShippingBasic.SetSendingInfo)
shipping send-batch    Batch ship from CSV file
shipping complete      Register delivery complete (ShippingBasic.SetSendingComplete)

6. claims — Cancel/Return/Exchange

claims list            Search claims (ShippingBasic.GetClaimInfo)
claims get             Get single claim detail
claims cancel          Process cancel request (Claim.SetCancelProcess)

7. lookup — Reference Data (ItemsBasic.*, v1.1)

lookup categories        Get category list
lookup brands            Search brands by keyword
lookup makers            Search manufacturers by keyword
lookup shipping-groups   Get seller delivery groups

8. batch — Batch Operations

batch sync-orders      Sync all orders from past N days (max 90) across all statuses

9. raw — Direct API Call (for any method not covered)

raw --method ShippingBasic.GetShippingInfo_v3 ShippingStatus=4 SearchCondition=1 SearchStartDate=20260604 SearchEndDate=20260803
raw --http-method POST --method ShippingBasic.SetSendingInfo OrderNo=12345 ShippingCorp=Yamato TrackingNo=1234

Quick Examples (快速示例)

> 📖 每个命令的完整实际示例：详见 references/usage_examples.md

# 🚀 首次使用：交互式配置
python scripts/qoo10_api.py account setup

# 📦 查询配送中订单（90天内）
python scripts/qoo10_api.py orders list --status 4 --start-date 20260604 --end-date 20260803

# 📋 查看商品详情
python scripts/qoo10_api.py goods get --item-code 625522959

# 💰 修改价格和库存
python scripts/qoo10_api.py price-inventory set --item-code 625522959 --price 3500 --qty 50

# 🚚 发货登记
python scripts/qoo10_api.py shipping send --order-no 1200879339 --corp "Yamato Transport" --tracking 665785548766

# 📊 批量发货（CSV）
python scripts/qoo10_api.py shipping send-batch --csv-file shipping.csv

# 📈 批量改价（CSV）
python scripts/qoo10_api.py price-inventory set-bulk --csv-input prices.csv

# 🔄 续期 SAK
python scripts/qoo10_api.py cert renew

# 📤 导出订单到 CSV
python scripts/qoo10_api.py --csv orders.csv orders list --status 4 --start-date 20260604 --end-date 20260803

Key Status Codes Reference

Shipping Status (ShippingBasic.GetShippingInfo_v3)

Item Status (goods)

Tax Rate (since 2024-01-25)

Important: 90-Day Search Limit

Qoo10 enforces a strict 90-day maximum for order/shipping/claim date range queries. The CLI automatically adjusts date ranges that exceed this limit. Always use recent date ranges for order queries.

CSV File Formats

Bulk price update (price-inventory set-bulk --csv-input)

ItemCode,SellPrice,ItemQty
625522959,3500,50
625522960,4200,30

Batch shipping (shipping send-batch --csv-file)

OrderNo,ShippingCorp,TrackingNo
4236887201,Yamato Transport,1234-5678-9012
4236887202,Sagawa Express,9876-5432-1098

API Endpoint & Calling Modes

All Qoo10 QAPI calls use a single REST endpoint:

https://api.qoo10.jp/GMKT.INC.Front.QAPIService/ebayjapan.qapi

Two calling modes

GET mode (default): All parameters including SAK in query string.

GET /ebayjapan.qapi?key=SAK&method=ShippingBasic.GetShippingInfo_v3&v=1.0&returnType=json&ShippingStatus=4&...

POST mode (raw --http-method POST): Method in URL path, SAK in header.

POST /ebayjapan.qapi/ShippingBasic.GetShippingInfo_v3
Headers: GiosisCertificationKey: SAK, QAPIVersion: 1.0
Body: returnType=application/json&ShippingStatus=4&...

Verified API Method Names

All method names below have been verified against the live Qoo10 API:

Response Format

{
  "ResultCode": 0,
  "ResultMsg": "Success",
  "ResultObject": "returned data"
}

• ResultCode: 0 = success
• ResultCode: -10001 = parameter error
• ResultCode: -10002 = date range exceeded 90 days
• ResultCode: -10004 = order number format error

The CLI tool checks ResultCode automatically and reports errors. Use --json for raw output.

Rate Limiting

• Limit: ~100 requests/minute per account
• The CLI auto-retries on HTTP 429 with backoff
• Batch operations maintain 0.5s intervals between calls

Python SDK (Alternative)

For programmatic use, the Python SDK (scripts/qoo10_client.py) provides a Qoo10Client class:

from qoo10_client import Qoo10Client

client = Qoo10Client(sak="YOUR_SAK_KEY")
# Query orders waiting for shipping
result = client.get_shipping_info_list(shipping_status="4", search_start_date="20260604", search_end_date="20260803")
# Ship an order
client.set_sending_info(order_no="12345", shipping_corp="Yamato", tracking_no="TRACK001")
# Generate SAK (static method, no existing SAK needed)
sak = Qoo10Client.get_certification_key(user_id="id", pwd="pass", certification_key="certkey")

Resources

scripts/qoo10_api.py (Primary)

Full CLI tool with all subcommands covering every Qoo10 QAPI operation. Run directly — no coding needed.

scripts/qoo10_client.py (SDK)

Python SDK class for programmatic integration. Importable module with all API methods.

scripts/config.py

Multi-account configuration manager. Stores profiles in ~/.qoo10/accounts.json.

references/api_reference.md

Full API specification with parameter tables for every Qoo10 QAPI method.

references/usage_examples.md

Complete real-world usage examples for every CLI command, including multi-step workflows and common scenarios.

references/cli_commands.md

CLI command reference with parameter tables and dangerous operation warnings.

Official Documentation

• QAPI Guide: https://api.qoo10.jp/GMKT.INC.Front.QAPIService/Document/QAPIGuideIndex.aspx
• API Help: http://api.qoo10.jp/GMKT.INC.Front.OpenApiService/APIList/guideindex.aspx