使い方ガイド

winecodeの基本操作からプロプラン機能まで

API

公開ワインリスト

公開中のワインリストを、自分のWebサイトやアプリからJSONで取得できます。ログイン・APIキー・アクセストークン・Authorizationヘッダーは不要です。読み取り専用のAPIです。

ベースURL:https://api.v2.winecode.app

公開URLから取得を始める

公開URLが https://winecode.app/example-shop の場合、example-shop がAPIのgroupKeyです。公開URLのエイリアスと元のグループキーのどちらも指定できます。非公開グループは取得できません。

curl 'https://api.v2.winecode.app/group/example-shop'

example-shopは説明用の値です。実際の公開URLの値に置き換え、パスパラメーターはencodeURIComponentなどでエンコードしてください。

ワインリストの公開設定を確認する

エンドポイント

公開ワイン一覧

GET https://api.v2.winecode.app/group/:groupKey

公開対象のワイン配列。該当するワインがなければ空配列 []。表示価格の安い順です。

ワイン詳細

GET https://api.v2.winecode.app/group/:groupKey/:threadId

ワイン1件。グループの取得対象外・下書き・個別非公開・表示価格なしの場合は200・空の本文です。存在しないIDは403です。在庫0でも返る場合があります。

タグ一覧

GET https://api.v2.winecode.app/group/tags/:groupKey

tagId、label、typeId、isSecret、useQty、hasThreadを持つ配列です。

ショップ情報・表示設定

GET https://api.v2.winecode.app/group/description/:groupKey

店舗の連絡先・説明文・priceType・ワイン種別の表示名などを返します。

threadIdは一覧の応答に含まれる整数です。ページ送り・検索・並び替え用のクエリーパラメーターはありません。取得した配列を利用側で絞り込みます。

一覧と詳細の取得条件

一覧はグループに属するワインから、下書きを除き、在庫qtyが正、公開用の表示価格price.sellが正、個別の非公開設定なし、の条件で返します。表示価格の安い順です。

詳細は在庫数では除外しないため、在庫0でも返る場合があります。グループの取得対象外・下書き・個別非公開・表示価格なしの場合は200・空の本文です。一方、削除済みなど存在しないthreadIdは403を返します。HTTPステータスと本文の有無を確認してからJSONへ変換してください。
const groupKey = encodeURIComponent('example-shop');
const response = await fetch(`https://api.v2.winecode.app/group/${groupKey}/12345`);
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const body = await response.text();
const wine = body === '' ? null : JSON.parse(body);

ワインのフィールド

以下は代表的なフィールドです。応答にはこのほかのフィールドも含まれます。例は架空データの抜粋です。

[
  {
    "threadId": 12345,
    "type": "RED",
    "name": "サンプル・ピノ・ノワール",
    "label": "Sample Pinot Noir",
    "year": 2022,
    "area": "フランス ブルゴーニュ",
    "producer": "サンプル生産者",
    "variety": "ピノ・ノワール",
    "tastingNote": "赤い果実の香り。",
    "qty": 3,
    "price": {
      "sell": 8800,
      "suggest": 11000,
      "glass": 1500
    },
    "currencyCode": {
      "sell": "JPY",
      "suggest": "JPY",
      "glass": "JPY"
    },
    "enableSecondPrice": false,
    "images": [],
    "attachments": []
  }
]
フィールド内容
threadIdワイン(スレッド)ID
typeRED / WHITE / SPARKLING / CHAMPAGNE / ROSE / ORANGE / OTHER
name / label銘柄名・外国語表記。グループ独自の表示名を反映します。
year生産年。0はノンヴィンテージです。
area / producer / appellation / variety産地・生産者・格付け・品種
tastingNote / tastingTagsテイスティングノート・テイスティング用タグ。ノートはグループ設定を反映します。
qtyグループ内の在庫数量
pricesell / suggest / glass の金額。未設定はnullの場合があります。
currencyCode元の価格種別ごとの通貨コード。表示価格の通貨はpriceTypeが0ならsell、1ならglass、2ならsuggestを参照します。
enableSecondPrice第2価格の表示設定
attachments / images公開対象の画像情報・画像URL。非公開画像は除外します。

購入価格price.purchase、memo、groupId、purchaseDate、place、historyは公開用のワイン応答から除外します。非公開画像も含みません。

表示価格とショップ情報

ショップ情報はgroupId、groupKey、groupAlias、type、shopName、shopAddress、shopPhone、shopUrl、shopInstagram、shopReservationUrl、description、priceType、threadTypeSettings、threadTypesを返します。連絡先・説明文はnullの場合があります。

priceTypeは0:販売額、1:グラス代、2:参考上代です。price.sellには選択した種別の表示価格が入ります。currencyCodeのキーは元の価格種別のままです。

enableSecondPriceがtrueでpriceTypeが0以外の場合、price.glassに元の販売額が入り、第2価格として表示できます。threadTypeSettingsはDEFAULTまたはCUSTOM、threadTypesはワイン種別をキーにした表示名で、未設定値はnullです。

タグ一覧

タグはtagId、label、typeId、isSecret、useQty、hasThreadを返します。typeId未設定時は0、hasThreadはnullの場合があります。useQtyは使用スレッドの集計で、公開ワイン一覧の件数とは一致しない場合があります。公開画面ではisSecretがtrueのタグを表示対象から除いてください。

エラーとキャッシュ

  • 403:不明・非公開のgroupKey、存在しない・削除済みのthreadId。
  • 400:整数でないthreadId。
  • 503:メンテナンス中など、一時的に利用できない場合。

以下は不明・非公開のgroupKeyに対する403の応答例です。存在しないthreadIdではエラーメッセージが異なります。

{"statusCode":403,"message":"正常なリクエストではありません"}

一覧とワインが取得できた詳細は、Cache-Control: public, max-age=60, s-maxage=60を返します。在庫・価格・公開設定の変更がキャッシュにより遅れて反映される場合があります。タグ・ショップ情報・空の詳細には、この60秒キャッシュ設定は付与しません。

ブラウザーからも認証ヘッダーなしで取得できます。定期取得時はキャッシュを利用し、必要以上の短い間隔で取得しないでください。