確定API version2 仕様書#
システム概要#
機能一覧#
売上データの取得・修正
- 未確定売上データの取得
- 売上データの修正処理(単品商品)
- 売上データの修正処理(複数商品)
売上データの確定・キャンセル
- 売上データの確定処理
- 売上データのキャンセル処理
確定データの取得・取消
- 当日確定データの取得
- 当日確定データの取消処理
- 確定済みデータの取得
共通の仕様#
- API からの返却値は text/json 形式となります。
- 当APIは日本標準時 (UTC+9) で動作しています。当日・前日などの表記については日本標準時が基準となります。
- プログラム終了後も API 認証キーが有効であれば API を利用することができます。
- JSON データで送信するときは特に記載がなければ数値型・文字列型のどちらでリクエストしても問題ありません。
- 形式についての説明
形式 | 説明 |
---|---|
URL | URL内に設定するパラメータ(プログラムIDなど)。例:https://ecsales-api.a8.net/v2/ins/${PROGRAM_ID} |
GET | GETリクエストパラメータ。例:https://ecsales-api.a8.net/v2/ins/${PROGRAM_ID}/unsealed?api_key=${API_KEY}&date=${DATE} |
JSON | JSONリクエストパラメータ。例:curl ‐X POST ‐H "Content‐type: application/json" ‐d "${JSONREQ}" "https://ecsales ‐api.a8.net/v2/ins/${PROGRAM_ID}/order/${ORDER_ID}/decide" |
- パラメータのnullと省略についての説明
- nullはパラメータ名は設定していますがパラメータ値に何も設定しない場合となります。
例:offsetがnull
- 省略はパラメータ名もパラメータ値も何も設定しない場合となります。
例:offsetを省略
- nullはパラメータ名は設定していますがパラメータ値に何も設定しない場合となります。
エンドポイント#
リスト取得系のエンドポイント
①https://ecsales-api.a8.net/v2/ins/${PROGRAM_ID}
Note
${PROGRAM_ID}はA8.netより発行されているプログラムIDを設定してください。
リスト取得(GET) | |
---|---|
未確定リスト取得 | 上記エンドポイント①/unsealed |
当日確定リスト取得 | 上記エンドポイント①/sealed/today |
昨日以前確定リスト取得 | 上記エンドポイント①/sealed |
確定・取消系処理時のエンドポイント
② https://ecsales-api.a8.net/v2/ins/${PROGRAM_ID}/order/${ORDER_ID}
Note
${ORDER_ID}はA8.net より発行される売上データのユニークキーを設定してください。
処理(POST) | |
---|---|
売上修正処理 | 上記エンドポイント②/modify |
売上確定処理 | 上記エンドポイント②/decide |
売上キャンセル処理 | 上記エンドポイント②/cancel |
当日確定取消処理 | 上記エンドポイント②/revival |
その他注意事項#
- 本資料で申し上げる「売上データ」とは、成果が未確定の状態のものを指します。
- 本資料で申し上げる「確定データ」とは、「売上データ」が成果として認められ確定されたものと、成果として認められずキャンセルしたものを指します。
- 日本標準時 (UTC+9) で 23:30 ~ 翌 01:00 前後は売上データの日次処理が行われるため、確定APIが利用できない場合があります。
- 同一の API 認証キーから 1 分間に 100 回以上のアクセスがあった場合、A8.net より API の使用用途について問い合わせさせていただく場合があります。
- 登録したIP以外からのアクセスは認証エラーとなります。
未確定売上データの取得/unsealed#
- GET処理となります。
- 未確定売上データを一覧で取得します。確定済みの売上データは含まれません。
- 1度に取得できる売上データは 10,000 件となります。10,000 件を超える未確定データがある場合には、データ取得開始位置パラメータを変更してください。
リクエストパラメータ#
パラメータ | 設定値 | 形式 | 必須 | 備考 |
---|---|---|---|---|
PROGRAM_ID | プログラムID | URL | 必須 | A8.net より発行されたプログラムID ..../v2/ins/の後ろに設定します。 |
api_key | API認証キー | GET | 必須 | A8.net より発行されるプログラムID に紐づく確定 API 認証キー |
date | 売上発生日 | GET | 任意 | yyyyMMdd。指定なし:全件取得 |
order_id | オーダーID | GET | 任意 | A8.net より発行される売上データのユニークキー |
order_no | 注文番号 | GET | 任意 | 申込1件毎に御社システムが発行する注文(申込)番号を設定。 |
offset | データ取得開始位置 | GET | 任意 | デフォルト: 0 任意の位置からデータを取得できます。例10001件目から先を取得。 |
レスポンスフィールド#
フィールド | 設定値 | 型 | 備考 | |||||
---|---|---|---|---|---|---|---|---|
status_code | ステータスコード | 数値 | 別途ステータスコード一覧を参照 | |||||
message | メッセージ | 文字列 | ||||||
results | 取得したリスト | 配列 | ||||||
sales_ymd | 売上発生日 | 文字列 | yyyy/MM/dd HH:MI:SS 形式 | |||||
as_id | メディアID | 文字列 | A8.netで管理しているメディアID | |||||
order_id | オーダーID | 文字列 | A8.net より発行される売上データのユニークキー | |||||
order_no | 注文番号 | 文字列 | 申込1件毎に御社システムが発行している注文(申込)番号 | |||||
decide_flg | 確定フラグ | 数値 | 0=未確定, 1=確定 | |||||
order_count | 注文件数 | 数値 | ||||||
order_money | 注文金額 | 数値 | ||||||
pay_money | 成果報酬額 | 数値 | ||||||
items | 商品リスト | 配列 | ||||||
code | 商品コード | 文字列 | 御社システム側で発行している商品を識別するコード | |||||
price | 商品単価 | 数値 | ||||||
quantity | 商品個数 | 数値 |
サンプルコード#
リクエスト
1 2 3 4 5 6 7 8 9 10 |
|
Note
リクエストサンプルコード解説ポイント
・ins/の後にプログラムIDの値を設定します。null及び省略は不可となります。
・api_keyはnull及び省略不可ですので必ず入れてください。
・例では現在日の前日をYYYYMMMDD形式にしてdateパラメータとして設定しています。nullや省略した場合は全件検索となります。
・例ではorder_idは省略しています。
・例ではorder_noはnull値が入っていますので、省略時と同じ全件検索となります。
・例ではoffsetはnull値が入っていますので、省略時と同じくデータを1件目から取得します。
・URLのプログラムIDの後にunsealedを指定します。
レスポンス結果
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
|
売上データの修正処理(単一商品)/modify#
- JSONデータを使用したPOST処理となります。
- 未確定売上データ1件の売上内容を修正します。
- 対象の売上に対して異なる種類の商品が複数ある場合は「売上修正(複数商品)」を参照してください。
リクエストパラメータ#
パラメータ | 設定値 | 形式 | 必須 | 備考 |
---|---|---|---|---|
PROGRAM_ID | プログラムID | URL | 必須 | A8.net より発行されたプログラムID |
api_key | API認証キー | JSON | 必須 | A8.net より発行されるプログラムID に紐づく確定 API 認証キー |
order_id | オーダーID | URL | 必須 | A8.net より発行される売上データのユニークキー |
price | 単価 | JSON | 任意 | price か quantity のどちらかは必須 |
quantity | 商品個数 | JSON | 任意 | price か quantity のどちらかは必須 |
reason_code | 修正理由コード | JSON | 必須 |
1: 品切れのため 2: 返品のため 3: 追加発注のため 4: 注文金額の変更 5: 単価の変更のため 6: その他 |
レスポンスフィールド#
フィールド | 設定値 | 型 | 備考 |
---|---|---|---|
status_code | ステータスコード | 数値 | 別途ステータスコード一覧を参照 |
message | メッセージ | 文字列 |
サンプルコード#
リクエスト
1 2 3 4 5 6 7 8 9 10 |
|
Note
リクエストサンプルコード解説ポイント
・ins/の後にプログラムIDの値を設定します。null及び省略は不可となります。
・api_keyはnull及び省略不可ですので必ず入れてください。
・order_idはnull及び省略不可ですので必ず入れてください。
・priceは変更したくない場合は省略してください。null値はエラーとなります。省略する場合はquantityは必ず入れてください。
・quantityは変更したくない場合は省略してください。null値はエラーとなります。省略する場合はpriceは必ず入れてください。
・reason_codeはnull及び省略不可ですので必ず入れてください。
・URL末尾はmodifyになります。
レスポンス結果
1 2 3 4 |
|
売上データの修正処理(複数商品)/modify#
- JSONデータを使用したPOST処理となります。
- 未確定売上データ1件に対して商品が複数ある場合の売上内容を修正します。
リクエストパラメータ#
パラメータ | 設定値 | 形式 | 必須 | 備考 | ||||
---|---|---|---|---|---|---|---|---|
api_key | API認証キー | JSON | 必須 | A8.net より発行されるプログラムID に紐づく確定 API 認証キー | ||||
order_id | オーダーID | URL | 必須 | A8.net より発行される売上データのユニークキー | ||||
items | 商品リスト | JSON | 必須 | 下記パラメータを配列として格納 | ||||
code | 商品コード | JSON | 必須 | 御社システムで発行している商品を判別するためのコード | ||||
price | 単価 | JSON | 任意 | price か quantity のどちらかは必須 |
||||
quantity | 商品個数 | JSON | 任意 | price か quantity のどちらかは必須 |
||||
reason_code | 修正理由コード | JSON | 必須 |
1: 品切れのため 2: 返品のため 3: 追加発注のため 4: 注文金額の変更 5: 単価の変更のため 6: その他 |
レスポンスフィールド#
フィールド | 設定値 | 型 | 備考 |
---|---|---|---|
status_code | ステータスコード | 数値 | 別途ステータスコード一覧を参照 |
message | メッセージ | 文字列 |
サンプルコード#
リクエスト
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
|
Note
リクエストサンプルコード解説ポイント
・ins/の後にプログラムIDの値を設定します。null及び省略は不可となります。
・api_keyはnull及び省略不可ですので必ず入れてください。
・order_idはnull及び省略不可ですので必ず入れてください。
・priceは変更したくない場合は省略してください。null値はエラーとなります。省略する場合はquantityは必ず入れてください。
・quantityは変更したくない場合は省略してください。null値はエラーとなります。省略する場合はpriceは必ず入れてください。
・reason_codeはnull及び省略不可ですので必ず入れてください。
・URL末尾はmodifyになります。
レスポンス結果
1 2 3 4 |
|
売上データの確定処理/decide#
- JSONデータを使用したPOST処理となります。
- 未確定売上データ1件を確定します。
リクエストパラメータ#
パラメータ | 設定値 | 形式 | 必須 | 備考 |
---|---|---|---|---|
PROGRAM_ID | プログラムID | URL | 必須 | A8.net より発行されたプログラムID |
api_key | API認証キー | JSON | 必須 | A8.net より発行されるプログラムID に紐づく確定 API 認証キー |
order_id | オーダーID | URL | 必須 | A8.net より発行される売上データのユニークキー |
レスポンスフィールド#
フィールド | 設定値 | 型 | 備考 |
---|---|---|---|
status_code | ステータスコード | 数値 | 別途ステータスコード一覧を参照 |
message | メッセージ | 文字列 |
サンプルコード#
リクエスト
1 2 3 4 5 6 7 |
|
Note
リクエストサンプルコード解説ポイント
・ins/の後にプログラムIDの値を設定します。null及び省略は不可となります。
・api_keyはnull及び省略不可ですので必ず入れてください。
・order_idはnull及び省略不可ですので必ず入れてください。
・URL末尾はdecideになります。
レスポンス結果
1 2 3 4 |
|
売上データのキャンセル処理/cancel#
- JSONデータを使用したPOST処理となります。
- 未確定売上データ1件をキャンセルします。
リクエストパラメータ#
パラメータ | 設定値 | 形式 | 必須 | 備考 |
---|---|---|---|---|
PROGRAM_ID | プログラムID | URL | 必須 | A8.net より発行されたプログラムID |
api_key | API認証キー | JSON | 必須 | A8.net より発行されるプログラムID に紐づく確定 API 認証キー |
order_id | オーダーID | URL | 必須 | A8.net より発行される売上データのユニークキー |
reason_code | 修正理由コード | JSON | 必須 |
1: 品切れのため 2: 返品のため 3: 追加発注のため 4: 注文金額の変更 5: 単価の変更のため 6: その他 |
レスポンスフィールド#
フィールド | 設定値 | 型 | 備考 |
---|---|---|---|
status_code | ステータスコード | 数値 | 別途ステータスコード一覧を参照 |
message | メッセージ | 文字列 |
サンプルコード#
リクエスト
1 2 3 4 5 6 7 8 |
|
Note
リクエストサンプルコード解説ポイント
・ins/の後にプログラムIDの値を設定します。null及び省略は不可となります。
・api_keyはnull及び省略不可ですので必ず入れてください。
・order_idはnull及び省略不可ですので必ず入れてください。
・reason_codeはnull及び省略不可ですので必ず入れてください。
・URL末尾はcancelになります。
レスポンス結果
1 2 3 4 |
|
当日確定データの取得/sealed/today#
- GET処理となります。
- 当日に確定またはキャンセルした売上データを一覧で取得します。
- 1度に取得できる確定データは 10,000 件となります。10,000 件を超える確定データがある場合には、データ取得開始位置パラメータを変更してください。
リクエストパラメータ#
パラメータ | 設定値 | 形式 | 必須 | 備考 |
---|---|---|---|---|
PROGRAM_ID | プログラムID | URL | 必須 | A8.net より発行されたプログラムID ..../v2/ins/の後ろに設定します。 |
api_key | API認証キー | GET | 必須 | A8.net より発行されるプログラムID に紐づく確定 API 認証キー |
order_id | オーダーID | GET | 任意 | A8.net より発行される売上データのユニークキー |
order_no | 注文番号 | GET | 任意 | 申込1件毎に御社システムが発行する注文(申込)番号を設定。 |
offset | データ取得開始位置 | GET | 任意 | デフォルト: 0 任意の位置からデータを取得できます。例10001件目から先を取得。 |
レスポンスフィールド#
フィールド | 設定値 | 型 | 備考 | |||||
---|---|---|---|---|---|---|---|---|
status_code | ステータスコード | 数値 | 別途ステータスコード一覧を参照 | |||||
message | メッセージ | 文字列 | ||||||
results | 取得したリスト | 配列 | ||||||
deide_ymd | 確定日 | 文字列 | yyyy/MM/dd HH:MI:SS 形式 | |||||
sales_ymd | 売上発生日 | 文字列 | yyyy/MM/dd HH:MI:SS 形式 | |||||
as_id | メディアID | 文字列 | A8.netで管理しているメディアID | |||||
order_id | オーダーID | 文字列 | A8.net より発行される売上データのユニークキー | |||||
order_no | 注文番号 | 文字列 | 申込1件毎に御社システムが発行している注文(申込)番号 | |||||
decide_flg | 確定フラグ | 数値 | 0=未確定, 1=確定 | |||||
order_count | 注文件数 | 数値 | ||||||
order_money | 注文金額 | 数値 | ||||||
pay_money | 成果報酬額 | 数値 | ||||||
items | 商品リスト | 配列 | ||||||
code | 商品コード | 文字列 | 御社システム側で発行している商品を識別するコード | |||||
price | 商品単価 | 数値 | ||||||
quantity | 商品個数 | 数値 |
サンプルコード#
リクエスト
1 2 3 4 5 6 7 8 |
|
Note
リクエストサンプルコード解説ポイント
・ins/の後にプログラムIDの値を設定します。null及び省略は不可となります。
・api_keyはnull及び省略不可ですので必ず入れてください。
・例ではorder_idは省略しています。
・例ではorder_noはnull値が入っていますので、省略時と同じ全件検索となります。
・例ではoffsetはnull値が入っていますので、省略時と同じくデータを1件目から取得します。
・URLのプログラムIDの後にsealed/todayを指定します。
レスポンス結果
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
|
当日確定データの取消処理/revival#
- JSONデータを使用したPOST処理となります。
- 当日中に確定またはキャンセルした売上データ1件の確定ステータスを未確定に戻します。
- 前日以前に確定したデータは取消・変更できません。
リクエストパラメータ#
パラメータ | 設定値 | 形式 | 必須 | 備考 |
---|---|---|---|---|
PROGRAM_ID | プログラムID | URL | 必須 | A8.net より発行されたプログラムID |
api_key | API認証キー | JSON | 必須 | A8.net より発行されるプログラムID に紐づく確定 API 認証キー |
order_id | オーダーID | URL | 必須 | A8.net より発行される売上データのユニークキー |
レスポンスフィールド#
フィールド | 設定値 | 型 | 備考 |
---|---|---|---|
status_code | ステータスコード | 数値 | 別途ステータスコード一覧を参照 |
message | メッセージ | 文字列 |
サンプルコード#
リクエスト
1 2 3 4 5 6 7 |
|
Note
リクエストサンプルコード解説ポイント
・ins/の後にプログラムIDの値を設定します。null及び省略は不可となります。
・api_keyはnull及び省略不可ですので必ず入れてください。
・order_idはnull及び省略不可ですので必ず入れてください。
・URL末尾はrevivalになります。
レスポンス結果
1 2 3 4 |
|
確定済みデータの取得/sealed#
- GET処理となります。
- 前日(指定日)以前に確定またはキャンセルした確定データを一覧で取得します。
- 91日以上前に確定またはキャンセルした確定データは取得できません。
- 1度に取得できる確定データは 10,000 件となります。10,000 件を超える確定データがある場合には、データ取得開始位置パラメータを変更してください。
リクエストパラメータ#
パラメータ | 設定値 | 形式 | 必須 | 備考 |
---|---|---|---|---|
PROGRAM_ID | プログラムID | URL | 必須 | A8.net より発行されたプログラムID ..../v2/ins/の後ろに設定します。 |
api_key | API認証キー | GET | 必須 | A8.net より発行されるプログラムID に紐づく確定 API 認証キー |
date | 確定日 | GET | 任意 | yyyyMMdd。指定なし:全件取得 |
order_id | オーダーID | GET | 任意 | A8.net より発行される売上データのユニークキー |
order_no | 注文番号 | GET | 任意 | 申込1件毎に御社システムが発行する注文(申込)番号を設定。 |
offset | データ取得開始位置 | GET | 任意 | デフォルト: 0 任意の位置からデータを取得できます。例10001件目から先を取得。 |
レスポンスフィールド#
フィールド | 設定値 | 型 | 備考 | |||||
---|---|---|---|---|---|---|---|---|
status_code | ステータスコード | 数値 | 別途ステータスコード一覧を参照 | |||||
message | メッセージ | 文字列 | ||||||
results | 取得したリスト | 配列 | ||||||
deide_ymd | 確定日 | 文字列 | yyyy/MM/dd 形式 | |||||
sales_ymd | 売上発生日 | 文字列 | yyyy/MM/dd 形式 | |||||
as_id | メディアID | 文字列 | A8.netで管理しているメディアID | |||||
order_id | オーダーID | 文字列 | A8.net より発行される売上データのユニークキー | |||||
order_no | 注文番号 | 文字列 | 申込1件毎に御社システムが発行している注文(申込)番号 | |||||
decide_flg | 確定フラグ | 数値 | 0=未確定, 1=確定 | |||||
order_count | 注文件数 | 数値 | ||||||
order_money | 注文金額 | 数値 | ||||||
pay_money | 成果報酬額 | 数値 |
サンプルコード#
リクエスト
1 2 3 4 5 6 7 8 9 10 |
|
Note
リクエストサンプルコード解説ポイント
・ins/の後にプログラムIDの値を設定します。null及び省略は不可となります。
・api_keyはnull及び省略不可ですので必ず入れてください。
・例ではorder_idはnull値が入っていますので、省略時と同じ全件検索となります。
・例ではorder_noは省略しています。
・例では現在日の前日をYYYYMMMDD形式にしてdateパラメータとして設定しています。nullや省略した場合は全件検索となります。
・例ではoffsetはnull値が入っていますので、省略時と同じくデータを1件目から取得します。
・URLのプログラムIDの後にsealedを指定します。
レスポンス結果
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
|
ステータスコード一覧#
- レスポンスフィールドの status_code および message の一覧です。
ステータスコード
コード | 内容 |
---|---|
10000 | 処理が成功しました。 |
10001 | プログラム ID の桁数は 15 桁にしてください。 |
10002 | オーダーID の桁数は 12 桁にしてください。 |
10004 | 認証に失敗しました。 |
10007 | 該当するオーダーID がありません。 10018 処理中にエラーが発生しました。 |
10023 | リクエスト JSON の型式が不正です。 |
10024 | リクエスト URL が不正です。 |
20000 | 注文番号は 50 桁以内にしてください。 |
20001 | 日時は YYYYMMDD もしくは YYYYMM の形で指定してください。 |
20002 | データ取得開始位置は数値を指定してください。 |
30102 | 指定されたオーダーID は確定済みです。 |
30103 | 指定されたオーダーID は承認待ち状態です。 |
30105 | データの整合性にエラーがあります。 |
30106 | データの整合性にエラーがあります。 |
30107 | データの整合性にエラーがあります。 |
30108 | データの整合性にエラーがあります。 |
30109 | データの整合性にエラーがあります。 |
30110 | データの整合性にエラーがあります。 |
30111 | データの整合性にエラーがあります。 |
30112 | データの整合性にエラーがあります。 |
30113 | データの整合性にエラーがあります。 |
30114 | データの整合性にエラーがあります。 |
30115 | データの整合性にエラーがあります。 |
30117 | データの整合性にエラーがあります。 |
30118 | DB 更新処理時に異常が発生しました。 |
30119 | キャンセル理由コードを指定してください。 |
30120 | キャンセル理由コードが不正です。 |
30301 | DB 更新処理時に異常が発生しました。 |
30311 | 商品リストが抽出できません。 |
30312 | 商品リストが配列型ではありません。 |
30313 | 商品コードを指定してください。 |
30314 | 商品コードが不正です。 |
30315 | 商品単価または商品個数を指定してください。 |
30316 | 商品単価または商品個数が不正です。 |
30317 | 修正理由コードを指定してください。 |
30318 | 修正理由コードが不正です。 |
30322 | 該当する商品コードがありません。 |
30323 | 指定されたオーダーID は確定済みです。 |
30324 | 指定されたオーダーID は商品が複数存在します。 |
30325 | 1オーダー内で総商品売上金額が 20 億を超えることはできません。 |
30401 | DB 更新処理時に異常が発生しました。 |
30411 | 指定されたオーダーID は未確定です。 30413 指定されたオーダーID は承認待ち状態です |
30413 | 指定されたオーダーID は承認待ち状態です |