SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillslinkfox-amazon-store-uploads

linkfox-amazon-store-uploads

Coding & development

View repository

Updated 10-16 00:00

About this skill

Amazon Store Uploads (File Upload)

This skill is dedicated to requesting an upload destination from Amazon and uploading files, in the same series as linkfox-amazon-store-auth : depends on linkfox-amazon-store-auth store selection (sellerId+region); directly POST /spApi/developerProxy pass in sellerId+region to call createUploadDestinationForResource, and finally use upload_to_destination.py to execute PUTon the returned URL (without going through the gateway).

This is Uploads API, not the Orders order API. For orders see linkfox-amazon-store-orders; for batch Feed files see linkfox-amazon-store-feeds。

How to Call

  • API Endpoint：POST /spApi/developerProxy(different operations are distinguished by the request body; for complete parameters/responses/error codes see references/api.md）
  • Python Script：python scripts/<脚本名>.py '<JSON 参数>' [--inline](available scripts are listed in the script overview above)
  • Cost Constraint: this tool consumes compute; on failure/empty results, do not automatically switch keywords, paginate, or repeatedly probe; if you need to continue searching, first explain to the user that additional consumption will be incurred.

Output Strategy (Script Default Behavior)：

  • Alwayswrite the complete response to <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-amazon-store-uploads-<timestamp>.json（<cwd> is the working directory when the script is executed, which in Claude Code is the current project directory;<session> is taken from the environment variable SESSION_ID, automatically aggregated according to the user's task;writing to /tmp is prohibited, if the current directory is not writable, report an error)
  • Response body ≤ 8 KB: after writing to disk, print the complete JSON to stdout
  • Response body > 8 KB: after writing to disk, stdout outputs only a summary (top-level fields, common counts such as total/costToken, length of the largest list field + first 3 samples)
  • Add --inline to force full printing to stdout (also written to disk)

Data Reading Suggestions: first look at the summary to determine whether it is sufficient; when specific fields are needed, prefer to use jqorConvertFrom-Json to extract on demand from the saved json file, avoiding bringing the entire JSON into context.

Resolve Authentication and Compute Issues

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

Abnormal Situations

  • API Key not configured: the environment variable is not configured LINKFOX_AGENT_API_KEY, and LINKFOXAGENT_API_KEY。
  • is also not configured. Response 401 or 402 status code
  • Response indicates insufficient compute 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 similar meaning.

Official Reference

createUploadDestinationForResource · Create an upload destination

Prerequisites

  1. Depends on linkfox-amazon-store-auth。
  2. resource must be consistent with the downstream API documentation (for example A+:aplus/2020-11-01/contentDocuments; Messaging is the corresponding messages resource path).
  3. contentMD5 is the Base64 MD5 digestof the content of the file to be uploaded; when passing filePath / content , the script can calculate it automatically.

Workflow

create_upload_destination_for_resource  →  uploadDestination { uploadDestinationId, url, headers }
upload_to_destination (PUT url + headers)  →  在 A+/Messaging 等 API 中引用 uploadDestinationId

Scripts

Script Description
create_upload_destination_for_resource.py POST uploads/2020-11-01/uploadDestinations/{resource}
upload_to_destination.py PUT to the returned url(with headers）
_spapi_uploads_common.py internal common module

Example

export LINKFOXAGENT_API_KEY="<your-key>"

# 1) 创建上传目的地（自动根据 filePath 计算 contentMD5）
python scripts/create_upload_destination_for_resource.py '{
  "sellerId":"A1...",
  "region":"NA",
  "resource":"aplus/2020-11-01/contentDocuments",
  "marketplaceId":"ATVPDKIKX0DER",
  "filePath":"/path/to/banner.jpg",
  "contentType":"image/jpeg"
}'

# 2) 上传文件（将上一步 stdout 中的 uploadDestination 传入）
python scripts/upload_to_destination.py '{
  "uploadDestination": { "url": "...", "headers": { } },
  "filePath": "/path/to/banner.jpg"
}'

Display Rules

  1. Successful creation of a destination is usually HTTP 201; first look at developerProxy, then look at uploadDestination。
  2. resource pass the unencoded downstream resource path; may or may not include a leading /, when generating the path preserve the internal /(greedy path), and do not pre-encode it into %2F。
  3. The gateway must allow the uploads/2020-11-01/ prefix.

Amazon SP-API Interface Protection and Retry Guidelines

When the same store consecutively receives 400, 403, 404, or 429 from Amazon SP-API, the gateway returns 450, 453, 454, or 459 and briefly cools down. These custom status codes are not native Amazon statuses and do not indicate account suspension; the purpose is to avoid continuous anomalies or high-frequency calls increasing store risk.

Status and message Scope Trigger and cooldown Handling
450：400，请求异常，请优化您的参数 Store + interface More than 3 times within 60 seconds: 5 minutes; more than 4 times within 10 minutes: 20 minutes Stop retrying with the original parameters, and check required fields, marketplace, ID, date, and request body
453：403，店铺未授权，请先授权 All interfaces of the store More than 2 times within 60 seconds: 5 minutes; more than 4 times within 10 minutes: 30 minutes Stop calling this store, and check authorization, permissions, store ownership, and region
454：404，资源不存在，请优化您的参数 Store + interface More than 3 times within 60 seconds: 5 minutes; more than 4 times within 10 minutes: 30 minutes Confirm the resource ID, the store/site it belongs to, resource status, and interface path
459：429限流中，请降低频率 Store + interface First time: 15 seconds; more than 2 times within 2 minutes: 30 seconds; more than 4 times within 3 minutes: 2 minutes Reduce concurrency, pagination, and polling frequency, and back off step by step
  • Immediately stop automatic or concurrent retries, and do not bypass the protection by switching scripts or repeatedly creating tasks; preferentially follow retryAfter、blockedUntil, and when there is none, follow the duration descriptions in the table.
  • For 450/453/454, you must first correct the parameters, authorization, or resource identifier, and after the cooldown retry cautiously at most once; if triggered again, stop calling. During 453, stop all SP-API calls for that store.
  • Keep existing task IDs such as reportId、feedId ; when the result of a write operation is uncertain, query the status first and do not directly replay.
  • Explain store protection to the user first, then give the cause, handling, and waiting time. You may reply: "To protect your Amazon store security, consecutive {reason} returns from Amazon SP-API were detected, and a brief protection period is currently in effect. Please first {handling action}, and try again after an estimated {waiting time}; this does not mean account suspension, nor is it a plan or computing power limit." Do not only say "LinkFox rate limiting" or "server busy".

Computing Power Consumption Rules

Does not consume computing power.

Feedback： skillName：linkfox-amazon-store-uploads。

More cross-border skills:LinkFox Skills