注文レポートAPIリファレンス（広告主向け）

概要

広告主向け管理画面で提供している注文別レポートと同等の情報を提供するAPIに関する仕様書です。 このAPIをリクエストするためには、「広告主向けトークン取得API」にリクエストを行い、有効なBearerトークンを取得している必要があります。

有効期限

このAPIのトークンの有効期限は30分間です。期限が切れるとリクエスト時にエラーメッセージ「invalid_token」が返却されますので、トークン取得APIに再度リクエストを行い、最新のトークンを取得し、指定してください。 エラーメッセージについては「レスポンスヘッダー」の章を参照ください。

利用制限

このAPIでは30分間以内に1,500回を超える正常リクエストが行われた場合に30分間ロックされます。ロック中のリクエスト時にはエラーメッセージ「locked」が返却されますので、時間を置いて再度リクエストしてください。 エラーメッセージについては「レスポンスヘッダー」の章を参照ください。

リクエスト

リクエストメソッド

GET

エンドポイント

v1：https://api.valuecommerce.com/report/v1/merchant/transaction/
v2：https://api.valuecommerce.com/report/v2/merchant/transaction/

エンドポイントのバージョンによって利用できるパラメーターが異なります。バージョンの記載がないパラメーターはすべてのバージョンで利用可能です。

リクエストヘッダー

リクエストヘッダーには下記を指定してください。

• Authorization: Bearer [bearer_token] ※1
• Accept: application/json

リクエストボディー

パラメーター名	説明	必須	初期値	許容文字列	許容バイト数
callback(※2)	コールバック関数名	×	null	半角英数および記号【_-】	0～50
limit	取得件数	×	100	半角数値（1〜1000）	0～4
offset	取得開始位置	×	0	半角数値（0〜9999999999）	0～10
sort	ソート順指定 レスポンスフィールド「rowData」以下より任意のフィールド名をカンマ区切りで複数指定可 「detail」フィールド以下詳細フィールド名は指定不可（「detail」フィールドも指定不可）また、各フィールド名には下記接頭句を許可する 降順（接頭句なしの場合は昇順）指定順＝ソート優先度とする	×	-orderDate	半角英数および記号【-,】	指定可能なフィールド名をカンマ区切りで結合したバイト数
field	レスポンスフィールド レスポンスフィールド「rowData」以下より任意のフィールド名をカンマ区切りで複数指定可 「detail」フィールド以下詳細フィールド名は指定不可（「detail」フィールドは指定可） 指定した順で、指定したフィールドのみを取得する	×	detailを除くすべて	半角英数および記号【, 】	指定可能なフィールド名をカンマ区切りで結合したバイト数
criteria	検索基準となる日付 下記から択一指定 a：処理（承認／拒否）日 c：クリック日 o：注文日 i：注文データ挿入日 ※個人情報保護法に基づき「c：クリック日」を指定した場合、個人関連情報についての誓約書締結状態によりマスク対象データはレスポンスに含まれません。 開示や利用を希望される場合は担当営業までご連絡ください。	×	o	半角英字【a,c,o,i】	0～1
from_date	検索対象となる期間の開始日 検索範囲は最大6ヵ月、参照可能期間は当月を含む過去25ヵ月まで	×	システム日付（YYYY-MM-DD）	半角数値および記号【-】	10（固定）
to_date	検索対象となる期間の終了日 検索範囲は最大6ヵ月、参照可能期間は当月を含む過去25ヵ月まで	×	システム日付（YYYY-MM-DD）	半角数値および記号【-】	10（固定）
approval_status	注文のステータス 下記からカンマ区切りで任意複数指定 p：保留 a：承認 c：拒否 i：請求済み	×	p	半角英字【p,a,c.i】および記号【, 】	0～7
program	プログラム種別 下記からカンマ区切りで任意複数指定 w：Webプログラム e：Eメールプログラム m：モバイルプログラム	×	w,e,m	半角英字【w,e,m】および記号【, 】	0～5
program_name	プログラム名	×	null	URLエンコード	500
order_id	注文番号	×	null	URLエンコード	300
cust_name	顧客氏名	×	null	URLエンコード	100
cust_email	顧客Eメール	×	null	URLエンコード	100
cust_tel	顧客電話番号	×	null	半角数値および記号【-】	0～30
affil_id	アフィリエイトサイトID ※個人情報保護法に基づき本項目を指定した場合、個人関連情報についての誓約書締結状態によりマスク対象データはレスポンスに含まれません。 開示や利用を希望される場合は担当営業までご連絡ください。	×	null	半角数値	0～10
affiliate_site	アフィリエイトサイト名 ※個人情報保護法に基づき本項目を指定した場合、個人関連情報についての誓約書締結状態によりマスク対象データはレスポンスに含まれません。 開示や利用を希望される場合は担当営業までご連絡ください。	×	null	URL エンコード	500
affiliate_site_type	アフィリエイトサイト種別 下記からカンマ区切りで任意複数指定 w：Webサイト e：メールマガジン m：モバイル	×	w,e,m	半角英字【w,e,m】および記号【, 】	0～5
user_id	顧客ID	×	null	URLエンコード	256
customer_status	顧客管理ステータス	×	null	半角英字【o,n,e】および記号【, 】	0～5

【注意事項】
1.[bearer_token]部分に、トークン取得APIから取得したbearer_tokenを指定してください。

2. JSONP返却を求める場合のみ指定してください。

指定例

callback

「callback_function_name({JSONレスポンスフィールド})」での返却を期待する場合。

callback=callback_function_name

limit

「1件目から50件」のみ取得する場合

limit=50

offset

「51件目から99件」取得する場合

limit=99&offset=50

sort

「第1ソートキー：merchantName降順、第2ソートキー：approvalDate昇順」で取得する場合

sort=-merchantName,approvalDate

field

「clieckDate,orderDate,merchantName」のみを取得する場合

field=clickDate,orderDate,merchantName

criteria / from_date / to_date

検索基準を「クリック日」とし日時未指定（当日中の注文）とする場合

criteria=c

検索基準を「クリック日」の「2017年1月1日」から「2017年1月31日」までとする場合

criteria=c&from_date=2017-01-01&to_date=2017-01-31

approval_status

注文ステータスp,a,cのみを取得する場合

approval_status=p,a,c

program

プログラム種別「e,m」のみを取得する場合

program=e,m

program_name

プログラム名に「ValueCommerce」を含む注文のみを取得する場合

program_name=ValueCommerce

order_id

注文番号「123456789」を含む注文のみを取得する場合

order_id=123456789

cust_name

顧客氏名が「田中太郎」を含む注文のみを取得する場合

cust_name=%93c%92%86%91%BE%98Y

cust_email

顧客Eメールが「test@valuecommerce.co.jp」を含む注文のみを取得する場合

cust_email=test%40valuecommerce.co.jp

cust_tel

顧客電話番号が「080-0000-0000」を含む注文のみを取得する場合

cust_tel=080-0000-0000

affil_id

アフィリエイトサイトIDが「12345678」の注文のみを取得する場合

affil_id=12345678

affiliate_site

アフィリエイトサイト名が「バリューポイントクラブ」を含む注文のみを取得する場合

affiliate_site=%83o%83%8A%83%85%81%5B%83%7C%83C%83%93%83g%83N%83%89%83u

affiliate_site_type

アフィリエイトサイト種別「e,m」のみを取得する場合

affiliate_site_type=e,m

user_id

顧客IDが「test001」を含む注文のみ取得する場合

user_id=test001

customer_status

顧客管理ステータス「o,n」のみを取得する場合

customer_status=o,n

レスポンス

レスポンスヘッダー

エラーメッセージ

error="XXX"error_description="XXX"の表記で、発生したエラーメッセージを示します。正常レスポンス時にはこの項目は返却しません。各エラーメッセージの示す内容は以下のとおりです。

Error	error_description	HTTP STATUS CODE	意味	対応要求
invalid_request	Authorization request header is in invalid format (or may not be encoded).	401	Authorizationヘッダー不正、指定されていない、Base64エンコードされていない場合	Authorizationヘッダーの値、生成方法を確認してください 詳しくは「リクエストヘッダー」の章を参照ください
invalid_credential	Inactive credential value.	401	Authorizationヘッダーが正常だが、アクティブなサイト署名情報とひもづかない不正値	管理画面で表示されているCLIENT_KEY/CLIENT_SECRETを再度ご確認ください 再生成されている可能性があります（このエラーメッセージはトークン取得APIに限り返却します）
invalid_token	The current bearer token is invalid or already expired. Please get a new one.	401	トークンが不正値、または有効期限切れ	トークン取得APIにリクエストを行い、最新のトークンを取得し、指定してください（このエラーメッセージは認証下APIに限り返却します）
Locked	The endpoint has been locked due to the requests limit. Please try again later.	403	期間内利用回数の上限を超え、ロック中のエンドポイントに対するアクセス	時間をおいて再度リクエストしてください
invalid_parameters	Some of request parameters are invalid.	400	いずれかのリクエストパラメーターが不正値	「リクエストボディー」の章をご確認ください
not_found	-	404	存在しないエンドポイントに対するアクセス	リクエストされたURLをご確認ください
server_error	-	500	システムメンテナンス中	時間をおいて再度リクエストしてください

レスポンスボディー

パラメーター名	説明	説明詳細	正常時返却	異常時返却
Error	エラー概要	レスポンスヘッダー「error」と同一	×	○
error_description	エラー詳細	レスポンスヘッダー「error_description」と同一	×	○
resultSet	正常時レスポンスフィールドセット	正常処理時のリクエスト・およびレスポンスに関する情報	○	×
responseInfo	レスポンス情報	正常処理時のレスポンスに関する情報	○	×
numberOfResult	取得件数	rowDataフィールド要素数 存在しない場合や一覧参照系以外のAPIでは0を返却する 一覧参照系でループして順に取得する場合、リクエストパラメーターのoffsetにレスポンスフィールドのnextOffsetを指定しnumberOfResultが0になるまでこれを繰り返す	○	×
nextOffset	次取得開始位置	次リクエスト時にoffsetに指定する値 存在しない場合、一覧参照系以外のAPIでは-1	○	×
responseTime	レスポンス返却日時	レスポンスを返却したサーバー日時 JST yyyy-mm-dd hh:ii:ss	○	×
requestInfo	リクエスト情報	正常処理時のリクエスト要求に関する情報	○	×
Query	クエリストリング	受け付けたリクエスト要求のクエリストリング	○	×
requestTime	リクエスト受付日時	リクエストを受け付けたサーバー日時 JST yyyy-mm-dd hh:ii:ss	○	×
rowData	詳細情報	正常処理時のリクエスト要求に対する詳細情報	○	×
approvalStatus	ステータス	該当注文のステータス	○	×
clickDate	クリック日	該当注文のクリック日 JST yyyy-mm-dd hh:ii:ss ※個人情報保護法に則り、「***」でマスク表示されます。 開示や利用を希望される場合は、担当営業までご連絡ください。	○	×
orderDate	注文日	該当注文の注文日 JST yyyy-mm-dd hh:ii:ss	○	×
approvalDate	処理日	該当注文の処理日 JST yyyy-mm-dd hh:ii:ss	○	×
transactionOid	注文OID	該当注文の注文OID	○ ※v2 only	×
orderId	注文番号	該当注文の注文番号	○	×
programName	プログラム名	該当注文のプログラム名	○	×
custName	顧客氏名	該当注文の顧客氏名	○	×
custEmail	顧客Eメール	該当注文の顧客Eメール	○	×
custTel	顧客電話番号	該当注文の顧客電話番号	○	×
affilId	アフィリエイトサイトID	該当注文のアフィリエイトサイトID ※個人情報保護法に則り、「***」でマスク表示されます。 開示や利用を希望される場合は、担当営業までご連絡ください。	○	×
affiliateSite	経由アフィリエイトサイト	該当注文の経由アフィリエイトサイト ※個人情報保護法に則り、「***」でマスク表示されます。 開示や利用を希望される場合は、担当営業までご連絡ください。	○	×
itemQuantity	注文個数	該当注文の注文個数	○	×
itemPriceTotal	注文金額	該当注文の注文金額	○	×
affilPaymentNet	報酬金額（税抜）	該当注文の報酬金額（税抜）	○	×
affilPaymentTax	消費税額	該当注文の消費税額	○	×
affilPayment	報酬金額	該当注文の報酬金額	○	×
approvalDeadline	承認期限	該当注文の承認期限	○	×
Update	更新日時	該当注文の更新日時 JST yyyy-mm-dd hh:ii:ss	○	×
Detail	注文詳細情報	該当注文の注文詳細情報 ※別表参照	○	×
userId	顧客ID	該当注文の顧客ID	○	×
customerStatus	顧客管理ステータス	該当注文の顧客管理ステータス	○	×

detail（注文詳細情報）フィールド一覧

フィールド名	説明	説明詳細
itemId	アイテムID	該当注文明細のアイテムID
productGroupCode	商品グループコード	該当注文明細の商品グループコード
itemName	商品名	該当注文明細の商品名
itemQuantity	アイテム個数	該当注文明細のアイテム個数
itemPrice	商品単価	該当注文明細の商品単価
itemPriceTotal	商品金額	該当注文明細の商品金額
affilPaymentNet	報酬金額（税抜）	該当注文明細の報酬金額（税抜）
affilPaymentTax	消費税額	該当注文明細の消費税額
affilPayment	報酬金額	該当注文明細の報酬金額
updDate	更新日時	該当注文明細の更新日時 JST yyyy-mm-dd hh:ii:ss
itemDetailId	アイテム注文番号	該当注文明細のアイテム注文番号

※ご請求時に消費税を再計算するため、「消費税額」「報酬金額」は実際のご請求額と異なる場合がございますのでご注意ください。