atouch API 概要

atouch API を利用することで、既存 atouch（Shop / Admin）の商品・注文・顧客データを標準の OpenAPI 3.1 + OAuth 2.1 で読み書きできます。

本番環境 https://api.developers.atouch.jp で提供しています。商品・注文・顧客の参照に加え、在庫・出荷・商品管理の書き込みに対応しています（すべて冪等）。詳細は下表のとおり。

ご利用にはクライアント資格情報の発行が必要です。運営までご連絡ください。

提供している API（ReadOnly）

分類	内容	必要スコープ
商品 / カテゴリ	商品一覧・詳細、カテゴリ、配送会社、自ショップ情報。updated_since で増分取得・sku 完全一致検索。在庫数に加えて購入手続き中の仮押さえ数（reserved_inventory）を返します	read_items / read_users
注文	注文ヘッダ・明細・配送（買い手 PII を除く）。updated_since で増分取得（注文検知のポーリングに利用）。明細は購入された種類（variant）、配送は送り状の番号・登録日時・お届け予定日を含みます	read_orders
注文の買い手 PII	購入者・お届け先の氏名/住所/電話	read_orders_pii
顧客	LINE 識別・タグ・注文	read_customers
顧客 PII	氏名/住所/電話/メール/性別	read_customers_pii

提供している API（Write）

分類	内容	必要スコープ
在庫予約	予約（仮押さえ）→確定／解放。可否は原子判定＝売り越しなし。予約は TTL（既定 15 分）で自動失効	write_reservations
出荷状況	出荷ステータス遷移（prepared → partial_shipped → shipped → re_shipped / returned）・送り状の登録/訂正	write_shipping
在庫更新	商品在庫の絶対値 SET（0〜99999）／増減／総在庫の指定（購入手続き中の仮押さえを API が差し引いて保存）。バリエーション商品は variant_id 指定で variant 在庫（set 商品は構成品から自動計算のため不可）	write_items
商品	新規登録（全種類: 通常/ギフト/チケット/無料チケット/先行販売チケット/セット）・既存商品の編集（部分更新・修正ログ記録）	write_items
カテゴリー	作成（階層 2 段まで・並び順は末尾自動採番）・編集（名前/公開状態/並び順）	write_items
商品画像	URL 指定でメイン画像の差し替え・追加画像の登録（JPEG/PNG・実バイト検証）・並び替え・削除。登録→画像→公開が API だけで完結	write_items
バリエーション	商品作成時に軸（色・サイズ等）と組合せを宣言。以後は variant の追加・編集（販売終了は status: inactive）。軸は作成時に確定	write_items

書き込み系はすべて Idempotency-Key ヘッダー必須です（同一キーの再送は安全に再生されます）。

マーチャントの修正ログ（管理画面の履歴）に残るのは、既存の管理画面でも履歴を残している操作だけです。具体的には 商品の編集・在庫の更新・出荷状況の変更が記録されます。商品の新規登録・カテゴリー操作・画像操作・バリエーション操作は、既存の管理画面でも履歴を残していないため記録されません（API 側で独自の履歴を作らない方針）。API の全操作は別途、当社の監査ログに記録しています。

基本仕様

• ベース URL: https://api.developers.atouch.jp
• プロトコル: HTTPS のみ
• データ形式: application/json; charset=utf-8
• User-Agent ヘッダー（必須）: 連携名/バージョン (+連絡先URL) の形で付けてください（例 my-connector/1.2 (+https://example.com/contact)）。無いリクエストは API に届く前に 403（HTML の本文）で拒否されます。HTTP クライアントやワーカー環境によっては既定で付かないので、明示的に設定してください
• 日時（レスポンス）: ISO 8601 / RFC 3339 の UTC（例 2026-06-01T03:00:00Z）
  日時（リクエスト）は 2 種類に分かれます:
  ・カーソル日時（updated_since）… 任意のオフセット可（Z でも +09:00 でも同じ瞬間として解釈します）
  ・業務日時（sell_from / sell_by / cancel_by / チケット系）… YYYY-MM-DD HH:mm(:ss) のみ。オフセットを付けると 400 になります。値は店舗ローカル（JST）の時刻として扱われます
  増分取得では、レスポンスの updated_at をそのまま次のカーソルに渡してください。自前の時計から作ると、時差の解釈違いで取りこぼしの原因になります。
• 金額: { "amount": 3200, "currency": "JPY" }（Money 型）
• 省略されることがある項目: 注文明細の variant と、商品の reserved_inventory（バリエーションごとの値を含む）は、取得できなかったときにキーごと省略します。null（種類なし）や 0（仮押さえなし）とは意味が違います。キーが無いときは、その意味に読み替えず、時間をおいて再取得してください。
• エンベロープ: 一覧は { "data": [...], "pagination": {...} }、エラーは { "error": { code, message } } で統一。
  単一リソースは原則 { "data": {...} } ですが、在庫更新・画像登録/並び替え/削除・予約系は互換性のため裸のオブジェクトを返します（例: { "item_id": "1", "inventory": 20, "previous_inventory": 5 }）。各エンドポイントのレスポンス例を参照してください。

レート制限

クライアント（client_id）単位で制限します。既定は次のとおりです。

種別	定常レート	バースト
読み取り（GET / HEAD）	5 req/秒	20
書き込み（POST / PATCH / PUT / DELETE）	1 req/秒	4

• 超過すると 429（{ "error": { "code": "rate_limited" } }）を返し、Retry-After（秒）と X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset ヘッダーを付与します。Retry-After に従って待ってから再送してください。
• バーストは連続送信できる回数、定常レートはならしたときの上限です。書き込みは読み取りの 1/5 に設定しています。
• 商品の一括投入を行う場合（例: 外部 EC からの初回同期）は、上の書き込みレートで所要時間を見積もってください。目安として 1,000 商品 ×（登録 + 画像 + 公開）≒ 3,000 呼び出しで 約 50 分です。並列数を上げても定常レートは変わりません。
• 連携の要件で恒常的に上限が足りない場合は、クライアント単位の引き上げを個別にご相談ください。

大量のデータを扱うとき

一括登録・一括更新の専用エンドポイントは提供していません。 単体のエンドポイントを繰り返し呼び出してください。

• Idempotency-Key を件ごとに付ければ、途中で通信が切れても安全に再送・再開できます（同じキーの再送は重複処理されません）
• 429 が返ったら Retry-After に従って待ってから続けてください
• 数百〜数千件でも、上記のレート制限の範囲で現実的な時間で完了します

⚠️ 繰り返し呼び出しでは要件を満たせない規模・用途がある場合は、具体的な件数と頻度を添えてご相談ください。実際の需要をもとに一括処理の提供を検討します。

外部システムと連携する場合

他の EC・在庫管理システムと双方向に同期する場合の注意点です。

• 在庫数 inventory は、購入手続き中の仮押さえ分を引いた後の数です。 購入者が決済を始めると在庫から先に引かれ、決済が完了しなければ数分で戻ります。仮押さえ中の数は reserved_inventory で返します（上の「在庫予約」の予約とは別のものです）。手元の総数と比べるときは inventory + reserved_inventory を使ってください。2 つは別々に読み取るので、仮押さえが動いた瞬間に読むと、合計が 1 回だけずれることがあります。差が出たら、もう一度読み直して同じ差になることを確かめてください。
• 総数を X に合わせるときは、総在庫の指定（total_inventory）を使ってください。 API が在庫の行をロックした中で仮押さえ中の数を数え、総数 − 仮押さえ中の数を在庫として保存します。仮押さえがその後に確定しても戻っても、総数が合います。手順は次のとおりです。
  ① 商品を読み、総数 T（inventory + reserved_inventory）を控える（種類のある商品は、商品の詳細で種類ごとの値を読む）
  ② その後に Atouch 側の注文を取り込み、X を決める。注文は前回の続きより少し前（目安 1 分）から読み直し、注文 ID で重複を除く（注文の更新日時は、確定より少し前に決まるため）。init の注文は販売に数えない
  ③ {"total_inventory": X, "expected_total_inventory": T} を送る。inventory・adjustment と一緒に送らないでください（対応前の環境は、知らない項目を捨てて inventory として処理します）
  ④ 409 total_inventory_changed は、① の後に総数が変わった（販売の確定や在庫の書き換え）ことを表し、何も書いていません。① からやり直し、新しい Idempotency-Key で送ります。409 inventory_busy は、在庫の行が購入手続きなどに使われていて書けなかったことを表します。Retry-After の後に同じ Idempotency-Key で再送するか、次の周期に回してください
  ⚠️ ① より前に確定していて、まだ取り込んでいない販売は、この手順でも防げません（T にその販売が入っているので、条件が合ってしまいます）。② の順序を守ってください。応答を受け取れなかったときは、同じ Idempotency-Key で再送してください（新しいキーで送ると、その間の販売を上書きすることがあります）。① の応答に reserved_inventory のキーが無いときは、その回は送らないでください。応答の inventory + reserved_inventory が X を上回るのは、総数が仮押さえ中の数を下回ったとき（在庫を 0 にします）で、次の周期も同じように送れば合っていきます。
• 販売分の変動は、変動量（adjustment）で送れます。 絶対値（inventory）は、指定した値をそのまま「いま売れる数」として上書きし、進行中の仮押さえも上書きします（仮押さえ分が後で在庫に戻ると、実際より多くなります）。絶対値を使うのは、販売を始める前の初回の投入と、在庫の管理を始めるとき（在庫を管理していない商品に総在庫の指定を送ると、422 unlimited_inventory になります）だけにしてください。
• 総在庫の指定が使えない環境（/openapi.json の StockUpdateRequest に total_inventory が無い環境＝単独で送ると 400、または、total_inventory に 503 capability_not_enabled が返る環境＝まだ開放されていない。どちらも何も書いていません）では、adjustment = X − (inventory + reserved_inventory) を送ってください。2 つの値は別々に読み取るので、差が出たら読み直して同じ差になることを確かめてから送ります。reserved_inventory のキーが無い応答と、inventory が null の商品では、この式を使わないでください。注文を取り込んでから商品を読むまでの間に確定した販売は、差として打ち消してしまう（次の突合まで実際より多くなる）ので、突合は販売の少ない時間帯に行ってください。 adjustment が 422（negative_inventory）になったら、その変動量を捨てずに、注文を取り込み、商品を読み直して計算し直し、新しい Idempotency-Key で送ります。読み直しても X が reserved_inventory を下回るときに限り inventory: 0 を書き、必ず 10 分ほど後に合わせ直してください。
• 注文明細の種類は variant で特定してください。 明細の sku は商品（親）に現在設定されている SKU で、同じ商品の別の種類でも同じ値になります。variant.id が null のとき（種類の削除・SKU や種類名の変更・同じ SKU の種類が複数ある、など）は、variant.sku と variant.name で照合してください。variant.sku が null（購入時点で SKU が未設定）のときは variant.name で照合し、1 つに決まらなければ人の確認に回してください。
• 取り消された注文は void と closed です。 どちらになっても、在庫は自動では戻りません。
• init は、成立していない注文です。 購入手続きが完了していないか、決済に失敗したものです。現在の購入手続きで作られるものは、通常は金額が 0 で明細もありません。2024 年以前に作られたものには、金額が入っています。注文の一覧は init も返すので、有効な注文として取り込まないでください。購入手続きが完了すると、同じ注文 ID のままステータスが変わり、金額と明細が入ります。init の段階で「処理済み」と記録すると、その注文を取りこぼします。
• 画像を URL 指定で登録する際の送信元（取得元でアクセス制限をかけている場合は許可リストに登録してください）:

項目	値
User-Agent	atouch-api/1.0 (+https://developers.atouch.jp)
Accept	image/jpeg,image/png;q=0.9,*/*;q=0.1

送信元 IP アドレスでの許可設定が必要な場合は、個別にご案内しますのでお問い合わせください。 環境や構成変更で変わり得るため、本ドキュメントには掲載していません。

個人情報（PII）の扱い

買い手の氏名・住所・電話・メール等の PII は、対応する PII スコープを持つトークンにのみ返します。持たない場合は該当フィールド自体をレスポンスに含めません（省略）。決済カード番号や決済代行トークンはどのスコープでも返しません。

次は はじめに でトークン取得と最初の API 呼び出しを行ってください。