atouch API 概要
atouch API を利用することで、既存 atouch（Shop / Admin）の商品・注文・顧客データを標準の OpenAPI 3.1 + OAuth 2.1 で読み書きできます。
本番環境 https://api.developers.atouch.jp で提供しています。商品・注文・顧客の参照に加え、在庫・出荷・商品管理の書き込みに対応しています（すべて冪等）。詳細は下表のとおり。
ご利用にはクライアント資格情報の発行が必要です。運営までご連絡ください。
提供している API（ReadOnly）
| 分類 | 内容 | 必要スコープ |
|---|---|---|
| 商品 / カテゴリ | 商品一覧・詳細、カテゴリ、配送会社、自ショップ情報。updated_since で増分取得・sku 完全一致検索 | read_items / read_users |
| 注文 | 注文ヘッダ・明細・配送（買い手 PII を除く）。updated_since で増分取得（注文検知のポーリングに利用） | 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）／増減。バリエーション商品は 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 - 日時（レスポンス）: 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 型） - エンベロープ: 一覧は
{ "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・在庫管理システムと双方向に同期する場合の注意点です。
- 在庫は変動量（
adjustment）で送ってください。 絶対値（inventory）を定期的に流すと、送信の間に Atouch 側で発生した販売を上書きしてしまい、在庫が過大に戻ります（売り越しの原因）。絶対値を使うのは初回の投入と定期的な突合に限るのが安全です。 adjustmentが 422 で失敗したら、その変動量を捨てずに絶対値で再同期してください。 失敗を無視すると差分が失われたまま進みます（negative_inventory= 結果が負 /unlimited_inventory= 在庫無制限の商品）。- 画像を 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 呼び出しを行ってください。