cXML という電子商取引のトランザクションを支えるプロトコルと向きあっている話

Slide 1

Slide 1 text

cXML という電子商取引のトランザクションを支えるプロトコルと向きあっている話 Kaigi on Rails 2024 Day1 - 10.25 (Fri.) Hall Blue Leaner Technologies Inc. @phigasui / がーしー

Slide 2

Slide 2 text

2 cXMLって聞いたことありますか?

Slide 3

Slide 3 text

3 cXML とは cXML とは ● 電子商取引(EC)に関するシステム間で一貫したドキュメントでの通信を目的としたプロトコル ○ 例「注文ではこのフォーマットでリクエストしてください」というのが定義されているここで知っておいてほしいこと ● システム間連携開発をやるよ ● 共通化されたプロトコルがあるよ

Slide 4

Slide 4 text

4 伝えたいこと ● cXML というニッチだけど面白い技術があるよ ○ おもしろい仕様の一例を紹介 ● システム間の連携開発を通した学び ○ 実際におきた大変だったこと ○ 乗り越えるためにやっていること

Slide 5

Slide 5 text

5 目次 ● なぜ cXML と向きあっているのか ● cXML とパンチアウト連携 ● 実際に発生した問題とそこからの学び

Slide 6

Slide 6 text

6 目次 ● なぜ cXML と向きあっているのか ● cXML とパンチアウト連携 ● 実際に発生した問題とそこからの学び

Slide 7

Slide 7 text

7 なぜ cXML と向きあっているのか A社 EC B社 EC C社 EC A社 EC B社 EC C社 EC 購買システム: 多様な取引先からの購買業務を一元管理それぞれの EC サイトで登録・ログインが必要購買システムにだけ登録・ログイン

Slide 8

Slide 8 text

8 なぜ cXML と向きあっているのか ● 複数の EC サイトと連携する必要がある ● 各接続先の API で連携しシステムを構築 ↓ 電子商取引(EC)では cXML というプロトコルが使われている A社 EC B社 EC C社 EC

Slide 9

Slide 9 text

9 目次 ● なぜ cXML と向きあっているのか ● cXML とパンチアウト連携 ● 実際に発生した問題とそこからの学び

Slide 10

Slide 10 text

10 cXML とパンチアウト連携 cXML とは commerce eXtensible Markup Language の略通信のモデルとデータ構造を定義している連携を楽にするため、パンチアウト連携という仕組みが用意されている

Slide 11

Slide 11 text

11 cXML とパンチアウト連携パンチアウト連携 ● EC の機能を使いながら購買の情報を連携 ECサイト ③商品をカートに追加購買システム ⑤購買の次ステップ (購買承認依頼など) リーニャー商品ページチェックアウト購買申請する ①アクセス ②チェックイン (ECサイトに自動ログイン) ④チェックアウト (カート情報を購買システムへ持ち帰る) 購買システムリーナーECで商品を探す

Slide 12

Slide 12 text

12 cXML とパンチアウト連携パンチアウト連携 ● EC の機能を使いながら購買の情報を連携 ECサイト ③商品をカートに追加購買システム ⑤購買の次ステップ (購買承認依頼など) リーニャー商品ページチェックアウト購買申請する ①アクセス ②チェックイン (購買システムに自動ログイン) ④チェックアウト (カート情報を購買システムへ持ち帰る) 購買システムリーナーECで商品を探す

Slide 13

Slide 13 text

13 cXML とパンチアウト連携パンチアウト連携 ● EC の機能を使いながら購買の情報を連携購買システム ⑤購買の次ステップ (購買承認依頼など) 購買申請する ①アクセス ④チェックアウト (カート情報を購買システムへ持ち帰る) 購買システムリーナーECで商品を探す ECサイト ③商品をカートに追加リーニャー商品ページチェックアウト ②チェックイン (ECサイトに自動ログイン)

Slide 14

Slide 14 text

14 cXML とパンチアウト連携パンチアウト連携 ● EC の機能を使いながら購買の情報を連携購買システム ⑤購買の次ステップ (購買承認依頼など) 購買申請する ①アクセス購買システムリーナーECで商品を探す ECサイト ③商品をカートに追加リーニャー商品ページチェックアウト ②チェックイン (ECサイトに自動ログイン) ④チェックアウト (カート情報を購買システムへ持ち帰る)

Slide 15

Slide 15 text

15 cXML とパンチアウト連携パンチアウト連携 ● EC の機能を使いながら購買の情報を連携 ECサイト ③商品をカートに追加購買システム ⑤購買の次ステップ (購買承認依頼など) リーニャー商品ページチェックアウト購買申請する ①アクセス ②チェックイン (ECサイトに自動ログイン) ④チェックアウト (カート情報を購買システムへ持ち帰る) 購買システムリーナーECで商品を探す？？

Slide 16

Slide 16 text

16 cXML とパンチアウト連携パンチアウト連携 ● EC の機能を使いながら購買の情報を連携購買システム ⑤購買の次ステップ (購買承認依頼など) 購買申請する ①アクセス ④チェックアウト (カート情報を購買システムへ持ち帰る) 購買システムリーナーECで商品を探す ECサイト ③商品をカートに追加リーニャー商品ページチェックアウト ②チェックイン (ECサイトに自動ログイン)

Slide 17

Slide 17 text

17 cXML とパンチアウト連携パンチアウト開始のリクエスト EC サイトでユーザー登録・ログインするための情報購買システムに戻る時に対象のカートを特定するための情報カート情報の送信先購買システムに戻る時に POSTしてもらうエンドポイント

Slide 18

Slide 18 text

18 cXML とパンチアウト連携パンチアウト連携 ● EC の機能を使いながら購買の情報を連携購買システム ⑤購買の次ステップ (購買承認依頼など) 購買申請する ①アクセス購買システムリーナーECで商品を探す ECサイト ③商品をカートに追加リーニャー商品ページチェックアウト ②チェックイン (ECサイトに自動ログイン) ④チェックアウト (カート情報を購買システムへ持ち帰る)

Slide 19

Slide 19 text

19 cXML とパンチアウト連携カート情報の連携購買システムに戻る時に対象のカートを特定するための情報パンチアウト開始時に連携したBuyerCookie

Slide 20

Slide 20 text

20 cXML とパンチアウト連携 cXML のリファレンスに600ページに渡ってほかにもたくさんの仕様が定義されている ● 注文のリクエスト ● 注文受理、キャンセルのリクエスト ● 出荷の情報などなど引用:「cXML Reference Guide」 https://xml.cxml.org/current/cXMLReferenceGuide_ja.pdf

Slide 21

Slide 21 text

21 cXML仕様実装すればどんな EC サイトとも連携できる!!

Slide 22

Slide 22 text

22 cXML仕様実装すればどんな EC サイトとも連携できる!! → ほんとうか?

Slide 23

Slide 23 text

23 目次 ● なぜ cXML と向きあっているのか ● cXML とパンチアウト連携 ● 実際に発生した問題とそこからの学び

Slide 24

Slide 24 text

24 ここまでのおさらい ● 複数の EC サイトとプロダクト間の連携が必要になる ● cXML というプロトコルで共通の仕様が定義されている ○ この仕様に則れば汎用的に連携できる ○ ただし、仕様は膨大

Slide 25

Slide 25 text

25 実際に発生した問題 ● 各接続先で異なる cXML の仕様がある ● いろいろな制約がある ○ 物理的な制限や各 EC での特殊な仕様 ● そもそも、cXML の仕様すべて対応できているわけではない ○ 我々のプロダクトも、連携先も...

Slide 26

Slide 26 text

26 実際に発生した問題 ● 各接続先で異なる cXML の仕様がある ● いろいろな制約がある ○ 物理的な制限や各 EC での特殊な仕様 ● そもそも、cXML の仕様すべて対応できているわけではない ○ 我々のプロダクトも、連携先も...

Slide 27

Slide 27 text

27 実際に発生した問題 - cXML の仕様のちがいの例 cXML では Extrinsic という要素が定義されている引用:「cXML Reference Guide」 https://xml.cxml.org/current/cXMLReferenceGuide_ja.pdf 日本語訳: 「非本質的な、付帯的な」

Slide 28

Slide 28 text

28 実際に発生した問題 - cXML の仕様のちがいの例各 EC 向けにサブクラスを実装して仕様のちがいを吸収リクエストにフックして実装するメソッドをオーバーライド

Slide 29

Slide 29 text

29 実際に発生した問題 - cXML の仕様のちがいの例仕様のちがいをのりこえていくために ● 連携先との仕様の認識すりあわせ ○ リーナーで定義した cXML 仕様をベースに調整

Slide 30

Slide 30 text

30 実際に発生した問題 ● 各接続先で異なる cXML の仕様がある ● いろいろな制約がある ○ 物理的な制限や各 EC での特殊な仕様 ● そもそも、cXML の仕様すべて対応できているわけではない ○ 我々のプロダクトも、連携先も...

Slide 31

Slide 31 text

31 実際に発生した問題 - 物理的な制約の例 ● cXML 各要素、属性の文字数までは決められない ○ 各 EC サイトで文字数の上限が異なるため注意が必要 ● とくに厄介なのが配送先の文字数 ○ 最終的には伝票に印字されるため物理的な限界がある

Slide 32

Slide 32 text

32 実際に発生した問題 - 物理的な制約の例実際にリーナー宛に届いた(届かなかった)商品の配送伝票 ● 謎の文字列入ってる ● お届け先の欄からはみ出てる ● Leaner Tec で途切れてる宛先不明となり営業所止めに担当者名

Slide 33

Slide 33 text

33 実際に発生した問題 - 物理的な制約の例仕様外の制約をのりこえていくために ● 連携のシナリオテスト ○ 連携先とそれぞれ確認が必要なケースを洗い出す ■ 例) 各税率の商品、情報が連携されるタイミング動的情報の最大文字数パターン、などなど ○ これで事前に文字数制限をキャッチできたこともあったテストケースのドキュメント

Slide 34

Slide 34 text

34 実際に発生した問題 ● 各接続先で異なる cXML の仕様がある ● いろいろな制約がある ○ 物理的な制限や各 EC での特殊な仕様 ● そもそも、cXML の仕様すべて対応できているわけではない ○ 我々のプロダクトも、連携先も...

Slide 35

Slide 35 text

35 実際に発生した問題 - 対応できていなかった cXML 仕様の例 ● 同一商品を複数個注文した内の一部キャンセル ○ 例: ボールペンを8本注文した内、2本だけ在庫切れでキャンセル

Slide 36

Slide 36 text

36 実際に発生した問題 - 対応できていなかった cXML 仕様の例 ● EC サイトから購買システムへ送信される注文の結果例. キャンセルされた時の cXML 意図しない type の場合処理方法が不明なため Error を通知

Slide 37

Slide 37 text

37 実際に発生した問題 - 対応できていなかった cXML 仕様の例 ● 通知されたエラーでは type が nil になっていた ○ 幸いイベントログを取得している 😌 ○ cXML のログを見てみると... ConﬁrmationStatus はいつも 1つ ConﬁrmationStatus が 2つ？

Slide 38

Slide 38 text

38 実際に発生した問題 - 対応できていなかった cXML 仕様の例 ● ConﬁrmationStatus が2つある時の cxml-ruby (gem) のパース結果 ○ たしかに type が nil ○ そもそも conﬁrmation_status 複数のため Array になりそうだが？

Slide 39

Slide 39 text

39 実際に発生した問題 - 対応できていなかった cXML 仕様の例 ● cxml-ruby の ConﬁrmationStatus の親要素の定義を確認 ○ 複数受け取られる定義ではない 🙂 複数要素OKな時は別の定義の仕方が必要

Slide 40

Slide 40 text

40 実際に発生した問題 - 対応できていなかった cXML 仕様の例 ● cXML のリファレンスを見ると購買システム側でも想定して実装してなかったがそもそも cxml-ruby の gem でも想定されていなかった 😂 引用:「cXML Reference Guide」 https://xml.cxml.org/current/cXMLReferenceGuide_ja.pdf

Slide 41

Slide 41 text

41 実際に発生した問題 - 対応できていなかった cXML 仕様の例これらのことからの学び ● 外部イベントのロギングにより再現と原因の究明ができた ○ 連携先からなにが送られてきたか分からなくなってしまうためイベントログ大事 ● 連携先との仕様調整でイレギュラーケースをいかに把握するか ○ 今やっていること ■ 定期的な同期コミュニケーションをとる ■ これまでに発見したイレギュラーケースを仕様にまとめる

Slide 42

Slide 42 text

42 cXML仕様実装すればどんな EC サイトとも連携できる!! → ほんとうか?

Slide 43

Slide 43 text

43 cXML仕様実装すればどんな EC サイトとも連携できる!! → ほんとうか? → 楽にはなるが、安心はできない 😂

Slide 44

Slide 44 text

44 まとめ ● cXML はおもしろい ○ イレギュラーケースにどう向きあうかは腕の見せどころ ● システム間連携ではエラーの再現ができるようにする ○ 外部の情報はログがないと再現や復旧が難しい ● 連携先との密なコミュニケーションが大事 ○ 全てを仕様書に表わすことは難しい ○ 細かい仕様のキャッチアップができる状態をつくる必要がある

Slide 45

Slide 45 text

45 おまけ

Slide 46

Slide 46 text

46 自己紹介 ● がーしー / @phigasui ○ Kaigi on Rails 2024 中は「がーしーえっくすえむえる」 ● 株式会社Leaner Technologies ● プロダクトエンジニア

Slide 47

Slide 47 text

47 なぜ cXML と向きあっているのか調達のスタンダードを刷新し続ける

Slide 48

Slide 48 text

48 Event

Slide 49

Slide 49 text

49 cXML とパンチアウト連携パンチアウトトランザクションの流れパンチアウト開始リクエストパンチアウト開始リクエストパンチアウト開始URL パンチアウト開始URL パンチアウト開始URL へアクセス商品カート追加チェックアウト注文情報注文情報購買システム EC サイト

Slide 50

Slide 50 text

50 cXML とパンチアウト連携パンチアウトトランザクションの流れパンチアウト開始リクエストパンチアウト開始リクエストパンチアウト開始URL パンチアウト開始URL パンチアウト開始URL へアクセス商品カート追加チェックアウト注文情報注文情報購買システム EC サイト

Slide 51

Slide 51 text

51 cXML とパンチアウト連携パンチアウトトランザクションの流れパンチアウト開始リクエストパンチアウト開始リクエストパンチアウト開始URL パンチアウト開始URL パンチアウト開始URL へアクセス商品カート追加チェックアウト注文情報注文情報購買システム EC サイト

Slide 52

Slide 52 text

52 cXML とパンチアウト連携注文以降のリクエストの流れ購買システム EC サイト最終承認注文注文確認出荷通知購買申請

Slide 53

Slide 53 text

53 cXML とパンチアウト連携注文以降のリクエストの流れ購買システム EC サイト最終承認注文注文確認出荷通知購買申請

Slide 54

Slide 54 text

54 cXML とパンチアウト連携注文のリクエスト OrderRequest ● 注文する商品情報(商品識別子や金額)、配送先を送って注文を要求する ● ItemOuts は PunchOutOrderMessage の ItemIns と同じ

Slide 55

Slide 55 text

55 cXML とパンチアウト連携注文以降のリクエストの流れ購買システム EC サイト最終承認注文注文確認出荷通知購買申請

Slide 56

Slide 56 text

56 cXML とパンチアウト連携注文確認のリクエスト ConﬁrmationRequest ● 注文を受けて一定時間後にリクエストが来る ● 注文を確定したり、キャンセル、金額の変更があればその情報が連携されたりする ● 複数回届く場合もある

Slide 57

Slide 57 text

57 Rails アプリケーションでの実装 Controller ServiceClass ParserClass GatewayClass Rails は API モード ● Gateway で EC サイトへのリクエスト ○ 各 EC 向けのサブクラスで仕様の差分を実装 ● Parser で必要な情報にアクセスしやすく ● cxml-ruby という Gem で cXML の操作やバリデーション cxml-ruby

Slide 58

Slide 58 text

58 Rails アプリケーションでの実装 cxml-ruby ● cXML のバリデーション ● cXML のパース ● Hash から cXML への変換各要素のクラスがあり存在する属性と子要素が定義されている