atouch API 概要
atouch API を利用することで、既存 atouch（Shop / Admin）の商品・注文・顧客データを標準の OpenAPI 3.1 + OAuth 2.1 で読み書きできます。
現在は クローズドβ。商品・注文・顧客の参照に加え、在庫・出荷・商品管理の書き込みを公開中です（すべて冪等・変更は操作履歴に記録）。詳細は下表のとおり。
提供している API（ReadOnly）
| 分類 | 内容 | 必要スコープ |
|---|---|---|
| 商品 / カテゴリ | 商品一覧・詳細、カテゴリ、配送会社、自ショップ情報 | read_items / read_users |
| 注文 | 注文ヘッダ・明細・配送（買い手 PII を除く） | 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）／増減。set 商品・バリエーション在庫（variant_id）は順次開放 | write_items |
| 商品 | 新規登録（全種類: 通常/ギフト/チケット/無料チケット/先行販売チケット/セット）・既存商品の編集（部分更新・修正ログ記録） | write_items |
| カテゴリー | 作成（階層 2 段まで・並び順は末尾自動採番）・編集（名前/公開状態/並び順） | write_items |
| 商品画像 | URL 指定でメイン画像の差し替え・追加画像の登録（JPEG/PNG・実バイト検証）。登録→画像→公開が API だけで完結 | write_items |
書き込み系はすべて Idempotency-Key ヘッダー必須です（同一キーの再送は安全に再生されます）。変更はマーチャントの修正ログに記録されます。
基本仕様
- ベース URL（dev）:
https://api.dev.developers.atouch.jp - プロトコル: HTTPS のみ
- データ形式:
application/json; charset=utf-8 - 日時: ISO 8601 + JST（例
2026-06-01T12:00:00+09:00） - 金額:
{ "amount": 3200, "currency": "JPY" }（Money 型） - エンベロープ: 単一
{ "data": {...} }/ 一覧{ "data": [...], "pagination": {...} }/ エラー{ "error": { code, message } }
個人情報（PII）の扱い
買い手の氏名・住所・電話・メール等の PII は、対応する PII スコープを持つトークンにのみ返します。持たない場合は該当フィールド自体をレスポンスに含めません（省略）。決済カード番号や決済代行トークンはどのスコープでも返しません。
次は はじめに でトークン取得と最初の API 呼び出しを行ってください。