質問一覧API

お客様から受けたお問い合わせの一覧を取得することができます。

変更履歴

2023年10月30日

サービス名称変更に伴い下記文言を修正しました。
ヤフオク!、ヤフオク → Yahoo!オークション

2022年3月4日

・リクエストパラメータ「dateType」から下記項目を削除しました。
 memoPostTime:メモ更新日時
・レスポンスパラメータに下記項目を追加しました。
 ・completeConditionId(質問の完了条件ID)
 ・completeConditionShortName(質問の完了条件文言)
 ・memo

2022年01月31日

リクエストパラメータから下記項目を削除しました。
 ・completeConditionId
 ・memoKeyword
 ・authType
下記リクエストパラメータの項目名を修正しました。
 修正前:filter
 修正後:requestFilter

リクエストURL

本番環境
https://circus.shopping.yahooapis.jp/ShoppingWebService/V1/externalTalkList
テスト環境
https://test.circus.shopping.yahooapis.jp/ShoppingWebService/V1/externalTalkList

リクエストパラメータ

Web APIの使い方#GETとは」をご参照ください。

リクエストURL

パラメータ 必須 デフォルトの値 値の例 説明
sellerId string teststore ストアアカウント
start int 1 1 トピックの読み込み開始位置
result int 20 20 返却トピック数(上限は20)
dateType string null 表示期間の絞り込み
 userPostTime:受付日時
 sellerPostTime:返信日時
 memoPostTime:メモ更新日時
startDate string null "1513076177" "dateType"が指定されている場合は必須(UNIX時間)
endDate string null "1513076177" "dateType"が指定されている場合は必須(UNIX時間)
qaType string null "order" 質問の絞り込み
 "item":注文前(注文検討中)の質問
 "order":注文後(既に注文済み)の質問
 指定なし:両方抽出
isPrivate boolean null true : 非公開質問のみ抽出
false : 公開質問のみ抽出
指定なし:両方抽出
category string null 2 カテゴリ取得APIのIDをリクエスト
子カテゴリがある場合は子カテゴリのID
子カテゴリがある親カテゴリだけの番号では質問できない
(別表:「カテゴリ情報」の項に記載のIDを指定してください)
sort string userPostTime ソートする際のキー
 userPostTime:受付日時
 sellerPostTime:返信日時
sortOrder string desc asc:昇順(古いものから順)
desc:降順(新しいものから順)
requestFilter string "answered,unanswered,completed" "answered"
"unanswered"
"completed"
フィルター
カンマ区切りで複数指定可能
指定しない場合全てを含めます。
セラー未回答 : unanswered
セラー回答済み : answered
完了 : completed
firstPoster string seller "seller"
"user"
最初投稿者の区別
セラー投稿質問:seller
ユーザー投稿質問:user
絞り込まない場合は未設定
※2020年1月から提供
serviceType string shp "auc"
"shp"
どのサービスからの注文か区別
Yahoo!ショッピング注文質問:shp
Yahoo!オークション注文質問:auc
絞り込まない場合は未設定
※2020年2月から提供
  • 必須△:"dateType"が指定されている場合は必須

サンプルリクエストURL

https://circus.shopping.yahooapis.jp/ShoppingWebService/V1/externalTalkList?
sellerId=xxxx&start=1&result=20

サンプルリクエスト

GET https://circus.shopping.yahooapis.jp/ShoppingWebService/V1/externalTalkList?
sellerId=xxxx&start=1&result=20 HTTP/1.1
Host: circus.shopping.yahooapis.jp
Authorization: Bearer <アクセストークン>

レスポンスフィールド

要素 フィールド 値の例 説明
summary Object { サマリ情報の情報群
filter int "all" 絞り込みの状態
 all:全て
 unanswered:未回答
 answered::回答済み
unansweredCount int 3 未回答件数
topic Object { トピックのサマリに関する情報
start int 1 レスポンスしたトピックのstart位置
end int 20 レスポンスしたトピックのend位置
count int 2243 レスポンスしたトピックの全ての件数
headlines Array<Object> [}
topicId string SHA256したトピックID
(質問詳細にリクエストする際のURLとする)
isUnread boolean 未読あり(既読していない)
 true:未読あり
 false:未読なし
isNoAnswer boolean 返信状況
 true:未返信
 false:返信済み
isCompleted boolean 質問が完了状態であるか
 true:完了済み
 false:未完了
completeConditionId int 1 質問の完了条件ID
completeConditionShortName string "通常完了" 質問の完了条件文言
userPostTime string "1513076177" 受付日時(最新のユーザー投稿日時)UNIX時間
sellerPostTime string | null "1513776685" 返信日時(最新のセラー投稿日時)UNIX時間
qaType string 注文種別
 order:注文後(既に注文済み)の質問
 item:注文前(注文検討中)の質問
isPrivate boolean true:非公開の質問
false:商品詳細に公開されている質問
category int 2 カテゴリ取得APIのID
title string "タイトルが入ります" タイトル
body string "メッセージ本文が入ります" メッセージ本文
messageCount int 10 投稿されているメッセージの総件数
userMaskedId string "JidfkgId" 商品Q&A内のシステムで、ハッシュ化したユーザID
商品Q&A独自のID体系(同一ユーザの判別ができる程度)
itemCode string | null :sellerId:_aAa 商品コード(SellerId_商品コード)
orderId string | null :sellerId:-10000000 注文ID:qaTypeがorderの時に応答それ以外は空
(SellerId-注文番号)
firstPoster stringl "seller" 最初投稿者の区別
セラー投稿質問:seller
ユーザー投稿質問:user
※2020年1月から提供
serviceType string "shp" どのサービスからの注文か区別
Yahoo!ショッピング注文質問:shp
Yahoo!オークション注文質問:auc
※2020年2月から提供
memo array | null
topicId string fcbc6999bdc56cbe184039ada7cf6b4cd109e0d593e1cf3b71b32c063c0a294d
memo string (メモ入力した内容) メモの内容
updateDate long 1551867030 最終保存時間
lastModifier long afront1815spoffy 最終保存者のBID

カテゴリ情報

※投稿時に選択可能か:質問投稿時に親カテゴリ子カテゴリの関係となっており、子カテゴリを選択しないと投稿できないため、トピックのレスポンスには当該カテゴリIDは基本的に含まれません、

カテゴリID 質問種別 カテゴリ名 投稿時に選択可能
1 注文前(注文検討中)の質問 商品の質問
2 注文前(注文検討中)の質問 お届け日・発送日について
3 注文前(注文検討中)の質問 在庫状態・再入荷予定
4 注文前(注文検討中)の質問 送料について
5 注文前(注文検討中)の質問 その他ストアへの連絡事項
6 注文後(既に注文済み)の質問 お届け日 ×
7 注文後(既に注文済み)の質問 お届け日(発送日の確認)
8 注文後(既に注文済み)の質問 お届け日(到着日の確認)
9 注文後(既に注文済み)の質問 注文キャンセル
10 注文後(既に注文済み)の質問 注文・決済内容の変更 ×
11 注文後(既に注文済み)の質問 注文・決済内容の変更(お届け先の変更)
12 注文後(既に注文済み)の質問 注文・決済内容の変更(注文内容の変更)
13 注文後(既に注文済み)の質問 注文・決済内容の変更(決済方法の変更)
14 注文後(既に注文済み)の質問 商品が届かない ×
15 注文後(既に注文済み)の質問 商品が届かない(発送通知ありだが届かない)
16 注文後(既に注文済み)の質問 商品が届かない(到着予定日に届かない)
17 注文後(既に注文済み)の質問 商品が届かない(その他)
18 注文後(既に注文済み)の質問 商品の質問
19 注文後(既に注文済み)の質問 連絡がない ×
20 注文後(既に注文済み)の質問 連絡がない(発送連絡がない)
21 注文後(既に注文済み)の質問 連絡がない(その他)
22 注文後(既に注文済み)の質問 領収書
23 注文後(既に注文済み)の質問 支払い方法の質問
24 注文後(既に注文済み)の質問 返品および返金について
25 注文後(既に注文済み)の質問 ギフトについて
26 注文後(既に注文済み)の質問 お届け日(その他)
27 注文後(既に注文済み)の質問 注文・決済内容の変更(その他)
28 注文後(既に注文済み)の質問 その他ストアへの連絡事項

サンプルレスポンス

レスポンス(JSON)

{
  "summary": {
    "filter": "all",
    "unansweredCount": 10,
    "topic" : {
        "start" : 1,
        "end"   : 20,
        "count" : 100
    }
  },
  "headlines" : [
    {
        "topicId" : "dbea226919fb786f9a67cced881e4f1e57f4636f18b2b4f154feb3019f533dde",
        "isUnread" : true,
        "isNoAnswer": true,
        "isCompleted": false,
        "firstPostTime": "1513076177",
        "updateTime": "1513776685",
        "qaType": "item",
        "isPrivate" :true,
        "category": 2,
        "title": "おすすめ商品でよく出てきますが・・",
        "body": "この商品はいつになったら買えるようになるんですか?¥n詳細を教えてください。",
        "messageCount": 10,
        "userMaskedId" : "jUDidkaE",
        "itemCode" : "teststore_2147483647",
        "orderId": null

    },
    {
        "topicId" : "e510844686b22b11bb579c0ee09828cbce7302f045968320d419769697327c18",
        "isUnread" : true,
        "isNoAnswer": true,
        "isCompleted": false,
        "firstPostTime": "1513076177",
        "updateTime": "1513776685",
        "qaType": "item",
        "isPrivate" :false,
        "category": 1,
        "title": "対応機種について",
        "body": "この商品は機種xxxxに対応していますか?",
        "messageCount": 8,
        "userMaskedId" : "8eIdgIqq",
        "itemCode" : "teststore_050",
        "orderId": null
    },
    {
        "topicId" : "42bc351b04925b8dd3448c4a6570b1183897701e00e724956e106b864af77890",
        "isUnread" : false,
        "isNoAnswer": false,
        "isCompleted": true,
        "firstPostTime": "1513076177",
        "updateTime": "1513779842",
        "qaType": "order",
        "userMaskedId" : "iOdie31",
        "isPrivate" :true,
        "category": 11,
        "title": "住所変更を希望します。",
        "body": "12/19に注文させていただきました、矢風と言います。¥n注文先の変更をさせてください。¥n¥n変更前: 〒107-6211 東京都港区赤坂9-7-1 ミッドタウン・タワー¥n¥n変更後〒102-8282: 東京都千代田区紀尾井町1-3: 東京ガーデンテラス紀尾井町 紀尾井タワー¥n¥n宜しくお願いします。",
        "messageCount": 2,
        "userMaskedId" : "8eIdgIqq",
        "itemCode" : null,
        "orderId": "teststore-10015077"
    }
  ]
}

エラー

Yahoo!ショッピングで提供している全てのAPIには、共通で利用するエラーコードがあります。エラーの際には、まず始めに以下をご確認ください。

質問一覧APIで固有に返すエラーコードは以下をご覧ください。

HTTPステータスコード 説明
400 Bad request. 渡されたパラメータがWebサービスで期待されたものと一致しない場合に返されます。
401 Unauthorized. 認証に失敗した場合に返されます。
404 Not found. 存在しないリソースにアクセスされた場合に返されます。
500 Internal Server Error. サーバー側で異常が発生した場合に返されます。
503 Service unavailable. 内部的な問題によってデータを返すことができない場合に返されます。

各エラーにおいて、次の形式のJSONレスポンスを返します。

フィールド 説明
error.reason エラー事由が記載されます。
{
     error : {
        reason: "Bad Request"
     }
}

ご注意

※こちらのAPIはYahoo! ID連携に対応したAPIです。
Yahoo! ID連携によるAPIアクセス方法の詳細は、以下のページをご確認ください。

※こちらのAPIを利用する場合は、こちらからClient ID(アプリケーションID)を取得してください。

利用制限

※短い時間の間に同一URLに大量にアクセスを行った場合、一定時間利用できなくなることもございます。(1クエリー/秒)

利用約款

このAPIに関する利用約款はこちら

アプリケーションの管理

利用のルール

開発のヒント