Taviro Open APIv1Base URL: https://taviroglobal.com

API Reference

Taviro Open API は、サプライヤー・販売パートナー・倉庫パートナーが自社システムや AI エージェントからプラットフォームを操作するための REST API です。すべてのレスポンスは JSON、認証は Bearer トークン 1 本。機械可読版は GET /api/docs で常に最新を取得できます。

エンドポイント定義（メソッド・パス・パラメータ）は言語共通です。以下のリファレンス本文は英語表記を正とし、日本語の補足は各所に付記しています。

Taviro Open API 是供应商、卖家、仓库合作方从自有系统或 AI Agent 操作平台的 REST API。所有响应均为 JSON，认证只需一个 Bearer 令牌。机器可读版本随时可通过 GET /api/docs 获取最新内容。

端点定义（方法、路径、参数）与语言无关；以下参考正文以英文为准。

The Taviro Open API lets suppliers, selling partners and warehouse partners operate the platform from their own systems or AI agents. All responses are JSON; authentication is a single Bearer token. A machine-readable version is always available at GET /api/docs.

Overview

Base URL	`https://taviroglobal.com`
Format	JSON request/response bodies, `Content-Type: application/json`
Currency	Amounts are JPY integers unless stated otherwise
IDs	Products `P-` · variants `V-` · orders `O-` · settlements `S-` · keys `K-*`
Machine-readable docs	`GET /api/docs` (no auth) — point your AI here first

Channel capabilities / チャネル別の対応状況 / 渠道能力一览

Shopify・TikTok Shop・eBay の3チャネルとも、承認済み商品のワンクリック出品に対応しています。それ以外の項目は現在の実装に基づく対応状況です（2026年9月時点）。「一部」は実装上の制限で、解消時にこの表を更新します。

チャネル	商品の出品	在庫の更新	注文の取込	追跡番号の反映	掲載停止・再開	キャンセル連携
Shopify	対応	対応在庫・価格・商品内容	対応Webhook	対応	対応	対応Webhook
TikTok Shop	対応カテゴリー・必須属性・倉庫が必要（`tiktokListing`）。制限カテゴリーは Seller Center で資格取得後	一部在庫数のみ	一部3分ごとの取得。TikTok 側の「注文情報」権限付与＋再認可後に有効	一部自社配送の追跡番号。注文取込が前提	対応	一部注文取込が前提
eBay	対応米国・英国サイト。サイトごとのカテゴリーと必須項目、画像1枚以上（`ebayListing`）	対応在庫・価格	対応3分ごとの取得（支払済み）	対応	対応	対応3分ごとの確認

Shopify、TikTok Shop、eBay 三个渠道都支持已审核商品的一键上架推送。其余项目按当前实际实现填写（2026 年 9 月）；「部分」为实现上的限制，解除后会更新本表。

渠道	商品推送	库存更新	订单同步	物流回传	下架 / 恢复	取消同步
Shopify	已支持	已支持库存、价格、商品内容	已支持Webhook	已支持	已支持	已支持Webhook
TikTok Shop	已支持需类目、必填属性、仓库（`tiktokListing`）；受限类目需先在 Seller Center 取得资质	部分仅库存数量	部分每 3 分钟拉取；需 TikTok 开放「订单信息」权限并重新授权后生效	部分自发货物流单号；前提是订单已同步	已支持	部分前提是订单已同步
eBay	已支持美国站与英国站；每站点类目与必填属性，至少一张图片（`ebayListing`）	已支持库存与价格	已支持每 3 分钟拉取（已付款）	已支持	已支持	已支持每 3 分钟检查

All three channels — Shopify, TikTok Shop and eBay — support one-click publishing of approved products. The other cells reflect the current implementation (September 2026); "Partial" marks a limit that this table is updated for when lifted.

Channel	Product push	Stock updates	Order sync	Tracking write-back	Unlist / relist	Cancellation sync
Shopify	Supported	SupportedStock, price and content	SupportedWebhook	Supported	Supported	SupportedWebhook
TikTok Shop	SupportedNeeds category, required attributes and warehouse (`tiktokListing`); restricted categories need Seller Center qualification first	PartialQuantity only	PartialPolled every 3 min; active once TikTok grants the order-information scope and the store is re-authorised	PartialSelf-ship tracking; requires order sync	Supported	PartialRequires order sync
eBay	SupportedUS and UK sites; category and required item specifics per site, at least one image (`ebayListing`)	SupportedStock and price	SupportedPolled every 3 min (paid orders)	Supported	Supported	SupportedChecked every 3 min

Authentication

3 種類の資格情報があり、いずれも Authorization: Bearer <token> ヘッダーで送ります。トークンは所有者本人として振る舞い、テナント分離が適用されます（サプライヤーは自社データのみ、販売パートナーは承認済みカタログと自店舗のみ）。

共有三类凭证，均通过 Authorization: Bearer <token> 头发送。令牌以其所有者身份行事并受租户隔离约束（供应商仅见自己的数据，卖家仅见已审核目录与自己店铺）。

Three credential types, all sent as Authorization: Bearer <token>. A token acts as its owner and is tenant-scoped (suppliers see only their own data; sellers see the approved catalog and their own shops/orders).

Type	Format	How to obtain	Scope & lifetime
API key	`tvk_<40 hex>`	Portal → AI & API tab → Create key (plaintext shown once)	Acts as its owner; revocable per key; cannot manage other keys
MCP OAuth token	`tvm_*`	Issued automatically by the MCP OAuth flow (PKCE)	Per AI client; revocable from the portal; dies on password change
Session token	opaque	`POST /api/auth/login`	Browser/portal sessions, 168h TTL; required for key management

curl https://taviroglobal.com/api/ops/summary \
  -H "Authorization: Bearer tvk_your_api_key"

Conventions

Pagination	List responses are capped (typically 100 rows, newest first). Filter server-side where query parameters exist.
Idempotency	State transitions reject repeats with 409/422 (e.g. paying a settlement twice, shipping a shipped order).
Destructive ops	Editing a live product returns it to `review`; it re-syncs to the connected stores only after re-approval — content + price + stock on Shopify, price + stock on eBay, stock only on TikTok Shop (see Channel capabilities).
Webhooks	Inbound only: Shopify order / fulfillment / GDPR webhooks and TikTok Shop order-status webhooks (signature-verified); eBay orders are polled. Outbound webhooks are on the roadmap.

Errors & rate limits

2xx 以外のレスポンスは必ず { "error": "CODE", ...詳細 } を返します。レート制限は API キーあたり 600 リクエスト/時。超過時は 429 と Retry-After（秒）ヘッダーが返ります。

非 2xx 响应必定携带 { "error": "CODE", ...详情 }。限流为每个 API 密钥 600 次/小时，超限返回 429 及 Retry-After（秒）头。

Every non-2xx response carries { "error": "CODE", ...details }. Rate limit: 600 requests/hour per API key; exceeding it returns 429 with a Retry-After header (seconds).

Status	Code (examples)	Meaning
401	`AUTH_REQUIRED`	Missing/invalid/revoked token
403	`FORBIDDEN` · `ACCOUNT_SUSPENDED` · `ACCOUNT_PENDING_REVIEW` · `KEY_CANNOT_MANAGE_KEYS`	Authenticated but not allowed
404	`PRODUCT_NOT_FOUND` · `ORDER_NOT_FOUND` …	Resource does not exist (or is outside your tenancy)
409	`EMAIL_ALREADY_REGISTERED` · `SETTLEMENT_ALREADY_PAID`	Conflict with current state
422	`PRODUCT_VALIDATION_FAILED` · `SELLING_PRICE_BELOW_COST` · `SHIPPING_REGIONS_REQUIRED` · `INVALID_DIMENSIONS` · `ORDERS_NOT_MERGEABLE`	Payload rejected; details in the body
429	`RATE_LIMITED`	Rate limit hit — honor `Retry-After`

State & KPIs

supplier · seller · warehouse · adminGET/api/state

Full tenant-scoped snapshot: products, orders, settlements, returns, shops. Poll sparingly — prefer targeted endpoints.

supplier · seller · adminGET/api/ops/summary

Operational KPI summary (orders, revenue, stock health, exception SLA).

Products

supplier · adminPOST/api/products

Create a product (enters operator review). Body: { name, category?, cost, price, stock, sku?, variantTitle?, weightGrams?, copy?, imageUrl?, fulfillmentMode?, taxonomyId?, attributes?, shipping?, lengthCm?, widthCm?, heightCm? }. shipping = { international, regions: [asia|north_america|europe|oceania|global], methods: [ems|epacket|surface|courier] } — omit for Japan-only. fulfillmentMode: supplier_direct | platform_warehouse.

supplier · adminPATCH/api/products/:id

Edit an owned product (same fields as create). Editing a live product returns it to review until re-approved.

supplier · adminPATCH/api/products/:id/copy

Update marketing copy only. Body: { copy }.

supplier · adminPOST/api/products/import-csv

Bulk create from CSV. Body: { csv }. Template: GET /api/products/import-template.csv.

seller · adminPOST/api/products/:id/import

List an approved product into ONE connected store (Shopify, TikTok Shop or eBay; default = the first connected store, pass shopId to choose). Body: { sellingPrice?, shopId?, tiktokListing?, ebayListing? }. sellingPrice (JPY, must be ≥ supplier cost) is kept through inventory syncs. Shopify needs no extra fields. A TikTok Shop target requires tiktokListing: { categoryId, warehouseId, attributes?, packageWeightGram?, packageDimensions? }; an eBay target requires ebayListing: { listings: [{ marketplaceId: "EBAY_US" | "EBAY_GB", categoryId, aspects: [{ name, values }] }] } — missing options answer 422 TIKTOK_LISTING_NO_CATEGORY / TIKTOK_LISTING_NO_WAREHOUSE / EBAY_LISTING_NO_MARKETPLACE. Category lookups: GET /api/tiktok/categories?shopId=&keyword=, GET /api/ebay/categories?shopId=&marketplaceId=&q=, GET /api/ebay/categories/:id/aspects?shopId=&marketplaceId=.

seller · adminPOST/api/listings/publish

Publish ONE approved product to MANY connected stores in one call (the portal's one-click publish). Body: { productId, targets: [{ shopId, sellingPrice?, options?: { tiktokListing?, ebayListing? } }] }, ≤ 20 targets, one per shop. Returns 200 { results: [{ shopId, channel, status: "done" | "failed", externalProductId, error? }], summary: { done, failed, pending } } — partial success is normal; each failed target carries a named, retryable error. A shop the caller cannot see fails the whole request with 404 before anything is pushed.

seller · adminGET/api/listings/matrix?productId=P-…

Per-store listing state of one product: { productId, productStatus, shops: [{ shopId, name, channel, status, price, lastSync, … }] }. GET /api/listings/tasks returns the caller's own publish history (done / failed / unlisted, with error codes).

seller · supplier · warehouse · adminGET/api/products/popularity

Aggregate demand per approved product: { popularity: { "P-1": { total, last30d } } }. Order counts only — no buyer or tenant data.

publicGET/api/feeds/meta.csv

Meta (Facebook/Instagram) catalog CSV feed of approved products.

Taxonomy

supplier · seller · adminGET/api/taxonomy/search?q=<text>&lang=ja|zh|en&limit=

Search the Shopify Standard Product Taxonomy (14k+ categories). Returns { results: [{ id, path, leaf }] }.

supplier · seller · adminGET/api/taxonomy/category/:id?lang=

Category detail with standard attributes and allowed values — feed these into attributes on product create/edit.

Inventory

supplier · adminPOST/api/inventory/variants/:variantId/adjust

Adjust stock by a delta. Body: { delta, reason }. Listed products auto-sync to every connected store — quantity on Shopify, TikTok Shop and eBay; price and content where the channel supports it (see Channel capabilities).

supplier · adminGET/api/inventory/low-stock

Variants at or below the low-stock threshold (10).

warehouse · adminPOST/api/products/:id/inbound

Warehouse inbound receiving for platform_warehouse products. Body: { qty, variantId? }. Received quantity becomes sellable stock.

Orders & shipping

supplier (own supplier_direct orders) · warehouse · adminPOST/api/orders/:id/ship

Mark shipped. Body: { carrier?, tracking? } — tracking auto-generates when omitted and is pushed back to the order's sales channel automatically.

warehouse · adminGET/api/orders/merge-candidates

Groups of pending orders sharing one seller + delivery address: { candidates: [{ orderIds, buyer, address, weightGrams, volumeCm3 }] }.

warehouse · adminPOST/api/orders/merge-ship

Ship ≥2 same-address orders as ONE parcel under one tracking number. Body: { orderIds, carrier?, tracking? }. Each channel order (Shopify / TikTok Shop / eBay) receives the shared tracking; the seller gets a merged-shipment notification.

warehouse · adminPOST/api/orders/:id/exception · /api/orders/:id/resolve

Flag an order as exception (address issue, stock mismatch) / return it to the shipping queue. The seller is notified on both transitions.

sellerPOST/api/orders/merge-preference

Body: { preference: "auto" | "never" } — whether the seller's same-address orders may be merged.

Settlements & exports

supplier · adminGET/api/settlements/export.csv

Settlement CSV for the caller's tenant.

supplier · adminGET/api/settlements/accounting.csv

Accounting-grade export (invoice numbers, due dates) — the basis for tax filings.

warehouse · adminGET/api/warehouse/pick-list.csv

Pick list for pending shipments.

API keys

Key management requires a browser session — an API key cannot create or revoke keys (403 KEY_CANNOT_MANAGE_KEYS).

session onlyGET/api/keys

List own keys (no secrets).

session onlyPOST/api/keys

Create a key. Body: { name }. The plaintext tvk_ key appears once in the response.

session onlyPOST/api/keys/:id/revoke

Revoke immediately.

Supplier WMS integration guide / 自社システム連携ガイド

スマレジをお使いの場合はこのガイドは不要です——サプライヤー管理画面の「AI・API連携」タブから契約IDを入力するだけで、商品取込と在庫同期が自動化されます。以下はその他の WMS・ERP 向けの標準パターンです。必要なのは API キー 1 本だけ。以下の 4 つの流れを実装すれば、商品登録・在庫同期・受注取得・出荷連携がすべて自動化できます。

如果你用的是 Smaregi（スマレジ），不需要看本指南——在供应商后台「AI・API連携」页输入契约ID即可自动导入商品和同步库存。以下是其他 WMS/ERP 的标准接入模式。只需一把 API 密钥，实现以下 4 个流程即可自动化商品登记、库存同步、订单获取和发货回传。

Using Smaregi? Skip this guide — enter your contract ID under the supplier portal's AI & API tab for automatic product import and stock sync. The pattern below is for any other WMS/ERP. One API key is all you need; the four flows below automate product registration, stock sync, order retrieval and shipping.

Step	Flow	Endpoint(s)	Notes
0	Get an API key / APIキー発行	Portal → AI・API連携 → キーを作成	The `tvk_` key acts as your supplier account. Store it server-side only.
1	Register products / 商品登録	`POST /api/products` (single) · `POST /api/products/import-csv` (bulk)	New products enter operator review. CSV template: `GET /api/products/import-template.csv` (v1.1, optional `samplePrice` column).
2	Keep stock in sync / 在庫同期	`POST /api/inventory/variants/:variantId/adjust` `{ delta, reason }`	Push a delta whenever your WMS stock changes. Listed products propagate to every connected store (Shopify / TikTok Shop / eBay) automatically within a few minutes; failed pushes are retried.
3	Fetch open orders / 受注取得	`GET /api/state` → `orders` where `status="warehouse"`	Poll every 5–15 min. Each order carries `productId / variantId / qty / address`. Buyer identity stays masked per platform policy.
4	Ship & report tracking / 出荷連携	`POST /api/orders/:id/ship` `{ carrier, tracking }`	Only for your own `supplier_direct` orders. Tracking auto-syncs to the seller's sales channel; the 48h SLA reminder stops immediately.

# 1) stock changed in your WMS: variant V-12 −3 units
curl -X POST https://taviroglobal.com/api/inventory/variants/V-12/adjust \
  -H "Authorization: Bearer tvk_your_api_key" -H "Content-Type: application/json" \
  -d '{ "delta": -3, "reason": "wms_sync" }'

# 2) ship order O-31 with tracking
curl -X POST https://taviroglobal.com/api/orders/O-31/ship \
  -H "Authorization: Bearer tvk_your_api_key" -H "Content-Type: application/json" \
  -d '{ "carrier": "ヤマト運輸", "tracking": "1234-5678-9012" }'

SLA: orders unshipped 48h after creation trigger automatic reminders (mail + in-app). Ship or flag an exception (POST /api/orders/:id/exception) before that. / 受注から48時間以内に出荷または問題申告をお願いします。超過すると自動リマインドが送信されます。

Warehouse partner integration guide / 倉庫パートナー連携ガイド

倉庫側システムとの連携は「入庫 → ピッキング → 出荷（同梱含む）」の 3 フローです。ポータルの AI・API連携タブで API キーを発行してください。

仓库侧系统对接共 3 个流程：「入库 → 拣货 → 出库（含合包）」。请先在门户的 AI・API 连携页签创建 API 密钥。

Warehouse-side integration is three flows: inbound → picking → shipping (incl. merged parcels). Create an API key in the portal's AI & API tab first.

Flow	Endpoint(s)	Notes
Inbound receiving / 入庫計上	`POST /api/products/:id/inbound` `{ qty, variantId? }`	For `platform_warehouse` products: received quantity becomes sellable stock (and syncs to all sales channels).
Pick list / ピッキングリスト	`GET /api/warehouse/pick-list.csv`	All pending shipments as CSV — import into your WMS or print.
Merge candidates / 同梱候補	`GET /api/orders/merge-candidates`	Same seller + same address groups with total weight/volume, ready for one-parcel shipping.
Ship / 出荷	`POST /api/orders/:id/ship` · `POST /api/orders/merge-ship` `{ orderIds, carrier?, tracking? }`	Tracking flows back to each order's sales channel automatically.
Exceptions / 問題申告	`POST /api/orders/:id/exception` · `/resolve`	Address issues, stock mismatch etc. — the seller is notified on both transitions.

MCP server

REST の代わりに、MCP 対応 AI（Claude、ChatGPT、Cursor 等）は https://taviroglobal.com/mcp（Streamable HTTP + OAuth 2.1/PKCE）に接続できます。ツールは 22 個：listing_guide・recommend_products・suggest_category・search_categories・get_category_attributes・create_image_upload_link・import_image_from_url・validate_products・create_draft_review_link・create_products_bulk・list_uploaded_images・upload_product_image・get_overview・list_products・create_product・import_product_to_shop・unlist_product_from_shop・adjust_inventory・list_orders・ship_order・list_settlements・receive_inbound。チャネルとの関係：import_product_to_shop は価格と店舗 ID のみを渡すため、出品先は接続済みの Shopify ストアです（TikTok Shop・eBay はカテゴリー等の指定が必要なため、上記 /api/listings/publish またはポータルから）。unlist_product_from_shop・adjust_inventory・ship_order・list_orders は3チャネル共通です。設定手順は AI 接続ガイドへ。

支持 MCP 的 AI（Claude、ChatGPT、Cursor 等）可不走 REST，直接连接 https://taviroglobal.com/mcp（Streamable HTTP + OAuth 2.1/PKCE）。共 22 个工具：listing_guide、recommend_products、suggest_category、search_categories、get_category_attributes、create_image_upload_link、import_image_from_url、validate_products、create_draft_review_link、create_products_bulk、list_uploaded_images、upload_product_image、get_overview、list_products、create_product、import_product_to_shop、unlist_product_from_shop、adjust_inventory、list_orders、ship_order、list_settlements、receive_inbound。与渠道的关系：import_product_to_shop 只传价格和店铺 ID，因此上架目标是已连接的 Shopify 店铺（TikTok Shop、eBay 需要类目等参数，请用上面的 /api/listings/publish 或门户）；unlist_product_from_shop、adjust_inventory、ship_order、list_orders 三渠道通用。配置步骤见 AI 接入指南。

Instead of REST, MCP-capable AIs (Claude, ChatGPT, Cursor, …) can connect to https://taviroglobal.com/mcp (Streamable HTTP + OAuth 2.1/PKCE). 22 tools: listing_guide, recommend_products, suggest_category, search_categories, get_category_attributes, create_image_upload_link, import_image_from_url, validate_products, create_draft_review_link, create_products_bulk, list_uploaded_images, upload_product_image, get_overview, list_products, create_product, import_product_to_shop, unlist_product_from_shop, adjust_inventory, list_orders, ship_order, list_settlements, receive_inbound. Channel note: import_product_to_shop passes only a price and a shop id, so it lists to connected Shopify stores (TikTok Shop and eBay need category options — use /api/listings/publish above or the portal); unlist_product_from_shop, adjust_inventory, ship_order and list_orders work across all three channels. Setup: see the AI connection guide.

Examples

Create a product with taxonomy, dimensions and international shipping

curl -X POST https://taviroglobal.com/api/products \
  -H "Authorization: Bearer tvk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "今治タオル ギフトセット",
    "cost": 1200, "price": 2980, "stock": 40, "sku": "IMB-TWL-01",
    "weightGrams": 420, "lengthCm": 25, "widthCm": 18, "heightCm": 6,
    "taxonomyId": "10021", "attributes": [{"name": "素材", "value": "綿"}],
    "shipping": { "international": true, "regions": ["asia", "north_america"], "methods": ["ems", "epacket"] },
    "copy": "愛媛県今治産。吸水性に優れた日常使いのタオルセットです。"
  }'

Search the taxonomy

curl "https://taviroglobal.com/api/taxonomy/search?q=タオル&lang=ja&limit=5" \
  -H "Authorization: Bearer tvk_your_api_key"

Ship two same-address orders as one parcel

curl -X POST https://taviroglobal.com/api/orders/merge-ship \
  -H "Authorization: Bearer tvk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "orderIds": ["O-12", "O-13"], "carrier": "Yamato" }'

Error response shape

HTTP/1.1 422 Unprocessable Entity
{ "error": "SELLING_PRICE_BELOW_COST", "cost": 1200, "sellingPrice": 980 }

Support: admin@taviroglobal.com — replies within 1–2 business days. Terms: /terms.html · Tax guide: /tax-guide.html

← Taviro トップへ← 返回 Taviro 首页← Back to Taviro home