ReCORE co-api 仕様書
概要
- 外部からReCOREを操作するためのAPI群を提供する
APIキーについて
- APIキーの発行は弊社へご依頼ください。
- キーはJWTで、
company_id scope iatが必ず含まれます。その他個別で必要なパラメータが含まれる場合があります。
- クライアントサイドから直接リクエストする(クライアントサイドにAPIキーを埋め込む)場合、情報漏洩などを防ぐためAPIキーのスコープを必ず確認し、不必要なスコープが割り当てられていないことを確認してください。
- 後述の通り、JWT個別パラメータの
store_idは、JWT内にその指定がない場合に限りリクエストヘッダで指定が可能です。情報漏洩を防ぐためstore_idが指定されていないJWTを使用する場合、それが適切かどうか検討してください。
- キーが漏洩した可能性がある場合は、漏洩したキーを添えて速やかに弊社までご連絡ください。
API共通基本仕様
リクエスト先
https://co-api.recore-pos.com
| key |
value |
| X-Identification |
(APIキー) |
| Content-Type |
application/json |
例
GET /products
X-Identification: eyJ0...
Content-Type: application/json
200 OK
400 Bad Request
{
"error": {
"code": "VALIDATE_FAILED",
"message": "入力値が不正です",
"detail": {
"pickup_date": [
"Pickup date can't be blank"
]
}
}
}
API共通特記事項
スロットリングについて
- 各APIエンドポイントごとに、1秒間あたりの最大リクエスト回数に制限があります。
- APIキーと接続元IPの組み合わせ毎に制御が行われます。
- 制限を超過すると 429 Too Many Requests が返却されます。
JWT個別パラメータstore_idについて
store_idはどの店舗のデータを操作するかを指定するものです。- JWT内に該当パラメータを持たない場合、
X-Store-Idをリクエストヘッダにつけることで指定が可能です。
- JWT内で指定がある場合その値が使用され、リクエストヘッダで書き換えることはできません。
ページネーションについて
概要
- リクエストパラメータとして
limit pageに対応したAPIの場合はオフセットページネーションが、limit cursorの場合はカーソルページネーションが利用できます。
オフセットページネーションについて
- 特に何も指定しない場合はこのモードで動作します。
- レスポンスヘッダに
X-Total-Countが必ず含まれ、検索結果の総件数（ただし上限1000件）が返却されます。
カーソルページネーションについて
- リクエストパラメータに
cursorが含まれる場合このモードで動作します。
- データを全件取得するようなユースケースではこのモードで操作してください。
- オフセットページネーションでは、取得中にデータの更新があった場合、取得漏れが発生します。
pageは無視されます。またレスポンスヘッダにX-Total-Countは含まれません。- 取得手順は次の通りです。疑似コードも例示します。
cursorに空文字（または任意の文字）をセットし、1ページ目を取得します。- レスポンスヘッダの
X-Next-Cursorからトークンを取得、cursorにセットし、次のページを取得します。
X-Next-Cursorがセットされなくなるまで取得を繰り返してください。
let responses = []
let cursor = ''
while (true) {
const query = {
updated_at_from: '2024-04-04 00:00:00',
updated_at_to: '2024-04-04 23:59:59',
cursor
}
const { body, header } = await api.get('/ec/orders?' + stringify(query))
responses = [...responses, ...body]
cursor = header['X-Next-Cursor']
if (!cursor) {
break
}
}
個別仕様書