カテゴリー閲覧API

山崎 翔平

2021-10-20T06:30:45.981Z

カテゴリー閲覧APIを利用することで、IBISEに登録しているカテゴリーの詳細情報を取得することができます。

カテゴリー閲覧APIのエンドポイントと、アクセスする際のHTTPメソッドは以下の通りです。URLに記載されている xxxxxx は、利用しているサブドメインに置き換えてください。

URLHTTPメソッド
https://xxxxxx.ibise.com/api/v1/categories/{categoryId}GET

指定パラメータ

  • カテゴリー詳細情報を取得する際は、以下の項目をクエリパラメータにて設定することができます。
項目キー必須/任意デフォルト値説明
タイムゾーンtimezone任意string該当アカウントが選択しているタイムゾーン'Asia/Tokyo'などのタイムゾーンを表す文字列。これにより出力の日時のタイムゾーンを指定することができます。マスター文字列については こちら を参照ください。
閲覧者タイプviewer_type任意string'all_users'カテゴリーを閲覧するユーザーのタイプを選択可能となります。現時点では、'all_users'のみ指定可能。'all_users'を選択の場合、管理者だけが閲覧可能、もしくは、エージェントのみが閲覧可能のカテゴリー情報は見れません。
ロケールlocale任意string該当アカウントの選択中のロケールカテゴリー情報を閲覧する際の言語指定。'JAPANESE', 'ENGLISH', 'TRADITIONAL_CHINESE'のいずれか。
  • 「公開」ステータスのカテゴリーのみ閲覧ができます。「公開」以外のステータスの記事が指定された場合、HTTPステータスコード 404(Not Found)が返されます。
  • ロケールを指定する場合、該当ロケール情報がある場合のみ値が返ります。該当するロケール情報を保持しない場合は、404(Not Found)が返されます。

返り値

  • 検索の結果情報(result) と、カテゴリの情報 (category) を JSON形式で返します。

結果情報 (result)

項目キー説明
APIバージョンversionstringAPIのバージョンを返す。v1なので'1'を返す。

カテゴリー情報 (category)

項目キー説明
カテゴリーIDcategory_idnumberカテゴリーの識別子
カテゴリー名namestringカテゴリー名(指定localeでの表示)
説明文descriptionstringカテゴリーの説明文(指定localeでの表示)。全文を表示します。
URLurlstringポータルサイトのカテゴリーページのURLを返します(指定localeでの表示)。ポータルサイト非公開の場合はnullを返します。
親カテゴリーIDparent_category_idnumber親カテゴリーID。親がない場合はnullを返します。
子カテゴリーの有無has_child_categoriesboolean子カテゴリを持つ場合はtrue、ない場合はfalseを返します。
ロケールlocalestringカテゴリー名などの出力で利用しているロケールを表示します。
作成日時created_atstringISO 8601のフォーマットで、指定timezoneで表示します。
更新日時updated_atstringISO 8601のフォーマットで、指定timezoneで表示します。

エラー時の対処

  • エラーが発生した場合、エラー種類を HTTP レスポンスのステータスコードに指定して、レスポンスを返します。
  • また、補足のエラーメッセージがある場合は、以下のような形式で JSONでエラーメッセージを返します。errors が配列になっていることに注意してください。
例) timezone=Asia/Ebisu
{
    errors: [
        {
             message: 'invalid timezone value: Asia/Ebisu'
        }
    ]
}

具体例

リクエスト

https://xxxxxx.ibise.com/api/v1/categories/11
  ?timezone=Asia/Tokyo
  &viwer_type=all_users
  &locale=JAPANESE

レスポンス

{
  result: {
    version: '1'
  },
  category: {
    category_id: 11,
    name: '運営会社からのお知らせ',
    description: '',
    url: 'https://faq.ibise.com/ja/categories/11',
    parent_category_id: null,
    has_child_categories: false,
    created_at: '2021-07-01T12:34:56+09:00',
    updated_at: '2021-07-02T01:23:45+09:00'
    },
  }
}
お問い合わせ