\r \r

Colipu 科力普采购助手\r

\r Enterprise B2B procurement API client for Colipu (科力普).\r Covers the full procurement lifecycle: product lookup, ordering, logistics, billing, and after-sales.\r \r

Prerequisites\r

\r

1. Get API credentials: Contact [email protected] for business cooperation and account setup.\r \r
2. Environment variables (required before first use):\r
   • COLIPU_USERNAME — API account username\r
   • COLIPU_PASSWORD — API account password\r
   • COLIPU_BASE_URL — optional, defaults to https://api.ucip.colipu.com/cip\r
   • COLIPU_TOKEN_FILE — optional, token cache file path (used only when persistence is enabled)\r
   • COLIPU_TOKEN_PERSIST — optional, defaults to 0; set to 1 to enable token disk persistence\r \r
3. Python with requests available in the current environment.\r \r
4. Token is auto-fetched and kept in memory by default (12 h TTL, auto-refresh).\r To persist token on disk, explicitly set both COLIPU_TOKEN_PERSIST=1 and COLIPU_TOKEN_FILE=/secure/path/colipu_token.json.\r Avoid storing token files in shared, synced, or backed-up workspace directories.\r \r

Core Rules\r

\r

1. Never fabricate data — always call the API; never guess prices, stock, or order status.\r
2. Never use web_search as a substitute for API data.\r
3. Ask for missing params — if SKU, order ID, or date range is missing, ask the user before calling.\r
4. SKU format — alphanumeric, case-sensitive, use lowercase (e.g. 2h1075, 1049204).\r
5. All commands run via: python scripts/colipu_client.py \x3Ccommand> [args]\r
6. On any API error: show errormsg to the user and suggest a corrective action.\r \r

Task Router\r

\r Match user intent to the command below, then execute.\r \r

Product\r

\r | Intent | Command | Required Args |\r |--------|---------|---------------|\r | Browse categories | categories | — |\r | Product detail | product-detail | --sku SKU |\r | Check price | product-price | --skus SKU1,SKU2 |\r | Check stock | product-stock | --skus SKU1 --area CODE |\r \r

• Area code format: 省编号_市编号_区编号, use * for all regions.\r
• --customer-code is optional on price/stock queries.\r \r

Order\r

\r | Intent | Command | Required Args |\r |--------|---------|---------------|\r | Place order | order-submit | --data order.json or --json '{...}' |\r | Confirm order | order-confirm | --order-id ID |\r | Cancel order | order-cancel | --order-id ID |\r | Query order detail | order-info | --order-id ID |\r | Query order status | order-state | --order-id ID |\r | Confirm receipt | order-signconfirm | --order-id ID |\r \r

Logistics\r

\r | Intent | Command | Required Args |\r |--------|---------|---------------|\r | Track by order | logistics | --order-id ID |\r | Track by delivery | delivery-logistics | --delivery-code CODE |\r \r

Billing & Invoice\r

\r | Intent | Command | Required Args |\r |--------|---------|---------------|\r | Reconciliation | bill-reconciliation | --start-date YYYY-MM-DD --end-date YYYY-MM-DD |\r | Apply for settlement | bill-apply | --data bill.json |\r \r

After-sales\r

\r | Intent | Command | Required Args |\r |--------|---------|---------------|\r | Apply return/exchange | aftersale-apply | --data return.json |\r | Query return status | aftersale-info | --apply-code CODE |\r | Cancel return | aftersale-cancel | --apply-code CODE |\r \r

Messages\r

\r | Intent | Command | Required Args |\r |--------|---------|---------------|\r | Get messages | messages | --type 302,303 |\r | Delete messages | message-delete | --ids ID1,ID2 |\r \r Message type codes: 202=price change, 203=stock change, 204=on/off shelf,\r 205=product change, 206=product pool change, 302=order status, 303=return status,\r 304=return audit, 700=bill audit, 701=bill invoice, 801=order split.\r \r

Workflow: Product Inquiry\r

\r

1. User gives SKU → product-detail --sku \x3Csku> for full info.\r
2. User wants price → product-price --skus \x3Csku1,sku2> returns 协议价/商城价/市场价.\r
3. User wants stock → product-stock --skus \x3Csku> --area \x3Ccode>.\r
4. User gives keyword only → categories first, then look up SKUs within a category\r (see category/{id}/skus in references/product.md).\r \r

Workflow: Order Lifecycle\r

\r

Submit ──→ Confirm ──→ Ship ──→ Deliver ──→ Sign receipt\r
  │           │                                  │\r
  └→ Cancel   └→ Revoke                 Reconcile / Invoice\r
                                                 │\r
                                         After-sales return\r
```\r
\r
1. **Submit**: Build order JSON (required: `yggc_order`, `name`, province/city/county,\r
   `address`, `phone`/`mobile`, `payment`, `order_price`, `freight`, `sku` array).\r
   See [references/order.md](references/order.md) for full field spec.\r
   Run `order-submit --data order.json`.\r
2. **Confirm**: `order-confirm --order-id \x3Cid>` — supports whole-order or partial confirm.\r
3. **Track**: `order-state --order-id \x3Cid>` for status code; `logistics --order-id \x3Cid>` for tracking.\r
4. **Cancel** (before shipping only): `order-cancel --order-id \x3Cid>`.\r
5. **Sign receipt**: `order-signconfirm --order-id \x3Cid>`.\r
\r
Order status codes: `0`=新建, `1`=签收, `-1`=拒收, `-2`=取消, `5`=发货, `3`=审批通过, `-3`=审批不通过.\r
\r
## Workflow: After-sales Return\r
\r
1. Build return JSON: `order_id` (required), `skus` array (`sku`/`num`/`price`),\r
   `apply_type` (`4`=退货, `5`=换货, `6`=维修, `7`=退款).\r
2. Submit: `aftersale-apply --data return.json`.\r
3. Track: `aftersale-info --apply-code \x3Ccode>`.\r
4. Cancel if needed: `aftersale-cancel --apply-code \x3Ccode>`.\r
\r
Return audit status: `0`=待审核, `1`=审核通过, `2`=客户取消, `3`=客服取消, `4`=审核不通过.\r
\r
## Error Handling\r
\r
All responses follow: `{success, errorcode, errormsg, requestId, result}`.\r
\r
| Code | Meaning | Suggested Action |\r
|------|---------|------------------|\r
| 0 | Success | Proceed normally |\r
| 5001 | Token expired | Client auto-refreshes; retry once |\r
| 5003 | Refresh token expired | Re-authenticate (client handles this) |\r
| 5004 | No data found | Tell user "no results found" |\r
| 5005 | Invalid params | Verify and correct parameters |\r
| 2060 | Duplicate order | Use a different order number |\r
| 2061 | Order not found | Verify order ID with user |\r
| 2062 | Order already confirmed | Inform user, no action needed |\r
| 2063 | Order already cancelled | Inform user, no action needed |\r
| 2065 | Submitting too fast | Wait briefly, then retry |\r
\r
## Output Format\r
\r
Present API results to users in a clear structured format:\r
\r
- **Product**: Name / SKU / Price (协议价 · 商城价 · 市场价) / Stock / Brand / Unit\r
- **Order**: Order ID / Status / Total amount / SKU list / Receiver / Address\r
- **Logistics**: Carrier / Tracking number / Latest event / Full timeline\r
- **Billing**: Order ID / Status / Create date / Signed amount per SKU\r
- **Return**: Apply code / Audit status / Type / Reason / SKU details\r
\r
## Auth Mechanism\r
\r
Token = `MD5(username + password + timestamp + password)` lowercase hex.\r
Timestamp format: `yyyyMMdd`. TTL: 12 hours.\r
Header on all requests (except token fetch): `Colipu-Token: {access_token}`.\r
\r
The client script handles auth automatically — no manual token management needed.\r
\r
## Troubleshooting\r
\r
| Symptom | Cause | Fix |\r
|---------|-------|-----|\r
| `Error: set COLIPU_USERNAME and COLIPU_PASSWORD env vars` | Env vars not configured | Set both env vars before running |\r
| `Failed to get token: ...` | Wrong credentials or network issue | Verify username/password; check connectivity |\r
| `{"success": false, "errorcode": "-1", ...}` | Network timeout or connection refused | Check internet; retry after a moment |\r
| Token file corrupt / garbled | Previous write interrupted | Delete `.data/colipu_token.json` and retry; client will re-authenticate |\r
| Price / stock returns empty | SKU doesn't exist or wrong case | SKUs are case-sensitive — use lowercase |\r
\r
## Detailed API Reference\r
\r
For full request/response schemas and examples, read the reference files:\r
\r
- Auth & token: [references/auth.md](references/auth.md)\r
- Product & categories: [references/product.md](references/product.md)\r
- Order lifecycle: [references/order.md](references/order.md)\r
- Billing & invoices: [references/billing.md](references/billing.md)\r
- After-sales returns: [references/aftersale.md](references/aftersale.md)\r
- Logistics tracking: [references/logistics.md](references/logistics.md)\r
- Message subscription: [references/message.md](references/message.md)\r