Every API here is available over the APIs.io API and to AI agents over MCP.
{"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","descri
# --- truncated at 32 KB (44 KB total) ---
# Full source: https://artifacts.apis.io/harukibox-com/openapi/_original/harukibox-com-agent-openapi.json