1688 Procurement Workflow

This skill helps LinkFox users run authorized 1688 procurement: OAuth status checks, SKU and address lookup, order preview, guarded order creation, payment URL retrieval, order tracking, logistics, cancellation, receipt confirmation, and post-completion invoicing.

Use

linkfox-1688-search-by-image

for image-based product discovery. This skill does not include image search.

Core Rules

Every script requires LinkFox platform identity from
```
LINKFOX_AGENT_API_KEY
```
or
```
LINKFOXAGENT_API_KEY
```
.
```
authorize_url.py
```
starts 1688 OAuth;
```
authorized_stores.py
```
checks the current LinkFox user's 1688 OAuth state.
Except those two authorization scripts, every procurement operation runs a script-level
```
authorizedStores
```
precheck before calling the target endpoint.
If no store has
```
status=ACTIVE
```
and
```
expired=false
```
, the target endpoint is not called.
After authorization is valid, procurement tools may be used independently as the user requests; the workflow is guidance, not a mandatory linear script. Image search remains in
```
linkfox-1688-search-by-image
```
.
Treat the workflow as a map, not full automation. Do not create orders, get payment URLs, cancel orders, confirm receipt, or apply for invoices based on earlier phrases like "continue".
Use exact internal request field names from
```
references/api.md
```
when calling scripts. Do not show these field names in normal user-facing text.
Treat ordinary 1688 procurement as the only user-facing procurement mode. Apply backend defaults internally per
```
references/api.md
```
; do not mention procurement type or ask users to choose one.
```
cancel_order.py
```
only attempts to cancel a 1688 order. It is not a refund or after-sales request. For paid orders, including paid-but-unshipped orders, do not call cancellation as a workaround; tell the user this Skill has no refund-application tool and refunds/after-sales must be handled on 1688 unless the backend adds that ability.
MCP enable/disable only controls MCP exposure. These scripts call tool-gateway HTTP routes directly; fully disabling a capability requires disabling the route or backend operation.

Read

references/api.md

for endpoint details and

references/workflow.md

before multi-step procurement.

Tools

Script	Risk	OAuth precheck	Purpose
`authorize_url.py`	Low	No	Generate a 1688 authorization link
`authorized_stores.py`	Low	No	Check current user's authorized 1688 accounts
`receive_address_list.py`	Low	Yes	Query receive addresses
`sku.py`	Low	Yes	Query product SKU/specification data
`order_preview.py`	Medium	Yes	Preview order price, freight, SKU, and address
`create_order.py`	High	Yes	Create a 1688 order
`payment_url.py`	High	Yes	Get payment URL
`order_status.py`	Low	Yes	Query order status
`logistics.py`	Low	Yes	Query logistics summary
`logistics_trace.py`	Low	Yes	Query logistics trace
`confirm_receive.py`	High	Yes	Confirm receipt
`cancel_order.py`	High	Yes	Cancel order
`invoice_amount.py`	Low	Yes	Query invoiceable amount before applying for an invoice
`invoice_apply.py`	High	Yes	Apply for an invoice after order completion

调用方式

API 端点：

POST /alibaba1688/{authorizeUrl|authorizedStores|receiveAddressList|sku|orderPreview|createOrder|paymentUrl|orderStatus|logistics|logisticsTrace|confirmReceive|cancelOrder|invoiceAmount|invoiceApply}

（完整参数、响应和错误处理见

references/api.md

）

Python 脚本：

python scripts/<script_name>.py '<JSON 参数>' [--inline] [--save] [--no-save]

Windows 推荐：

$env:PAYLOAD = '<JSON 参数>'

后运行

python scripts/<script_name>.py --payload-env PAYLOAD [--inline] [--save]

成本约束：本工具会消耗积分。失败、空结果、参数不完整或授权不足时，不得自动连续试探、换参数重试或轮询；需要继续查询时先向用户说明会产生额外消耗。
缓存约束：本采购 Skill 不做 24h 响应缓存；授权、价格、库存、订单状态和物流以实时返回为准，高风险写操作更不能缓存。
授权约束：除
```
authorize_url.py
```
和
```
authorized_stores.py
```
外，脚本会在调用目标接口前自动检查当前用户的 ACTIVE 1688 授权；没有 ACTIVE 且未过期授权时不会调用目标 endpoint。
授权刷新：accessToken 临期或已过期时后端会用该用户自己的 refreshToken 自动刷新，调用
```
authorizedStores
```
或采购接口时都会触发，Skill 与用户无需介入。只有 refreshToken 为空、失效或刷新失败（
```
authorizedStores
```
返回
```
expired=true
```
）时才需要重新走
```
authorize_url.py
```
授权；不要向用户展示或播报 token 有效期、过期时间、刷新窗口等内部授权细节。
高风险约束：
```
create_order.py
```
、
```
payment_url.py
```
、
```
confirm_receive.py
```
、
```
cancel_order.py
```
、
```
invoice_apply.py
```
必须在用户用中文自然语言单独明确确认后调用。内部确认字段和请求细节只供 Agent 调脚本使用，不要展示给用户。

powershell

$env:PAYLOAD = "{}"
python scripts/authorized_stores.py --payload-env PAYLOAD --inline

脚本入参方式：

直接传 JSON 字符串：

python scripts/sku.py '{"offerId":"..."}'

从环境变量读取：

python scripts/sku.py --payload-env PAYLOAD

从文件读取：

python scripts/sku.py --payload-file payload.json

加
```
--inline
```
强制全量打印到 stdout
加
```
--save
```
强制保存对 token 类敏感字段脱敏
加
```
--no-save
```
禁止保存响应文件

输出策略（脚本默认行为）：

响应体 ≤ 8 KB：默认不落盘，直接把完整脱敏 JSON 打印到 stdout，避免每次查询都在 Skill 目录生成数据文件。

响应体 > 8 KB：默认将完整脱敏响应写入

<writable-root>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-1688-procurement-<operation>-<timestamp>.json

，stdout 只输出摘要。

```
<writable-root>
```
优先取
```
ACPX_WORKSPACES
```
的第一个工作区，其次为脚本执行时的当前目录，最后回退到用户目录；
```
<session>
```
取自环境变量
```
SESSION_ID
```
，未提供时自动生成；禁止写入
```
/tmp
```
。

加

--save

或设置

LINKFOX_SKILL_SAVE_RESPONSE=1

强制保存；加

--no-save

或设置

LINKFOX_SKILL_NO_SAVE=1

禁止保存；

--inline

不隐含保存。

读数据建议：先看 stdout 摘要判断是否足够；需要保存完整响应再加

--save

，之后优先用

jq

或

ConvertFrom-Json

从保存的 JSON 文件按需抽取，避免整份 JSON 进入上下文。

解决认证和积分问题

发生以下异常情况时，采用 references/onboarding.md 引导解决问题：

异常情况

未配置API Key：环境变量未配置
```
LINKFOX_AGENT_API_KEY
```
，也未配置
```
LINKFOXAGENT_API_KEY
```
。
响应401或402状态码
响应提示积分或余额不足：消息含"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值"，或类似含义的内容。

High-Risk Confirmation

Ask the user for a separate Chinese natural-language confirmation immediately before each high-risk call, restating the exact order/action summary in business terms only. If the immediately preceding assistant message clearly asks for confirmation of one specific high-risk action, a reply of "确认" is valid. Earlier phrases such as "继续", "可以", or "按上面来" are not valid for later high-risk actions. Do not ask the user to type English parameter names.

After the user confirms in Chinese, the Agent must add the internal safety field required by

references/api.md

when calling the script. Never mention internal fields, request field names, or backend defaults in user-facing confirmation text unless debugging a tool error.

Common Workflow

Run
```
authorized_stores.py
```
; continue only when the current user has an ACTIVE, unexpired 1688 authorization.
If not authorized, run
```
authorize_url.py
```
, let the user complete OAuth, then re-check
```
authorized_stores.py
```
.
If starting from an image, use
```
linkfox-1688-search-by-image
```
to get an
```
offerId
```
.

Run

sku.py

, then

receive_address_list.py

, then

order_preview.py

Show product, SKU/specification, quantity, price, freight, address, total, and warnings in business terms.
Only after separate Chinese confirmation, run
```
create_order.py
```
; add required safety fields internally without showing them to the user.
Only after separate Chinese confirmation, run
```
payment_url.py
```
; pass the created order ID internally without showing request field names to the user.

Use

order_status.py

logistics.py

, and

logistics_trace.py

for tracking.

Use
```
cancel_order.py
```
and
```
confirm_receive.py
```
only after separate confirmations for the exact order and action; pass the selected 1688 order ID internally. Do not describe cancellation as refund handling for paid orders.
After receipt confirmation, run
```
invoice_amount.py
```
to query the invoiceable amount and whether each order can be invoiced; pass the returned
```
amount
```
as-is (do not recompute). Only after separate Chinese confirmation of the invoice type, title, and amount, run
```
invoice_apply.py
```
; pass
```
confirmApplyInvoice=true
```
and the amount internally. Walk
```
successList
```
/
```
failedList
```
per order; treat
```
INVOICE_ALREADY_APPLIED
```
as already-invoiced, not an error.

Display Rules

Show authorization status first when procurement depends on OAuth. Do not assume authorization from a browser redirect alone.
```
authorizedStores
```
output is the current LinkFox user's 1688 authorization state. Do not describe it as all stores in the database.
For authorization, only tell the user whether it is available or whether re-authorization is required. Do not display token expiry times, token validity periods, refresh windows, or internal fields such as
```
tokenExpiresAt
```
.
Never display full API keys, JWTs, access tokens, refresh tokens, callback codes, app secrets, session keys, or Authorization headers.
Show order preview clearly in business terms: product, SKU/specification, quantity, unit price, product total, freight, receive address, order total, buyer message, and warnings.
Before high-risk calls, summarize the exact operation, key IDs, amount/status when available, then ask the user to confirm in Chinese. Do not show internal boolean fields, request field names, or implementation details.
For receive addresses, show enough to let the user choose safely, but avoid unnecessarily repeating full phone numbers or sensitive address details.
Report
```
costToken
```
or equivalent cost fields only when returned.

Important Limitations

Do not create or call image-search scripts here; image search belongs to
```
linkfox-1688-search-by-image
```
.
Do not expose
```
/alibaba1688/proxy/callback
```
,
```
/alibaba1688/authorizeCallback
```
, or browser OAuth callback URLs as Skill capabilities.
Do not ask users to provide 1688 tokens, refresh tokens, callback codes, or secrets. OAuth token exchange is handled by MyERP and ecom-plat.
Do not query backend databases to discover authorization state. Use
```
authorizedStores
```
.
Do not automatically retry write operations or run the full purchase loop.
Do not use
```
_dataQuery_executeDynamicQuery
```
for live procurement responses.

User Expression & Scenario Quick Reference

Applicable -- 1688 procurement scenarios:

User Says	Scenario
"查询我的1688授权店铺" / "show my authorized 1688 stores"	Authorization check
"生成1688授权链接" / "authorize my 1688 account"	New OAuth authorization
"查这个 offerId 的 SKU"	SKU lookup
"查1688收货地址"	Receive address lookup
"帮我预览1688订单"	Order preview
"确认下单"	High-risk create order gate
"获取支付链接"	High-risk payment URL gate
"查1688订单状态/物流"	Order tracking
"取消这个1688订单"	High-risk cancel gate
"确认收货"	High-risk confirm receive gate
"查1688可开票金额" / "这个订单能开发票吗"	Invoiceable amount query
"给这个1688订单开发票" / "确认开票"	High-risk invoice apply gate

Not applicable -- use another skill or backend system:

Image-based 1688 product discovery ->
```
linkfox-1688-search-by-image
```
Keyword-based 1688 sourcing/ranking -> use existing 1688 search/ranking skills when available
MyERP OAuth callback/proxy callback handling -> backend service, not a Skill
Direct token repair or manual 1688 token input -> backend authorization bridge

Feedback

Auto-detect and report feedback via the Feedback API when actual behavior differs from this skill, results do not match user intent, the user expresses satisfaction/dissatisfaction, or anything could be improved. Call the Feedback API as specified in

references/api.md

without interrupting the user's flow. Do not include API keys, tokens, full addresses, phone numbers, or payment URLs in feedback content.

For more high-quality, professional cross-border e-commerce skills, visit LinkFox Skills.

linkfox-1688-procurement

NPX Install

Tags

SKILL.md Content