外部注文データ登録API

2021年8月26日外部注文データ登録API

前提条件

外部注文データ登録APIを利用するためには以下の条件を満たす必要があります。

別途有償サービス「外部注文データ登録API」オプションの契約をしている必要があります。
外部注文データ登録設定画面で認証コードを発行、設定を保存している必要があります。

外部注文データ登録の概要

注文情報をCSVフォーマットに沿って作成し、アップロードをすると注文登録情報を一括で登録できます。

一度に登録できるデータ件数に制限はありませんが、アップロードファイルの最大サイズは10MBです。
1つの注文で登録できる商品の種類は50種類までです。
1つの注文で指定できる配送先は50か所までです。
管理画面での設定に関わらず、取り込まれたCSVファイル内の各項目の値が注文情報として登録されます。
合計請求金額の値と各明細項目の値の整合性が取れない場合、指定された値が注文情報として登録されます。
取り込んだ注文は決済会社との売上処理、キャンセル処理を含むすべての連携処理ができません。
取り込んだ注文が予めmakeshopに登録されている会員IDと紐づく場合は対象会員のショップのマイページの購入履歴に表示されます。

ご利用前の準備

外部注文データ連携設定画面で外部注文データ登録APIを利用するための設定を行います。

No	項目名	説明
1	外部注文データ	外部注文データ登録設定画面に遷移します。
2	認証コード	発行ボタン押下で認証コードを発行し、入力不可のテキスト領域に認証コードを表示します。保存ボタンが押下されるまでは発行した認証コードを保存しません。一度も保存を行っていない場合は認証を行えないため、商品情報取得APIの各機能を利用できません。認証コードの登録の有無により発行ボタンの文言が切り替わります。認証コードが保存されていない場合は「発行」を表示、認証コードが保存されている場合は「再発行」を表示。
3	連携設定	当APIの利用可否を制御します。許可状態の変更は既存の注文には影響しない。
4	保存ボタン	上記で設定された外部注文データ登録の設定を保存します。連携設定が「許可しない」の場合、外部注文データ登録APIの各機能を利用できません。

外部注文データ登録APIの処理フロー

以下が外部注文データ登録API利用時の概略図です。

API仕様

API名	概要	送信方法	送信文字コード	レスポンス形式	レスポンス文字コード	備考
認証API	一時キーとアップロード先URLを返却する	POST	UTF-8	application/json	UTF-8
登録受付API	CSVファイルを受け取り、バッチ処理対象に加える	POST	UTF-8	application/json	UTF-8	ファイルサイズ等のファイルに関する基本的なチェックを実施。各項目のバリデートチェックは行わない。
登録結果取得API	CSVファイルから注文データを登録した結果を返却する	POST	UTF-8	application/json	UTF-8	CSV各項目のバリデートチェック結果は当APIにて返却。結果取得の期限は登録受付APIから当日含め30日間有効。
エラー詳細取得API	登録結果取得APIでのエラー内容の結果記載ファイルを返却する	POST	UTF-8	application/json	UTF-8	・バリデートチェックエラーの場合
エラー詳細取得API	登録結果取得APIでのエラー内容の結果記載ファイルを返却する	POST	UTF-8	application/octet-stream	※CSVファイルはSJIS-win	・バリデートチェックOKの場合

認証APIの仕様

外部注文データ登録用の一時キーとアップロード先URLを取得します。

リクエストURL


https://www.makeshop.jp/api/order_upload/auth.html

送信パラメータ

method：post

No	項目名	必須	説明
1	id	○	ショップID（メイクショップの管理画面ログインID） ※副管理者IDは使えません。
2	auth_code	○	makeshop管理画面で発行、登録した認証コード

○：必須項目

戻りパラメータ

No	項目名	パラメータ名	必須	説明
1	アップロードURL	url	△※1	アップロード先URL
2	一時キー	temp_key	△※1	登録受付APIへのアクセスに必要となる一時キー（初回発行時より5分間有効）
3	エラーメッセージ	error_message	△※2	エラーメッセージ

〇：機能を利用できる場合、必ず返却します。
△：項目パラメータのキー値は必ず返却するが、条件により値が空になります。
※1 送信パラメータを利用した認証に成功した場合、返却します。
※2 送信パラメータによる認証時にエラーが発生した場合、返却します。

送信結果の判定について

送信結果の成功/エラーの判定はHTTPステータスにて行っていただけます。

HTTPステータスコード	送信結果	備考
200	成功
400番台	送信パラメータエラー
500	システムエラー

登録受付APIの仕様

一時キーと共に注文データのCSVファイルを取得したURLにアップロードします。

リクエストURL

認証APIで取得したURL

送信パラメータ

method：post
nctype：multipart/form-data
アップロード可能な最大ファイルサイズは10MBです。

No	項目名	必須	説明
1	key	○	認証APIで取得した一時キー（初回発行時より5分間有効）
2	upload_file	○	注文データCSVファイル

○：必須項目

戻りパラメータ

No	送信結果	パラメータ名		説明
1	注文登録受付番号	order_receipt_number	△※1	アップロード先URL
2	一時キー	temp_key	△※1	注文登録受付番号（登録結果取得APIで使用する）
3	エラーメッセージ	error_message	△※2	エラーメッセージ

△：項目パラメータのキー値は必ず返却するが、条件により値が空になります。
※1 送信パラメータを利用した認証に成功した場合、返却します。
※2 送信パラメータによる認証時にエラーが発生した場合、返却します。

送信結果の判定について

送信結果の成功/エラーの判定はHTTPステータスにて行っていただけます。

HTTPステータスコード	送信結果	備考
200	成功
400番台	送信パラメータエラー
500	システムエラー

サンプルCSV

サポート対象
アップロードファイルのフォーマットは以下からダウンロードして確認してください。

最新フォーマット項目一覧

CSVファイルの一行目は項目名です。登録する商品のデータは2行目から記載してください。
各注文情報の〇は入力必須項目です。

列番号	Excel上の列記号	項目名	各注文情報		備考
列番号	Excel上の列記号	項目名	1行目	2行目以降	備考
1	A	受注番号	○	○	半角英数字81文字以内で任意の注文番号を指定してください。注文の特定に使用します。取り込まれた注文にはmakeshopの注文番号が採番されます。入力例：20130130101629-5108746d3d7ba


2	B	配送先番号	○	○	配送先の特定のため指定します。配送先が1つの注文は1のみを指定してください。 1：通常配送 2～：配送先の数に応じる


3	C	受注日時	○		受注日時を半角数字で指定してください。形式はyyyymmddhhmmssで指定してください。入力例：20191115123015


4	D	入金確認日時			入金確認日時を半角数字で指定してください。形式はyyyymmddhhmmssで指定してください。入力例：20191118164500


5	E	決済方法コード	○		決済方法のコードを指定してください。 ※小文字では登録できません。 C：クレジットカード（イプシロン） T：クレジットカード（ペイジェント） Y：クレジット（ペイメントゲートウェイ） Z：コンビニ決済（イプシロン） F：コンビニ決済（ペイメントゲートウェイ） Q：キャリア決済（イプシロン） U：キャリア決済（ペイメントゲートウェイ） D1：Amazon Pay L1：atone R：代引き B：銀行振込 P：郵便振込 N：NP後払い（手動）取り込み後、決済会社との連携はできません。 C、T、Y、Z、F、Q、U、D1、L1は決済完了ステータスで取り込まれます。 R、B、P、Nは入金確認日時が未入力の場合は未入金ステータス、指定がある場合は入金済みステータスで取り込まれます。

















6	F	会員番号			makeshopにあらかじめ登録されたユーザーの会員IDを半角英数字で指定してください。ショップ上に存在しない、または削除会員の会員IDを指定した場合はエラーとなります。入力例：180723000002


7	G	消費税額合計	〇		0：税抜（内税）、1：税込、2：税抜（外税）※外税時のみ


8	H	消費税フラグ	〇		注文が税込か税別かを指定してください。 0: 税別 1: 税込


9	I	配送手数料合計			注文の合計配送料を半角数字で指定してください。入力例：500
9	I	配送手数料合計			注文の合計配送料を半角数字で指定してください。入力例：500
10	J	決済手数料			注文の合計決済手数料を半角数字で指定してください。決済方法コードがZ、F、R、N以外の場合に数値を指定するとエラーになります。入力例：500


11	K	値引額			注文の割引額を半角数字で指定してください。詳細注文情報では優待会員割引として登録されます。入力例：200


12	L	ポイント値引額			注文の利用ポイントを半角数字で指定してください。入力例：100
12	L	ポイント値引額			注文の利用ポイントを半角数字で指定してください。入力例：100
13	M	請求金額	〇		注文の合計請求金額を半角数字で指定してください。消費税、配送手数料、決済手数料、割引額、商品価格などの累計と指定金額が異なる場合も、指定された金額が合計金額として登録されます。入力例：2980


14	N	注文者名前（姓）	〇		注文者の名前（姓）を指定してください。
15	O	注文者名前（名）			注文者の名前（名）を指定してください。
16	P	注文者フリガナ（姓）	〇		注文者の名前（姓）のフリガナを指定してください。
17	Q	注文者フリガナ（名）			注文者の名前（名）のフリガナを指定してください。
18	R	注文者メールアドレス	〇		注文者のメールアドレスを指定してください。入力例：info@example.com
18	R	注文者メールアドレス	〇		注文者のメールアドレスを指定してください。入力例：info@example.com
19	S	注文者住所：郵便番号	〇		注文者の郵便番号を指定してください。入力例：1508512（150-8512でも可）
19	S	注文者住所：郵便番号	〇		注文者の郵便番号を指定してください。入力例：1508512（150-8512でも可）
20	T	注文者住所：都道府県	〇		注文者の住所の都道府県名をを指定してください。 ※都/道/府/県は任意です。以下の指定が可能です。・各都道府県名・東京(23区内) ・東京(23区外) ・海外・離島部入力例：東京(23区内)








21	U	注文者住所：市区郡町村	〇		注文者の住所の市区群町村を指定してください。入力例：渋谷区
21	U	注文者住所：市区郡町村	〇		注文者の住所の市区群町村を指定してください。入力例：渋谷区
22	V	注文者住所：それ以降の住所			注文者の住所の市区群町村以降を指定してください。入力例：桜丘町
22	V	注文者住所：それ以降の住所			注文者の住所の市区群町村以降を指定してください。入力例：桜丘町
23	W	注文者電話番号	〇		注文者の電話番号を指定してください。入力例：00-0000-0000
23	W	注文者電話番号	〇		注文者の電話番号を指定してください。入力例：00-0000-0000
24	X	注文者からの連絡事項			注文者からの連絡事項を指定してください。入力例：ギフトラッピング希望
24	X	注文者からの連絡事項			注文者からの連絡事項を指定してください。入力例：ギフトラッピング希望
25	Y	処理可否		配送先ごとに指定	配送状態を以下から指定してください。 0：未配送 1：配送完了 2：返送 3：キャンセル




26	Z	配送先名前（姓）	〇	〇配送先ごとに指定	配送先の名前（姓）を指定してください。
26	Z	配送先名前（姓）	〇	〇配送先ごとに指定	配送先の名前（姓）を指定してください。
27	AA	配送先名前（名）		配送先ごとに指定	配送先の名前（名）を指定してください。
28	AB	配送先フリガナ（姓）	〇	〇配送先ごとに指定	配送先の名前（姓）のフリガナを指定してください。
28	AB	配送先フリガナ（姓）	〇	〇配送先ごとに指定	配送先の名前（姓）のフリガナを指定してください。
29	AC	配送先フリガナ（名）		配送先ごとに指定	配送先の名前（名）のフリガナを指定してください。
30	AD	配送先住所：郵便番号	〇	〇配送先ごとに指定	配送先の注文者の郵便番号を指定してください。入力例：1508512（150-8512でも可）
30	AD	配送先住所：郵便番号	〇	〇配送先ごとに指定	配送先の注文者の郵便番号を指定してください。入力例：1508512（150-8512でも可）
31	AE	配送先住所：都道府県	〇	〇配送先ごとに指定	配送先の住所の都道府県名をを指定してください。 ※都/道/府/県は任意です。以下の指定が可能です。・各都道府県名・東京(23区内) ・東京(23区外) ・海外・離島部入力例：東京(23区内)







32	AF	配送先住所：市区郡町村	〇	〇配送先ごとに指定	配送先の住所の市区群町村を指定してください。入力例：渋谷区
32	AF	配送先住所：市区郡町村	〇	〇配送先ごとに指定	配送先の住所の市区群町村を指定してください。入力例：渋谷区
33	AG	配送先住所：それ以降の住所		配送先ごとに指定	配送先の住所の市区群町村以降を指定してください。入力例：桜丘町
33	AG	配送先住所：それ以降の住所		配送先ごとに指定	配送先の住所の市区群町村以降を指定してください。入力例：桜丘町
34	AH	配送先電話番号		配送先ごとに指定	配送先の電話番号を指定してください。入力例：00-0000-0000
34	AH	配送先電話番号		配送先ごとに指定	配送先の電話番号を指定してください。入力例：00-0000-0000
35	AI	配送方法	〇	〇商品ごとに指定	makeshopにあらかじめ登録されている配送方法名を指定してください。商品、配送先ごとに指定が可能です。指定された配送方法がmakeshopに登録されていない場合は「配送方法なし」で登録されます。入力例：佐川急便



36	AJ	配送希望日		配送先ごとに指定	配送希望日を半角数字で指定してください。形式はyyyymmddで指定してください。入力例：20190825


37	AK	配送処理日時			配送処理日時を半角数字で指定してください。形式はyyyymmddhhmmssで指定してください。入力例：20190824102233 ※会員ポイントの有効期限に影響します。



38	AL	配送手数料		商品ごとに指定	商品、配送方法、配送先ごとに配送手数料を指定できます。配送手数料合計と商品、配送方法ごとの配送手数料の合計が一致しない場合も、指定された値が登録されます。配送手数料の明細は注文確認メール（再送用）に表示されます。入力例：300



39	AM	商品コード	〇	〇商品ごとに指定	任意の商品コードを指定してください。 makeshopにあらかじめ登録されている商品の独自商品コードを指定すると、注文情報と商品の紐づけができます。（商品名、商品価格などは取り込まれたデータで登録されます。）入力例：ITEM-001



40	AN	商品名	〇	〇商品ごとに指定	商品名を指定してください。入力例：Tシャツ
40	AN	商品名	〇	〇商品ごとに指定	商品名を指定してください。入力例：Tシャツ
41	AO	選択肢情報		商品ごとに指定	オプションを指定できます。複数のオプションがある場合はパイプ（\|）区切りで指定してください。 2つ以上のオプションが指定された場合、2つ目のオプションにカンマ区切りで登録されます。注文内で同一配送先に同じ商品コードの商品が含まれる場合はエラーとなり登録できません。入力例：色、黒\|サイズ、M（色,黒\|サイズ,Mなどでも可）




42	AP	販売価格	〇	〇商品ごとに指定	商品の販売価格を指定してください。入力例：1980
42	AP	販売価格	〇	〇商品ごとに指定	商品の販売価格を指定してください。入力例：1980
43	AQ	数量	〇	〇商品ごとに指定	商品の購入数を指定してください。入力例：1
43	AQ	数量	〇	〇商品ごとに指定	商品の購入数を指定してください。入力例：1
44	AR	消費税率	〇	〇商品ごとに指定	商品の消費税率を指定してください。 0、5、8、10のみ指定できます。
44	AR	消費税率	〇	〇商品ごとに指定	商品の消費税率を指定してください。 0、5、8、10のみ指定できます。
45	AS	管理者メモ			注文備考などを指定できます。 1行目で入力した注文番号を入力しておくことで、取り込んだ後「メモ」で注文検索することができます。入力例：返品クレームあり


46	AT	軽減税率区分	〇	〇商品ごとに指定	商品の軽減税率区分を以下から指定してください。消費税率が8の場合のみYを設定できます。 Y：軽減税率対象 N：軽減税率対象外



47	AU	消費税0%対象請求金額			消費税0％対象商品の合計金額を半角数字で指定してください。 0円以上の値が登録された場合に指定された金額が合計金額として登録されます。入力例：2980


48	AV	消費税5%対象請求金額			消費税5％対象商品の合計金額を半角数字で指定してください。 0円以上の値が登録された場合に指定された金額が合計金額として登録されます。入力例：2980


49	AW	消費税8%対象請求金額			消費税8％対象商品の合計金額を半角数字で指定してください。 0円以上の値が登録された場合に指定された金額が合計金額として登録されます。入力例：2980


50	AX	消費税10%対象請求金額			消費税10％対象商品の合計金額を半角数字で指定してください。 0円以上の値が登録された場合に指定された金額が合計金額として登録されます。入力例：2980


51	AZ	消費税8%			消費税フラグが2（外税）の場合、必須です。消費税10%との合計が消費税額合計と一致するようにしてください。


52	BA	消費税10%			消費税フラグが2（外税）の場合、必須です。消費税8%との合計が消費税額合計と一致するようにしてください。

登録結果取得APIの仕様

登録受付APIで取得した注文登録受付番号で登録結果を取得する。

リクエストURL

https://www.makeshop.jp/api/order_upload/result.html

送信パラメータ

method：post

No	項目名	必須	説明
1	id	○	ショップID（メイクショップの管理画面ログインID） ※副管理者IDは使えません。
2	auth_code	○	makeshop管理画面で発行、登録した認証コード
3	order_receipt_number	○	登録受付APIで返却された注文登録受付番号

○：必須項目

戻りパラメータ

No	項目名	パラメータ名	必須	説明
1	エラーメッセージ	error_message	△※2	送信パラメータに関する処理のエラーメッセージ
2	登録処理ステータス	status	△※1	processing：処理中 complete：全件正常終了 error：1件以上のエラー有り
3	エラー件数	error_count	△※3	エラー件数
4	ダウンロードURL	url	△※3	エラー発生時のエラー詳細CSVファイル取得用URL

〇：機能を利用できる場合、必ず返却します。
△：項目パラメータのキー値は必ず返却するが、条件により値が空になります。
※1 送信パラメータを利用した登録結果取得に成功した場合、返却します。
※2 送信パラメータによる登録結果取得時にエラーが発生した場合、返却します。
※3 送信パラメータによる登録結果取得に成功し、処理ステータス：errorの場合に返却します。

送信結果の判定について

送信結果の成功/エラーの判定はHTTPステータスにて行っていただけます。

HTTPステータスコード	送信結果	備考
200	成功
400番台	送信パラメータエラー

エラー詳細取得APIの仕様

登録結果取得APIでのエラー内容の結果記載ファイルを取得します。

リクエストURL

登録結果取得APIから返却されたURL

送信パラメータ

method：post

No	項目名	必須	説明
1	id	○	ショップID（メイクショップの管理画面ログインID） ※副管理者IDは使えません。
2	auth_code	○	makeshop管理画面で発行、登録した認証コード
3	order_receipt_number	○	登録受付APIで返却された注文登録受付番号

○：必須項目

戻りパラメータ

No	項目名	パラメータ名	必須	説明
1	エラーメッセージ	error_message	△	送信パラメータに関する処理のエラーメッセージ

△：バリデートエラーが発生した場合に返却します。

ダウンロードCSVフォーマット

No	EXCEL上の列番号	内容	説明
1	A	該当行No	エラーが発生した行番号
2	B	エラーメッセージ	CSVによる注文データ登録時のエラーメッセージを返却

※送信された注文登録受付番号にエラーが発生していなかった場合はヘッダ行のみの空ファイルとなります。
※CSVファイル名："error_detail"(固定値) + 登録受付番号 + "_"(固定値) + YYYYMMDDHHMMSS + ".csv"(固定値)

送信結果の判定について

送信結果の成功/エラーの判定はHTTPステータスにて行っていただけます。

HTTPステータスコード	送信結果	備考
200	成功
400番台	送信パラメータエラーメッセージ

複数配送注文の取り込み方

配送先番号を指定すると、複数の配送がある注文として取り込むことができます。

▲図1．複数配送注文の取り込み方のCSVファイルのサンプル

配送手数料について

配送先番号を指定することで複数配送注文として取り込むことができます。

1つの注文、1つの配送先を指定し、商品ごとの配送方法および配送手数料に指定した値が一致する場合、配送手数料は包括されます。
例：1つの注文、1つの配送先で配送方法、配送手数料が200円で一致する場合、注文の配送手数料は200円となります。

▲図2-1．1つの注文・配送先と配送方法および配送手数料の値が一致する場合のCSVファイルのサンプル

例：1つの注文、1つの配送先を指定し、商品ごとの配送方法が一致、配送手数料が異なる場合の配送手数料は300円となります。

▲図2-2．1つの注文・配送先を指定し、商品ごとの配送方法が一致、配送手数料が異なる場合のCSVファイルのサンプル

外部注文データ登録API

前提条件

外部注文データ登録の概要

ご利用前の準備

外部注文データ登録APIの処理フロー

API仕様

認証APIの仕様

リクエストURL

送信パラメータ

戻りパラメータ

送信結果の判定について

登録受付APIの仕様

リクエストURL

送信パラメータ

戻りパラメータ

送信結果の判定について

サンプルCSV

最新フォーマット項目一覧

登録結果取得APIの仕様

リクエストURL

送信パラメータ

戻りパラメータ

送信結果の判定について

エラー詳細取得APIの仕様

リクエストURL

送信パラメータ

戻りパラメータ

ダウンロードCSVフォーマット

送信結果の判定について

複数配送注文の取り込み方

配送手数料について

目次

よくある質問

APIテストフォーム

サンプルコード

仕様変更履歴