SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillslinkfox-1688-procurement

linkfox-1688-procurement

General & other

View repository

Updated 10-16 06:23

About this skill

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

How to call

  • API endpoint：POST /alibaba1688/{authorizeUrl|authorizedStores|receiveAddressList|sku|orderPreview|createOrder|paymentUrl|orderStatus|logistics|logisticsTrace|confirmReceive|cancelOrder|invoiceAmount|invoiceApply}(For complete parameters, responses, and error handling, see references/api.md）
  • Python script：python scripts/<script_name>.py '<JSON 参数>' [--inline] [--save] [--no-save]
  • Recommended for Windows：$env:PAYLOAD = '<JSON 参数>' then run python scripts/<script_name>.py --payload-env PAYLOAD [--inline] [--save]
  • Cost constraints: This tool consumes computing power. On failure, empty results, incomplete parameters, or insufficient authorization, do not automatically probe continuously, retry with different parameters, or poll; if further queries are needed, first explain to the user that additional consumption will be incurred.
  • Cache constraints: This procurement Skill does not perform 24h response caching; authorization, prices, inventory, order status, and logistics are subject to real-time returns, and high-risk write operations must not be cached even more.
  • Authorization constraints: Except for authorize_url.py and authorized_stores.py , the script automatically checks the current user's ACTIVE 1688 authorization before calling the target interface; when there is no ACTIVE and unexpired authorization, the target endpoint will not be called.
  • Authorization refresh: When the accessToken is near expiry or has expired, the backend automatically refreshes it using that user's own refreshToken. This is triggered when calling authorizedStores or procurement interfaces, and the Skill and user do not need to intervene. Only when the refreshToken is empty, invalid, or refresh fails (authorizedStores returns expired=true) is it necessary to go through authorize_url.py authorization again; do not display or announce internal authorization details such as token validity period, expiration time, or refresh window to the user.
  • High-risk constraints：create_order.py、payment_url.py、confirm_receive.py、cancel_order.py、invoice_apply.py must be called only after the user separately and explicitly confirms in natural Chinese language. Internal confirmation fields and request details are only for the Agent to call the script and must not be shown to the user.
$env:PAYLOAD = "{}"
python scripts/authorized_stores.py --payload-env PAYLOAD --inline

Script input methods：

  • Pass a JSON string directly:python scripts/sku.py '{"offerId":"..."}'
  • Read from environment variables:python scripts/sku.py --payload-env PAYLOAD
  • Read from a file:python scripts/sku.py --payload-file payload.json
  • Add --inline to force full printing to stdout
  • Add --save to force masking of sensitive token-type fields when saving
  • Add --no-save to prohibit saving response files

Output strategy (default script behavior)：

  • Response body ≤ 8 KB: by default it is not written to disk; the complete masked JSON is printed directly to stdout, avoiding the generation of data files in the Skill directory for every query.
  • Response body > 8 KB: by default the complete masked response is written to <writable-root>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-1688-procurement-<operation>-<timestamp>.json, and stdout outputs only a summary.
  • <writable-root> prioritizes taking ACPX_WORKSPACES 's first workspace, then the current directory when the script is executed, and finally falls back to the user directory;<session> is taken from the environment variable SESSION_ID, and is automatically generated when not provided; writing to /tmp。
  • is prohibited. Add --save or set LINKFOX_SKILL_SAVE_RESPONSE=1 to force saving; add --no-save or set LINKFOX_SKILL_NO_SAVE=1 to prohibit saving;--inline does not imply saving.

Data reading suggestions: First check the stdout summary to determine whether it is sufficient; if the complete response needs to be saved, add --save, then preferentially use jq or ConvertFrom-Json Extract on demand from the saved JSON file to avoid bringing the entire JSON into context.

Resolve authentication and compute resource issues

When the following exceptional situations occur, use references/onboarding.md to guide resolution of the issue:

Exceptional situations

  • API Key not configured: The environment variable is not configured LINKFOX_AGENT_API_KEY, and neither is LINKFOXAGENT_API_KEY。
  • Response 401 or 402 status code
  • Response indicates insufficient compute resource or balance: The message contains "insufficient compute balance/insufficient billing/insufficient balance/quota exceeded/insufficient balance/package expired/recharge required/please recharge", or content with a similar meaning.

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

  1. Run authorized_stores.py; continue only when the current user has an ACTIVE, unexpired 1688 authorization.
  2. If not authorized, run authorize_url.py, let the user complete OAuth, then re-check authorized_stores.py.
  3. If starting from an image, use linkfox-1688-search-by-image to get an offerId.
  4. Run sku.py, then receive_address_list.py, then order_preview.py.
  5. Show product, SKU/specification, quantity, price, freight, address, total, and warnings in business terms.
  6. Only after separate Chinese confirmation, run create_order.py; add required safety fields internally without showing them to the user.
  7. Only after separate Chinese confirmation, run payment_url.py; pass the created order ID internally without showing request field names to the user.
  8. Use order_status.py, logistics.py, and logistics_trace.py for tracking.
  9. 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.
  10. 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

  1. Show authorization status first when procurement depends on OAuth. Do not assume authorization from a browser redirect alone.
  2. authorizedStores output is the current LinkFox user's 1688 authorization state. Do not describe it as all stores in the database.
  3. 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.
  4. Never display full API keys, JWTs, access tokens, refresh tokens, callback codes, app secrets, session keys, or Authorization headers.
  5. Show order preview clearly in business terms: product, SKU/specification, quantity, unit price, product total, freight, receive address, order total, buyer message, and warnings.
  6. 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.
  7. For receive addresses, show enough to let the user choose safely, but avoid unnecessarily repeating full phone numbers or sensitive address details.
  8. 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
"Query my authorized 1688 stores" / "show my authorized 1688 stores" Authorization check
"Generate a 1688 authorization link" / "authorize my 1688 account" New OAuth authorization
"Check the SKU for this offerId" SKU lookup
"Check 1688 shipping addresses" Receive address lookup
"Help me preview a 1688 order" Order preview
"Confirm order placement" High-risk create order gate
"Get the payment link" High-risk payment URL gate
"Check 1688 order status/logistics" Order tracking
"Cancel this 1688 order" High-risk cancel gate
"Confirm receipt" High-risk confirm receive gate
"Check the 1688 invoiceable amount" / "Can this order be invoiced" Invoiceable amount query
"Issue an invoice for this 1688 order" / "Confirm invoicing" 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.