云途物流 & 燕文物流 Shipping

Scope and boundaries

• Do not request Shopify login or use Shopify APIs. This skill operates only against YunExpress and Yanwen APIs.
• Use it for carrier-side work only: checking parcels, orders, channels, warehouses, rates, charges, tracking, labels, and preparing carrier orders. Do not use it to register carrier accounts, manage a Shopify store, fulfill orders automatically, or make customs/address decisions for the merchant.
• Treat carrier account codes and API secrets as secrets. Put each only in a private, ignored yunexpress-shipping.env or yanwen-shipping.env in the user's working directory; never paste them into chat, source files, command history, reports, or Git.
• The supplied OMS specification includes a UAT address and test account. A test credential may return real, accurate quotation results, but it is not a substitute for the merchant's own credentials and must never be embedded, disclosed, or used for creating operational shipments.
• Read operations may run after a connection check. Any operation that creates, changes, cancels, deletes, intercepts, registers/disables IOSS, changes subscriptions, or submits CPSC data needs an explicit user approval immediately before --execute.
• Do not call user registration; direct account creation, frozen-account, product-permission, and billing issues to the relevant carrier.

Onboarding

YunExpress

Ask the merchant to obtain their own credentials:

1. Sign in to YunExpress.
2. Select 专线 (or B2B) in the left navigation.
3. Open API寄件, then select API.
4. Copy 客户代码 and API密钥 into their private yunexpress-shipping.env using init-env below. Set YUNTU_OMS_BASE_URL=http://oms.api.yunexpress.com for production. For UAT, use only the UAT URL supplied by YunExpress with matching UAT credentials.

Run the read-only check before all other work. It validates authentication by loading countries, product methods, goods types, and a quote; it never creates an order.

Yanwen

Ask the merchant to obtain their own Yanwen 制单账号 and secret:

1. Sign in to the Yanwen customer centre.
2. Select 小包专线.
3. Open 账号管理, then 制单账号管理.
4. Select 新增制单账号 and copy the resulting 制单账号 and 密钥 into private yanwen-shipping.env using yanwen_shipping.py init-env. Use https://open.yw56.com.cn/api/order for production or https://open-fat.yw56.com.cn/api/order for Yanwen testing.

Run check before quoting, tracking, or creating a Yanwen order. A Yanwen shipping account can be frozen even when its signature is valid; report the carrier error and direct the merchant to Yanwen sales or support instead of retrying a create request.

Workflow

1. Identify the requested carrier. Read references/yunexpress-api.md for YunExpress or references/yanwen-api.md for Yanwen before preparing the selected operation.
2. Create the private env template, fill it locally, then run check.
3. For a quote, resolve country and shipping methods if needed, then run get quote with dimensions, weight, postal code, package type, and optional services.
4. For tracking or shipment lookup, prefer get order, get tracking, get all-tracking, get tracking-number, or get fee-detail; use post carrier or post label with an identifier-array payload when required.
5. For a shipment or another state change, make a JSON payload file in the user's working directory, run the command without --execute, and show the redacted request plan and validation findings.
6. Ask for a clear confirmation that names the operation and affected order numbers. Only then repeat with --execute.
7. Verify a created or changed waybill with get order; verify tracking changes with the relevant subscription listing. Keep the response RequestId for support, but redact personal data in summaries.

Script entry points

python <absolute-path-to-skill>/scripts/yunexpress_shipping.py init-env --env yunexpress-shipping.env
python <absolute-path-to-skill>/scripts/yunexpress_shipping.py check --env yunexpress-shipping.env
python <absolute-path-to-skill>/scripts/yunexpress_shipping.py get countries --env yunexpress-shipping.env
python <absolute-path-to-skill>/scripts/yunexpress_shipping.py get quote --env yunexpress-shipping.env --query CountryCode=GB Weight=0.125 Length=1 Width=1 Height=1 PackageType=0
python <absolute-path-to-skill>/scripts/yunexpress_shipping.py get order --env yunexpress-shipping.env --query OrderNumber=<waybill-or-order-or-tracking-number>
python <absolute-path-to-skill>/scripts/yunexpress_shipping.py post create-order --env yunexpress-shipping.env --input shipment.json
python <absolute-path-to-skill>/scripts/yunexpress_shipping.py post create-order --env yunexpress-shipping.env --input shipment.json --execute
python <absolute-path-to-skill>/scripts/yanwen_shipping.py init-env --env yanwen-shipping.env
python <absolute-path-to-skill>/scripts/yanwen_shipping.py check --env yanwen-shipping.env
python <absolute-path-to-skill>/scripts/yanwen_shipping.py get channels --env yanwen-shipping.env
python <absolute-path-to-skill>/scripts/yanwen_shipping.py get track --env yanwen-shipping.env --numbers <waybill-or-last-mile-number>
python <absolute-path-to-skill>/scripts/yanwen_shipping.py post create-order --env yanwen-shipping.env --input shipment.json
python <absolute-path-to-skill>/scripts/yanwen_shipping.py post create-order --env yanwen-shipping.env --input shipment.json --execute

Use --help to list all supported operations. post prints a redacted preview for a write until --execute is present. It sends JSON with UTF-8, derives Authorization: Basic from Base64(customer-code & API-secret), and never logs that token.

Output rules

• Quote results: compare service code/name, total fee, currency, billable weight, tracking availability, goods type, and delivery days; label prices as a point-in-time API result.
• Shipment preview: include order count (maximum 10 per create request), destination, selected product code, weight/dimensions, declared goods, optional services, and validation errors. Do not display full street addresses, phone numbers, emails, or credentials in chat.
• Labels: return the temporary label URL and order-level errors; do not automatically download, print, or share it.
• Explain YunExpress non-0000 response codes with references/yunexpress-api.md and Yanwen non-0 response codes with references/yanwen-api.md; escalate account, product-permission, frozen-account, address, or clearance decisions to the merchant or relevant carrier.