更新履歴
最終更新日: 2023/07/20
ver. | 年月日 | 更新内容 |
---|---|---|
0.1 | 2021/04/15 | ・新規作成 |
0.2 | 2021/05/03 | ・「4.1.5 Get item detail content data API」のレスポンスに「item_detail_code」を追加 ・「4.1.5 Get item detail content data API」のリクエストとレスポンスの属性を変更 ・「6.3.2 Update Table Activity API」のHTTPメソッドを変更 ・「7. エラーコード」を追記 |
0.3 | 2021/05/20 | ・「5.3.1 Create Order API 」リクエストパラメータの"order_details.tax"の仕様を"int型"から"float型"に変更と"消費税金額"から"消費税率"に変更 ・「6.1 取得データ」へ追記 ・「6.3.1 Get Table Activity API」のレスポンスの"state"の概要へ追記 ・「7.1 一覧」エラーコードを追記 |
0.4 | 2021/05/29 | ・「4.1.1 Get category data API」「4.1.2 Get item data API」「4.1.3 Get table data API」「4.1.4 Get item detail data API」「5.3.2 Get Order Create Status API」「5.3.3 Get Order Status API」「6.3.1 Get Table Activity API」のリクエストパラメータ名をスネークケースからキャメルケースへ変更 |
0.5 | 2021/06/03 | 「5.3.3 Get Order Status API」のレスポンスに含まれる"order_status"に誤りがあった為修正 |
1.0 | 2021/06/21 | ・「3.2.3 Providet Token API」のexpired_timeの型をStringからIntへ修正 ・「4.1.5 Get item detail content data API」のレスポンスへ"price"、"priceTaxIn"、"tax"を追加 ・「5.3.1 Create Order API」の"state"を必須へ修正 ・「6.3.1 Get Table Activity API」のレスポンスへ"from_table_activity_code"、"toward_table_activity_code"、"table_activity_state"を追加 |
1.1 | 2021/06/24 | ・「5.3.1 Create Order API 」リクエストパラメータの"order_details.item_detail_content.tax"の仕様を"int型"から"float型"に修正と"消費税金額"から"消費税率"に修正 |
1.2 | 2021/07/29 | ・「4.1.1 Get category data API」リクエストパラメータに"categoryState"を追加 ・「4.1.2 Get item data API」リクエストパラメータに"itemState"を追加 ・「4.1.3 Get table data API」リクエストパラメータに"tableState"を追加 ・「4.1.4 Get item detail data API」リクエストパラメータに"itemDetailState"を追加 ・「4.1.5 Get item detail content data API」リクエストパラメータに"ItemDetailContentState"を追加 ・「5.3.1 Create Order API」リクエストパラメータの"customer"の型を"json array"から"json"へ修正 ・「7.1 一覧」LK_ERROR_019~23を追記 |
1.3 | 2021/09/01 | ・「4.1.1 Get category data API」レスポンスに"tags"のパラメータ追加と説明を追記 ・「4.1.2 Get item data API」レスポンスに"tags"のパラメータ追加と説明を追記 ・「5.3.1 Create Order API」リクストを店内オーダーとテイクアウトオーダー別に記載 ・「5.3.1 Create Order API」"order_details" の"item_code"の概要を追記 ・「5.3.2 Get Order Create Status API」レスポンスの"state"の概要を修正 ・「6.3.3 Create Table Activity API」を新規で追加 |
1.4 | 2021/09/16 | ・「5.3.1 Create Order API」テイクアウト用リクエストパラメータの"delivery_time"について追記 |
1.4.1 | 2023/07/20 | パラメータ毎の値の文字数上限(byte)を追記、リクエスト/レスポンスサンプル記述その他軽微な修正 |
1. 概要
POS連携用のAPIについて記載する。
POS連携APIは弊社のクラウドサーバへリクエストが届くため、POSへクライアントから直接リクエストを行うわけではない。また、POSはホストの役割を想定している。
1.1 用語の定義
用語 | 概要 |
---|---|
POS連携API | 弊社が提供するAPI |
POS | 弊社のPOSレジ |
POSサーバ | 弊社のPOSサーバ |
クライアント | 弊社と連携をするサービスの運営元 |
店舗 | POSまたはクライアントのサービスを利用するエンドユーザ |
エンドユーザ | 店舗の顧客 |
2. 提供API一覧
名称 | URI | 概要 |
---|---|---|
Authentication Login API | /auth/login | ログイン認証を行う |
Provider authorization API | /provider/authorize | アクセストークンを取得する |
Provider Token API | /provider/token/ | リフレッシュトークンを利用し、アクセストークンを取得する |
Create Order API | /order/create | 注文の作成/更新/取消を行う |
Get Order Create Status API | /order/create/status | 注文がPOSへの反映状況を取得する |
Get Order Status API | /order/status | 注文のステータスを取得する |
Get Table Activity API | /table/activity | 稼働テーブルのデータを取得する |
Update Table Activity API | /table/activity/update | テーブルの更新を行う |
Get category data API | /category/read | 部門データの取得を行う |
Get item data API | /item/read | 商品データの取得を行う |
Get table data API | /table/read | テーブルデータの取得を行う |
Get item detail data API | /item/detail/read | 商品詳細データの取得を行う |
Get item detail content data API | /item/detail/content/read | 商品詳細の商品データの取得を行う |
3. OAuth2認証
POS連携APIは認証にOAuth2を利用している。そのため、POS連携APIをコールする前にアクセストークンを取得する必要がある。
POS連携APIをコールする際は、以下のHTTPヘッダを付与すること。なお、値に関してはURLエンコード処理を行う必要はない。
Authorization: <access_token>
3.1 アクセストークン取得の流れ
弊社が提供するアカウントでログインに成功後、アクセストークンを取得する。
アクセストークンの有効期限が切れた場合、リフレッシュトークンを使用し新しいアクセストークンを取得する。
Authentication Login APIのレスポンスに含まれるsession_idの有効時間は60秒。
3.2 API詳細
3.2.1 Authentication Login API
ログイン認証を行うためのAPI
項目 | |
---|---|
URI | /auth/login |
メソッド | POST |
リクエスト
属性 | 必須 | 型 | 概要 |
---|---|---|---|
username | ◯ | String | 弊社が提供する |
password | ◯ | String | 弊社が提供する |
レスポンス
属性 | 必須 | 型 | 概要 |
---|---|---|---|
role_id | ◯ | String | ユーザに関連するロールID |
service_id | ◯ | String | ユーザに関連するサービスID |
session_id | ◯ | String | アクセストークンを取得する際に使用するログインのセッション |
user_id | ◯ | String | ユーザID |
サンプル
POST /auth/login
{
"username": "username",
"password": "password"
}
ステータスコード200応答
{
"role_id": "string",
"service_id": "string",
"session_id": "string",
"user_id": "string"
}
ステータスコード | 概要 |
---|---|
200 | OK |
201 | Created |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
3.2.2 Provider authorization API
アクセストークンを取得するためのAPI
項目 | |
---|---|
URI | /provider/authorize |
メソッド | POST |
リクエスト
属性 | 必須 | 型 | 概要 |
---|---|---|---|
client_id | ◯ | String | 弊社が提供する |
client_secret | ◯ | String | 弊社が提供する |
scope | ◯ | String | 弊社が提供する |
session_id | ◯ | String | Authentication Login APIで提供するセッションID |
レスポンス
属性 | 必須 | 型 | 概要 |
---|---|---|---|
access_token | ◯ | String | POS連携APIをコールするために使用するアクセストークン |
expired_time | ◯ | String | アクセストークンの有効期限 |
refresh_token | ◯ | String | 新しいアクセストークンを取得するために使用されるリフレッシュトークン |
サンプル
POST /provider/authorize
{
"client_id": "string",
"client_secret": "string",
"scope": "string",
"session_id": "string"
}
ステータスコード200応答
{
"access_token": "string",
"expired_time": "string",
"refresh_token": "string"
}
ステータスコード | 概要 |
---|---|
200 | OK |
201 | Created |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
3.2.3 Providet Token API
新たなアクセストークンを取得するためのAPI
項目 | |
---|---|
URI | /provider/token/ |
メソッド | POST |
リクエスト
属性 | 必須 | 型 | 概要 |
---|---|---|---|
client_id | ◯ | String | 弊社が提供する |
client_secret | ◯ | String | 弊社が提供する |
refresh_token | ◯ | String | Provider authorization APIで提供するリフレッシュトークン |
レスポンス
属性 | 必須 | 型 | 概要 |
---|---|---|---|
access_token | ◯ | String | APIをコールするために使用するアクセストークン |
expired_time | ◯ | Int | アクセストークンの有効期限 |
refresh_token | ◯ | String | 新しいアクセストークンを取得するために使用されるリフレッシュトークン |
サンプル
POST /provider/token
{
"client_id": "string",
"client_secret": "string",
"refresh_token": "string"
}
ステータスコード200応答
{
"access_token": "string",
"expired_time": int,
"refresh_token": "string"
}
ステータスコード | 概要 |
---|---|
200 | OK |
201 | Created |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
4. マスターデータについて
弊社の店舗管理画面でダウンロードできるCSVファイルとは別にAPIでも各データの共通コードを取得できる。
API経由ではCSVには記載のない詳細データが含まれている。
4.1 API詳細
4.1.1 Get category data API
部門を取得するAPI
項目 | |
---|---|
URI | /category/read |
メソッド | GET |
・部門の階層について
部門は2階層まで作成が可能で"lft","rgt"で決まる。
例) alcohol部門の2階層目にcocktail部門が存在するパターン
+---------------+----------+---------+---------+
| category_code | name | lft | rgt |
+---------------+----------+---------+---------+
| 270_101011 | alcohol | 100 | 200 |
| 270_101012 | lunch | 300 | 400 |
| 270_101013 | cocktail | 100.001 | 100.002 |
+---------------+----------+---------+---------+
・tagsについて
Web管理画面にて任意の文字列を最大5つまで登録が可能。登録した値が"tags"として取得できる。APIのレスポンスでは、登録されている任意の文字列を返す。
データのサンプル
データあり (5つ登録時)
"tags": {
"tag_1": "任意の文字列",
"tag_2": "任意の文字列",
"tag_3": "任意の文字列",
"tag_4": "任意の文字列",
"tag_5": "任意の文字列"
}
データあり (3つ登録時)
"tags": {
"tag_1": "任意の文字列",
"tag_2": "任意の文字列",
"tag_3": "任意の文字列"
}
データなし
"tags": null
リクエスト
属性 | 必須 | 型 | 概要 |
---|---|---|---|
categoryCode | String | 部門の識別コード この引数が省略された場合、全ての部門を取得する |
|
shopCode | ◯ | String | 店舗識別コード |
categoryState | Int | 部門ステータス 1: 利用中 3: 削除 |
レスポンス
属性 | 必須 | 型 | 概要 |
---|---|---|---|
shop_code | ◯ | String | 店舗識別コード |
categories | ◯ | json array | categoriesの表を参照 |
categories
属性 | 必須 | 型 | 概要 |
---|---|---|---|
category_code | ◯ | String | 部門の識別コード |
name | ◯ | String | 部門名 |
description | ◯ | String | 部門の説明 |
lft | ◯ | Double | 部門の階層識別に使われる値 |
rgt | ◯ | Double | 部門の階層識別に使われる値 |
sort_order | ◯ | Int | POSでの並び順 |
state | ◯ | Int | 部門ステータス 1: 利用中 3: 削除 |
created | ◯ | Int | 作成時間 |
modified | ◯ | Int | 最終変更時間 |
tags | ◯ | Json | 任意の文字列 |
サンプル
GET /category/read
{
"categoryCode": "string",
"shopCode": "string"
}
ステータスコード200応答
{
"shop_code": "string",
"categories": [
{
"category_code": "string",
"created": 0,
"description": "string",
"lft": 0,
"modified": 0,
"name": "string",
"rgt": 0,
"sort_order": 0,
"state": 0,
"tags": {
"tag_1": "String"
}
}
]
}
ステータスコード | 概要 |
---|---|
200 | OK |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
4.1.2 Get item data API
商品を取得するAPI
項目 | |
---|---|
URI | /item/read |
メソッド | GET |
・商品と部門の関係
商品は必ずどこかの部門に属している。
・tagsについて
Web管理画面にて任意の文字列を最大5つまで登録が可能。登録した値が"tags"として取得できる。
データのサンプル
データあり (5つ登録時)
"tags": {
"tag_1": "任意の文字列",
"tag_2": "任意の文字列",
"tag_3": "任意の文字列",
"tag_4": "任意の文字列",
"tag_5": "任意の文字列"
}
データあり (3つ登録時)
"tags": {
"tag_1": "任意の文字列",
"tag_2": "任意の文字列",
"tag_3": "任意の文字列"
}
データなし
"tags": null
リクエスト
属性 | 必須 | 型 | 概要 |
---|---|---|---|
itemCode | String | 商品の識別コード この引数が省略された場合、全ての商品を取得する |
|
shopCode | ◯ | String | 店舗識別コード |
itemState | Int | 商品ステータス 1: 利用中 3: 削除 |
レスポンス
属性 | 必須 | 型 | 概要 |
---|---|---|---|
shop_code | ◯ | String | 店舗識別コード |
items | ◯ | json array | itemsの表を参照 |
items
属性 | 必須 | 型 | 概要 |
---|---|---|---|
item_detail_code | ◯ | String | 商品詳細の識別コード |
category_code | ◯ | String | 部門の識別コード |
item_code | ◯ | String | 商品の識別コード |
description | ◯ | String | 商品の説明 |
name | ◯ | String | 商品の名前 |
price | ◯ | Int | 税抜価格 |
price_tax_in | ◯ | Int | 税込価格 |
sort_order | ◯ | Int | POSでの並び順 |
state | ◯ | Int | 商品ステータス 1: 利用中 3: 削除 |
stock | ◯ | Int | 商品の残数 |
tax | ◯ | Float | 消費税率 |
created | ◯ | Int | 作成時間 |
modified | ◯ | Int | 最終更新時間 |
tags | ◯ | Json | 任意の文字列 |
サンプル
GET /item/read
{
"itemCode": "string",
"shopCode": "string"
}
ステータスコード200応答
{
"shop_code": "string",
"items": [
{
"category_code": "string",
"code": "string",
"created": 0,
"description": "string",
"item_detail_code": "string",
"modified": 0,
"name": "string",
"price": 0,
"price_tax_in": 0,
"sort_order": 0,
"state": 0,
"stock": 0,
"tax": 0,
"tags": {
"tag_1": "String"
}
}
]
}
ステータスコード | 概要 |
---|---|
200 | OK |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
4.1.3 Get table data API
テーブルを取得するAPI
項目 | |
---|---|
URI | /table/read |
メソッド | GET |
リクエスト
属性 | 必須 | 型 | 概要 |
---|---|---|---|
tableCode | String | テーブルの識別コード この引数が省略された場合、全てのテーブルを取得する |
|
shopCode | ◯ | String | 店舗識別コード |
tableState | Int | テーブルステータス 1: 利用中 3: 削除 |
レスポンス
属性 | 必須 | 型 | 概要 |
---|---|---|---|
shop_code | ◯ | String | 店舗識別コード |
tables | ◯ | json array | tablesの表を参照 |
tables
属性 | 必須 | 型 | 概要 |
---|---|---|---|
table_code | ◯ | String | テーブルの識別コード |
description | ◯ | String | テーブルの説明 |
name | ◯ | String | テーブルの名前 |
sort_order | ◯ | Int | POSでの並び順 |
state | ◯ | Int | テーブルステータス 1: 利用中 3: 削除 |
created | ◯ | Int | 作成時間 |
modified | ◯ | Int | 最終更新時間 |
サンプル
GET /table/read
{
"tableCode": "string",
"shopCode": "string"
}
ステータスコード200応答
{
"shop_code": "string",
"tables": [
{
"created": 0,
"description": "string",
"modified": 0,
"name": "string",
"sort_order": 0,
"state": 0,
"table_code": "string"
}
]
}
ステータスコード | 概要 |
---|---|
200 | OK |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
4.1.4 Get item detail data API
商品詳細を取得するAPI
項目 | |
---|---|
URI | /item/detail/read |
メソッド | GET |
リクエスト
属性 | 必須 | 型 | 概要 |
---|---|---|---|
itemDetailCode | String | 商品詳細の識別コード この引数が省略された場合、全ての商品詳細を取得する |
|
shopCode | ◯ | String | 店舗識別コード |
itemDetailState | Int | 商品詳細のステータス 1: 利用中 3: 削除 |
レスポンス
属性 | 必須 | 型 | 概要 |
---|---|---|---|
shop_code | ◯ | String | 店舗識別コード |
item_details | ◯ | json array | item_detailsの表を参照 |
item_details
属性 | 必須 | 型 | 概要 |
---|---|---|---|
item_detail_code | ◯ | String | 商品詳細の識別コード |
name | ◯ | String | 商品詳細の名称 |
state | ◯ | Int | 商品詳細のステータス 1: 利用中 3: 削除 |
sort_order | ◯ | Int | POSでの並び順 |
created | ◯ | Int | 作成時間 |
modified | ◯ | Int | 最終更新時間 |
サンプル
GET /item/detail/read
{
"shopCode": "string",
"itemDetailCode": "string"
}
ステータスコード200応答
{
"shopCode": "string",
"itemDetails": [
{
"created": 0,
"item_detail_code": "string",
"modified": 0,
"name": "string",
"sort_order": 0,
"state": 0
}
]
}
ステータスコード | 概要 |
---|---|
200 | OK |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
4.1.5 Get item detail content data API
商品詳細の詳細を取得するAPI
オプションやトッピングなどと言われる注文方法で利用するデータ
項目 | |
---|---|
URI | /item/detail/content/read |
メソッド | GET |
リクエスト
属性 | 必須 | 型 | 概要 |
---|---|---|---|
itemDetailCode | String | 商品詳細の識別コード この引数に値がある場合、item_detail_codeに属する商品詳細の商品を取得する |
|
itemDetailContentCode | String | 商品詳細の商品の識別コード この引数が省略された場合、全ての商品詳細の商品を取得する |
|
shopCode | ◯ | String | 店舗識別コード |
ItemDetailContentState | Int | 商品詳細の商品のステータス 1: 利用中 3: 削除 |
※itemDetail.stateは考慮されていません。
レスポンス
属性 | 必須 | 型 | 概要 |
---|---|---|---|
shopCode | ◯ | String | 店舗識別コード |
itemDetailContents | ◯ | json array | itemDetailContentsの表を参照 |
itemDetailContents
属性 | 必須 | 型 | 概要 |
---|---|---|---|
itemCode | ◯ | String | 商品の識別コード NULLの場合は、金額が設定されていないデータ |
itemDetailContentCode | ◯ | String | 商品詳細の商品の識別コード |
itemDetailCode | ◯ | String | 商品詳細の識別コード |
name | ◯ | String | 商品詳細の商品名 |
state | ◯ | Int | 商品詳細の商品のステータス 1: 利用中 3: 削除 |
price | ◯ | Int | 商品の税抜単価 |
priceTaxIn | ◯ | Int | 商品の税込単価 |
tax | ◯ | Double | 商品の税率 |
sort_order | ◯ | Int | POSでの並び順 |
created | ◯ | Int | 作成時間 |
modified | ◯ | Int | 最終更新時間 |
サンプル
GET /item/detail/content/read
{
"itemDetailCode": "string",
"itemDetailContentCode": "string",
"shopCode": "string"
}
ステータスコード200応答
{
"shopCode": "string",
"itemDetailContents": [
{
"created": 0,
"itemCode": "string",
"itemDetailCode": "string",
"itemDetailContentCode": "string",
"modified": 0,
"name": "string",
"price": 0,
"priceTaxIn": 0,
"tax": 0,
"sortOrder": 0,
"state": 0
}
]
}
ステータスコード | 概要 |
---|---|
200 | OK |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
5. 注文について
注文フロー
エンドユーザから注文が入った後に、クライアントはCreate Order APIをコールする。Create Order APIのレスポンスのステータスコードが200だとしてもこの時点ではPOSに反映されていない。そのため、Get Order Create Status APIをコールしレスポンスの"create_status"を確認する必要がある。
**注文の更新と削除** 更新または削除をするには対象のorder_codeとtransaction_idを指定する。
**item_detailとitem_detail_contentについて** 商品対するオプションやトッピングなどと言われる注文方法はitem_detailとitem_detail_contentを利用する。
item_detailは詳細名称であり、item_detail_contentは実際に選択する商品のこと。注文時にこのパラメータは必須ではない。
item_detail | Item_detail_content |
---|---|
飲み方 | ロック |
飲み方 | ストレート |
サイズ | 大盛り |
サイズ | 普通 |
**データ構造** POS連携APIで扱っているデータに関しての構造は以下
5.1 店内オーダー
注文のサイクル
最初の注文と同じテーブルへの2回目以降の注文でパラメータが異なり、同じテーブルへの2回目の注文以降は"table_activity_code"が必要となる。このサイクルはPOSでそのテーブルが会計されるまで続く。また、transaction_idもこのサイクル内では同じ値を使う。
5.2 テイクアウトオーダー
価格について
POSはテイクアウトオーダーに対して価格の変更(値引きや追加料金など)を行わない。POSの商品とテイクアウトオーダーの価格が異なる場合はテイクアウトオーダーを「正」とする。
5.3 API詳細
5.3.1 Create Order API
POSへ注文をするためのAPI
店内オーダーとテイクアウトオーダーでパラメータが異なる。
項目 | |
---|---|
URI | /order/create |
メソッド | POST |
リクエスト(店内オーダー)
属性 | 必須 | 型 | 概要 |
---|---|---|---|
order_code | ◯ | String(32) | クライアントが作成する任意のユニークのコード |
service_id | ◯ | String | Authentication Login APIで提供するservice_id |
service_type | ◯ | Int | 2: 店内オーダー |
shop_code | ◯ | String | 店舗識別コード |
request_id | ◯ | String | クライアントが作成する任意のUID このIDはネットワーク上の問題が発生した場合に、重複をチェックするために使用される |
transaction_id | ◯ | String(255) | クライアントが作成する任意のUID このIDは注文のトランザクションを管理するために使用する |
state | ◯ | Int | 注文の状態 1: Create 2: Update 3: Delete |
order_details | ◯ | json array | order_detailsの表を別途参照 |
table_code | Int | テーブルの識別コード この引数が省略された場合はtable_activity_codeが必須 |
|
table_activity_code | Int | 稼働テーブルに割り振られるコード この引数が省略された場合はtable_codeが必須 |
|
order_time | Int | 注文時間(タイムスタンプ) | |
discount_type | Int | 割引の種別 1: 小計金額からの"%"による割引 2: 小計金額からの"円"による割引 3: 合計金額からの"%"による割引 4: 合計金額からの円による割引 |
|
discount_percent | Int | テーブルに対する割引率 discount_typeが1または3の場合は必須 |
|
discount_value | Int | テーブルに対する実際に値引く金額 | |
customer_number | Int | 客数(省略の場合1となる) | |
comment | String | 注文に対するコメント | |
subtotal | Double | 小計金額(税抜) | |
total | Double | 合計金額(税込) |
リクエスト(テイクアウトオーダー)
属性 | 必須 | 型 | 概要 |
---|---|---|---|
order_code | ◯ | String(32) | クライアントが作成する任意のユニークのコード |
service_id | ◯ | String | Authentication Login APIで提供するservice_id |
service_type | ◯ | Int | 1: テイクアウトオーダー |
shop_code | ◯ | String | 店舗識別コード |
request_id | ◯ | String | クライアントが作成する任意のUID このIDはネットワーク上の問題が発生した場合に、重複をチェックするために使用される |
transaction_id | ◯ | String(255) | クライアントが作成する任意のUID このIDは注文のトランザクションを管理するために使用する |
state | ◯ | Int | 注文の状態 1: Create 2: Update 3: Delete |
order_details | ◯ | json array | order_detailsの表を別途参照 |
order_time | Int | 注文時間(タイムスタンプ) | |
discount_type | Int | 割引の種別 1: 小計金額からの"%"による割引 2: 小計金額からの"円"による割引 3: 合計金額からの"%"による割引 4: 合計金額からの円による割引 |
|
discount_percent | Int | テーブルに対する割引率 discount_typeが1または3の場合は必須 |
|
discount_value | Int | テーブルに対する実際に値引く金額 | |
customer_number | Int | 客数(省略の場合1となる) | |
comment | String | 注文に対するコメント | |
subtotal | Double | 小計金額(税抜) | |
total | Double | 合計金額(税込) | |
payment_status | Int | 支払い状況 1: 未払い 2: 支払い済 |
|
vendor_service | String | 媒体業者(Uber Eats, 出前館...など) | |
vendor_order_id | String | 媒体業者が採番した注文ID | |
delivery_time | Int | 注文受け取り時間(タイムスタンプ) キッチン伝票に印字される |
|
customer | ◯ | json | customerの表を別途参照 |
order_details
service_typeに関わらず共通
属性 | 必須 | 型 | 概要 |
---|---|---|---|
order_detail_code | ◯ | String(32) | クライアントが作成する任意のユニークなコード |
item_code | String | 商品固有のコード nullまたは、省略をすることでPOSに未登録の商品でも注文が可能 |
|
item_name | ◯ | String | 商品名 |
order_number | ◯ | Int | 商品の個数 |
price | ◯ | Int | 商品の税抜価格 |
price_tax_in | ◯ | Int | 商品の税込価格 |
comment | String | コメント | |
discount_value | Int | 商品に対する値引く金額 | |
discount_percent | Int | 商品に対する値引き率 discount_typeが1または3の場合は必須 |
|
discount_type | Int | 割引の種別 1: 商品小計金額からの"%"による割引 2: 商品小計金額からの"円"による割引 3: 商品合計金額からの"%"による割引 4: 商品合計金額からの円による割引 |
|
tax | ◯ | Float | 消費税率 |
subtotal | ◯ | Int | 商品小計金額(税抜) |
total | ◯ | Int | 商品合計金額(税込) |
item_detail_content | json array | item_detail_contentの表を別途参照 |
item_detail_content
service_typeに関わらず共通
属性 | 必須 | 型 | 概要 |
---|---|---|---|
comment | String | コメント | |
discount_percent | Int | 商品に対する値引き率 discount_typeが1または3の場合は必須 |
|
discount_type | Int | 割引の種別 1: 商品小計金額からの"%"による割引 2: 商品小計金額からの"円"による割引 3: 商品合計金額からの"%"による割引 4: 商品合計金額からの円による割引 |
|
discount_value | Int | 商品に対する値引く金額 | |
item_detail_content_code | String | 商品詳細商品固有のコード | |
item_name | String | 商品名 | |
order_detail_code | String(32) | クライアントが作成する任意のユニークなコード | |
order_number | Int | 商品の個数 | |
price | Int | 商品の税抜価格 | |
price_tax_in | Int | 商品の税込価格 | |
subtotal | Int | 商品小計金額(税抜) | |
tax | Float | 消費税率 | |
total | Int | 商品金額(税込) |
customer
属性 | 必須 | 型 | 概要 |
---|---|---|---|
customer_code | ◯ | String | クライアントが作成した顧客固有のユニークなコード |
name | ◯ | String | 顧客の名前 |
phone | ◯ | String | 顧客の電話番号 |
String | 顧客のメールアドレス |
レスポンス
属性 | 必須 | 型 | 概要 |
---|---|---|---|
order_code | ◯ | String(32) | クライアントが作成した任意のユニークなコード |
サンプル
POST /order/create
{
"customer_number": 0,
"delivery_time": int,
"discount_percent": 0,
"discount_type": 0,
"discount_value": 0,
"order_code": "String",
"order_details": [
{
"comment": "string",
"discount_percent": 0,
"discount_type": 0,
"discount_value": 0,
"item_code": "String",
"item_name": "string",
"order_detail_code": "String",
"order_number": 0,
"price": 0,
"price_tax_in": 0,
"subtotal": 0,
"tax": 0,
"total": 0
}
],
"order_time": "String",
"payment_status": 0,
"service_id": "String",
"service_type": Int,
"shop_code": "String",
"state": 0,
"subtotal": "String",
"table_activity_code": 0,
"table_code": 0,
"total": "String",
"transaction_id": "String",
"comment": "String",
"request_id": "String",
"item_detail_content": [
{
"comment": "string",
"discount_price": 0,
"discount_type": 0,
"discount_value": 0,
"item_detail_content_code": "string",
"item_name": "string",
"order_detail_code": "string",
"order_number": 0,
"price": 0,
"price_tax_in": 0,
"subtotal": 0,
"tax": 0,
"total": 0
}
],
"customer": {
"customer_code": "string",
"email": "string",
"name": "string",
"phone": "string"
},
}
ステータスコード200応答
{
"order_code": "String"
}
ステータスコード | 概要 |
---|---|
200 | OK |
201 | Created |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
5.3.2 Get Order Create Status API
POSの注文反映状況を確認するAPI
項目 | |
---|---|
URI | /order/create/status |
メソッド | GET |
リクエスト
属性 | 必須 | 型 | 概要 |
---|---|---|---|
orderCode | ◯ | String(32) | クライアントが作成する任意のユニークのコード |
serviceId | ◯ | String | Authentication Login APIで提供するservice_id |
shopCode | ◯ | String | 店舗識別コード |
レスポンス
属性 | 必須 | 型 | 概要 |
---|---|---|---|
order_code | ◯ | String(32) | クライアントが作成した任意のユニークのコード |
create_status | ◯ | Int | 作成された注文のステータス 1: 保留: APIサーバでは受信したがPOSへ未送信 2: 成功: POSへ注文が反映された 3: 失敗 |
table_activity_code | String | 稼働テーブルのコード create_status=2の際に値が返る |
|
state | ◯ | Int | POSサーバへの反映状態 1: POSサーバへ未反映 2: POSサーバへ反映 |
created_time | Int | POSの注文作成時間 |
サンプル
GET /order/create/status
{
"orderCode": "string",
"serviceId": "string",
"shopCode": "string"
}
ステータスコード200応答
{
"order_code": "string",
"create_status": int,
"table_activity_code": "string",
"state": int,
"created_time": int
}
ステータスコード | 概要 |
---|---|
200 | OK |
201 | Created |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
5.3.3 Get Order Status API
注文のステータスを取得するAPI
項目 | |
---|---|
URI | /order/status |
メソッド | GET |
リクエスト
属性 | 必須 | 型 | 概要 |
---|---|---|---|
orderCode | ◯ | String(32) | クライアントが作成する任意のユニークのコード |
serviceId | ◯ | String | Authentication Login APIで提供するservice_id |
shopCode | ◯ | String | 店舗識別コード |
レスポンス
属性 | 必須 | 型 | 概要 |
---|---|---|---|
order_code | ◯ | String(32) | クライアントが作成した任意のユニークのコード |
service_type | ◯ | Int | 1: テイクアウトオーダー 2: 店内オーダー |
order_status | ◯ | Int | 注文のステータス ※service_typeによって異なる service_type=1 0: 失敗 1: 注文の成功(POSに反映されていない) 2: POSへ反映された 3: 受渡し済 4: キャンセル(請求なし) 5: キャンセル(請求あり) service_type=2 0: 失敗 1: 注文の成功(POSに反映されていない) 2: POSへ反映された 3: 支払い済 4: table_activityの削除(POSでの操作) |
payment_status | ◯ | Int | 支払いのステータス 1: 支払い前 2: 支払い済み 3: キャンセル |
state | Int | 注文の状態 1: アクティブ 3: 削除 |
|
created | Int | POSの注文作成時間 | |
modified | Int | POSでの注文データの最終更新時間 |
サンプル
GET /order/status
{
"orderCode": "string",
"serviceId": "string",
"shopCode": "string"
}
ステータスコード200応答
{
"order_code": "string",
"order_status": int,
"payment_status": int,
"service_type": int,
"state": int,
"created": int,
"modified": int
}
ステータスコード | 概要 |
---|---|
200 | OK |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
6. テーブルについて
6.1 取得データ
Get Table Activity APIでは全て、または指定テーブルの注文や会計のデータを取得できる。
注文データの同期をとる場合に利用する。
会計のデータを取得する場合は、table_activity_codeを指定してください。
また、テイクアウトオーダーでもこのデータは作成される。
6.2 テーブルの更新
更新したいテーブルに関連するtransaction_idを指定すること。
このtransaction_idは注文時にクライアントが発行する値。
6.3 API詳細
6.3.1 Get Table Activity API
テーブルのデータを取得するためのAPI
項目 | |
---|---|
URI | /table/activity |
メソッド | GET |
リクエスト
属性 | 必須 | 型 | 概要 |
---|---|---|---|
shopCode | ◯ | String | 店舗識別コード |
tableActivityCode | String | Get Order Create Status APIで取得できる稼働テーブルのコード | |
tableCode | String | テーブルの識別コード |
レスポンス
属性 | 必須 | 型 | 概要 |
---|---|---|---|
shop_code | ◯ | String | 店舗識別コード |
table_activities | ◯ | json array |
table_activities
属性 | 必須 | 型 | 概要 |
---|---|---|---|
table_activity_code | ◯ | String | 稼働テーブルのコード |
table_code | ◯ | String | テーブルの識別コード |
table_activity_customer_number | Int | テーブルの客数 | |
table_activity_created | ◯ | Int | POSの稼働テーブル作成時間 |
table_activity_modified | Int | POSでの稼働テーブルの最終更新時間 | |
table_activity_state | ◯ | Int | 稼働テーブルデータの状態 0: 未稼働 1: アクティブ(注文可) 2: 会計済み、テーブル移動後(注文不可) 3: 削除 |
from_table_activity_code | Int | 移動元のtable_activity_code | |
toward_table_activity_code | Int | 移動先のtable_activity_code | |
tax | ◯ | Double | テーブルの税合計 |
subtotal | ◯ | Double | 小計金額(税抜) |
subtotal_tax_non | ◯ | Double | 非課税の小計金額 |
subtotal_tax_normal | ◯ | Double | 10%税の小計金額 |
subtotal_tax_reduced | ◯ | Double | 8%税の小計金額 |
total | ◯ | Double | 合計金額(税込) |
total_tax_non | ◯ | Double | 非課税の合計金額 |
total_tax_normal | ◯ | Double | 10%税の合計金額 |
total_tax_reduced | ◯ | Double | 8%税の合計金額 |
discount_value | Int | テーブルに対する実際に値引く金額 | |
discount_percent | Int | テーブルに対する割引率 | |
discount_type | Int | 割引の種別 1: 小計金額からの"%"による割引 2: 小計金額からの"円"による割引 3: 合計金額からの"%"による割引 4: 合計金額からの円による割引 |
|
order_list | ◯ | json array | order_listの表を別途参照 |
order_detail_list | ◯ | json array | order_detail_listの表を別途参照 |
payment_list | json array | payment_listの表を別途参照 | |
payment_order_detail_list | json array | payment_order_detail_listの表を別途参照 |
order_list
属性 | 必須 | 型 | 概要 |
---|---|---|---|
code | ◯ | String(32) | 注文のコード(order_code) |
shop_code | ◯ | String | 店舗識別コード |
state | ◯ | Int | POSにおける注文の状態 0: アクティブ(POSから注文) 1: アクティブ 3: 削除 |
status | ◯ | Int | 注文のステータス |
created | ◯ | Int | 注文の作成時間 |
modified | ◯ | Int | 注文の最終更新時間 |
order_detail_list
属性 | 必須 | 型 | 概要 |
---|---|---|---|
order_detail_code | String(32) | 注文詳細のコード | |
order_code | ◯ | String(32) | 注文のコード |
discount_value | Int | 商品に対する値引く金額 | |
discount_percent | Int | 商品に対する値引き率 | |
discount_type | 割引の種別 1: 商品小計金額からの"%"による割引 2: 商品小計金額からの"円"による割引 3: 商品合計金額からの"%"による割引 4: 商品合計金額からの円による割引 |
||
item_code | ◯ | String | 商品の識別コード |
item_name | ◯ | String | 商品名 |
order_number | ◯ | Int | 商品の個数 |
price | ◯ | Int | 商品の税抜価格 |
price_tax_in | ◯ | Int | 商品の税込価格 |
subtotal | ◯ | Int | 商品小計金額(税抜) |
tax | ◯ | Int | 消費税額 |
total | ◯ | Int | 商品合計金額(税込) |
payment_list
属性 | 必須 | 型 | 概要 |
---|---|---|---|
payment_code | String | 会計の識別コード | |
created | Int | 支払い時間 | |
deposit | Int | 預け金額 | |
change | Int | お釣り | |
discount_percent | Int | 割引率 | |
discount_value | Int | 割引金額 | |
fraction | Int | 端数値引き | |
discount_type | Int | 割引の種別 1: 小計金額からの"%"による割引 2: 小計金額からの"円"による割引 3: 合計金額からの"%"による割引 4: 合計金額からの円による割引 |
|
late_night_charge | Int | 深夜料金率 | |
late_night_charge_price | Int | 深夜料金の金額 | |
late_night_charge_type | Int | 深夜料金の種別 | |
service_charge | Int | サービス料金率 | |
service_charge_price | Int | サービス料金の金額 | |
service_charge_type | Int | サービス料金の種別 | |
subtotal | ◯ | Int | 小計金額(税抜き) |
tax | ◯ | Int | 消費税金額 |
total | ◯ | Int | 合計金額(税込) |
type | ◯ | Int | 支払い種別 1: 現金 2: 信計 3: その他 4: 複数 |
state | ◯ | Int | 会計の状態 1: アクティブ 2: 取消 |
payment_order_detail_list
属性 | 必須 | 型 | 概要 |
---|---|---|---|
created | ◯ | Int | 分割支払い時間 |
order_detail_code | ◯ | String(32) | 注文詳細のコード |
order_number | ◯ | Int | 商品の個数 |
payment_code | ◯ | String | 会計の識別コード |
state | ◯ | Int | 会計の状態 1: アクティブ 2: 取消 |
サンプル
GET /table/activity
{
"shopCode": "string",
"tableActivityCode": "string"
}
ステータスコード200応答
{
"shop_code": "string",
"table_activities": [
{
"order_detail_list": [
{
"details": "string",
"discount_value": 0,
"discount_percent": 0,
"discount_type": 0,
"item_code": "string",
"item_name": "string",
"order_code": "string",
"order_detail_code": "string",
"order_number": 0,
"price": 0,
"price_tax_in": 0,
"subtotal": 0,
"tax": 0,
"total": 0
}
],
"order_list": [
{
"order_code": "string",
"created": 0,
"modified": 0,
"shop_code": "string",
"state": 0,
"status": 0
}
],
"payment_list": [
{
"change": 0,
"payment_code": "string",
"created": 0,
"deposit": 0,
"discount_value": 0,
"discount_percent": 0,
"discount_price2": 0,
"discount_type": 0,
"late_night_charge": 0,
"late_night_charge_price": 0,
"late_night_charge_type": 0,
"service_charge": 0,
"service_charge_price": 0,
"service_charge_type": 0,
"state": 0,
"subtotal": 0,
"tax": 0,
"total": 0,
"type": 0
}
],
"payment_order_detail_list": [
{
"created": 0,
"order_detail_code": "string",
"order_number": 0,
"payment_code": "string",
"state": 0
}
],
"subtotal": 0,
"subtotal_tax_non": 0,
"subtotal_tax_normal": 0,
"subtotal_tax_reduced": 0,
"table_activity_code": "string",
"table_activity_created": 0,
"table_activity_customer_number": 0,
"table_activity_modified": 0,
"table_code": "string",
"tax": 0,
"total": 0,
"total_tax_non": 0,
"total_tax_normal": 0,
"total_tax_reduced": 0
}
]
}
ステータスコード | 概要 |
---|---|
200 | OK |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
6.3.2 Update Table Activity API
table_activityの更新をするAPI
項目 | |
---|---|
URI | /table/activity/update |
メソッド | PUT |
リクエスト
属性 | 必須 | 型 | 概要 |
---|---|---|---|
shop_code | ◯ | String | 店舗識別コード |
table_activity_code | String | Get Order Create Status APIで取得できる稼働テーブルのコード この引数が省略された場合はtable_codeが必須 |
|
table_code | String | テーブルの識別コード この引数が省略された場合はtable_activity_codeが必須 |
|
payment_status | Int | クライアントの支払い状況 1.未払い 2.支払い済 |
|
discount_value | Int | テーブルに対する実際に値引く金額 | |
discount_percent | Int | テーブルに対する割引率 discount_typeが1または3の場合は必須 |
|
discount_type | Int | 割引の種別 1: 小計金額からの"%"による割引 2: 小計金額からの"円"による割引 3: 合計金額からの"%"による割引 4: 合計金額からの円による割引 |
|
request_id | ◯ | String | クライアントが作成する任意のUID このIDはネットワーク上の問題が発生した場合に、重複をチェックするために使用される |
transaction_id | ◯ | String(255) | クライアントが作成する任意のUID このIDはテーブル更新のトランザクションを管理するために使用する |
table_activity_customer_number | Int | 客数 | |
modified | ◯ | Int | 更新時間(タイムスタンプ) |
レスポンス
属性 | 必須 | 型 | 概要 |
---|---|---|---|
shop_code | ◯ | String | 店舗識別コード |
サンプル
PUT /table/activity/update
{
"discount_percent": 0,
"discount_type": 0,
"discount_value": 0,
"payment_status": 0,
"shop_code": "string",
"table_activity_code": "string",
"table_code": "string",
"request_id": "string",
"transaction_id": "string",
}
ステータスコード200応答
{
"shop_code": "string"
}
ステータスコード | 概要 |
---|---|
200 | OK |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
6.3.3 Create Table Activity API
table activityを作成するAPI
項目 | |
---|---|
URI | /table/activity/create |
メソッド | POST |
リクエスト
属性 | 必須 | 型 | 概要 |
---|---|---|---|
shop_code | ◯ | String | 店舗識別コード |
request_id | ◯ | String | クライアントが作成する任意のUID このIDはネットワーク上の問題が発生した場合に、重複をチェックするために使用される |
transaction_id | ◯ | String(255) | クライアントが作成する任意のUID このIDは注文のトランザクションを管理するために使用する |
table_code | ◯ | String | テーブルの識別コード |
table_activity_customer_number | Int | 客数(省略の場合1となる) |
レスポンス
属性 | 必須 | 型 | 概要 |
---|---|---|---|
tableActivityCode | ◯ | String | 稼働テーブルに割り振られるコード |
サンプル
POST /table/activity/create
{
"shop_code": "String",
"request_id": "String",
"transaction_id": "String",
"table_code": "String",
"table_activity_customer_number": Int
}
ステータスコード200応答
{
"tableActivityCode": "string"
}
ステータスコード | 概要 |
---|---|
200 | OK |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
7. エラーコード
7.1 一覧
エラーコード | ステータス | メッセージ |
---|---|---|
LK_ERROR_001 | 404 | {shop_code} not found |
LK_ERROR_002 | 404 | {category_code} not found |
LK_ERROR_003 | 404 | {item_code} not found |
LK_ERROR_004 | 404 | {order_code} not found |
LK_ERROR_005 | 404 | {table_code} not found |
LK_ERROR_007 | 401 | Access token does not exist or expired |
LK_ERROR_008 | 403 | Permission denied |
LK_ERROR_010 | 400 | Bad Request |
LK_ERROR_011 | 404 | {table_activity_code} not found |
LK_ERROR_012 | 400 | Request duplicate |
LK_ERROR_013 | 404 | {service_id} not found |
LK_ERROR_014 | 500 | Internal server error |
LK_ERROR_015 | 404 | {item_detail_code} not found |
LK_ERROR_016 | 404 | {item_detail_content_code} not found |
LK_ERROR_017 | 403 | mPOS is not open |
LK_ERROR_018 | 400 | id format UUID.replace(-) |
LK_ERROR_019 | 400 | discount percent {0} is not valid |
LK_ERROR_020 | 400 | order state {0} is not supported |
LK_ERROR_021 | 400 | order state {0} is not supported |
LK_ERROR_022 | 400 | items {0} deleted or not found |
LK_ERROR_023 | 400 | items detail content {0} deleted or not found |
LK_ERROR_024 | 400 | stock is not valid of item code **** STOCK EXCEEDS |