BカートAPI ドキュメント V1
基本的な仕様について
現在クロスドメインでの接続を許可していないため、JavaScriptでAPIをご利用いただけませんのでご注意ください。(サンプルのjQueryも利用いただけません。)
利用制限について
BカートAPIは300秒につき300回までリクエストすることが可能です。
300秒に300回を越えると300秒間のロックがかかりアクセスできなくなります。
なお、サイトID(Bカート環境のID)とクライアントID(トークンのID)の組み合わせに対してレート制限が適用されます。
またリクエスト上限を超えた場合のみ、レスポンスヘッダーに「Retry-After」というカスタムヘッダーが追加され、解除までの時間を取得することも可能です。
仕様変更について
BカートAPIでは基本的に後方互換性を保ちつつ変更を行います。
例えば廃止予定の項目がある場合、既存の項目は残しつつ新しい項目を追加します。
その後一定期間を設けて廃止予定の項目を削除するような流れとなります。
また、下記のような後方互換性を保った変更は事前の予告なく実施する場合がありますので、これらの変更(例: プロパティの増減や順番)に影響を受けないようにアプリケーションの実装を行ってください。
新しいエンドポイントの追加
既存のエンドポイントに新しいプロパティの追加
必須ではないURIパラメータの追加
APIを使用した構築例について
BカートAPIを使用しての、販売管理システムや倉庫管理システム等の連携について、構築事例をご紹介しております。
APIの使用をご検討されている方、現在使用中で運用方法をご検討されている方などはこちらをご参照ください。
権限について
APIの利用できる許可を管理することが出来ます。 パーソナルアクセストークンの場合は発行する際にスコープを設定することが出来ます。
Oauthクライアントの場合はクライアント側で許可コードリクエスト時にパラメータを送りログイン時に許可します。
スコープ一覧
アクセストークンの取得
パーソナルアクセストークン
詳細はプライベートアプリ開発をご確認ください。
OAuth2.0
先にアプリストア アプリ開発をご確認ください。
1 認可コード取得
まずはアプリ利用者に、アプリがBカートAPIを通して取得するデータのアクセス権について、確認と許可を得るための画面を表示する必要があります。下記のURLにパラメータを設定しリクエストしてください。
許可されることで、アクセストークンをリクエストする際に必要な認可コードが発行されます。
リクエスト例
リクエスト後、アプリ利用者に「許可」された場合は、「code」というクエリパラメータに認可コードが付与されたアプリの「リダイレクトURI」にリダイレクトされます。
※ 認可コードの有効期限は発行から10分間です。
認可ページで「キャンセル」された、または何かしらのエラーが起きた場合は、「error」というクエリパラメータにエラーの内容を表す文字列が付与されます。
2 アクセストークン発行
次に、取得した認可コードを含むパラメータをセットして、以下のURLにアクセストークンをリクエストしてください。
リクエストが成功すると、以下のようなJSONデータが返却されます。
「access_token」には、アクセストークン、「refresh_token」には、アクセストークンを更新するためのリフレッシュトークンが含まれます。
「expires_in」には、アクセストークンが無効になるまでの秒数を含んでいます。アクセストークンの有効期限は14日間です。
リクエストが失敗した場合は下記のようなパラメータを持つエラー内容のJSONデータが返却されます。
3 リフレッシュトークンによるアクセストークンの更新
取得したアクセストークンは有効期限があるため、有効期限が切れそう(切れた)場合は、アクセストークンと合わせて取得したリフレッシュトークン(refresh_token)を使って、新しいアクセストークンを再取得してください。リフレッシュトークンには有効期限はありません。
下記のURLにパラメータを設定しリクエストしてください。
リクエストが成功すると、認可コードとの交換時と同じように以下のようなJSONデータが返却されます。
リフレッシュトークンを使用したアクセストークン再発行時にも、新たなリフレッシュトークンが発行されますので、都度最新のリフレッシュトークンを使用して再発行を行ってください。
使用済みのリフレッシュトークンと、古いアクセストークンは再取得と同時に無効になります。
リクエストが失敗した場合は下記のようなパラメータを持つエラー内容のJSONデータが返却されます。
リクエスト
エンドポイント
BカートAPIはRESTの原則に基づき設計されています。エンドポイントと呼ばれる一意なURIに対してGET、PATCH、POSTといったHTTPメソッドでパラメータを送信することで、取得、更新、登録することが出来ます。
エンドポイントのベースURIは下記になります。
リクエストを行うエンドポイントはAPIを確認ください。
GETリクエストではパラメータを指定することで絞り込みを行うことが出来ます。
マルチバイト文字列を含む場合はURLエンコードする必要があります。
リクエストヘッダ
GET (取得API)
{:access_token}には取得したアクセストークンを記述
PATCH (更新API)
{:access_token}には取得したアクセストークンを記述
※ Content-Typeはapplication/x-www-form-urlencodedでも指定可能です。
POST (登録API)
{:access_token}には取得したアクセストークンを記述
※ Content-Typeはapplication/x-www-form-urlencodedでも指定可能です。
リクエストBODY
更新したい項目をリクエストBODYに指定して実行します。
リクエストBODYに書かれたKEYの値のみ更新されます。
登録のリクエストではリクエストしなかったKEYはデフォルトの値で設定されます。
※KEYによっては必須になる場合があります。
パラメータ
URIパラメータ
一覧取得のリクエストではURLにパラメータをつけることで、レスポンスを絞り込むことが出来ます。 利用できるパラメータは各ドキュメントにあるURIパラメータを参照してください。
共通のURIパラメータ
例:状態が完了している受注情報を5件取得
拡張パラメータ
拡張パラメータを使うことで、より高度な絞り込みが可能になります。
拡張パラメータ一覧
例:状態が完了している2019年5月の受注情報を取得
下記の指定では値にカンマを含む場合に、カンマ区切りの複数値として扱います(値にカンマを含まない場合は単一値として扱います)。
※カスタム項目(IDを配列のキーとして指定する項目)の場合は、検索方式文字列(has, has_any など)の後ろに[ID]を指定してください。下記は一例です。他の拡張パラメータにおいても同様のルールにて指定が可能です(「or__B = x」を除く)。
例)検索対象の項目が「customs[6]」の場合
レスポンス
レスポンスヘッダ
例
レスポンスボディ
レスポンスはJSON形式になります。
エラーレスポンス
APIで正常に処理が行われなかった場合は下記のレスポンスが返ります。
※事前告知の上、よりエラーを明確にする把握できるように仕様を変更する場合がございます。
パラメータの値が不正な場合
errorsのレスポンスが返り、不正なパラメータの結果を返します。
APIの権限、API Keyが不正な場合
存在しないAPIのURLを叩いた場合
リファレンス
各APIのエンドポイントや利用可能なパラメータ、指定可能なりリクエストBODYは下記になります。
また、サンプルのエンドポイントにあるID、リクエストBODYなどはサンプルになります。
GETproduct_customs
application/json
Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6IjNkNTk3NGU2NGVmMjUzYjgxZGNlODQ1MThkMWQwYzE2ZThjOTYxZGJhODY4ZDNjYTM1YzRmMmQ0Yjg0M2M4ZGYwNzYyYTA5MDBlYmY0MmEzIn0.eyJhdWQiOiI5IiwianRpIjoiM2Q1OTc0ZTY0ZWYyNTNiODFkY2U4NDUxOGQxZDBjMTZlOGM5NjFkYmE4NjhkM2NhMzVjNGYyZDRiODQzYzhkZjA3NjJhMDkwMGViZjQyYTMiLCJpYXQiOjE1NjEzNTMwODksIm5iZiI6MTU2MTM1MzA4OSwiZXhwIjoxNTkyOTc1NDg5LCJzdWIiOiI4OCIsInNjb3BlcyI6WyJwcm9kdWN0cy1yZWFkIiwicHJvZHVjdHNfbG9naW4tcmVhZCIsInByb2R1Y3RzLXdyaXRlIiwicHJvZHVjdF9zZXRzLXJlYWQiLCJwcm9kdWN0X3NldHNfbG9naW4tcmVhZCIsInByb2R1Y3Rfc2V0cy13cml0ZSIsInByb2R1Y3Rfc3RvY2stcmVhZCIsInByb2R1Y3Rfc3RvY2std3JpdGUiLCJjYXRlZ29yaWVzLXJlYWQiLCJjdXN0b21lcnMtcmVhZCIsImN1c3RvbWVycy13cml0ZSIsImxvZ2luLXJlYWQiLCJvdGhlcl9hZGRyZXNzZXMtcmVhZCIsIm9yZGVycy1yZWFkIiwib3JkZXJzLXdyaXRlIiwib3JkZXJfcHJvZHVjdHMtcmVhZCIsIm9yZGVyX3Byb2R1Y3RzLXdyaXRlIiwibG9naXN0aWNzLXJlYWQiLCJsb2dpc3RpY3Mtd3JpdGUiLCJwcmljZV9ncm91cHMtcmVhZCIsInZpZXdfZ3JvdXBzLXJlYWQiLCJzaGlwcGluZ19ncm91cHMtcmVhZCJdfQ.N2gaXBEG3q--83orYpka1WFepyOxuAt3Felo8YjbXlXN4KYsi74CJot06oZnfCK5X6Y9Tzvx8Ew4s0V__6K0MkBgPHgZjwzwlqjfWXMFQ8wEgNYAeiyofLyolSoeE5i-FT7tb8iMs3NXPJGzs2pLBSKaqRA40cWUSibDRSlqh1_ntBeCjDYA3TMrNQNAnys-dbqCpzN-MkDN-W79c6ZXiLJBMdEER6euP_zDgOF0s4aK2YV3vcMdB5B8DzNtdw_K0uY13fzB6R9b7F9ENfp0GnLg2C2fnK9czU1vaH4CwNtg0kuhM97LHNH1aZepmFlp60ehRcD5cnu1Yog-q8jCaaYZGe4wTtGbuLSB6E-g8OaVJCk3j5Nc6HWqgMqgsO8GY4smbfuDB960NaO-Dl10NewOb-WEWcIN-sIUoGByVLZzF5Uy05q4Et5Z1nYqinAn9Y9uH2AvfOv5nGoq7rwVufOeMXhq3bDGcctv2RWL4PoL6hH_x9wy4AtW0RNDF0zOjfmX7fNaJYdbmiEQW9_DYqZzJt11tTquzn2c5LzJRzNAaDDuF8nulvmrTPW57Zn5lbILu9jGrZtmhgfnU53zYqThM0yCTHB4_1DE0Nb7a6fCAp-dQCkr-Ww5ilStmL2q-mrdBkQtpu3Pij1DgD7GDbMEpEr3KbE70UqyjKQIa64
nginx
application/json
chunked
keep-alive
no-cache, private
Tue, 12 Dec 2023 09:41:06 GMT
300
299
PATCHproduct_customs/:id
リクエストBODY
application/json
Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6IjNkNTk3NGU2NGVmMjUzYjgxZGNlODQ1MThkMWQwYzE2ZThjOTYxZGJhODY4ZDNjYTM1YzRmMmQ0Yjg0M2M4ZGYwNzYyYTA5MDBlYmY0MmEzIn0.eyJhdWQiOiI5IiwianRpIjoiM2Q1OTc0ZTY0ZWYyNTNiODFkY2U4NDUxOGQxZDBjMTZlOGM5NjFkYmE4NjhkM2NhMzVjNGYyZDRiODQzYzhkZjA3NjJhMDkwMGViZjQyYTMiLCJpYXQiOjE1NjEzNTMwODksIm5iZiI6MTU2MTM1MzA4OSwiZXhwIjoxNTkyOTc1NDg5LCJzdWIiOiI4OCIsInNjb3BlcyI6WyJwcm9kdWN0cy1yZWFkIiwicHJvZHVjdHNfbG9naW4tcmVhZCIsInByb2R1Y3RzLXdyaXRlIiwicHJvZHVjdF9zZXRzLXJlYWQiLCJwcm9kdWN0X3NldHNfbG9naW4tcmVhZCIsInByb2R1Y3Rfc2V0cy13cml0ZSIsInByb2R1Y3Rfc3RvY2stcmVhZCIsInByb2R1Y3Rfc3RvY2std3JpdGUiLCJjYXRlZ29yaWVzLXJlYWQiLCJjdXN0b21lcnMtcmVhZCIsImN1c3RvbWVycy13cml0ZSIsImxvZ2luLXJlYWQiLCJvdGhlcl9hZGRyZXNzZXMtcmVhZCIsIm9yZGVycy1yZWFkIiwib3JkZXJzLXdyaXRlIiwib3JkZXJfcHJvZHVjdHMtcmVhZCIsIm9yZGVyX3Byb2R1Y3RzLXdyaXRlIiwibG9naXN0aWNzLXJlYWQiLCJsb2dpc3RpY3Mtd3JpdGUiLCJwcmljZV9ncm91cHMtcmVhZCIsInZpZXdfZ3JvdXBzLXJlYWQiLCJzaGlwcGluZ19ncm91cHMtcmVhZCJdfQ.N2gaXBEG3q--83orYpka1WFepyOxuAt3Felo8YjbXlXN4KYsi74CJot06oZnfCK5X6Y9Tzvx8Ew4s0V__6K0MkBgPHgZjwzwlqjfWXMFQ8wEgNYAeiyofLyolSoeE5i-FT7tb8iMs3NXPJGzs2pLBSKaqRA40cWUSibDRSlqh1_ntBeCjDYA3TMrNQNAnys-dbqCpzN-MkDN-W79c6ZXiLJBMdEER6euP_zDgOF0s4aK2YV3vcMdB5B8DzNtdw_K0uY13fzB6R9b7F9ENfp0GnLg2C2fnK9czU1vaH4CwNtg0kuhM97LHNH1aZepmFlp60ehRcD5cnu1Yog-q8jCaaYZGe4wTtGbuLSB6E-g8OaVJCk3j5Nc6HWqgMqgsO8GY4smbfuDB960NaO-Dl10NewOb-WEWcIN-sIUoGByVLZzF5Uy05q4Et5Z1nYqinAn9Y9uH2AvfOv5nGoq7rwVufOeMXhq3bDGcctv2RWL4PoL6hH_x9wy4AtW0RNDF0zOjfmX7fNaJYdbmiEQW9_DYqZzJt11tTquzn2c5LzJRzNAaDDuF8nulvmrTPW57Zn5lbILu9jGrZtmhgfnU53zYqThM0yCTHB4_1DE0Nb7a6fCAp-dQCkr-Ww5ilStmL2q-mrdBkQtpu3Pij1DgD7GDbMEpEr3KbE70UqyjKQIa64
application/json
nginx
application/json
chunked
keep-alive
no-cache, private
Tue, 12 Dec 2023 09:42:41 GMT
300
298
PATCHproduct_customs
リクエストBODY
application/json
Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6IjNkNTk3NGU2NGVmMjUzYjgxZGNlODQ1MThkMWQwYzE2ZThjOTYxZGJhODY4ZDNjYTM1YzRmMmQ0Yjg0M2M4ZGYwNzYyYTA5MDBlYmY0MmEzIn0.eyJhdWQiOiI5IiwianRpIjoiM2Q1OTc0ZTY0ZWYyNTNiODFkY2U4NDUxOGQxZDBjMTZlOGM5NjFkYmE4NjhkM2NhMzVjNGYyZDRiODQzYzhkZjA3NjJhMDkwMGViZjQyYTMiLCJpYXQiOjE1NjEzNTMwODksIm5iZiI6MTU2MTM1MzA4OSwiZXhwIjoxNTkyOTc1NDg5LCJzdWIiOiI4OCIsInNjb3BlcyI6WyJwcm9kdWN0cy1yZWFkIiwicHJvZHVjdHNfbG9naW4tcmVhZCIsInByb2R1Y3RzLXdyaXRlIiwicHJvZHVjdF9zZXRzLXJlYWQiLCJwcm9kdWN0X3NldHNfbG9naW4tcmVhZCIsInByb2R1Y3Rfc2V0cy13cml0ZSIsInByb2R1Y3Rfc3RvY2stcmVhZCIsInByb2R1Y3Rfc3RvY2std3JpdGUiLCJjYXRlZ29yaWVzLXJlYWQiLCJjdXN0b21lcnMtcmVhZCIsImN1c3RvbWVycy13cml0ZSIsImxvZ2luLXJlYWQiLCJvdGhlcl9hZGRyZXNzZXMtcmVhZCIsIm9yZGVycy1yZWFkIiwib3JkZXJzLXdyaXRlIiwib3JkZXJfcHJvZHVjdHMtcmVhZCIsIm9yZGVyX3Byb2R1Y3RzLXdyaXRlIiwibG9naXN0aWNzLXJlYWQiLCJsb2dpc3RpY3Mtd3JpdGUiLCJwcmljZV9ncm91cHMtcmVhZCIsInZpZXdfZ3JvdXBzLXJlYWQiLCJzaGlwcGluZ19ncm91cHMtcmVhZCJdfQ.N2gaXBEG3q--83orYpka1WFepyOxuAt3Felo8YjbXlXN4KYsi74CJot06oZnfCK5X6Y9Tzvx8Ew4s0V__6K0MkBgPHgZjwzwlqjfWXMFQ8wEgNYAeiyofLyolSoeE5i-FT7tb8iMs3NXPJGzs2pLBSKaqRA40cWUSibDRSlqh1_ntBeCjDYA3TMrNQNAnys-dbqCpzN-MkDN-W79c6ZXiLJBMdEER6euP_zDgOF0s4aK2YV3vcMdB5B8DzNtdw_K0uY13fzB6R9b7F9ENfp0GnLg2C2fnK9czU1vaH4CwNtg0kuhM97LHNH1aZepmFlp60ehRcD5cnu1Yog-q8jCaaYZGe4wTtGbuLSB6E-g8OaVJCk3j5Nc6HWqgMqgsO8GY4smbfuDB960NaO-Dl10NewOb-WEWcIN-sIUoGByVLZzF5Uy05q4Et5Z1nYqinAn9Y9uH2AvfOv5nGoq7rwVufOeMXhq3bDGcctv2RWL4PoL6hH_x9wy4AtW0RNDF0zOjfmX7fNaJYdbmiEQW9_DYqZzJt11tTquzn2c5LzJRzNAaDDuF8nulvmrTPW57Zn5lbILu9jGrZtmhgfnU53zYqThM0yCTHB4_1DE0Nb7a6fCAp-dQCkr-Ww5ilStmL2q-mrdBkQtpu3Pij1DgD7GDbMEpEr3KbE70UqyjKQIa64
application/json
nginx
application/json
chunked
keep-alive
no-cache, private
Tue, 12 Dec 2023 09:46:39 GMT
300
298
POSTproduct_customs
リクエストBODY
application/json
Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6IjNkNTk3NGU2NGVmMjUzYjgxZGNlODQ1MThkMWQwYzE2ZThjOTYxZGJhODY4ZDNjYTM1YzRmMmQ0Yjg0M2M4ZGYwNzYyYTA5MDBlYmY0MmEzIn0.eyJhdWQiOiI5IiwianRpIjoiM2Q1OTc0ZTY0ZWYyNTNiODFkY2U4NDUxOGQxZDBjMTZlOGM5NjFkYmE4NjhkM2NhMzVjNGYyZDRiODQzYzhkZjA3NjJhMDkwMGViZjQyYTMiLCJpYXQiOjE1NjEzNTMwODksIm5iZiI6MTU2MTM1MzA4OSwiZXhwIjoxNTkyOTc1NDg5LCJzdWIiOiI4OCIsInNjb3BlcyI6WyJwcm9kdWN0cy1yZWFkIiwicHJvZHVjdHNfbG9naW4tcmVhZCIsInByb2R1Y3RzLXdyaXRlIiwicHJvZHVjdF9zZXRzLXJlYWQiLCJwcm9kdWN0X3NldHNfbG9naW4tcmVhZCIsInByb2R1Y3Rfc2V0cy13cml0ZSIsInByb2R1Y3Rfc3RvY2stcmVhZCIsInByb2R1Y3Rfc3RvY2std3JpdGUiLCJjYXRlZ29yaWVzLXJlYWQiLCJjdXN0b21lcnMtcmVhZCIsImN1c3RvbWVycy13cml0ZSIsImxvZ2luLXJlYWQiLCJvdGhlcl9hZGRyZXNzZXMtcmVhZCIsIm9yZGVycy1yZWFkIiwib3JkZXJzLXdyaXRlIiwib3JkZXJfcHJvZHVjdHMtcmVhZCIsIm9yZGVyX3Byb2R1Y3RzLXdyaXRlIiwibG9naXN0aWNzLXJlYWQiLCJsb2dpc3RpY3Mtd3JpdGUiLCJwcmljZV9ncm91cHMtcmVhZCIsInZpZXdfZ3JvdXBzLXJlYWQiLCJzaGlwcGluZ19ncm91cHMtcmVhZCJdfQ.N2gaXBEG3q--83orYpka1WFepyOxuAt3Felo8YjbXlXN4KYsi74CJot06oZnfCK5X6Y9Tzvx8Ew4s0V__6K0MkBgPHgZjwzwlqjfWXMFQ8wEgNYAeiyofLyolSoeE5i-FT7tb8iMs3NXPJGzs2pLBSKaqRA40cWUSibDRSlqh1_ntBeCjDYA3TMrNQNAnys-dbqCpzN-MkDN-W79c6ZXiLJBMdEER6euP_zDgOF0s4aK2YV3vcMdB5B8DzNtdw_K0uY13fzB6R9b7F9ENfp0GnLg2C2fnK9czU1vaH4CwNtg0kuhM97LHNH1aZepmFlp60ehRcD5cnu1Yog-q8jCaaYZGe4wTtGbuLSB6E-g8OaVJCk3j5Nc6HWqgMqgsO8GY4smbfuDB960NaO-Dl10NewOb-WEWcIN-sIUoGByVLZzF5Uy05q4Et5Z1nYqinAn9Y9uH2AvfOv5nGoq7rwVufOeMXhq3bDGcctv2RWL4PoL6hH_x9wy4AtW0RNDF0zOjfmX7fNaJYdbmiEQW9_DYqZzJt11tTquzn2c5LzJRzNAaDDuF8nulvmrTPW57Zn5lbILu9jGrZtmhgfnU53zYqThM0yCTHB4_1DE0Nb7a6fCAp-dQCkr-Ww5ilStmL2q-mrdBkQtpu3Pij1DgD7GDbMEpEr3KbE70UqyjKQIa64
application/json
nginx
application/json
chunked
keep-alive
no-cache, private
Tue, 12 Dec 2023 09:48:53 GMT
300
297
在庫
商品セットの在庫