Edited at

Square APIのカタログ種別と管理画面の関係

More than 1 year has passed since last update.

SquareのCatalog APIでは以下のCatalogObjectTypeが指定できます(via connect-ruby-sdk/catalog_object_type.rb at 42344c30c1aad845e6914acf537066af7d42e962 · square/connect-ruby-sdk)。


  • ITEM

  • CATEGORY

  • ITEM_VARIATION

  • TAX

  • DISCOUNT

  • MODIFIER_LIST

  • MODIFIER

だいたい分かりますが、実際管理画面のどこで設定した情報が出ているのかが分かりづらいので検証しました。


商品情報

ITEM を指定すると管理画面の商品ライブラリタブの情報が出ています。バリエーションも入っています。

Screenshot_ 2017-11-25 11.07.06.png

api = SquareConnect::CatalogApi.new

opts = {
types: [
SquareConnect::CatalogObjectType::ITEM
].join(',')
}
pp api.list_catalog(opts)
=>
{:objects=>
[{:type=>"ITEM",
:id=>"YZALIZK7ARSE6MSXIPN5XV3Y",
:updated_at=>"2017-07-03T00:37:59.725Z",
:version=>1499042279725,
:is_deleted=>false,
:present_at_all_locations=>true,
:item_data=>
{:name=>"DevRel Meetup in Tokyo当日払い",
:description=>"",
:category_id=>"MAABDA5E4PUTJU5O5ZUYITNW",
:image_url=>
"https://square-production.s3.amazonaws.com/files/061af82446322beaedb79d477d9b442dd64ac78a/original.png",
:variations=>
[{:type=>"ITEM_VARIATION",
:id=>"7B4DUHF57AOV45NLEFTGPXS7",
:updated_at=>"2017-07-03T00:37:59.725Z",
:version=>1499042279725,
:is_deleted=>false,
:present_at_all_locations=>true,
:item_variation_data=>
{:item_id=>"YZALIZK7ARSE6MSXIPN5XV3Y",
:name=>"当日払い",
:sku=>"1",
:pricing_type=>"FIXED_PRICING",
:price_money=>{:amount=>1000, :currency=>"JPY"}}}],
:product_type=>"REGULAR",
:skip_modifier_screen=>false}},
{:type=>"ITEM",
:id=>"GOCQNZGFOU5BJITSTSIJAKG4",
:updated_at=>"2017-11-24T09:29:35.934Z",
:version=>1511515775934,
:is_deleted=>false,
:present_at_all_locations=>true,
:item_data=>
{:name=>"MOONGIFTエナジー",
:description=>"テスト用の商品です",
:category_id=>"CK2T22WWTKOI6LZ7KH6QECQC",
:variations=>
[{:type=>"ITEM_VARIATION",
:id=>"GMXBG4Y4XWDQGFKJCJHYZCCU",
:updated_at=>"2017-11-24T09:29:35.934Z",
:version=>1511515775934,
:is_deleted=>false,
:present_at_all_locations=>true,
:item_variation_data=>
{:item_id=>"GOCQNZGFOU5BJITSTSIJAKG4",
:name=>"Sサイズ",
:sku=>"E-S",
:pricing_type=>"FIXED_PRICING",
:price_money=>{:amount=>100, :currency=>"JPY"}}},
{:type=>"ITEM_VARIATION",
:id=>"UUAOONEUM2ROCL2UEW3VLH2I",
:updated_at=>"2017-11-24T09:29:35.934Z",
:version=>1511515775934,
:is_deleted=>false,
:present_at_all_locations=>true,
:item_variation_data=>
{:item_id=>"GOCQNZGFOU5BJITSTSIJAKG4",
:name=>"Mサイズ",
:sku=>"E-M",
:pricing_type=>"FIXED_PRICING",
:price_money=>{:amount=>200, :currency=>"JPY"}}},
{:type=>"ITEM_VARIATION",
:id=>"J3XSNMEFXVUEOCZPEREPDH5Y",
:updated_at=>"2017-11-24T09:29:35.934Z",
:version=>1511515775934,
:is_deleted=>false,
:present_at_all_locations=>true,
:item_variation_data=>
{:item_id=>"GOCQNZGFOU5BJITSTSIJAKG4",
:name=>"Lサイズ",
:sku=>"E-L",
:pricing_type=>"FIXED_PRICING",
:price_money=>{:amount=>300, :currency=>"JPY"}}}],
:product_type=>"REGULAR",
:skip_modifier_screen=>false}}]}


商品バリデーションだけ

ITEM_VARIATION を指定するとバリエーションの部分だけが出てきます。商品名は出ません。

Screenshot_ 2017-11-25 11.07.06のコピー.png

opts = {

types: [
SquareConnect::CatalogObjectType::ITEM_VARIATION
].join(',')
}
pp api.list_catalog(opts)
=>
#<SquareConnect::ListCatalogResponse:0x007f84cc9242c8
@objects=
[#<SquareConnect::CatalogObject:0x007f84cc924020
@id="7B4DUHF57AOV45NLEFTGPXS7",
@is_deleted=false,
@item_variation_data=
#<SquareConnect::CatalogItemVariation:0x007f84cc92f678
@item_id="YZALIZK7ARSE6MSXIPN5XV3Y",
@name="当日払い",
@price_money=
#<SquareConnect::Money:0x007f84cc92f100 @amount=1000, @currency="JPY">,
@pricing_type="FIXED_PRICING",
@sku="1">,
@present_at_all_locations=true,
@type="ITEM_VARIATION",
@updated_at="2017-07-03T00:37:59.725Z",
@version=1499042279725>,
#<SquareConnect::CatalogObject:0x007f84cc92cfb8
@id="GMXBG4Y4XWDQGFKJCJHYZCCU",
@is_deleted=false,
@item_variation_data=
#<SquareConnect::CatalogItemVariation:0x007f84cc92c658
@item_id="GOCQNZGFOU5BJITSTSIJAKG4",
@name="Sサイズ",
@price_money=
#<SquareConnect::Money:0x007f84cc92c0e0 @amount=100, @currency="JPY">,
@pricing_type="FIXED_PRICING",
@sku="E-S">,
@present_at_all_locations=true,
@type="ITEM_VARIATION",
@updated_at="2017-11-24T09:29:35.934Z",
@version=1511515775934>,
#<SquareConnect::CatalogObject:0x007f84cc581f58
@id="UUAOONEUM2ROCL2UEW3VLH2I",
@is_deleted=false,
@item_variation_data=
#<SquareConnect::CatalogItemVariation:0x007f84cc5815f8
@item_id="GOCQNZGFOU5BJITSTSIJAKG4",
@name="Mサイズ",
@price_money=
#<SquareConnect::Money:0x007f84cc581080 @amount=200, @currency="JPY">,
@pricing_type="FIXED_PRICING",
@sku="E-M">,
@present_at_all_locations=true,
@type="ITEM_VARIATION",
@updated_at="2017-11-24T09:29:35.934Z",
@version=1511515775934>,
#<SquareConnect::CatalogObject:0x007f84cc57aa28
@id="J3XSNMEFXVUEOCZPEREPDH5Y",
@is_deleted=false,
@item_variation_data=
#<SquareConnect::CatalogItemVariation:0x007f84cc579e20
@item_id="GOCQNZGFOU5BJITSTSIJAKG4",
@name="Lサイズ",
@price_money=
#<SquareConnect::Money:0x007f84cc5798a8 @amount=300, @currency="JPY">,
@pricing_type="FIXED_PRICING",
@sku="E-L">,
@present_at_all_locations=true,
@type="ITEM_VARIATION",
@updated_at="2017-11-24T09:29:35.934Z",
@version=1511515775934>]>


オプショングループ + オプション

MODIFIER_LIST はオプショングループ相当ですが、この時点ですべてオプション情報も内包されて返ってきます。

Screenshot_ 2017-11-25 11.09.54.png

opts = {

types: [
SquareConnect::CatalogObjectType::MODIFIER_LIST,
].join(',')
}
pp api.list_catalog(opts)
=>
#<SquareConnect::ListCatalogResponse:0x007f84cda55d30
@objects=
[#<SquareConnect::CatalogObject:0x007f84cda55a88
@id="AVAKLPH63VRKBE7NY6W5ED3R",
@is_deleted=false,
@modifier_list_data=
#<SquareConnect::CatalogModifierList:0x007f84cda550b0
@modifiers=
[#<SquareConnect::CatalogObject:0x007f84cda54c28
@id="PEXECUBGDIOJM72OJTIU3S26",
@modifier_data=
#<SquareConnect::CatalogModifier:0x007f84cda54480
@name="ハンバーガー",
@price_money=
#<SquareConnect::Money:0x007f84cda54228
@amount=500,
@currency="JPY">>,
@type="MODIFIER",
@version=1511575302109>,
#<SquareConnect::CatalogObject:0x007f84cda4e238
@id="53PWGGMTQINZ46RLDCFJIUYQ",
@modifier_data=
#<SquareConnect::CatalogModifier:0x007f84cda4da90
@name="ドリンク",
@price_money=
#<SquareConnect::Money:0x007f84cda4d838
@amount=100,
@currency="JPY">>,
@type="MODIFIER",
@version=1511575302109>,
#<SquareConnect::CatalogObject:0x007f84cda474d8
@id="TNJ2AJQVMPOOVWZXYCROCSBP",
@modifier_data=
#<SquareConnect::CatalogModifier:0x007f84cda46c90
@name="ポテト",
@price_money=
#<SquareConnect::Money:0x007f84cda46a38
@amount=150,
@currency="JPY">>,
@type="MODIFIER",
@version=1511575302109>],
@name="とくとくセット",
@selection_type="MULTIPLE">,
@present_at_all_locations=true,
@type="MODIFIER_LIST",
@updated_at="2017-11-25T02:01:42.109Z",
@version=1511575302109>]>


オプション

オプションだけを取り出す場合には MODIFIER を指定します。

Screenshot_ 2017-11-25 11.09.54のコピー.png

opts = {

types: [
SquareConnect::CatalogObjectType::MODIFIER,
].join(',')
}
pp api.list_catalog(opts)
=>
#<SquareConnect::ListCatalogResponse:0x007f84cc8fc958
@objects=
[#<SquareConnect::CatalogObject:0x007f84cc8fc6b0
@id="PEXECUBGDIOJM72OJTIU3S26",
@is_deleted=false,
@modifier_data=
#<SquareConnect::CatalogModifier:0x007f84cd9cfc58
@name="ハンバーガー",
@price_money=
#<SquareConnect::Money:0x007f84cd9cfa00 @amount=500, @currency="JPY">>,
@present_at_all_locations=true,
@type="MODIFIER",
@updated_at="2017-11-25T02:01:42.109Z",
@version=1511575302109>,
#<SquareConnect::CatalogObject:0x007f84cd9cd9d0
@id="53PWGGMTQINZ46RLDCFJIUYQ",
@is_deleted=false,
@modifier_data=
#<SquareConnect::CatalogModifier:0x007f84cd9ccfd0
@name="ドリンク",
@price_money=
#<SquareConnect::Money:0x007f84cd9ccd78 @amount=100, @currency="JPY">>,
@present_at_all_locations=true,
@type="MODIFIER",
@updated_at="2017-11-25T02:01:42.109Z",
@version=1511575302109>,
#<SquareConnect::CatalogObject:0x007f84cd9c6e00
@id="TNJ2AJQVMPOOVWZXYCROCSBP",
@is_deleted=false,
@modifier_data=
#<SquareConnect::CatalogModifier:0x007f84cd9c6400
@name="ポテト",
@price_money=
#<SquareConnect::Money:0x007f84cd9c61a8 @amount=150, @currency="JPY">>,
@present_at_all_locations=true,
@type="MODIFIER",
@updated_at="2017-11-25T02:01:42.109Z",
@version=1511575302109>]>


カテゴリ

CATEGORY はそのままカテゴリ情報が返ってきます。商品情報は入ってきません。

Screenshot_ 2017-11-25 11.11.51.png

opts = {

types: [
SquareConnect::CatalogObjectType::CATEGORY
].join(',')
}
pp api.list_catalog(opts)
=>
#<SquareConnect::ListCatalogResponse:0x007f84cd99f8c8
@objects=
[#<SquareConnect::CatalogObject:0x007f84cd99f620
@category_data=
#<SquareConnect::CatalogCategory:0x007f84cd99ece8 @name="チケット">,
@id="MAABDA5E4PUTJU5O5ZUYITNW",
@is_deleted=false,
@present_at_all_locations=true,
@type="CATEGORY",
@updated_at="2017-07-03T00:37:59.385Z",
@version=1499042279385>,
#<SquareConnect::CatalogObject:0x007f84cd99ea40
@category_data=
#<SquareConnect::CatalogCategory:0x007f84cd99e108 @name="飲料">,
@id="CK2T22WWTKOI6LZ7KH6QECQC",
@is_deleted=false,
@present_at_all_locations=true,
@type="CATEGORY",
@updated_at="2017-11-24T09:29:35.729Z",
@version=1511515775729>]>


ディスカウント

ディスカウント(値引き)タブは DISCOUNT で取れます。

Screenshot_ 2017-11-25 11.30.28.png

opts = {

types: [
SquareConnect::CatalogObjectType::DISCOUNT
].join(',')
}
pp api.list_catalog(opts)
=>
#<SquareConnect::ListCatalogResponse:0x007f84cc8dedb8
@objects=
[#<SquareConnect::CatalogObject:0x007f84cc8deae8
@discount_data=
#<SquareConnect::CatalogDiscount:0x007f84cc8de138
@amount_money=
#<SquareConnect::Money:0x007f84cc8ddc60 @amount=500, @currency="JPY">,
@discount_type="FIXED_AMOUNT",
@name="1000円以上で送料無料">,
@id="SG353KJSVUWL35WMO23IIU3U",
@is_deleted=false,
@present_at_all_locations=true,
@type="DISCOUNT",
@updated_at="2017-11-24T09:33:55.594Z",
@version=1511516035594>]>


税金

税金タブの情報は TAX で取得できます。

opts = {

types: [
SquareConnect::CatalogObjectType::TAX
].join(',')
}
pp api.list_catalog(opts)
=>
#<SquareConnect::ListCatalogResponse:0x007f84cc502f00
@objects=
[#<SquareConnect::CatalogObject:0x007f84cc502c30
@id="W4T3CX5OZUPCHXRI5O2DU2KG",
@is_deleted=false,
@present_at_all_locations=true,
@tax_data=
#<SquareConnect::CatalogTax:0x007f84cc5021b8
@applies_to_custom_amounts=true,
@calculation_phase="TAX_SUBTOTAL_PHASE",
@enabled=true,
@inclusion_type="ADDITIVE",
@name="消費税",
@percentage="8.0">,
@type="TAX",
@updated_at="2017-11-24T09:34:17.762Z",
@version=1511516057762>]>


これ以外の情報、特にギフトカードについてはカタログオブジェクトは異なる管理になっているようで、指定できませんでした。

このデータ関係が分かると、Square APIを使う上でデータをどう適用すれば良いかが分かりやすくなるでしょう。特にオプションは MODIFIER となっており、名前が日英で異なっているので注意が必要です。

Square Connect API Documentation