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

SquareのCatalog APIでは以下のCatalogObjectTypeが指定できます（via [connect-ruby-sdk/catalog_object_type.rb at 42344c30c1aad845e6914acf537066af7d42e962 · square/connect-ruby-sdk](https://github.com/square/connect-ruby-sdk/blob/42344c30c1aad845e6914acf537066af7d42e962/lib/square_connect/models/catalog_object_type.rb)）。

- ITEM
- CATEGORY
- ITEM_VARIATION
- TAX
- DISCOUNT
- MODIFIER_LIST
- MODIFIER

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

## 商品情報

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

<img width="1024" alt="Screenshot_ 2017-11-25 11.07.06.png" src="https://qiita-image-store.s3.amazonaws.com/0/197026/4e4e0b05-c45d-3655-4c8d-11910782c4cc.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` を指定するとバリエーションの部分だけが出てきます。商品名は出ません。

<img width="1024" alt="Screenshot_ 2017-11-25 11.07.06のコピー.png" src="https://qiita-image-store.s3.amazonaws.com/0/197026/a9a07782-6946-d0bd-ce89-dcd51c0226bf.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` はオプショングループ相当ですが、この時点ですべてオプション情報も内包されて返ってきます。

<img width="1024" alt="Screenshot_ 2017-11-25 11.09.54.png" src="https://qiita-image-store.s3.amazonaws.com/0/197026/288ad1ca-3cc2-84b0-e233-ae92b490d0ef.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` を指定します。

<img width="1024" alt="Screenshot_ 2017-11-25 11.09.54のコピー.png" src="https://qiita-image-store.s3.amazonaws.com/0/197026/8ce543b6-9035-dd0c-26c2-05abdbace7fc.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` はそのままカテゴリ情報が返ってきます。商品情報は入ってきません。

<img width="1024" alt="Screenshot_ 2017-11-25 11.11.51.png" src="https://qiita-image-store.s3.amazonaws.com/0/197026/d2d99502-daa0-0123-6949-ea851ea8f027.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` で取れます。

<img width="1024" alt="Screenshot_ 2017-11-25 11.30.28.png" src="https://qiita-image-store.s3.amazonaws.com/0/197026/623ec804-01ab-f395-e81c-770cfcb5cd2e.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](https://docs.connect.squareup.com/api/connect/v2#type-catalogobject)