スマレジ・プラットフォーム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は通知されないため、必要に応じて対象リソースの再取得を行ってください。

レスポンス

  • HTTPSリクエストには常に200系のステータスコードを返してください。
  • Webhookではレスポンスボディは利用しません。
  • HTTPSリクエストには 3秒以内 に応答する必要があります。超過した場合、接続が切断され、エラーとして扱われます。
    Webhook受信後の処理は、非同期で処理することを検討してください。
  • Webhookから通知されるHTTPSリクエストは失敗しても再送は行われません。
    ※再送機能は検討中です。

その他要注意事項

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

利用者通知

アプリ利用者が新しく追加されたとき、又は利用を停止したとき、Webhookにて顧客情報を通知します。

リクエスト

Header

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

Body

フィールド名 タイプ 値/説明
action string start : アプリ購入時
end : アプリ利用停止時
date string アクション発生日(yyyy-mm-dd)
contractId string イベントの発生した契約ID(HeaderのSmaregi-Contract-Idと同じ値)
clientId string 認証認可情報のクライアントID

レスポンス

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

その他要注意事項

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

ログイン (β)

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

ユーザー認可の要求

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

認可エンドポイントURL

http://id.smaregi.dev/authorize

クエリーパラメーター

パラメーター 必須 値の説明
response_type code
client_id アプリのクライアントID
scope openid
state ※推奨 CSRF対策に設定するランダムな文字列。
redirect_uri ユーザー認可後のリダイレクト先URL。デベロッパーサイトでアプリに登録したリダイレクトURIと一致する必要あり。

認可コードの取得

ユーザーが認可するとリダイレクトURIに対して結果がリダイレクトされます。

クエリーパラメーター

パラメーター 値の説明
code ユーザーアクセストークン取得に使用する認可コード。1回のみ利用可能。有効期限は5分となります。
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と同じ値を指定。

レスポンス

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

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

レスポンスの例

Content-Type: application/json

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

ユーザー情報を取得

UserInfoエンドポイントからログインユーザー情報を取得できます。

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

レスポンス

キー 値の説明
sub 契約またはユーザーの識別子
contract 契約情報
- id 契約ID
- is_owner ユーザーが契約のオーナーであるか

レスポンスの例

Content-Type: application/json

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




<no summary>

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