{"openapi":"3.1.0","info":{"title":"harukibox Agent API","version":"2026.05.16","description":"Agent / MCP / CLI 用的 harukibox API。所有端點以 Bearer token 認證，token 透過 @harukibox/cli 跑 `harukibox login`（OAuth PKCE 或 device flow）取得。每個 token 屬於某個 user 並繼承其 organization 權限；token 只能存取 token 擁有者的 organization 內資料。\n\n替代協定：本 spec 描述 REST 介面；同一組工具亦可透過 Remote MCP (Streamable HTTP, MCP 2025-06-18) 在 POST /api/agent/mcp 以 JSON-RPC 2.0 呼叫，方便 Claude / ChatGPT 等 MCP 原生 client 接入。","contact":{"name":"harukibox","url":"https://harukibox.com","email":"support@harukibox.com"}},"servers":[{"url":"https://harukibox.com/api/agent"}],"x-mcp":{"endpoint":"https://harukibox.com/api/agent/mcp","transport":"streamable-http","protocolVersion":"2025-06-18","authorizationServer":"https://harukibox.com/.well-known/oauth-authorization-server","protectedResource":"https://harukibox.com/.well-known/oauth-protected-resource"},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"hrk_<env>_<base32>","description":"透過 @harukibox/cli `harukibox login` 取得的 Personal Access Token。"}},"schemas":{"Error":{"type":"object","properties":{"success":{"type":"boolean","const":false},"message":{"type":"string"},"code":{"type":"string","nullable":true}},"required":["success","message"]},"Me":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"displayName":{"type":"string","nullable":true},"storeName":{"type":"string","nullable":true},"role":{"type":"string"}}},"organization":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"}}},"token":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"scopes":{"type":"array","items":{"type":"string"}},"expiresAt":{"type":"string","format":"date-time","nullable":true},"ipAllowlist":{"type":"array","items":{"type":"string"}}}}}}}},"Product":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"sku":{"type":"string"},"status":{"type":"string"},"category":{"type":"string","nullable":true},"priceTwd":{"type":"number","nullable":true},"priceJpy":{"type":"number","nullable":true},"currentStock":{"type":"integer","nullable":true},"initialStock":{"type":"integer","nullable":true},"stockAdjustment":{"type":"integer","nullable":true},"releaseDate":{"type":"string","nullable":true},"ipId":{"type":"string","format":"uuid","nullable":true},"locationId":{"type":"string","format":"uuid","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Registration":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"registrationId":{"type":"string","nullable":true},"status":{"type":"string"},"totalAmount":{"type":"number","nullable":true},"buyerId":{"type":"string","format":"uuid","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"Buyer":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true}}},"Shipping":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"ProductsList":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer","nullable":true}}}},"required":["success","data"]},"RegistrationsList":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Registration"}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer","nullable":true}}}},"required":["success","data"]},"BuyersList":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Buyer"}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer","nullable":true}}}},"required":["success","data"]},"ShippingsList":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Shipping"}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer","nullable":true}}}},"required":["success","data"]},"RegistrationCreate":{"type":"object","required":["productId","buyerName","items"],"properties":{"productId":{"type":"string","description":"Must belong to the calling organization."},"buyerName":{"type":"string","maxLength":120,"description":"Exactly as written in the 喊單."},"status":{"type":"string","description":"Defaults to pending."},"paymentMethod":{"type":"string","maxLength":40},"paidAmount":{"type":"number","minimum":0},"discount":{"type":"number","minimum":0},"notes":{"type":"string","maxLength":2000,"description":"Record anything that could not be determined, so the seller can resolve it."},"items":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"品項名稱，例：娃娃 / 立牌"},"character":{"type":"string","description":"Omit rather than guess."},"quantity":{"type":"integer","minimum":1,"maximum":999,"default":1},"price":{"type":"number"},"note":{"type":"string","description":"例：尺寸 M"}}}}}}}},"security":[{"BearerAuth":[]}],"paths":{"/me":{"get":{"operationId":"getMe","summary":"Current user + organization + token info","description":"Return the user, organization and token metadata bound to the calling Bearer token. Always call this first to confirm which store the agent is operating against.","tags":["account"],"x-required-scope":"me","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/products":{"get":{"operationId":"listProducts","summary":"List products","description":"List products in the calling organization. Supports search (matches name + SKU), status filter and pagination.","tags":["products"],"x-required-scope":"products:read","parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100,"minimum":1}},{"name":"search","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductsList"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createProduct","summary":"Create a product","description":"Create a new product in the calling organization. Requires the products:write scope. Will return 403 with QUOTA_EXCEEDED if the organization plan limit is reached.","tags":["products"],"x-required-scope":"products:write","x-openai-isConsequential":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","sku"],"properties":{"name":{"type":"string","maxLength":200},"sku":{"type":"string","maxLength":100},"priceTwd":{"type":"number","minimum":0},"priceJpy":{"type":"number","minimum":0},"description":{"type":"string","maxLength":2000},"category":{"type":"string","maxLength":100},"status":{"type":"string","enum":["現貨","預購","售罄","active","preorder","instock","outofstock"]},"initialStock":{"type":"integer","minimum":0},"releaseDate":{"type":"string"},"ipId":{"type":"string","format":"uuid"},"locationId":{"type":"string","format":"uuid"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/Product"}}}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope or quota exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"SKU already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/products/{id}":{"patch":{"operationId":"updateProduct","summary":"Patch an existing product and/or its items","description":"Correct data on a product that already exists. Only the fields you send change; items are matched by `itemId` and any item you do not mention is left untouched — nothing is ever deleted through this endpoint.\n\nUse this instead of creating records again. Re-creating an item the seller already has produces duplicates, not a fix.\n\n🔴 Selling prices are deliberately NOT accepted here. The product `priceTwd` is the representative price the seller set by hand (it drives list ordering and margin figures), and item TWD prices and item names cascade into the price snapshot stored on every existing order. Those changes need the full web/iOS flow.\n\nImages must be public http/https URLs; send null to clear. Requires a plan with canIntegrate.","tags":["products"],"x-required-scope":"products:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"sku":{"type":"string"},"priceJpy":{"type":"number","description":"JPY cost on the product itself."},"thumbnailUrl":{"type":["string","null"],"description":"Public http/https URL, or null to clear."},"releaseDate":{"type":["string","null"]},"status":{"type":"string"},"category":{"type":["string","null"]},"notes":{"type":["string","null"]},"isPreorder":{"type":"boolean"},"items":{"type":"array","maxItems":100,"description":"In-place patches for existing items. Cannot create or delete items.","items":{"type":"object","properties":{"itemId":{"type":"string"},"priceJpy":{"type":"number"},"imageUrl":{"type":["string","null"]},"quantity":{"type":"integer"},"character":{"type":["string","null"]},"role":{"type":["string","null"]}},"required":["itemId"],"additionalProperties":false}}},"additionalProperties":false}}}},"responses":{"200":{"description":"Patched — see productUpdated, itemsUpdated, itemIdsNotFound"},"400":{"description":"Validation failed, bad image URL, duplicate SKU, or no itemId matched this product"},"402":{"description":"PLAN_UPGRADE_REQUIRED — plan does not allow agent writes"},"404":{"description":"Product not found in this organization"}}},"get":{"operationId":"getProduct","summary":"Get product by id, with its items","description":"Fetch a single product and the items (品項) under it — the orderable variants, each with its own price. Call this before creating registrations: lines bind to items BY NAME, so use the names returned here verbatim or the order gets no price. Returns 404 if the product does not exist or belongs to a different organization.","tags":["products"],"x-required-scope":"products:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/Product"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/registrations":{"get":{"operationId":"listRegistrations","summary":"List registrations (orders)","description":"List orders (registrations) in the calling organization. Filter by status or buyer.","tags":["registrations"],"x-required-scope":"registrations:read","parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100,"minimum":1}},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"buyerId","in":"query","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegistrationsList"}}}}}},"post":{"operationId":"createRegistrations","summary":"Create one or many registrations (orders)","description":"Create registrations from a 喊單 batch. Send a single object for one order, or { registrations: [...] } for up to 50 at once. Entries are processed independently — the response reports per-entry success/failure, so one bad productId does not discard the rest. Partial success still returns 200: resend only the failed entries, never the whole batch, or the successful ones duplicate. Requires a plan with canIntegrate; read-only plans get 402.","tags":["registrations"],"x-required-scope":"registrations:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/RegistrationCreate"},{"type":"object","required":["registrations"],"properties":{"registrations":{"type":"array","minItems":1,"maxItems":50,"items":{"$ref":"#/components/schemas/RegistrationCreate"}}}}]}}}},"responses":{"200":{"description":"All or some entries created"},"400":{"description":"Validation failed, or every entry failed"},"402":{"description":"Plan does not allow agent writes (upgrade required)"}}},"patch":{"operationId":"updateRegistrations","summary":"Update status / payment / notes on existing registrations","description":"The seller's daily action — 「這批改成已到台」「這幾筆標記已付款」. Send one `{id, ...}` or `{updates: [...]}` (up to 50). `id` accepts the registration UUID or the REG-XXXX number. Only status / paymentMethod / notes are changeable (paidAmount is ignored with a warning: payments go through the buyer-payments ledger so prepaid deductions can't double-count); items are deliberately not editable here because changing them re-runs pricing and item binding, and one unmatched name would silently zero the order. Processed per entry; partial success returns 200 — re-send only the failed entries. Requires a plan with canIntegrate.","tags":["registrations"],"x-required-scope":"registrations:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Single form: UUID or REG-XXXX"},"status":{"type":"string"},"paidAmount":{"type":"number","minimum":0,"deprecated":true,"description":"Ignored — record payments via buyer-payments."},"paymentMethod":{"type":"string"},"notes":{"type":"string"},"updates":{"type":"array","maxItems":50,"items":{"type":"object"},"description":"Batch form; each entry has the single-form shape."}}}}}},"responses":{"200":{"description":"All or some entries updated"},"400":{"description":"Validation failed, or every entry failed"},"402":{"description":"Plan does not allow agent writes (upgrade required)"}}}},"/products/{id}/items":{"post":{"operationId":"createProductItems","summary":"Add items (品項) to a product","description":"Add orderable variants under a product — 娃娃・レオナ, 立牌・イデア and so on. Prices live on items, and registration lines bind to them BY NAME (plus character when names repeat) to pick up those prices; a product with no items produces zero-value orders. These are variants; there is no field for physical condition anywhere in the system. Re-sending existing items is safe: duplicates are skipped and reported. Items do NOT count against the plan quota. Requires a plan with canIntegrate.","tags":["products"],"x-required-scope":"products:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":200},"character":{"type":"string","maxLength":100,"description":"角色／款式，同名品項靠這個區分"},"characterGroup":{"type":"string","maxLength":100},"sku":{"type":"string","maxLength":100},"priceJpy":{"type":"number","minimum":0},"priceTwd":{"type":"number","minimum":0},"salePriceTwd":{"type":"number","minimum":0},"quantity":{"type":"integer","minimum":0},"shippingCost":{"type":"number","minimum":0},"imageUrl":{"type":"string","format":"uri"},"barcode":{"type":"string","maxLength":100}}}}}}}}},"responses":{"200":{"description":"Nothing created — every item already existed"},"201":{"description":"Items created"},"400":{"description":"Validation failed, or product not in this organization"},"402":{"description":"Plan does not allow agent writes (upgrade required)"}}}},"/buyers/{id}":{"get":{"operationId":"getBuyer","summary":"Get one buyer with recent order history","description":"Return a buyer plus up to 20 recent registrations. Use this to resolve ambiguous 喊單 lines (e.g. \"娃娃 一隻\" with no character) from what the buyer usually orders. Contact details are masked — see /buyers.","tags":["buyers"],"x-required-scope":"buyers:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"404":{"description":"Buyer not found in this organization"}}}},"/buyers":{"get":{"operationId":"listBuyers","summary":"List buyers","description":"List buyers in the calling organization. Search matches name / phone / email.","tags":["buyers"],"x-required-scope":"buyers:read","parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100,"minimum":1}},{"name":"search","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyersList"}}}}}}},"/stats":{"get":{"operationId":"getStats","summary":"Sales and payment statistics","description":"Aggregated numbers in one call — 「這個月哪個 IP 賣最好」「還有誰沒付款」 — instead of paging through every registration and summing them client-side. Amounts use the same calculation as the web dashboard (item-level), NOT the raw total_amount column, which is 0 on a majority of rows. When reporting unpaid figures, check summary.registrationsWithPayment: many stores never record payments, so \"unpaid\" may mean \"not recorded\".","tags":["registrations"],"x-required-scope":"registrations:read","parameters":[{"name":"groupBy","in":"query","schema":{"type":"string","enum":["ip","product","status","buyer"],"default":"status"}},{"name":"from","in":"query","schema":{"type":"string"},"description":"YYYY-MM-DD or ISO; Taipei day boundary"},{"name":"to","in":"query","schema":{"type":"string"},"description":"inclusive"},{"name":"status","in":"query","schema":{"type":"string"},"description":"comma separated"},{"name":"sort","in":"query","schema":{"type":"string","enum":["amount","unpaid","paid","count","quantity"],"default":"amount"}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}},{"name":"excludeCancelled","in":"query","schema":{"type":"boolean"}},{"name":"unpaidOnly","in":"query","schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Unknown groupBy or malformed date"}}}},"/buyers/{id}/character-stats":{"get":{"operationId":"getBuyerCharacterStats","summary":"Which characters a buyer collects","description":"Ranked list of the characters this buyer actually orders — the fastest way to resolve an ambiguous 喊單 line with no character named. Identified by NAME (aliases merged). If their orders record no characters at all the response says so; that means you cannot infer a preference and must ask the seller.","tags":["buyers"],"x-required-scope":"buyers:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Buyer name"}],"responses":{"200":{"description":"OK"},"404":{"description":"No orders under that name"}}}},"/buyer-aliases":{"get":{"operationId":"listBuyerAliases","summary":"Read buyer alias grouping","description":"Which display names belong to the same buyer.","tags":["buyers"],"x-required-scope":"buyers:read","responses":{"200":{"description":"OK"}}},"post":{"operationId":"setBuyerAlias","summary":"Group names as the same buyer","description":"Merge display names into one buyer. Only do this on the seller's confirmation — merging two different people mixes their orders and money, and this endpoint cannot undo it. Requires a plan with canIntegrate.","tags":["buyers"],"x-required-scope":"buyers:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["primaryName","aliases"],"properties":{"primaryName":{"type":"string"},"aliases":{"type":"array","minItems":1,"items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Merged into existing grouping"},"201":{"description":"New grouping created"},"400":{"description":"Self-alias or validation failure"},"402":{"description":"Plan does not allow agent writes"},"409":{"description":"Would create a conflicting or circular grouping"}}}},"/shipping-calculations":{"get":{"operationId":"listShippingCalculations","summary":"Past freight allocations","tags":["shippings"],"x-required-scope":"products:read","parameters":[{"name":"includeRaw","in":"query","schema":{"type":"boolean"},"description":"Include original input (large)"}],"responses":{"200":{"description":"OK"}}},"post":{"operationId":"allocateShipping","summary":"Split freight across packages","description":"Allocates a total freight cost across packages by weight, using the same algorithm as the web app. Every package needs a weight — a wrong weight silently shifts cost onto the wrong buyer. Requires a plan with canIntegrate; counts against the shipping_templates quota.","tags":["shippings"],"x-required-scope":"shippings:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["packages"],"properties":{"packages":{"type":"array","minItems":1,"items":{"type":"object","required":["label"],"properties":{"label":{"type":"string"},"weight":{"type":"number","minimum":0},"trackingNumber":{"type":"string"}}}},"totalCost":{"type":"number","minimum":0},"batchName":{"type":"string"}}}}}},"responses":{"201":{"description":"Created"},"402":{"description":"Plan does not allow agent writes"},"403":{"description":"Quota exceeded"}}}},"/images":{"post":{"operationId":"uploadImage","summary":"Upload an image, get a public URL back","description":"Upload an image and receive a public URL for a product `thumbnailUrl` or item `imageUrl`. The image is resized (long edge 1200) and re-encoded to WebP server-side.\n\nTwo sources: `imageUrl` (the server fetches it — prefer this, no transport size limit) or `imageBase64` (raw bytes — the source file must be under ~45KB, because callers going through MCP hit a 64KB request-body cap and base64 inflates by 4/3). Corrupt or truncated data is rejected with IMAGE_DECODE_FAILED rather than stored. The URL is publicly readable. Requires a plan with canIntegrate.","tags":["products"],"x-required-scope":"products:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"imageUrl":{"type":"string","description":"讓後端自己抓的圖片網址（大圖走這條）"},"imageBase64":{"type":"string","description":"base64 或 data URI；原始檔須 <45KB"},"contentType":{"type":"string","description":"選填，以檔頭為準"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Uploaded — data.url, plus bytes/width/height and sourceBytes"},"400":{"description":"IMAGE_DECODE_FAILED (corrupt/truncated), bad URL, or over 10MB"},"402":{"description":"PLAN_UPGRADE_REQUIRED"}}}},"/confirm-links":{"get":{"operationId":"listConfirmLinks","summary":"List confirmation links with status","description":"Confirmation links let a buyer check their order before it ships. Buyer email is never returned — only hasBuyerEmail. Read dataStatus: no_confirm_links means none were ever created.","tags":["registrations"],"x-required-scope":"registrations:read","parameters":[{"name":"status","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","maximum":100}}],"responses":{"200":{"description":"OK — check dataStatus"}}},"post":{"operationId":"createConfirmLink","summary":"Generate a confirmation link for one order","description":"Accepts a registration UUID or the REG-… number. If a live link already exists it is returned with isExisting:true — no duplicate, no extra quota. The expiry countdown starts when the buyer first opens it. Counts against the confirm-links quota. Requires canIntegrate.","tags":["registrations"],"x-required-scope":"registrations:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"registrationId":{"type":"string"},"expiresHours":{"type":"integer"}},"required":["registrationId"],"additionalProperties":false}}}},"responses":{"200":{"description":"data.shortUrl is what the seller hands the buyer"},"403":{"description":"QUOTA_EXCEEDED"},"404":{"description":"Registration not found in this organization"}}},"patch":{"operationId":"updateConfirmLink","summary":"Activate / expire / reactivate a confirmation link","description":"linkId accepts the link uuid or its shortCode. Expiring is not final for arrived orders: once the order reaches 已抵台 the link revives read-only so the buyer can reach the shop link.","tags":["registrations"],"x-required-scope":"registrations:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"linkId":{"type":"string"},"action":{"type":"string","enum":["activate","expire","reactivate"]},"expiresHours":{"type":"integer"}},"required":["linkId","action"],"additionalProperties":false}}}},"responses":{"200":{"description":"Updated"},"404":{"description":"Not found in this organization"}}}},"/buyer-payments":{"get":{"operationId":"listBuyerPayments","summary":"Prepaid balances (all buyers) or one buyer's transactions","description":"Without buyerName: every buyer with a non-zero balance (positive = store holds their money, negative = they owe). With buyerName: that person's history, aliases resolved. dataStatus no_records means nobody has prepaid — not a failure.","tags":["buyers"],"x-required-scope":"buyers:read","parameters":[{"name":"buyerName","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","maximum":100}}],"responses":{"200":{"description":"OK — check dataStatus"}}},"post":{"operationId":"recordBuyerPayment","summary":"Record a prepaid balance movement","description":"type: deposit / deduction / refund / adjustment — every type moves the balance and needs amount. For a note with no money movement use /buyer-memos instead. The balance is computed by the database (deductions spread across orders); the reply carries the new balance. Requires canIntegrate.","tags":["buyers"],"x-required-scope":"buyers:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"buyerName":{"type":"string"},"type":{"type":"string","enum":["deposit","deduction","refund","adjustment"]},"amount":{"type":"number"},"notes":{"type":"string"},"registrationId":{"type":"string"},"relatedProduct":{"type":"string"}},"required":["buyerName","type","amount"],"additionalProperties":false}}}},"responses":{"200":{"description":"Recorded — data.balanceAfter is the new balance"}}}},"/buyer-memos":{"get":{"operationId":"listBuyerMemos","summary":"Notes that follow a buyer across orders","description":"Standing preferences and obligations (「只收未拆」). Expired memos are returned but flagged isExpired — do not act on those.","tags":["buyers"],"x-required-scope":"buyers:read","parameters":[{"name":"buyerName","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","maximum":100}}],"responses":{"200":{"description":"OK — check dataStatus"}}},"post":{"operationId":"createBuyerMemo","summary":"Attach a note to a buyer","tags":["buyers"],"x-required-scope":"buyers:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"buyerName":{"type":"string"},"content":{"type":"string"},"expiresAt":{"type":["string","null"]}},"required":["buyerName","content"],"additionalProperties":false}}}},"responses":{"200":{"description":"Created"}}}},"/ip-roles":{"get":{"operationId":"listIpRoles","summary":"Series (IP) and their character lists","tags":["products"],"x-required-scope":"products:read","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","maximum":200}}],"responses":{"200":{"description":"OK — check dataStatus"}}},"post":{"operationId":"createIpRole","summary":"Create a series with its characters","description":"Creating an existing name returns it with isExisting:true instead of duplicating. Requires canIntegrate.","tags":["products"],"x-required-scope":"products:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":"string"},"color":{"type":"string"},"description":{"type":"string"},"imageUrl":{"type":"string"},"characters":{"type":"array","items":{"type":"string"}},"characterGroups":{"type":"array","items":{"type":"string"}}},"required":["name"],"additionalProperties":false}}}},"responses":{"200":{"description":"Created (or existing)"}}},"patch":{"operationId":"updateIpRole","summary":"Update a series / append characters","description":"addCharacters appends with dedupe; characters REPLACES the whole list (anything left out is gone). The two are mutually exclusive.","tags":["products"],"x-required-scope":"products:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ipId":{"type":"string"},"name":{"type":"string"},"code":{"type":"string"},"color":{"type":"string"},"description":{"type":["string","null"]},"imageUrl":{"type":["string","null"]},"addCharacters":{"type":"array","items":{"type":"string"}},"characters":{"type":"array","items":{"type":"string"}},"characterGroups":{"type":"array","items":{"type":"string"}}},"required":["ipId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Updated"},"404":{"description":"Not found in this organization"}}}},"/shipment-batches":{"get":{"operationId":"listShipmentBatches","summary":"Shipping batches (one product, many orders shipped together)","tags":["shippings"],"x-required-scope":"shippings:read","parameters":[{"name":"status","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","maximum":100}}],"responses":{"200":{"description":"OK — check dataStatus"}}},"post":{"operationId":"createShipmentBatch","summary":"Group orders into one shipping batch","description":"All registrations must belong to the SAME product — mixed products are rejected; split them. Totals are computed server-side with the web UI's logic. Requires canIntegrate.","tags":["shippings"],"x-required-scope":"shippings:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"registrationIds":{"type":"array","items":{"type":"string"},"maxItems":500},"name":{"type":"string"},"notes":{"type":"string"},"productId":{"type":"string"}},"required":["registrationIds"],"additionalProperties":false}}}},"responses":{"200":{"description":"Created"},"400":{"description":"Mixed products or ids not found"}}}},"/store-links":{"get":{"operationId":"listStoreLinks","summary":"Shop links given to buyers","description":"Shop links (賣場連結): the seller storefront URLs buyers use to actually pay once goods land in Taiwan. NOT to be confused with `/products/links` (相關連結), which are the seller's private sourcing pages carrying the JPY cost and must never reach a buyer.\n\nA link belongs to a set of buyers, not to an order — a buyer with orders across three group-buys that land together gets one link, not three. `pendingBuyers` is who has not ordered yet. ALWAYS read `dataStatus`: `no_store_links` means none have ever been created, which is different from an empty result.","tags":["registrations"],"x-required-scope":"registrations:read","parameters":[{"name":"includeArchived","in":"query","schema":{"type":"string","enum":["1"]}}],"responses":{"200":{"description":"OK — check dataStatus"}}},"post":{"operationId":"createStoreLink","summary":"Publish a shop link to buyers","description":"Publish a shop link to the buyers who should receive it. Pass `productIds` and recipients are derived: every buyer with a registration on those products, aliases merged so one person is not listed twice. That derivation is the point — a seller should not hand-pick 30 names out of 200.\n\nThe buyer then sees it on their confirmation link and in the buyer portal; expired confirmation links revive read-only for arrived orders so the shop stays reachable.\n\nThe response reports `withEmailCount`. Pass it on — the remaining buyers have to be messaged by the seller directly. Max 200 recipients; split by product if exceeded. Requires a plan with canIntegrate.","tags":["registrations"],"x-required-scope":"registrations:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","description":"Shown to the buyer, to tell which batch this is. e.g. 「8月扭曲仙境團到貨」."},"url":{"type":"string","description":"Storefront URL. http/https only."},"productIds":{"type":"array","items":{"type":"string"},"description":"Products that just landed; recipients are derived from their registrations."},"buyerNames":{"type":"array","items":{"type":"string"},"description":"Extra buyers, merged and de-duplicated with the derived list."},"note":{"type":"string","description":"Seller-private note. Never shown to buyers."}},"required":["title","url"],"additionalProperties":false}}}},"responses":{"200":{"description":"Published — see recipientCount, withEmailCount, recipients"},"400":{"description":"Missing title/url, bad URL scheme, no recipients, or over 200 recipients"},"402":{"description":"PLAN_UPGRADE_REQUIRED — plan does not allow agent writes"}}}},"/locations":{"get":{"operationId":"listLocations","summary":"Warehouse hierarchy and item placement","description":"Locations → areas → boxes, and which items sit where. Pass `item` to answer 「這批貨放在哪一箱」. ALWAYS read `dataStatus` first: if the store has not tagged item locations yet, say exactly that rather than guessing a location or implying a fault.","tags":["products"],"x-required-scope":"products:read","parameters":[{"name":"item","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK — check dataStatus"}}},"patch":{"operationId":"assignItemLocation","summary":"Put items into a box or location","description":"Assign items to a box (`boxId`) or to a location without a box (`locationId`). Select items with EITHER `itemIds` (max 200) OR `productId`. Assigning to a box also sets the location automatically — never send both targets.\n\nThe seller must tell you where the goods went; do not infer a box from its name. Requires a plan with canIntegrate.","tags":["products"],"x-required-scope":"products:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"itemIds":{"type":"array","items":{"type":"string"},"maxItems":200,"description":"Item ids to move. Mutually exclusive with productId."},"productId":{"type":"string","description":"Move every item under this product. Mutually exclusive with itemIds."},"boxId":{"type":"string","description":"Target box. Mutually exclusive with locationId."},"locationId":{"type":"string","description":"Target location, not in a box. Mutually exclusive with boxId."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Assigned — see assignedCount, target.path, missingItemIds"},"400":{"description":"Ambiguous or missing selector/target, or batch too large"},"402":{"description":"PLAN_UPGRADE_REQUIRED — plan does not allow agent writes"},"404":{"description":"Target box/location or items not found in this organization"}}}},"/products/links":{"get":{"operationId":"listProductLinks","summary":"Seller's private reference links on products","description":"A seller's own reference links (相關連結) — where they sourced the product. PRIVATE to the seller, never shown to buyers: these pages carry the JPY price, which is the seller's cost. Pass `productId` for one product; omit to list every product that has links.","tags":["products"],"x-required-scope":"products:read","parameters":[{"name":"productId","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK — check dataStatus when empty"}}},"post":{"operationId":"setProductLinks","summary":"Attach reference links to one or many products","description":"Seller-private reference links (相關連結), never shown to buyers. One source page usually covers several products (a POP UP STORE listing has badges, standees and folders that are separate products but share one URL), so this takes an array of productIds (max 100). `append` (default) skips URLs already present and keeps their existing titles; `replace` swaps the whole set. Only http/https accepted. Read the returned message — if every product already had the link, nothing changed. Requires a plan with canIntegrate.","tags":["products"],"x-required-scope":"products:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["productIds","links"],"properties":{"productIds":{"type":"array","items":{"type":"string"},"maxItems":100},"links":{"type":"array","items":{"type":"object","required":["url"],"properties":{"url":{"type":"string"},"title":{"type":"string"}}}},"mode":{"type":"string","enum":["append","replace"],"default":"append"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Applied — see appliedCount, results, missingProductIds"},"400":{"description":"No productIds, batch too large, or no valid http/https link"},"402":{"description":"PLAN_UPGRADE_REQUIRED"},"404":{"description":"None of the productIds exist in this organization"}}}},"/shippings":{"get":{"operationId":"listShippings","summary":"List shipments","description":"List shipments in the calling organization.","tags":["shippings"],"x-required-scope":"shippings:read","parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100,"minimum":1}},{"name":"status","in":"query","schema":{"type":"string"},"description":"Accepts Chinese labels too, e.g. 已到臺"},{"name":"buyerName","in":"query","schema":{"type":"string"}},{"name":"view","in":"query","schema":{"type":"string","enum":["orders","shipments"],"default":"orders"},"description":"orders (default) reads shipping state off the ORDERS, which is where it actually lives and what the web 出貨管理 page shows. shipments reads standalone courier records, which most stores never create — an empty result there means no tracking records, not nothing to ship."}],"responses":{"200":{"description":"OK — check `dataStatus`"}}},"patch":{"operationId":"advanceShipping","summary":"Move orders to the next shipping stage in bulk","description":"Moving to `sent` / `completed` also deducts the buyer's prepaid balance — only for orders paid by 匯款 (bank transfer) and only when the store's auto-deduct setting is not off; the reply reports `deductionSkippedByPaymentMethod`. If that deduction fails the status change is rolled back for that entry, so money and status never disagree. Processed per entry; partial success returns 200 — re-send only the failed ones. Requires a plan with canIntegrate.","tags":["shippings"],"x-required-scope":"shippings:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["registrationIds","status"],"properties":{"registrationIds":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string","description":"UUID or REG-XXXX"}},"status":{"type":"string"},"skipDeduct":{"type":"boolean","description":"Skip prepaid deduction (rare)"}}}}}},"responses":{"200":{"description":"All or some entries updated"},"400":{"description":"Validation failed, or every entry failed"},"402":{"description":"Plan does not allow agent writes (upgrade required)"}}},"post":{"operationId":"createShipments","summary":"Create courier shipment records","description":"Standalone shipment records (tracking number, courier). Note that most stores track shipping through the order status instead — see the `view` parameter on GET. Requires a plan with canIntegrate.","tags":["shippings"],"x-required-scope":"shippings:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"All or some created"},"400":{"description":"Validation failed, or every entry failed"},"402":{"description":"Plan does not allow agent writes (upgrade required)"}}}},"/tokens":{"get":{"operationId":"listMyTokens","summary":"List my Personal Access Tokens","description":"List all PATs (active, revoked, expired) belonging to the user that owns the calling token. For self-introspection / multi-machine cleanup. Uses the `me` scope.","tags":["account"],"x-required-scope":"me","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"tokenPrefix":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["active","revoked","expired"]},"expiresAt":{"type":"string","format":"date-time","nullable":true},"lastUsedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}}}}}}}}}}},"/tokens/{id}":{"delete":{"operationId":"revokeMyToken","summary":"Revoke one of my Personal Access Tokens","description":"Revoke (set revoked_at) a specific PAT. Only tokens owned by the calling user can be revoked; other ids return 404 to avoid existence leak. Uses the `me` scope.","tags":["account"],"x-required-scope":"me","x-openai-isConsequential":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tokenPrefix":{"type":"string"},"revoked":{"type":"boolean"}}}}}}}},"404":{"description":"Not found / already revoked / belongs to another user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/search":{"get":{"operationId":"globalSearch","summary":"Global search (products / buyers / registrations)","description":"Search across products, buyers and registrations. Pass `type` to narrow the scope.","tags":["search"],"x-required-scope":"search","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1}},{"name":"type","in":"query","schema":{"type":"string","enum":["products","buyers","registrations"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"query":{"type":"string"},"data":{"type":"object","properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"buyers":{"type":"array","items":{"$ref":"#/components/schemas/Buyer"}},"registrations":{"type":"array","items":{"$ref":"#/components/schemas/Registration"}}}}}}}}}}}}}}