スマレジ・プラットフォームAPI 共通仕様書 (1.0.0)

概要

このドキュメントは、スマレジ・プラットフォームAPIの共通部分の仕様についてをまとめたものです。

スマレジ・プラットフォームAPIを利用する事で、仕様の範囲内で外部システムから、スマレジをはじめ、スマレジ ・ウェイター、スマレジ ・タイムカード、各プロダクトのデータにアクセスすることができます。

※各プロダクトのAPI機能詳細については、各仕様書をご参照ください。
※各プロダクトの仕様変更に伴い、APIの仕様が変更される場合があります。


基本情報

各APIにて共通している項目は以下のとおりです。

項目 内容
使用プロトコル HTTP/1.1 (https)
HTTPメソッド GET、POST、PUT、PATCH、DELETE のいずれか
文字コード UTF-8

APIエンドポイント

環境によりエンドポイントURLが異なります。このドキュメントではサンドボックス環境を対象に例を記載しています。

サンドボックス環境 本番環境
アクセストークンAPI https://id.smaregi.dev https://id.smaregi.jp
プラットフォームAPI https://api.smaregi.dev https://api.smaregi.jp

アクセストークン

アプリアクセストークン

アプリとしてアプリユーザーのデータにAPIアクセスするにはアプリアクセストークンを取得する必要があります。

POST https://id.smaregi.dev/app/{契約ID}/token

{契約ID} はアプリユーザーの契約IDに置き換えてください。
契約IDは利用者通知により通知します。

リクエストヘッダー

ヘッダー名 値の説明
Authorization Basic {Base64文字列}
Base64文字列には、クライアントIDとクライアントシークレットをコロン(:)で結合してBase64エンコードしたものを指定。
Content-Type application/x-www-form-urlencoded

クライアントIDとクライアントシークレットは、デベロッパーサイトでアプリの「環境設定」ページから確認してください。

リクエストボディ

キー 必須 値の説明
grant_type client_credentials
scope 要求するAPIスコープ。複数の場合は半角スペースで結合して指定。

要求できるAPIスコープは、アプリのAPI設定で有効にしたスコープの中から選択できます。
有効ではないスコープを要求しても無視され、存在しないスコープを含む場合はエラーを返します。

レスポンス

成功時にアクセストークンを含む下記のレスポンスを取得できます。

キー 値の説明
scope アクセストークンで有効なスコープリスト
token_type Bearer
expires_in アクセストークンの有効期間(秒)
access_token アクセストークン
  • アクセストークン発行時の有効期間は変更になる可能性があります。

レスポンスの例

Content-Type: application/json

{
    "scope": "{SCOPE_NAME} {SCOPE_NAME} {SCOPE_NAME}",
    "token_type": "Bearer",
    "expires_in": 3600,
    "access_token": "{ACCESS_TOKEN}"
}

リクエスト

各プロダクトのAPIリクエストには、取得したアプリアクセストークンをAuthorizationリクエストヘッダーに含めて送信してください。
※各プロダクトのAPIエンドポイントについては、仕様書ページより、各仕様書をご参照ください。

リクエストの例

スマレジ の店舗(ID:1)情報を取得します。

GET https://api.smaregi.dev/{契約ID}/pos/stores/1 HTTP/1.1
Authorization: Bearer {アクセストークン}

{アクセストークン}はAPIアクセストークン、{契約ID}はアプリユーザーの契約IDに置き換えてください。


レスポンス

成功時

APIリクエストが正常に完了した時は、HTTPステータスコード200でレスポンスを返却します。

成功レスポンスの例

HTTP/1.1 200 OK
Content-Type: application/json

{
  "productId": "1",
  "productName": "スマレジTシャツ",
  "productCode": "100002454",
  "categoryId": "3",
  "price": "3000",
  "description": "スマレジロゴがプリントされたTシャツです。",
  "displaySequence": "5",
  "ProductPrices": [
    {
      "storeId": "1",
      "priceDivision": "1",
      "startDate": "2020-02-01",
      "price": "2800"
    }
  ]
}

レスポンスの詳細は各仕様書を参照してください。


失敗時

エラーが発生した場合は、エラー原因に応じたHTTPステータスコードおよびメッセージを返却します。
レスポンスの内容は下記の通りです。

レスポンスヘッダー

ヘッダー名 値の説明
Content-Type application/problem+json

レスポンスボディ

キー 値の説明
type エラータイプを識別するURI、もしくは about:blank
title エラーの概要
detail エラーの説明
status HTTPステータスコード

エラーレスポンスの例

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "about:blank",
  "title": "Bad Request",
  "detail": "アクセストークンの有効期限切れです。",
  "status": 400
}

エラーレスポンスの詳細は各仕様書を参照してください。


HTTPステータスコード (共通部分)

共通するHTTPステータスコードは以下のとおりです。
※詳細は各仕様書を参照してください。

HTTPステータスコード 内容
400 パラメータが不正です
401 アクセストークンが無効です
403 アクセス権限がありません
404 リソースが存在しません
500 予期しないエラーが発生しました
503 サービス利用不可
サービスが一時的に過負荷やメンテナンスで使用できません

Webhook

Webhookの使い方

  • スマレジの管理画面、スマレジ・アプリの操作によりイベントが発生すると、Webhook送信先エンドポイントに対してWebhookイベントのリクエストを送信します。
    ※詳細は下記「リクエスト」参照
  • リクエストを受け取った後、正しく送信されたことの確認の為、送信元にレスポンスを返してください。
    ※詳細は下記「レスポンス」参照
  • Webhookではイベントの対象となったデータのPK情報しか通知されないため、実際の値は取得APIにて取得してください。

リクエスト

Webhookでは、イベントが発生した際に、以下の情報をWebhook送信先エンドポイントに対してPOSTします。

Header

フィールド名 値/説明
Content-Type application/json
Smaregi-Contract-Id イベントの発生した契約ID
Smaregi-Event イベント名
Webhook設定画面にてカスタムヘッダーに設定したフィールド名

Body

フィールド名 タイプ 値/説明
action string イベントに対して発生したアクション名
詳細は各API仕様書の各イベント参照
例) created : 登録、edited : 更新
(PK項目) - PK項目の項目名と値については各API仕様書の各イベント参照
※一括処理(アクションが bulk〜 )の場合、更新対象のIDは通知されないため、必要に応じて対象リソースの再取得を行ってください。

レスポンス

Webhook受信後、ステータスコード 200 のレスポンスを返してください。

スマレジプラットフォームは、Webhook送信後 3秒以内 にレスポンスを受信できなければエラーとして扱い送信処理を終了します。再送はありません。 次の処理を推奨します。

  • Webhook受信処理と受信後の処理を非同期で処理すること
  • レスポンスボディに何も設定しないこと

通信の影響など、同じWebhookが重複して送信されることがあります。またエラー時の再送処理も検討中です。 重複する内容のWebhookも考慮した受信処理をご検討ください。

その他要注意事項

  • ユーザー都合により、アプリが利用停止中になっている場合、Webhookは送信されません。
    その後、利用を再開した場合も利用停止中に発生したWebhookは送信されません。

利用者通知

アプリ利用者が下記の操作をしたときに、Webhookにて顧客情報を通知します。

  • 利用を開始したとき
  • 利用を停止したとき
  • プランを変更したとき

リクエスト

Header

フィールド名 値/説明
Content-Type application/json
Smaregi-Contract-Id イベントの発生した契約ID
Smaregi-Event AppSubscription
  • Webhookで設定したカスタムヘッダーは送信されません。

Body

フィールド名 タイプ 値/説明
action string start : アプリ利用開始時
end : アプリ利用停止時
change-plan : プラン変更時
date string アクション発生日(yyyy-mm-dd)
contractId string イベントの発生した契約ID(HeaderのSmaregi-Contract-Idと同じ値)
clientId string 認証認可情報のクライアントID
plan object {"trial_days": "お試し日数(integer)", "price": "プラン価格(integer)", "name": "プラン名"}

Content-Type: application/json

{
    "action": "start",
    "date": "2020-01-01",
    "contractId": "user_contract",
    "clientId": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "plan": {
        "trial_days": 15,
        "price": 3000,
        "name": "スタンダードプラン"
    }
}

レスポンス

※「Webhook - レスポンス」をご確認ください。

その他要注意事項

  • Webhook受信後、アプリアクセストークンを発行するとプラットフォームAPIを利用できるようになります。

ログイン (β)

OAuth 2.0 Authorization Code Grant と OpenID Connect に基づいて、スマレジアカウントでのログインを利用できます。

ユーザー認可の要求

ユーザーにログインと認可を要求するには、認可エンドポイントURLにクエリーパラメータを含めてユーザーをリダイレクトしてください。

認可エンドポイントURL

https://id.smaregi.dev/authorize

クエリーパラメーター

パラメーター 必須 値の説明
response_type code
client_id アプリのクライアントID
scope ユーザーに認可を要求するスコープ。
複数の場合は半角スペースで結合して指定。
state ※推奨 CSRF対策に設定するランダムな文字列。
動的にランダムな文字列を生成して利用することを推奨。
redirect_uri ユーザー認可後のリダイレクト先URL。
デベロッパーサイトでアプリに登録したリダイレクトURIと一致する必要あり。
code_challenge PKCE。動的に生成した code_verifier 値のSHA256ハッシュ値をBase64 URLエンコードした値。
publicクライアントは必須、confidentialクライアントは推奨。
code_challenge_method PKCE。S256 を指定。

scope の指定

OpenID Connect で指定するスコープと、プラットフォームAPIアクセスで必要なスコープを指定してください。

スコープ 説明
openid ログインユーザーの識別子の取得、UserInfoエンドポイントへのアクセス。
email ログインユーザーのアカウントのメールアドレスを参照。 openid の指定が必須。
profile ログインユーザーのプロフィール情報(現在は name のみ)を参照。 openid の指定が必須。
offline_access リフレッシュトークンの取得。

ユーザーアクセストークンでのプラットフォームAPIへのアクセスは、各サービスAPIの対応状況が異なりますので各API仕様書をご確認ください。 対応していないスコープが含まれる場合、エラーをリダイレクトURIへリダイレクトします。

PKCE code_verifier, code_challenge の生成

code_verifier の値は、[A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~" からなる、43文字~128文字のランダムな文字列を生成してください。
ユーザーアクセストークンの取得時に使用します。

code_challenge の値は、code_challenge_method で指定のメソッドで code_verfifier を計算した結果を使用します。
S256 では code_verifier 値のSHA256ハッシュ値をURLセーフなBase64エンコードした値になります。

confidentialクライアントについてはPKCEの利用を推奨としていますが、将来的に必須とする予定です。

認可コードの取得

ユーザーが認可するとリダイレクトURIにリダイレクトされ、下記のクエリーパラメーターを含みます。

クエリーパラメーター

パラメーター 値の説明
code ユーザーアクセストークン取得に使用する認可コード。
有効期限は5分で、1回のみ利用できます。
state CSRF対策に設定したランダムな文字列。
ユーザー認可の要求時に指定した state 値と一致することを検証してください。

認可コードの有効期限は変更される可能性があります。

エラーレスポンス

ユーザーが認可しなかった場合は下記のクエリーパラメーターを含む結果がリダイレクトされます。

パラメーター 値の説明
error エラーコード
error_description エラー内容
state CSRF対策に設定したランダムな文字列。
ユーザー認可の要求時に指定した state 値と一致することを検証してください。

ユーザーアクセストークンの取得

認可コードを使ってユーザーアクセストークンを取得できます。

POST https://id.smaregi.dev/authorize/token

リクエストヘッダー

ヘッダー名 値の説明
Authorization Basic {Base64文字列}
Base64文字列には、クライアントIDとクライアントシークレット(なければ省略)を
コロン(:)で結合してBase64エンコードしたものを指定。
Content-Type application/x-www-form-urlencoded

クライアントIDとクライアントシークレットは、デベロッパーサイトでアプリの「環境設定」ページから確認してください。

リクエストボディ

キー 必須 値の説明
grant_type authorization_code
code 取得した認可コード
redirect_uri ユーザー認可の要求時に指定したリダイレクトURIと同じ値を指定。
code_verifier PKCE。[A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"
からなる、43文字〜128文字の動的に生成したランダムな文字列。
認可エンドポイントでPKCEを指定した場合、必須。

レスポンス

成功時にアクセストークンを含む下記のレスポンスを取得できます。

キー 値の説明
token_type Bearer
expires_in アクセストークンの有効期間(秒)
access_token アクセストークン
scope アクセストークンに付与されたAPIスコープ。
id_token ユーザー認可の要求時にスコープに openid を指定したときのみ含まれる。
refresh_token リフレッシュトークン。
スコープに offline_access を指定したときのみ含まれる。
有効期限 30日間。
  • アクセストークン・リフレッシュトークン発行時の有効期間は変更になる可能性があります。
  • 要求したスコープがアクセストークンに付与されないことがあります。必要なスコープを含むか確認してください。

レスポンスの例

Content-Type: application/json

{
    "token_type": "Bearer",
    "expires_in": 3600,
    "access_token": "{ACCESS_TOKEN}",
    "scope": "{SCOPE}"
}

ユーザー情報を取得

UserInfoエンドポイントからログインユーザー情報を取得できます。ユーザーアクセストークンに openid スコープが必要です。

POST https://id.smaregi.dev/userinfo
ヘッダー名 値の説明
Authorization Bearer {ACCESS_TOKEN} 取得したアクセストークンを指定。

レスポンス

キー 必要スコープ 値の説明
sub openid 契約またはユーザーの識別子
contract openid 契約情報
- id 契約ID
- is_owner ユーザーが契約のオーナーであるか
name profile ログインユーザーのアカウントに登録されている表示用フルネーム
email email ログインユーザーのアカウントに登録されているメールアドレス
email_verified email メールアドレスが検証済みか

レスポンスの例

Content-Type: application/json

{
    "sub": "smaregi:abc123",
    "contract": {
        "id": "smaregi",
        "is_owner": true
    }
}

ユーザーアクセストークンの更新

ユーザーアクセストークンの取得時に offline_access スコープを含めていればリフレッシュトークンを取得でき、リフレッシュトークンを使ってユーザーアクセストークンを更新することができます。

POST https://id.smaregi.dev/authorize/token

リクエストヘッダー

ヘッダー名 値の説明
Authorization Basic {Base64文字列}
Base64文字列には、クライアントIDとクライアントシークレット(なければ省略)を
コロン(:)で結合してBase64エンコードしたものを指定。
Content-Type application/x-www-form-urlencoded

リクエストボディ

キー 必須 値の説明
grant_type refresh_token
refresh_token ユーザーアクセストークン取得時に含まれるリフレッシュトークン。

レスポンス

ユーザーアクセストークンの取得時と同じ項目になります。 レスポンスに含まれる新しいアクセストークン・リフレッシュトークンを使用してください。




<no summary>

get /dummy
/dummy
Copyright (C) 2020 Smaregi, Inc. All rights reserved.