FAQ

開発者向けAPIについてのよくある質問です。kickflow自体についてのFAQはこちら。

チケットAPIについてのFAQ
コメントAPIについてのFAQ
1. メンションはどのようなフォーマットで投稿すればよいですか？
Webhook APIについてのFAQ
1. X-Kickflow-Signatureと受信したペイロードとシークレットからHMAC-SHA256を計算した値が一致しないのはなぜですか？
全般についてのFAQ
1. Personal Access TokenとService Account Tokenのどちらを使用すべきでしょうか？
2. APIのレスポンスに、API仕様書に記載のないフィールドが含まれているのですが、これは参照してもよいですか？

チケットAPIについてのFAQ

チケットのJSONから、特定のフォームフィールドの入力を取得する方法を教えて下さい

ワークフローはkickflow内部でバージョン管理されているため、管理者がワークフローを編集する度に内部のフォームのidが変わります。代わりに、codeというワークフローの編集をまたいで不変のキーが存在しておりますので、こちらを軸に入力を取得してください。

以下の手順で指定したフィールドの入力を取得できます。

対象のフォームフィールドのcodeから、フォームフィールドのidを取得します。
- フォームフィールドのcodeはワークフローの管理画面やREST APIで確認できます。
チケットの入力値の配列inputsから、formFieldIdが1で取得したidに一致するものを取得します。

チケットの作成・更新時に、ファイルを添付することができますか？

パフォーマンス上の理由から、現在エンタープライズプランのお客様のみ添付ファイルのアップロードAPIを利用可能です。アップロード後のレスポンスに含まれる signedId をチケットの作成APIのリクエストボディに詰めてください。

チケットの作成・更新時に、リクエストボディ内の自動計算フィールドの入力には何を入力すればよいですか？

自動計算フィールドの値はサーバー側で計算されるため、リクエストボディ内の入力値はnullでかまいません。

なお、リクエストボディ内のフォーム入力inputsには、自動計算フィールドを含むすべてのフィールドを指定する必要があるため、自動計算フィールドに対応する入力オブジェクトを省略することはできないのでご注意ください。

// リクエストボディの例
// 前提: フィールドコード123が単価、フィールドコード456が数量、フィールドコード789が合計金額（自動計算）の場合

// OK: すべてのフィールドの入力を指定している
{
   ...,
   "inputs": [
      {
         "formFieldCode": "123",
         "value": "1000"
      },
      {
         "formFieldCode": "456",
         "value": "3"
      },
      {
         "formFieldCode": "789",
         "value": null
      }
   ]
}

// NG: 自動計算フィールドの入力を省略している
{
   ...,
   "inputs": [
      {
         "formFieldCode": "123",
         "value": "1000"
      },
      {
         "formFieldCode": "456",
         "value": "3"
      }
   ]
}

任意の申請者になりすましてチケットを作成することはできますか？

Service Account Tokenを利用したAPI連携を実装することで可能です。詳しくは REST APIの認証についてのセクションをご覧ください。

コメントAPIについてのFAQ

メンションはどのようなフォーマットで投稿すればよいですか？

コメントの本文内に、<@メンションしたいユーザーのUUID>という形式でメンションできます。

例えば、以下のように投稿すると、

<@e4dc2845-3e25-4ce7-9ff9-10b1ddb4377b> よろしくお願いします。

以下のように表示され、山田太郎さんにメンションの通知が送信されます。

@山田太郎 よろしくお願いします。

Webhook APIについてのFAQ

X-Kickflow-Signatureと受信したペイロードとシークレットからHMAC-SHA256を計算した値が一致しないのはなぜですか？

Webhook APIで送信されるペイロードのJSON文字列に含まれる &, <, > の文字はそれぞれ以下のコードにエスケープされ、X-Kickflow-Signatureを算出する際は、エスケープされた状態の文字列でHMAC-SHA256を計算します。

&: \u0026
<: \u003c
>: \u003e

WebhookのペイロードとシークレットからHMAC-SHA256を計算する際に、上記の文字列をアンエスケープして計算するとX-Kickflow-Signatureと一致しなくなります。必ず受信したペイロードをそのまま使用して計算した値とX-Kickflow-Signatureを比較してください。

全般についてのFAQ

Personal Access TokenとService Account Tokenのどちらを使用すべきでしょうか？

原則として、どうしてもService Account Tokenを使用しないといけない場合を除いてPersonal Access Tokenの使用を優先してください。 Service Account TokenはPersonal Access Tokenに比べてアクセスできる範囲がはるかに大きいため、万が一トークンが漏洩したときに影響範囲が大きくなります。

Service Account Tokenを利用せざるを得ない例として、「外部サービスでユーザーが何らかの操作を行ったときに、自動的にkickflow内でそのユーザーがチケットを申請する」といった連携が挙げられます。一方で、「組織図を定期的に同期する」「外部の取引先マスタをkickflowの汎用マスタに取り込む」といった連携では、Personal Access Tokenを使用するだけで実現可能です。

また、Personal Access Tokenを使用して外部と連携する場合でも、トークンを発行するユーザーアカウントには必要最低限の権限のみを付与することをおすすめします。普段実際の社員が使うユーザーアカウントとは別に、連携に必要な権限のみを付与した連携専用のユーザーアカウントを用意することも検討してください。

APIのレスポンスに、API仕様書に記載のないフィールドが含まれているのですが、これは参照してもよいですか？

APIのレスポンスには、仕様書に記載のないフィールドが含まれる場合があります。こうしたフィールドは動作保証対象外となります。事前の予告なくフィールドが変更・削除される恐れがあるため、参照しないようにしてください。

FAQ

Table of contents