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 |
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 Shopify only after re-approval. |
| Webhooks | Inbound only (Shopify order/GDPR webhooks, HMAC-verified). 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
Full tenant-scoped snapshot: products, orders, settlements, returns, shops. Poll sparingly — prefer targeted endpoints.
Operational KPI summary (orders, revenue, stock health, exception SLA).
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.
Edit an owned product (same fields as create). Editing a live product returns it to review until re-approved.
Update marketing copy only. Body: { copy }.
Bulk create from CSV. Body: { csv }. Template: GET /api/products/import-template.csv.
List an approved product into the seller's connected Shopify store. Optional { sellingPrice } (JPY, must be ≥ supplier cost); kept through inventory syncs.
Aggregate demand per approved product: { popularity: { "P-1": { total, last30d } } }. Order counts only — no buyer or tenant data.
Meta (Facebook/Instagram) catalog CSV feed of approved products.
Taxonomy
Search the Shopify Standard Product Taxonomy (14k+ categories). Returns { results: [{ id, path, leaf }] }.
Category detail with standard attributes and allowed values — feed these into attributes on product create/edit.
Inventory
Adjust stock by a delta. Body: { delta, reason }. Exported products auto-sync to connected Shopify stores.
Variants at or below the low-stock threshold (10).
Warehouse inbound receiving for platform_warehouse products. Body: { qty, variantId? }. Received quantity becomes sellable stock.
Orders & shipping
Mark shipped. Body: { carrier?, tracking? } — tracking auto-generates when omitted and is pushed back to the order's sales channel automatically.
Groups of pending orders sharing one seller + delivery address: { candidates: [{ orderIds, buyer, address, weightGrams, volumeCm3 }] }.
Ship ≥2 same-address orders as ONE parcel under one tracking number. Body: { orderIds, carrier?, tracking? }. Each Shopify order receives the shared tracking; the seller gets a merged-shipment notification.
Flag an order as exception (address issue, stock mismatch) / return it to the shipping queue. The seller is notified on both transitions.
Body: { preference: "auto" | "never" } — whether the seller's same-address orders may be merged.
Settlements & exports
Settlement CSV for the caller's tenant.
Accounting-grade export (invoice numbers, due dates) — the basis for tax filings.
Pick list for pending shipments.
API keys
403 KEY_CANNOT_MANAGE_KEYS).List own keys (no secrets).
Create a key. Body: { name }. The plaintext tvk_ key appears once in the response.
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 automatically within ~10 min. |
| 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" }'
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）に接続できます。ツール：listing_guide・recommend_products・search_categories・get_category_attributes・suggest_category・create_image_upload_link・import_image_from_url・validate_products・create_products_bulk・create_draft_review_link・create_product・import_product_to_shop・adjust_inventory・list_products・list_orders・ship_order・list_settlements・get_overview・receive_inbound。設定手順は AI 接続ガイドへ。
支持 MCP 的 AI（Claude、ChatGPT、Cursor 等）可不走 REST，直接连接 https://taviroglobal.com/mcp（Streamable HTTP + OAuth 2.1/PKCE）。工具清单同上；配置步骤见 AI 接入指南。
Instead of REST, MCP-capable AIs (Claude, ChatGPT, Cursor, …) can connect to https://taviroglobal.com/mcp (Streamable HTTP + OAuth 2.1/PKCE). Tools include listing_guide, recommend_products, suggest_category, create_image_upload_link, validate_products, create_products_bulk, create_draft_review_link, create_product, import_product_to_shop and more. 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 }