Sep 16, 2021 12:46:44

blayn POS連携API 仕様

更新履歴

最終更新日: 2021/09/16

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. 概要

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 アクセストークンを取得する
Providet 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 アクセストークン取得の流れ

Authorization_flow.png

弊社が提供するアカウントでログインに成功後、アクセストークンを取得する。
アクセストークンの有効期限が切れた場合、リフレッシュトークンを使用し新しいアクセストークンを取得する。
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 {
　"role_id": "String",
　"service_id": "String",
　"session_id": "String",
　"user_id": "String"
}
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 {
　"access_token": "String",
　"expired_time": "String",
　"refresh_token": "String"
}
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 {
　"access_token": "String",
　"expired_time": int,
　"refresh_token": "String"
}
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 {
　"shop_code": "string"
　"categories": []
}
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 {
　"shop_code": "string"
　"items": [],
}
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 {
　"shop_code": "string"
　"tables": [],
}
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 {
　"shop_code": "string"
　"itemDetails"" []
}
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 {
　"shopCode": "string"
　"itemDetailContents": []
}
401 Unauthorized
403 Forbidden
404 Not Found

5. 注文について

注文フロー
エンドユーザから注文が入った後に、クライアントはCreate Order APIをコールする。Create Order APIのレスポンスのステータスコードが200だとしてもこの時点ではPOSに反映されていない。そのため、Get Order Create Status APIをコールしレスポンスの"create_status"を確認する必要がある。

order_flow.png


**注文の更新と削除** 更新または削除をするには対象のorder_codeとtransaction_idを指定する。

update_order.png


**item_detailとitem_detail_contentについて** 商品対するオプションやトッピングなどと言われる注文方法はitem_detailとitem_detail_contentを利用する。

item_detailは詳細名称であり、item_detail_contentは実際に選択する商品のこと。注文時にこのパラメータは必須ではない。

item_detail Item_detail_content
飲み方 ロック
飲み方 ストレート
サイズ 大盛り
サイズ 普通

**データ構造** POS連携APIで扱っているデータに関しての構造は以下

data_structure.png

5.1 店内オーダー

注文のサイクル
最初の注文と同じテーブルへの2回目以降の注文でパラメータが異なり、同じテーブルへの2回目の注文以降は"table_activity_code"が必要となる。このサイクルはPOSでそのテーブルが会計されるまで続く。また、transaction_idもこのサイクル内では同じ値を使う。

order_cycle.png

5.2 テイクアウトオーダー

価格について
POSはテイクアウトオーダーに対して価格の変更(値引きや追加料金など)を行わない。POSの商品とテイクアウトオーダーの価格が異なる場合はテイクアウトオーダーを「正」とする。

5.3 API詳細

5.3.1 Create Order API

POSへ注文をするためのAPI
店内オーダーとテイクアウトオーダーでパラメータが異なる。

項目
URI /order/create
メソッド POST

リクエスト(店内オーダー)

属性 必須 型 概要
order_code ◯ String クライアントが作成する任意のユニークのコード
service_id ◯ String Authentication Login APIで提供するservice_id
service_type ◯ Int 2: 店内オーダー
shop_code ◯ String 店舗識別コード
request_id ◯ String クライアントが作成する任意のUID
このIDはネットワーク上の問題が発生した場合に、重複をチェックするために使用される
transaction_id ◯ String クライアントが作成する任意の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 クライアントが作成する任意のユニークのコード
service_id ◯ String Authentication Login APIで提供するservice_id
service_type ◯ Int 1: テイクアウトオーダー
shop_code ◯ String 店舗識別コード
request_id ◯ String クライアントが作成する任意のUID
このIDはネットワーク上の問題が発生した場合に、重複をチェックするために使用される
transaction_id ◯ String クライアントが作成する任意の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 クライアントが作成する任意のユニークなコード
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 Int クライアントが作成する任意のユニークなコード
order_number Int 商品の個数
price Int 商品の税抜価格
price_tax_in Int 商品の税込価格
subtotal Int 商品小計金額(税抜)
tax Float 消費税率
total Int 商品金額(税込)

customer

属性 必須 型 概要
customer_code ◯ String クライアントが作成した顧客固有のユニークなコード
name ◯ String 顧客の名前
phone ◯ String 顧客の電話番号
email String 顧客のメールアドレス

レスポンス

属性 必須 型 概要
order_code ◯ String クライアントが作成した任意のユニークなコード

サンプル

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 {
　"order_code": "String"
}
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 クライアントが作成する任意のユニークのコード
serviceId ◯ String Authentication Login APIで提供するservice_id
shopCode ◯ String 店舗識別コード

レスポンス

属性 必須 型 概要
order_code ◯ String クライアントが作成した任意のユニークのコード
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 {
　"order_code": "String",
　"create_status": Int,
　"table_activity_code": "String",
　"state": Int,
　"created_time": Int
}
201 Created
401 Unauthorized
403 Forbidden
404 Not Found

5.3.3 Get Order Status API

注文のステータスを取得するAPI

項目
URI /order/status
メソッド GET

リクエスト

属性 必須 型 概要
orderCode ◯ String クライアントが作成する任意のユニークのコード
serviceId ◯ String Authentication Login APIで提供するservice_id
shopCode ◯ String 店舗識別コード

レスポンス

属性 必須 型 概要
order_code ◯ String クライアントが作成した任意のユニークのコード
service_type ◯ Int 1: テイクアウトオーダー
2: 店内オーダー
order_status ◯ Int 注文のステータス
※service_typeによって異なる

service_type=1
　1: 注文の成功(POSに反映されていない)
　2: POSへ反映された
　3: 受渡し済
　4: キャンセル(請求なし)
　5: キャンセル(請求あり)

service_type=2
　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 {
　"order_code": "String",
　"order_status": Int,
　"payment_status": Int,
　"service_type": Int,
　"state": Int,
　"created": Int,
　"modified": Int
}
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 注文のコード(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 注文詳細のコード
order_code ◯ String 注文のコード
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 注文詳細のコード
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 {
　"shop_code": "String",
　"table_activities": []
}
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 クライアントが作成する任意の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 {
　"shop_code": "string"
}
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 クライアントが作成する任意の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 {
　"tableActivityCode": "string"
}
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