連携アプリの設定

画面：サイドメニュー「管理－システムの管理＞連携アプリの設定」

ℹ 補足：このページは、サービス管理担当者の方を対象としています。
⚙ 前提条件：設定するには、システムの管理権限が必要です。
ℹ 補足：各利用者の詳細は「利用者について」を参照してください。

本サービスから利用できるWeb・Windowsアプリケーションの設定や、外部システムとの連携で利用するWebAPIキーの設定を行います。

アプリ起動リンクの設定

サイドメニューから利用できるWeb・Windowsアプリケーションを設定します。
サイドメニューからリンクをクリックすると、アプリケーションを起動・表示できます。

⚠ 注意：連携アプリケーションにWindowsアプリケーションを設定している場合、店舗ではActiveXコントロールのインストールを求められます。

アプリ起動リンクの登録・編集

アプリ起動リンクを新しく登録、または既存のアプリ起動リンクを編集します。

⚠ 注意：入力が必須の項目には、入力欄の右横に「*」が表示されます。必ず入力してください。

［取りやめる］ボタンをクリックすると、編集内容を破棄して元の画面に戻ります。
［登録する］ボタンをクリックすると、編集内容を登録して元の画面に戻ります。
［削除する］ボタンは既存のアプリ起動リンク編集時に表示され、このアプリ起動リンクを削除できます。

アプリ起動リンクの一覧

登録したアプリ起動リンクを確認します。

［追加する］ボタンをクリックすると、アプリ起動リンクを登録できます。
一覧の［編集］ボタンをクリックすると、アプリ起動リンクの設定確認／編集ができます。

アプリ起動リンクの削除

設定しているアプリ起動リンクを削除します。

［取りやめる］ボタンをクリックすると、削除を取りやめて元の画面に戻ります。
［削除する］ボタンをクリックすると、このアプリ起動リンクを削除します。

WebAPIキーの管理

外部アプリケーションによるWebAPIを利用した、本サービスへのアクセス用キーを管理します。
WebAPIキーは最大20個まで登録できます。

WebAPIキーの登録・編集

WebAPIキーを新しく登録、または既存のWebAPIキーを編集します。

⚠ 注意：入力が必須の項目には、入力欄の右横に「*」が表示されます。必ず入力してください。

［取りやめる］ボタンをクリックすると、編集内容を破棄して元の画面に戻ります。
［登録する］ボタンをクリックすると、編集内容を登録して元の画面に戻ります。
［削除する］ボタンは既存のキー編集時に表示され、このキーを削除できます。

WebAPIキーの一覧

登録したWebAPIキーを確認します。

［キーを作成する］ボタンをクリックすると、WebAPIキーを作成できます。
一覧の［編集］ボタンをクリックすると、WebAPIキーの設定確認／編集ができます。

WebAPIキーの削除

設定しているWebAPIキーを削除します。

［取りやめる］ボタンをクリックすると、削除を取りやめて元の画面に戻ります。
［削除する］ボタンをクリックすると、このキーを削除します。

外部ポータル用URLの生成

外部ポータルに新着のお知らせ一覧を埋め込むためのコードを生成できます。
新着一覧を埋め込みたい箇所に、生成したコードを貼り付けて利用してください。
本部ユーザー、店舗・FC法人向けの新着一覧に対応しています。

⚙ 前提条件：「システムの管理＞オプションの管理＞セキュリティの設定」の［外部サービスによる本部ユーザー認証］を「Googleアカウントで認証する」に設定している、または［店舗の自動ログイン機能］を「Googleアカウントで認証する」に設定している場合に利用できます。

＜選択項目＞

＜埋め込み用コード＞

上記項目を選択した状態のURLが生成されます。
表示されたコードを埋め込み先に貼り付けてください。

⚠ 注意：iOSやSafariで利用するには「サイト越えトラッキングを防ぐ」設定を解除する必要があります。表示されない場合は、画面に表示されるプライバシーの設定を実施してください。
ℹ 補足：設定手順は「G Suiteとの相乗効果で、店舗がもっと見える」も参照してください。

SharePointのアクセスキー

SharePointサイトに、本部ユーザー向け新着のお知らせ一覧を表示するアプリを配置できます。
SharePointストアよりShopらん連携用のアプリ（Shopらん for SharePoint）を追加し、アクセスキーを設定してください。
本部ユーザー向けの新着一覧に対応しています。

⚙ 前提条件：「システムの管理＞オプションの管理＞セキュリティの設定」の［外部サービスによる本部ユーザー認証］を「Azure ADアカウントで認証する」または「SAML2.0で認証する」に設定している場合に利用できます。SAML2.0での認証の場合、Microsoft 365 のIDまたはメールアドレス（ログイン名ポリシーの設定による）とShopらんのログインIDが一致している必要があります。

＜キーの削除＞

キーを削除すると、表示されていたキーは無効となり、新たに設定できるアクセスキーが表示されます。

ℹ 補足：アクセスキーは、安全かつ継続して利用できるよう常に二つ表示されます。削除したキーは即時無効となるため、アプリに設定するアクセスキーをもう一方のキーに変更した上で削除してください。

ℹ 補足：設定手順は「SharePointとの連携で店舗がもっと見える」も参照してください。

Webhookの設定

本部ユーザーや店舗・店舗スタッフがデータを登録したタイミングで、外部アプリケーションへWebhookを通知する設定を行います。
緊急のお知らせを社内SNSに通知したり、店舗の報告画像を別システムに送ったりできます。

＜Webhookとは＞

データの更新タイミングで、外部システムが公開するHTTPエンドポイントに、更新イベントをHTTPのPOSTメソッドで通知する仕組みです。

⚙ 前提条件：Webhookからの通知を受け取り、処理を行うプログラムを自社用に開発する必要があります。

Webhookの登録・編集

Webhookを新しく登録、または既存のWebhookを編集します。

［キャンセル］ボタンをクリックすると、編集内容を破棄して元の画面に戻ります。
［保存する］ボタンをクリックすると、編集内容を登録して元の画面に戻ります。
［削除する］ボタンは既存のWebhook編集時に表示され、このWebhookを削除できます。

お知らせのWebhook

「イベント」で「お知らせ」を指定した場合のWebhookの仕様を説明します。

＜通知するイベント＞

＜送信データ＞

WebhookのHTTPリクエストはHTTP/1.1をサポートしています。

ペイロード形式バージョン：v1

お知らせ基本情報と本文のテキストデータを送信します。
添付PDFや添付ファイルのダウンロードはできません。

{
    "noticeId": {お知らせの内部ID(long)},
    "dispId": {お知らせNo.(int)},
    "event": "PUBLISH" or "UPDATE" or "DELETE" or "VERIFY",
    "title": "お知らせのタイトル",
    "priority": 3(NORMAL) or 4(IMPORTANT) or 7(CRITICAL),
    "keywords": ["キーワード1","キーワード2",…],
    "category"[
    {
        "id": {カテゴリグループのID},
        "label": "カテゴリグループのラベル",
        "selected": [{"key":"アイテムのキー","label":"アイテムのラベル"},…]
    },… ],
    "calendarArea": ["カレンダー表示位置","週間カレンダースケジュール表示位置"],
    "openDate": "公開日時(UTC)",
    "closeDate": "公開終了日時(UTC)",
    "beginDate": "実施期間の開始日時(UTC)",
    "endDate": "実施期間の終了日時(UTC)",
    "recvStores": ["店舗コード1","店舗コード2",…],//送り先店舗を個別の店舗に展開した結果
    "colors": [{"colorsId":"区分のID","label":"区分名"},…],
    "targetStaff": 0(全てのスタッフ) or 1(店長あて) or 3(店長+副店長あて) or 4(担当ユーザーあて) or 8(店舗アドバイザーあて),
    "userConcerned": [本部関係者],
    "replyType": 0(なし) or 1(店舗ごとに1回答) or 2(店舗ごとに複数回答) or 3(スタッフごとに1回答)
    "replyDueDate": "回答期限",
    "pubUser": {発信者},
    "pubGroup": {発信部署},
    "pdf":[
           {
            "pdfId": "添付PDFのファイルID",
            "fileName": "ファイル名",
            "length": ファイルのバイト数
           }
    ], //添付PDF
    "tasks":[
    {
        "dueDate": "実施する作業の実施予定日(終了)",
        "beginDate": "実施する作業の実施予定日(開始)",
        "name": "作業内容"
    },…],
    "approvedDate": "公開承認日時",
    "regAccount": {登録ユーザー},
    "updAccount": {最終更新ユーザー},
    "sessionOwner": {操作したユーザー},
    "templateId": {お知らせ雛形のID(int)},
    "templateName": "お知らせ雛形名",
    "text": "お知らせの本文（480バイト）",
    "data": {
        "10001": "部品の値のCSVと同じ文字列表現",
        "10002": 
        ：（省略）
        "10009": "ファイル名",
        "10010": "ファイル名",
        ：（省略）
    },
    "text": "テキスト",
    "token": "webhookの発行元を検証するためのトークン" 
}

ペイロード形式バージョン：v2

お知らせ基本情報と本文のテキストデータ、また添付PDFや添付ファイルのダウンロードURLとKey情報を送信します。

{
    "id": {お知らせNo.(int)},
    "event": "PUBLISH" or "UPDATE" or "DELETE" or "VERIFY",
    "title": "お知らせのタイトル",
    "priority": 3(NORMAL) or 4(IMPORTANT) or 7(CRITICAL),
    "keywords": ["キーワード1","キーワード2",…],
    "category"[
    {
        "id": {カテゴリグループのID},
        "label": "カテゴリグループのラベル",
        "selected": [{"key":"アイテムのキー","label":"アイテムのラベル"},…]
    },… ],
    "calendarArea": ["カレンダー表示位置","週間カレンダースケジュール表示位置"],
    "openDate": "公開日時(UTC)",
    "closeDate": "公開終了日時(UTC)",
    "beginDate": "実施期間の開始日時(UTC)",
    "endDate": "実施期間の終了日時(UTC)",
    "recvStores": ["店舗コード1","店舗コード2",…],//送り先店舗を個別の店舗に展開した結果
    "colors": [{"colorsId":"区分のID","label":"区分名"},…],
    "targetStaff": 0(全てのスタッフ) or 1(店長あて) or 3(店長+副店長あて) or 4(担当ユーザーあて) or 8(店舗アドバイザーあて),
    "userConcerned": [本部関係者],
    "replyType": 0(なし) or 1(店舗ごとに1回答) or 2(店舗ごとに複数回答) or 3(スタッフごとに1回答)
    "replyDueDate": "回答期限",
    "pubUser": {発信者},
    "pubGroup": {発信部署},
    "pdf":[
           {
            "pdfId": "添付PDFのファイルID",
            "fileName": "ファイル名",
            "length": ファイルのバイト数,
            "contentType": "application/pdf",
            "key": "ファイルのキー情報",
            "contentUrl": "ダウンロードURL"
            }
    ], //添付PDF
    "tasks":[
    {
        "dueDate": "実施する作業の実施予定日(終了)",
        "beginDate": "実施する作業の実施予定日(開始)",
        "name": "作業内容"
    },…],
    "approvedDate": "公開承認日時",
    "regAccount": {登録ユーザー},
    "updAccount": {最終更新ユーザー},
    "sessionOwner": {操作したユーザー},
    "templateId": {お知らせ雛形のID(int)},
    "templateName": "お知らせ雛形名",
    "text": "お知らせの本文（480バイト）",
    "data": {
        "10001": "部品の値のCSVと同じ文字列表現",
        "10002": 
        ：（省略）
        "10009": [
　　　　　　　      {
　　　　　　　        "fileName": ファイル名,
　　　　　　　        "bytes": ファイルのバイト数,
　　　　　　　        "key": "ファイルのキー情報",
　　　　　　　        "contentUrl": "ダウンロードURL"
                  }
        ],
        "10010": {
                    "fileName": "ファイル名",
                    "bytes": ファイルのバイト数,
                    "key": "ファイルのキー情報",
                    "contentUrl": "ダウンロードURL"
                  },
        ：（省略）
　　},
    "text": "テキスト",
    "pdfUrl": "お知らせ印刷PDFデータURL",
    "token": "webhookの発行元を検証するためのトークン" 
}

＜ファイルのダウンロード方法＞

ペイロードで返されたURL{contentUrl}もしくは{pdfUrl}にお知らせの操作の権限を持つWebAPIキーをセットしてリクエストを発行します。WebAPIキーは WebAPIキーの管理 で確認してください。

例）

GET {xxxUrl} HTTP/1.1
X-ShopRun-Auth: {WebAPIキー} 

ペイロード形式バージョン：Microsoft Teams

TeamsのIncoming Webhookのコネクタを利用することで、アダプティブカード形式のデータを送信します。
カードにはお知らせ基本情報（発信者、発信部署、タイトル、公開日、送り先、回答期限、作業）と本文を出力します。 本文はお知らせ雛形フォームに配置された部品のデータが上から下、左から右の順で出力します。

{
  "type": "message",
  "attachments": [
    {
      "contentType": "application/vnd.microsoft.card.adaptive",
      "content": {
        "body": [
          {
            "items": [
              {
                "columns": [
                  {
                    "items": [
                      {
                        "url": "リンク",
                        "altText": "Microsoft アカウント",
                        "size": "small",
                        "style": "person",
                        "type": "Image"
                      }
                    ],
                    "width": "auto",
                    "type": "Column"
                  },
                  {
                    "items": [
                      {
                        "text": "発信者",
                        "weight": "bolder",
                        "wrap": true,
                        "type": "TextBlock"
                      },
                      {
                        "text": "発信部署",
                        "isSubtle": true,
                        "size": "small",
                        "wrap": true,
                        "spacing": "NONE",
                        "type": "TextBlock"
                      }
                    ],
                    "width": "stretch",
                    "type": "Column"
                  }
                ],
                "type": "ColumnSet"
              },
              {
                "text": "お知らせタイトル",
                "size": "medium",
                "weight": "bolder",
                "type": "TextBlock"
              },
              {
                "facts": [
                  {
                    "title": "公開日",
                    "value": "公開日"
                  },
                  {
                    "title": "送り先",
                    "value": "送り先店舗"
                  },
                  {
                    "title": "",
                    "value": "送り先区分"
                  },
                  {
                    "title": "",
                    "value": "送り先の対象"
                  },
                  {
                    "title": "回答期限",
                    "value": "回答期限日"
                  },
                  {
                    "title": "実施する作業",
                    "value": "作業予定日1 作業名1"
                  },
                  {
                    "title": "",
                    "value": "作業予定日2 作業名2"
                  }
                ],
                "type": "FactSet"
              }
            ],
            "type": "Container"
          },
          {
            "inlines": [
              "本文"
            ],
            "type": "RichTextBlock"
          },
          {
            "inlines": [
              {
                "text": "ファイル添付 ",
                "color": "accent",
                "type": "TextRun"
              },
              "\n",
              "ファイル名"
            ],
            "type": "RichTextBlock"
          },
          {
            "items": [
              {
                "spacing": "none",
                "columns": [
                  {
                    "items": [
                      {
                        "url": "ファイルのダウンロードURL",
                        "width": "16px",
                        "type": "Image"
                      }
                    ],
                    "width": "auto",
                    "type": "Column"
                  },
                  {
                    "items": [
                      {
                        "text": "ファイル名",
                        "type": "TextBlock"
                      }
                    ],
                    "width": "stretch",
                    "type": "Column"
                  }
                ],
                "type": "ColumnSet"
              },
              {
                "spacing": "none",
                "columns": [
                  {
                    "items": [
                      {
                        "url": "ファイルのダウンロードURL",
                        "width": "16px",
                        "type": "Image"
                      }
                    ],
                    "width": "auto",
                    "type": "Column"
                  },
                  {
                    "items": [
                      {
                        "text": "ファイル添付",
                        "type": "TextBlock"
                      }
                    ],
                    "width": "stretch",
                    "type": "Column"
                  }
                ],
                "type": "ColumnSet"
              }
            ],
            "type": "Container"
          }
        ],
        "actions": [
          {
            "url": "お知らせのURL",
            "title": "お知らせを表示する",
            "tooltip": "お知らせのURL",
            "type": "Action.OpenUrl"
          }
        ],
        "msteams": {
          "width": "Full"
        },
        "type": "AdaptiveCard",
        "version": "1.5",
        "$schema": "http://adaptivecards.io/schemas/adaptive-card.json"
      }
    }
  ],
  "token": "webhookの発行元を検証するためのトークン"
}

フォトレポートのWebhook

「イベント」で「フォトレポート」を指定した場合のWebhookの仕様を説明します。

＜通知するイベント＞

＜送信データ＞

WebhookのHTTPリクエストはHTTP/1.1をサポートしています。

{
  "event": "POST",
  "info": {
    "reportId": {フォトレポートの内部ID(long)},
    "title": "フォトレポートのタイトル",
    "description": "説明",
    "dueDate": "〆切日時",
    "openDate": "公開日時",
    "recvStores":  ["店舗コード1","店舗コード2",…],//対象店舗を個別の店舗に展開した結果
  },
  "position": {
    "position": {報告箇所の内部ID(long)},
    "title": "報告箇所名",
    "description": "報告箇所の説明"
  },
  "post": {
    "position": {報告箇所の内部ID(long)},
    "target": {報告した店舗},
    "caption": "説明",
    "altitude": "位置情報の取得ができた場合は高度(m)",
    "latitude": "位置情報の取得ができた場合は緯度",
    "longitude": "位置情報の取得ができた場合は経度",
    "locationLabel": "位置情報の取得ができた場合かつジオコーディングができた場合は住所",
    "mediaType": "mediaのMIMEタイプ",
    "media": {//報告された画像・動画
      "md5": "ファイルのMD5値",
      "length": "ファイルのバイト数",
      "url": "ダウンロードURL",
      "caption": 常にブランク
    },
    "thumbnail": {//サムネイル画像
      "md5": "ファイルのMD5値",
      "length": "ファイルのバイト数",
      "url": "ダウンロードURL",
      "caption": 常にブランク
    }
  },
  "token": "Webhook を検証するため、またファイルのダウンロード時に指定するヘッダーとして利用" 
}

＜画像ファイルのダウンロード方法＞

ダウンロードURLは20分間有効です。
ペイロードで返されたダウンロードURL{url}に{token} をセットしてリクエストを発行します。

例1）tokenをヘッダーに指定する場合

GET {url}
HTTP/1.1
X-ShopRun-WebhookToken: {token} 

例2）tokenをGetメソッドのパラメータに指定する場合

GET {url}?token={token} HTTP/1.1

Webhookの一覧

登録したWebhookの一覧を確認できます。

［Webhookを追加］ボタンをクリックすると、Webhookを登録できます。
［Webhookの履歴を見る］ボタンをクリックすると、Webhookの履歴を確認できます。
一覧の［編集］ボタンをクリックすると、Webhookの設定確認／編集ができます。

Webhookのリトライ

ペイロード先からリトライ可能なエラーが返った場合は、5回までリトライします。

＜リトライ対象＞

Webhookの削除

設定しているWebhookを削除します。

［取りやめる］ボタンをクリックすると、削除を取りやめて元の画面に戻ります。
［削除する］ボタンをクリックすると、このWebhookを削除します。

Webhookの履歴

最近10日間に呼び出したお知らせや業務アプリ、フォトレポートのWebhookの履歴を確認できます。

Webhookの履歴一覧

Webhookの履歴一覧では、下記の情報を確認できます。