本部ユーザーや店舗ごとのセッションで、閲覧可能な新着お知らせ一覧を取得します。
外部ポータルに、ユーザー・店舗ごとの新着お知らせを表示できます。
お知らせごとに個別URLが付与され、シングルサインオンでお知らせを表示できます。
呼び出し先URL
{your-domain} の部分は、ご利用の環境に合わせて変更してください。
https://{your-domain}/h2/STRNoticeFinder.doリクエスト
新着お知らせの取得APIの呼び出し回数に制限はありません。
ただし、セッション操作APIには呼び出し回数の制限があるため、ポーリングする場合は、セッション操作APIで取得したセッションキーをキャッシュして使い回してください。
| パラメータ名 | 意味 | 必須 | 制約 |
|---|---|---|---|
| func | 動作モード | 〇 | 必ず findByOpenDate を指定します。 |
| key | WebAPIキー | 〇 | お知らせ操作APIが利用可能なWebAPIキーを指定します。 |
| sessionKey | 対象となる本部ユーザー、店舗、店舗スタッフのセッションキー | 〇 | セッション操作APIで生成した有効なセッションキーを指定します。 |
| date | 対象日付 | 新着お知らせを取得したい日付を yyyy-MM-dd 形式の文字列で指定します。単一の日付を指定した場合は、指定日に公開されたお知らせ と 過去7日間の未読のお知らせ を返します。 期間を指定した場合は、期間中に公開されたお知らせ を返します。 ℹ 補足：期間を指定する場合は、開始日と終了日をカンマ（ ,）区切りで指定します。例） yyyy-MM-dd,yyyy-MM-ddℹ 補足：期間に8日以上を指定した場合はエラーになります。 ℹ 補足：本部ユーザーのセッションキーを指定した場合は、指定日または指定期間に公開されたお知らせを返します。 ℹ 補足：パラメータを省略した場合は、今日の日付が指定されたものとして扱われます。 | |
| max | 取得するお知らせ件数の最大値 | 取得するお知らせ件数の最大値を指定します。 ℹ 補足：パラメータを省略した場合は、件数制限を行わず、すべての結果を返します。 | |
| priority | 取得する重要度 | 指定した値以上の重要度のお知らせを取得します。3：通常4：重要7：緊急例） 4 を指定した場合は、重要度が 重要 と 緊急 のお知らせを取得します。ℹ 補足：存在しない重要度を指定した場合、またはパラメータを省略した場合は、すべての重要度のお知らせを返します。 | |
| responseType | レスポンス形式 | レスポンス形式を指定します。1：チェックされているカテゴリ項目を category(X)=Y の Y の部分について、カテゴリ項目IDではなく表示文字列として返します。2：お知らせの送り先の店舗コードを改行区切り（\r\n）で返します。ℹ 補足：複数の値を指定する場合は、ビット加算して指定します。 3 を指定すると、1 と 2 の両方を指定したことになります。ℹ 補足：パラメータを省略した場合は、カテゴリ項目IDを返します。 |
レスポンス
APIの呼び出し結果は、次のスキーマのXML文書として返されます。
<?xml version="1.0"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<xsd:element name="response">
<xsd:sequence>
<xsd:element name="result" type="xsd:int" minOccurs="1" maxOccurs="1" />
<xsd:element name="errors" type="xsd:string" minOccurs="0" maxOccurs="1"/>
<xsd:element name="notice-list">
<xsd:sequence>
<xsd:element name="notice" minOccurs="0">
<xsd:attribute name="app" type="xsd:string" use="optional" />
<xsd:attribute name="approved" type="xsd:string" use="optional" />
<xsd:attribute name="begin" type="xsd:string" use="required" />
<xsd:attribute name="calendar-area" type="xsd:string" use="optional" />
<xsd:attribute name="calendar-display-style" type="xsd:int" use="optional" />
<xsd:attribute name="category" type="xsd:string" use="optional" />
<xsd:attribute name="close" type="xsd:string" use="required" />
<xsd:attribute name="end" type="xsd:string" use="required" />
<xsd:attribute name="id" type="xsd:long" use="required" />
<xsd:attribute name="last-modified" type="xsd:string" use="required" />
<xsd:attribute name="open" type="xsd:string" use="required" />
<xsd:attribute name="open-text" type="xsd:string" use="optional" />
<xsd:attribute name="priority" type="xsd:int" use="optional" />
<xsd:attribute name="pub-group" type="xsd:string" use="required" />
<xsd:attribute name="pub-user" type="xsd:string" use="required" />
<xsd:attribute name="read" type="xsd:boolean" use="optional" />
<xsd:attribute name="recv-stores" type="xsd:string" use="optional" />
<xsd:attribute name="reply-type" type="xsd:int" use="required" />
<xsd:attribute name="reply-date" type="xsd:string" use="optional" />
<xsd:attribute name="text" type="xsd:string" use="required" />
<xsd:attribute name="title" type="xsd:string" use="required" />
<xsd:attribute name="url" type="xsd:string" use="required" />
<xsd:attribute name="weekly-schedule-area" type="xsd:string" use="optional" />
</xsd:element>
</xsd:sequence>
</xsd:element>
</xsd:sequence>
</xsd:element>
</xsd:schema>
| 要素 | 意味 | 備考 |
|---|---|---|
//response/result | リザルトコード | 次の値を返します。1：成功4：入力パラメータの内容にエラーがある8：その他のシステムエラーが発生 |
//response/errors | エラーメッセージ | エラーが発生した場合は、詳細なエラーメッセージが文字列で返されます。 |
//response/notice-list/notice | 新着お知らせ | 新着のお知らせ情報が返されます。以下の情報が属性値で指定されます。 （日付・時刻はすべて yyyy-MM-dd HH:mm:ss 形式のUTC時刻です）app：売場ノートアプリでお知らせを開くためのURL。売場ノートアプリが有効な場合のみ返します。approved：お知らせの承認日時。承認機能を利用しない場合は登録日時です。begin：実施期間の開始端です。calendar-area：カレンダー表示エリアです。calendar-display-style：カレンダー表示方法です。1=実施期間中ずっと表示する2=実施期間の開始日のみ表示する3=表示しない4=実施期間の開始日と終了日のみ表示するcategory：関連づけられたカテゴリ定義です。category(X)=ID\n の形式で、チェックされているカテゴリ項目分の文字列が設定されます。X の部分にはカテゴリグループのIDが入ります。複数のカテゴリグループがある場合は、カテゴリグループのソート順で並べて生成されます。close：公開終了時刻です。end：実施期間の終了端です。id：お知らせ番号です。last-modified：最終更新日です。open：公開開始時刻です。open-text：WebAPIを呼び出した時点で、お知らせ一覧画面に表示される公開日列の値が返されます。yyyy/MM/dd または HH:mm 形式の文字列です。priority：重要度です。critical=緊急important=重要normal=通常pub-group：発信部署名です。pub-user：発信者名です。read：セッションキーのセッションが店舗・店舗スタッフの場合に、既読状況を返します。true=既読false=未読既読状況の反映には1分程度かかる場合があります。 recv-stores：送り先の店舗コードです。改行区切り（\r\n）の文字列として返します。reply-type：回答タイプです。0=回答なし1=1店舗ごと1回答2=店舗ごと複数回答3=スタッフごと回答reply-date：回答期限です。text：お知らせ雛形に入力されたテキストデータです。title：お知らせのタイトルです。url：お知らせを開くためのURLです。weekly-schedule-area：週間カレンダーのスケジュール表示位置です。notice=お知らせtask=作業 |
新着お知らせの取得に成功した場合のレスポンスXML例
<response>
<result>1</result>
<notice-list>
<notice app="shopruns://{your-domain}/h2/_/RBxEREREREWDpUREREQ" approved="2020-11-27 01:56:52" begin="2020-11-26 15:00:00" calendar-area="report" calendar-display-style="1" category="category(226)=02
category(178)=01
category(167)=Floor" close="0000-00-00 00:00:00" end="2020-11-30 15:00:00" id="740" last-modified="2020-11-27 01:56:40" open="2020-11-26 15:00:00" open-text="10:56" priority="normal" pub-group="運営企画部" pub-user="渡辺 誠人" read="false" recv-stores="str00001
str00002
str00003" reply-type="0" text="A部門の売価を変更します" title="A部門売価変更指示" url="/h2/STRHeadPage.do?sso=718844_615ded54-9764-4dfc-9753-0af079d4643c_2ahwOOUc&startPage=STRViewNotice.do%3FnoticeId%3D261%26version%3D0" weekly-schedule-area="notice" />
</notice-list>
</response>
上の例では、//response/result の値が 1 のため、呼び出しは成功しています。//response/notice-list/notice に取得したお知らせが返されます。
新着お知らせの取得に失敗した場合のレスポンスXML例
<response>
<result>8</result>
<errors><![CDATA[
* invalid 'sessionKey' parameter.
]]></errors>
</response>
上の例では、//response/result の値が 8 のため、呼び出しは失敗しています。//response/errors には、指定した sessionKey が正しくないことを示すエラーメッセージが返されます。