ReCORE.co-api

ECゲートウェイ

概要

ECゲートウェイは、任意のECモール・ECプラットフォームとReCOREを連携するためのAPI群です。 ReCOREが直接連携に対応していないモールでも、このAPIを利用することでReCOREと統合することができます。 利用を開始する場合は、弊社営業担当を通じECアカウントとして「汎用」を追加しec_account_idを発行してください。

連携フロー

出品・受注管理フロー

1. ReCORE上で出品・在庫更新などの操作が行われると、タスクが発行されます
2. 外部システムは /ec/gateway/tasks を定期的にポーリングしてタスクを取得します
3. タスクの内容に応じてECモール側で処理を実行します
4. 処理完了後、成功時は /ec/gateway/tasks/{task_id}/succeeded、失敗時は /ec/gateway/tasks/{task_id}/failed を呼び出して結果を報告します

受注取り込みフロー

1. ECモールで受注が発生したら、外部システムは /ec/gateway/order/upsert を呼び出して受注情報をReCOREに送信します
2. 定期的にECモールの受注情報をポーリングし、新規・更新があれば送信してください

タスク一覧取得

概要

• 処理待ちのタスク一覧を取得する
• 外部システムは定期的にこのエンドポイントをポーリングしてタスクを取得する

基本情報

• リクエストパス: GET /ec/gateway/tasks
• スコープ: ec:gateway:task:index
• 店舗IDの指定: 必要なし
• 基本制限レート: 5 rps

query

key	説明	制約など
ec_account_id	ECアカウントID	必須
type	タスクタイプで絞り込み	任意、下記タスクタイプ参照

例

• Request

GET /ec/gateway/tasks?ec_account_id=1

• Response

[
  {
    "id": "01HQXYZ123ABC456DEF789GHJ",
    "mall_id": "GENERAL",
    "type": "CREATE_INVENTORY",
    "ec_account_id": 1,
    "data": {
      "ec_inventory_id": 123
    },
    "issued_at": 1708054490
  }
]

key	type	説明
*	array<object>	タスク一覧
*.id	string	タスクID
*.mall_id	string	モールID（常にGENERAL）
*.type	string	タスクタイプ
*.ec_account_id	int	ECアカウントID
*.data	object	タスク固有のデータ
*.issued_at	int	タスク発行日時（Unix timestamp）

タスクタイプ一覧

以下の10種類のタスクタイプが存在します。

出品関連

CREATE_INVENTORY（出品作成）

ReCOREで新規出品が作成された際に発行されます。

data内のkey	type	説明
ec_inventory_id	int	出品ID

• モール側で出品作成を行ってください
• 詳細情報は GET /ec/inventories/{ec_inventory_id} で取得してください

UPDATE_INVENTORY（出品情報更新）

出品情報（タイトル、説明文、画像など）が更新された際に発行されます。

data内のkey	type	説明
ec_inventory_id	int	出品ID

• モール側で出品情報の更新を行ってください
• 詳細情報は GET /ec/inventories/{ec_inventory_id} で取得してください

UPDATE_PRICE（価格更新）

出品商品の価格が更新された際に発行されます。

data内のkey	type	説明
ec_inventory_id	int	出品ID
ec_inventory_variant_id	int	出品バリエーションID

• モール側で出品価格の更新を行ってください
• 詳細情報は GET /ec/inventories/{ec_inventory_id} で取得してください
• variants 配列から該当の ec_inventory_variant_id の出品情報を参照してください

UPDATE_STOCK（在庫数更新）

出品商品の在庫数が更新された際に発行されます。

data内のkey	type	説明
ec_inventory_id	int	出品ID
ec_inventory_variant_id	int	出品バリエーションID

• モール側で在庫数の更新を行ってください
• 詳細情報は GET /ec/inventories/{ec_inventory_id} で取得してください
• variants 配列から該当の ec_inventory_variant_id の出品情報を参照してください

DELETE_INVENTORY（出品削除）

出品が削除された際に発行されます。

data内のkey	type	説明
ec_inventory_id	int	出品ID

• モール側で該当商品を削除してください
• 詳細情報は GET /ec/inventories/{ec_inventory_id} で取得してください

OPEN_INVENTORY（出品公開）

出品を公開状態にする際に発行されます。

data内のkey	type	説明
ec_inventory_id	int	出品ID

• モール側で該当商品を公開状態にしてください
• 詳細情報は GET /ec/inventories/{ec_inventory_id} で取得してください

CLOSE_INVENTORY（出品終了）

出品を終了状態にする際に発行されます。

data内のkey	type	説明
ec_inventory_id	int	出品ID

• モール側で該当商品を非公開状態にしてください
• 詳細情報は GET /ec/inventories/{ec_inventory_id} で取得してください

受注関連

CONFIRM_ORDER（入金確認）

受注の入金確認を行う際に発行されます。

data内のkey	type	説明
ec_order_id	int	受注ID

• モール側で入金確認処理を行ってください
• 詳細情報は GET /ec/orders/{ec_order_id} で取得してください

FULFILL_ORDER（出荷）

受注の出荷処理を行う際に発行されます。

data内のkey	type	説明
ec_order_id	int	受注ID
ec_fulfillment_id	int	出荷ID

• 詳細情報は GET /ec/orders/{ec_order_id} で取得してください
• fulfillments 配列から該当の ec_fulfillment_id の出荷情報を参照してください

CANCEL_ORDER（キャンセル）

受注のキャンセル処理を行う際に発行されます。

data内のkey	type	説明
ec_order_id	int	受注ID
reason	string	キャンセル理由

• モール側でキャンセル処理を行ってください
• 詳細情報は GET /ec/orders/{ec_order_id} で取得してください

タスク成功報告

概要

• タスクの処理が成功したことを報告する
• タスクは報告後に削除される

基本情報

• リクエストパス: PUT /ec/gateway/tasks/{task_id}/succeeded
• スコープ: ec:gateway:task:succeeded:update
• 店舗IDの指定: 必要なし
• 基本制限レート: 20 rps

path

key	説明	制約など
task_id	タスクID	必須

body

key	type	説明	制約など
type	string	タスクタイプ	必須、タスクのtypeと一致する必要がある
data	?object	タスク固有の結果データ	タスクタイプにより異なる

タスクタイプ別のdataパラメータ:

タスクタイプ	必須パラメータ
CREATE_INVENTORY	mall_product_code: モール側で発行された商品コード
UPDATE_INVENTORY	なし
UPDATE_PRICE	なし
UPDATE_STOCK	なし
DELETE_INVENTORY	なし
OPEN_INVENTORY	なし
CLOSE_INVENTORY	なし
CONFIRM_ORDER	なし
FULFILL_ORDER	なし
CANCEL_ORDER	なし

例

• Request

PUT /ec/gateway/tasks/01HQXYZ123ABC456DEF789GHJ/succeeded

{
  "type": "CREATE_INVENTORY",
  "data": {
    "mall_product_code": "SHOP-12345"
  }
}

• Response

204 No Content

タスク失敗報告

概要

• タスクの処理が失敗したことを報告する
• タスクは報告後に削除される
• ReCORE上ではエラーとして記録される

基本情報

• リクエストパス: PUT /ec/gateway/tasks/{task_id}/failed
• スコープ: ec:gateway:task:failed:update
• 店舗IDの指定: 必要なし
• 基本制限レート: 20 rps

path

key	説明	制約など
task_id	タスクID	必須

body

key	type	説明	制約など
type	string	タスクタイプ	必須、タスクのtypeと一致する必要がある
data	?object	エラー情報	任意
data.code	?string | null	エラーコード	任意
data.message	?string | null	エラーメッセージ	任意

例

• Request

PUT /ec/gateway/tasks/01HQXYZ123ABC456DEF789GHJ/failed

{
  "type": "UPDATE_STOCK",
  "data": {
    "code": "OUT_OF_STOCK",
    "message": "モール側で在庫更新に失敗しました"
  }
}

• Response

204 No Content

受注登録・更新

概要

• ECモールの受注情報をReCOREに登録・更新する
• mall_order_id をキーとしてupsertされる（同一のmall_order_idの場合は更新）
• 外部システムはECモールの受注情報を定期的にポーリングし、このエンドポイントに送信する

基本情報

• リクエストパス: POST /ec/gateway/order/upsert
• スコープ: ec:gateway:order:upsert:store
• 店舗IDの指定: 必要なし
• 基本制限レート: 20 rps

body

key	type	説明	制約など
mall_id	string	モールID	必須、GENERAL固定
ec_account_id	int	ECアカウントID	必須
data	object	受注データ	必須
data.mall_order_id	string	モール受注ID	必須、50文字以内
data.status	string	受注ステータス	必須、下記参照
data.fraud_status	string | null	不正検知ステータス	下記参照
data.ordered_at	string	受注日時	必須、ISO 8601形式
data.shipped_at	string | null	出荷日時	ISO 8601形式
data.payment_total	int	お客様支払額	必須、0以上
data.payment_method	string | null	支払い方法	-
data.shipping_method	string | null	配送方法	-
data.buyer_name	string | null	購入者氏名	100文字以内
data.buyer_name_kana	string | null	購入者かな	100文字以内
data.buyer_email	string | null	購入者メールアドレス	256文字以内
data.shipping_postal_code	string | null	配送先郵便番号	20文字以内
data.shipping_country_code	string | null	配送先国コード	ISO-3166、2文字
data.shipping_state_or_region	string | null	配送先都道府県	200文字以内
data.shipping_city	string | null	配送先市区町村	200文字以内
data.shipping_address1	string | null	配送先住所1	-
data.shipping_address2	string | null	配送先住所2	-
data.shipping_address3	string | null	配送先住所3	-
data.shipping_phone	string | null	配送先電話番号	50文字以内
data.shipping_name	string | null	配送先宛名	100文字以内
data.earliest_delivery_at	string | null	配送日時指定（開始）	ISO 8601形式
data.latest_delivery_at	string | null	配送日時指定（終了）	ISO 8601形式
data.comment	string | null	受注時備考	-
data.member_id	int | null	会員ID	ReCOREの会員IDを指定
data.order_adjustment	int	受注全体調整額	必須
data.shipping_price	int	送料	必須、0以上
data.shipping_tax	int	送料消費税額	必須、0以上
data.shipping_tax_rate_type	string	送料税区分	必須、下記参照
data.payment_price	int	支払手数料	必須、0以上
data.payment_tax	int	支払手数料消費税額	必須、0以上
data.payment_tax_rate_type	string	支払手数料税区分	必須、下記参照
data.option_price	int	サービス料	必須、0以上
data.option_tax	int	サービス料消費税額	必須、0以上
data.option_tax_rate_type	string	サービス料税区分	必須、下記参照
data.earned_point	int	獲得ポイント	必須、0以上
data.goods	array<object>	受注明細	必須
data.goods.*.mall_item_id	string	モール明細ID	必須、50文字以内
data.goods.*.mall_item_code	string | null	モールSKU	50文字以内
data.goods.*.unit_price	int	単価	必須、0以上
data.goods.*.unit_adjustment	int	単価調整額	必須、0以上
data.goods.*.tax	int	消費税額	必須、0以上
data.goods.*.tax_rate_type	string	税区分	必須、下記参照
data.goods.*.quantity	int	数量	必須、0以上
data.goods.*.title	string | null	商品名	-
data.goods.*.comment	string | null	明細備考	-

受注ステータス

値	説明
PENDING	代金未回収状態、発送不可
UNSHIPPED	代金回収済み、発送可
SHIPPED	出荷済み
CANCELED	キャンセル済み
OTHER	その他（予期しない状態）

• 確定状態（SHIPPED または CANCELED）の受注は更新できません。これらのステータスの受注に対してupsertを行った場合、リクエストは無視されます。

不正検知ステータス

値	説明
SAFE	安全
PENDING	判定中
HIGH_RISK	高リスク
MEDIUM_RISK	中リスク
null	未判定

税区分

値	説明
GENERAL	一般
RELIEF	軽減税率
NO_TAX	非課税

例

• Request

POST /ec/gateway/order/upsert

{
  "mall_id": "GENERAL",
  "ec_account_id": 1,
  "data": {
    "mall_order_id": "ORDER-12345",
    "status": "UNSHIPPED",
    "fraud_status": null,
    "ordered_at": "2024-02-12T10:30:00+09:00",
    "shipped_at": null,
    "payment_total": 3300,
    "payment_method": "クレジットカード",
    "shipping_method": "宅急便",
    "buyer_name": "山田 太郎",
    "buyer_name_kana": "ヤマダ タロウ",
    "buyer_email": "yamada@example.com",
    "shipping_postal_code": "150-0001",
    "shipping_country_code": "JP",
    "shipping_state_or_region": "東京都",
    "shipping_city": "渋谷区",
    "shipping_address1": "神宮前1-2-3",
    "shipping_address2": "ABCビル 5F",
    "shipping_address3": null,
    "shipping_phone": "03-1234-5678",
    "shipping_name": "山田 太郎",
    "earliest_delivery_at": "2024-02-15T09:00:00+09:00",
    "latest_delivery_at": "2024-02-15T18:00:00+09:00",
    "comment": "配達時に不在の場合は宅配ボックスへ",
    "member_id": null,
    "order_adjustment": 0,
    "shipping_price": 500,
    "shipping_tax": 50,
    "shipping_tax_rate_type": "GENERAL",
    "payment_price": 0,
    "payment_tax": 0,
    "payment_tax_rate_type": "GENERAL",
    "option_price": 0,
    "option_tax": 0,
    "option_tax_rate_type": "GENERAL",
    "earned_point": 0,
    "goods": [
      {
        "mall_item_id": "ITEM-001",
        "mall_item_code": "SKU-001",
        "unit_price": 2500,
        "unit_adjustment": 0,
        "tax": 250,
        "tax_rate_type": "GENERAL",
        "quantity": 1,
        "title": "テスト商品A",
        "comment": null
      }
    ]
  }
}

• Response

204 No Content

実装ガイドライン

ポーリング間隔

• タスク取得のポーリング間隔は数秒程度を推奨します
• 基本制限レートを超えないよう注意してください

エラーハンドリング

• モール側でのエラー発生時は、適切なエラーコードとメッセージを付与して失敗報告を行ってください
• 一時的なエラーの場合はリトライを実装することを推奨します
• タスクは7日間で自動削除されるため、それまでに処理を完了してください

受注同期

• 受注情報は定期的にECモールから取得し、変更があればupsertエンドポイントで同期してください
• mall_order_id で一意に識別されるため、同じIDで送信すると更新となります
• ステータス変更も含めて最新の状態を送信してください