ReCORE.co-api

Webhook

概要

• Webhookを利用することで各アプリケーションは、定期的なポーリングを行うことなくリアルタイムで、ReCOREデータとの同期や特定のイベントを元に任意の処理ができます。

ヘッダ

• 各メッセージは下記のような共通のヘッダを持っています。

User-Agent: ReCORE-Webhook
X-ReCORE-Message-ID: e878f0a2-fd3f-5884-b4ac-ae1b74bd0f64:5235
X-ReCORE-Timestamp: 2024-05-11T14:57:06.391Z
X-ReCORE-Company-ID: novasto_demo001
X-ReCORE-Topic: bad.status.changed

key	説明
User-Agent	常にReCORE-Webhook
X-ReCORE-Message-ID	メッセージID
X-ReCORE-Timestamp	送信日時
X-ReCORE-Company-ID	企業ID
X-ReCORE-Topic	トピック

注意事項

送信失敗とリトライについて

• 受信側がHTTPステータスコード200番台以外を返したときは送信失敗とみなされます。
• 5秒以内に応答しなかった場合は送信失敗とみなされます。
• 送信リトライは5秒おきに最大5回繰り返され、それでも送信できなかった場合メッセージは破棄されます。

重複配信について

• ほとんどの場合配信は1回だけ行われますが、稀に同じメッセージが複数回配信される場合があります。
• 冪等性を考慮して設計し、担保できない場合はX-ReCORE-Message-IDを使い、重複排除処理を行ってください。

配信の順序保証について

• ほとんどの場合配信はイベントが発生した順に行われますが、稀に順番が前後して配信される場合があります。
• 配信順序の担保が必要な場合はX-ReCORE-Timestampを使い、適切な実装を行ってください。

bodyの形式について

• bodyは対応する取得APIのレスポンスを基準とした形式で配信します。
• イベント処理に追加リクエストが不要になるよう、関連リソース(商品など)を埋め込みで含む場合があります。取得APIとの差分は各トピックのbodyに明記します。

トピック

bad.status.changed

概要

• 宅配買取ケースのステータスが変更になったときに通知

body

宅配買取ケース取得とほぼ同様
差分は下記を参照

key	type	説明
goods.*.product	object	商品
goods.*.product.id	int	商品ID
goods.*.product.code	string	商品コード
goods.*.product.alias_code	string | null	代替商品コード
goods.*.product.status	string	ステータス
goods.*.product.title	string	商品名
goods.*.product.image_url	string | null	商品画像URL
goods.*.product.category	object	カテゴリ
goods.*.product.category.id	int	カテゴリID
goods.*.product.category.name	string	カテゴリ名
goods.*.product.category.ancestors	array<object>	親カテゴリ、カテゴリ先頭から並ぶ
goods.*.product.category.ancestors.*.id	int	親カテゴリID
goods.*.product.category.ancestors.*.name	string	親カテゴリ名
goods.*.product.created_at	int | null	作成日時
goods.*.product.updated_at	int | null	更新日時

bad.sub_status.changed

概要

• 宅配買取ケースのサブステータスが変更になったときに通知

body

bad.status.changedと同様

bad.return_status.changed

概要

• 宅配買取ケースの返送ステータスが変更になったときに通知
• 返品ケースのbad.return.status.changedとは別のトピック

body

bad.status.changedと同様

bad.return.status.changed

概要

• 宅配買取の返品ケースのステータスが変更になったときに通知
• 商品を返送するbad.return_status.changedとは別のトピック

body

宅配買取の返品取得と同様

bas.status.changed

概要

• 店頭買取ケースのステータスが変更になったときに通知

body

店頭買取ケース取得とほぼ同様
差分は下記を参照

key	type	説明
goods.*.product	object	商品
goods.*.product.id	int	商品ID
goods.*.product.code	string	商品コード
goods.*.product.alias_code	string | null	代替商品コード
goods.*.product.status	string	ステータス
goods.*.product.title	string	商品名
goods.*.product.image_url	string | null	商品画像URL
goods.*.product.category	object	カテゴリ
goods.*.product.category.id	int	カテゴリID
goods.*.product.category.name	string	カテゴリ名
goods.*.product.category.ancestors	array<object>	親カテゴリ、カテゴリ先頭から並ぶ
goods.*.product.category.ancestors.*.id	int	親カテゴリID
goods.*.product.category.ancestors.*.name	string	親カテゴリ名
goods.*.product.created_at	int | null	作成日時
goods.*.product.updated_at	int | null	更新日時

bas.sub_status.changed

概要

• 店頭買取ケースのサブステータスが変更になったときに通知

body

bas.status.changedと同様

bas.return.status.changed

概要

• 店頭買取の返品ケースのステータスが変更になったときに通知

body

店頭買取の返品取得と同様

big.status.changed

概要

• 一般仕入ケースのステータスが変更になったときに通知

body

一般仕入ケース取得と同様

big.sub_status.changed

概要

• 一般仕入ケースのサブステータスが変更になったときに通知

body

big.status.changedと同様

big.return.status.changed

概要

• 一般仕入の返品ケースのステータスが変更になったときに通知

body

一般仕入の返品取得と同様

sas.status.changed

概要

• 店頭販売ケースのステータスが変更になったときに通知

body

店頭販売ケース取得と同様

sas.sub_status.changed

概要

• 店頭販売ケースのサブステータスが変更になったときに通知

body

sas.status.changedと同様

sas.return.status.changed

概要

• 店頭販売の返品ケースのステータスが変更になったときに通知

body

店頭販売の返品取得と同様

sig.status.changed

概要

• 一般販売ケースのステータスが変更になったときに通知

body

一般販売ケース取得と同様

sig.sub_status.changed

概要

• 一般販売ケースのサブステータスが変更になったときに通知

body

sig.status.changedと同様

sig.return.status.changed

概要

• 一般販売の返品ケースのステータスが変更になったときに通知

body

一般販売の返品取得と同様

item.change_store.status.changed

概要

• 在庫店舗変更（店間移動）ケースのステータスが変更になったときに通知

body

在庫店舗変更ケース取得とほぼ同様
差分は下記を参照

key	type	説明
details.*.src_item.product	object	移動元在庫の商品 商品取得(sm)のレスポンスと同様
details.*.dist_item.product	object	移動先在庫の商品 商品取得(sm)のレスポンスと同様

item.change_store.sub_status.changed

概要

• 在庫店舗変更（店間移動）ケースのサブステータスが変更になったときに通知

body

item.change_store.status.changedと同様

item.transfer.created

概要

• 在庫振替が実行されたときに通知
• 在庫振替ケースはステータスを持たず、実行後に変更されることはないため、通知は1ケースにつき1回のみ
• detailsに振替元(src_item)と振替先(dist_item)の対応が含まれる

body

在庫振替ケース取得とほぼ同様
差分は下記を参照

key	type	説明
details.*.src_item.product	object	振替元在庫の商品 商品取得(sm)のレスポンスと同様
details.*.dist_item.product	object	振替先在庫の商品 商品取得(sm)のレスポンスと同様

item.disposal.created

概要

• 在庫廃棄が実行されたときに通知
• 在庫廃棄ケースはステータスを持たず、実行後に変更されることはないため、通知は1ケースにつき1回のみ
• 1回の廃棄操作で複数店舗の在庫を指定した場合、店舗ごとにケースが作成されるため、ケースの数だけ通知される

body

在庫廃棄ケース取得とほぼ同様
差分は下記を参照

key	type	説明
details.*.item.product	object	廃棄した在庫の商品 商品取得(sm)のレスポンスと同様

identification.status.changed

概要

• 本人確認のステータスが変更になったときに通知

body

本人確認取得と同様

provider.gmo_bank.status.changed [廃止予定]

概要

• GMO銀行振込のステータスが変更になったときに通知
• このトピックは後方互換性のために維持されています。新規実装では bank_transfer.status.changed を使用してください。

body

GMO銀行振込取得と同様

bank_transfer.status.changed

概要

• 銀行振込のステータスが変更になったときに通知

body

銀行振込詳細取得と同様

provider.pickup.status.changed

概要

• ヤマト集荷のステータスが変更になったときに通知

body

{
  "id": 2,
  "status": "COLLECTING",
  "tracking_number": null,
  "pickup_date": "2024-06-09",
  "pickup_time": "16",
  "referable_id": 40,
  "referable_type": "rt_bad",
  "closing_at": 1717797600,
  "created_at": 1717819826,
  "updated_at": 1717821794
}

key	type	説明
id	int	集荷ID
status	string	ステータス
tracking_number	string | null	問い合わせ番号
pickup_date	string	集荷日時
pickup_time	string | null	集荷時間コード 宅配買取の希望集荷時間帯コード表を参照
referable_id	int | null	関連先ID
referable_type	string | null	関連先タイプ
closing_at	int | null	変更締め日時
created_at	int | null	作成日時
updated_at	int | null	更新日時

• ステータス
  • PENDING 依頼中
  • COLLECTING 集荷中
  • COLLECTED 集荷済み
  • DONE 配達完了
  • FAILED エラー

member.created

概要

• 会員が作成されたときに通知

body

会員取得と同様

member.updated

概要

• 会員が更新されたときに通知
• 会員ポイントが更新されたときに通知

body

会員取得と同様

product.created

概要

• 商品が作成されたときに通知

body

商品取得と同様

product.updated

概要

• 商品が更新されたときに通知

body

商品取得と同様

item.created

概要

• 在庫が作成されたときに通知

body

在庫取得と同様

item.updated

概要

• 在庫が更新されたときに通知
• 在庫価格が更新されたときに通知
• 在庫数が更新されたときに通知

body

在庫取得と同様

item.price.changed

概要

• 在庫価格が更新されたときに通知

body

在庫取得と同様

item.stock.changed

概要

• 在庫数が更新されたときに通知

body

在庫取得と同様

item.stocktaking.status.changed

概要

• 棚卸しケースのステータスが変更になったときに通知

body

棚卸し取得と同様

ec.order.status.changed

概要

• EC受注のステータスが変更になったときに通知

body

受注取得と同様

ec.order.sub_status.changed

概要

• EC受注のサブステータスが変更になったときに通知

body

受注取得と同様

Webhook登録API

登録済みWebhook検索

概要

• 登録済みWebhookの検索を行う

基本情報

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

query

なし

例

• Request

GET /webhooks

• Response

[
  {
    "id": "01HXM1FRZY28Q8QE6A1F984GA0",
    "address": "https://example.com",
    "topics": [
      "bad.status.changed"
    ]
  }
]

key	type	説明
*	array<object>	Webhook
*.id	string	WebhookID
*.address	string	配信先URL
*.topics	array<string>	受信トピック

登録済みWebhook取得

概要

• 登録済みWebhookを1件取得する

基本情報

• リクエストパス: GET /webhooks/{webhook_id}
• スコープ: webhook:show
• 店舗IDの指定: 必要なし
• 基本制限レート: 5 rps

例

• Request

GET /webhooks/01HXM1FRZY28Q8QE6A1F984GA0

• Response

登録済みWebhook検索のresponse[0]と同様

Webhook登録

概要

• Webhookを登録する

基本情報

• リクエストパス: POST /webhooks
• スコープ: webhook:store
• 店舗IDの指定: 必要なし
• 基本制限レート: 2 rps

body

key	type	説明	制約など
address	string	配信先URL	-
topics	array<string>	受信トピック	-

例

• Request

POST /webhooks

{
  "address": "https://example.com",
  "topics": [
    "bad.status.changed"
  ]
}

• Response

登録済みWebhook取得と同様

登録済みWebhook更新

概要

• 登録済みWebhookを更新する

基本情報

• リクエストパス: PUT /webhooks/{webhook_id}
• スコープ: webhook:update
• 店舗IDの指定: 必要なし
• 基本制限レート: 2 rps

body

key	type	説明	制約など
address	?string	配信先URL	-
topics	?array<string>	受信トピック	-

例

• Request

PUT /webhooks/01HXM1FRZY28Q8QE6A1F984GA0

{
  "address": "https://example.com",
  "topics": [
    "bad.status.changed"
  ]
}

• Response

登録済みWebhook取得と同様

登録済みWebhook削除

概要

• 登録済みWebhookを削除する

基本情報

• リクエストパス: DELETE /webhooks/{webhook_id}
• スコープ: webhook:destroy
• 店舗IDの指定: 必要なし
• 基本制限レート: 2 rps

例

• Request

DELETE /webhooks/01HXM1FRZY28Q8QE6A1F984GA0

• Response

なし