こんにちは。CData Software Japan リードエンジニアの杉本です。
今回は国産のクラウド勤怠管理システムである KING OF TIME から提供されているAPIの使い方を解説していきたいと思います。
KING OF TIME とは？
KING OF TIMEは誰でも簡単に使えるシンプルなUIのクラウド型勤怠管理システムです。
https://www.kingtime.jp/
とても充実した機能のAPIを提供しており、企業情報や従業員情報などのマスタデータ操作や日別、月別の勤怠・打刻データを取得できるAPIを提供しています。
https://developer.kingtime.jp/
現在対応している機能群は以下のとおりです。
https://developer.kingtime.jp/#header-%E3%83%87%E3%83%BC%E3%82%BF%E5%BD%A2%E5%BC%8F
それでは使い方について解説していきましょう。
認証方法について
KING OF TIME APIの認証方法は取得したアクセストークンを Authorization HeaderのBearerトークンとして指定する方式です。
https://developer.kingtime.jp/#header-%E3%82%A2%E3%82%AF%E3%82%BB%E3%82%B9%E3%83%88%E3%83%BC%E3%82%AF%E3%83%B3
Authorization: Bearer 8j9f7v4893y58rvt7nyfq2893n75tr78937n83
アクセストークンは管理画面のUIから取得・管理し、更新や削除、有効の確認はAPIを通じても実施可能です。
アクセストークン の取得方法
アクセストークンは以下の手順で取得します。
まず、KING OF TIMEの管理画面にアクセスし「その他」をクリックします。
その他の設定一覧から「オプション」へ移動し
一番したの外部サービス連携の中にある「KING OF TIME Web API連携設定」を「使用する」にチェックを入れて、「登録」します。その後「連携設定」が表示されるので、このボタンをクリックします。
この連携設定の画面からアクセストークンの管理を行います。
まず「＋新規アクセストークン発行」をクリックします。
アクセストークンの用途名を入力し、このアクセストークンへ付与するAPI権限を選択します。
最後に接続元のIPアドレスを指定して、「登録」をクリックすればOKです。
再度設定画面に戻ってくると、アクセストークンが表示されるので、これを使ってAPIリクエストを行うことができます。
API の使い方
それでは、実際にAPIリクエストを行ってみましょう。
APIリクエストには Postman を使用しました。
KING OF TIMEのAPIエンドポイントは「https://api.kingtime.jp/v1.0」
レスポンスフォーマットは「application/json; charset=utf-8」です。
従業員情報の取得
従業員情報の取得は「employees」を指定することで実行できます。
https://developer.kingtime.jp/#%E5%BE%93%E6%A5%AD%E5%93%A1-%E5%BE%93%E6%A5%AD%E5%93%A1%E3%83%87%E3%83%BC%E3%82%BF-get
GET /v1.0/employees HTTP/1.1
Host: api.kingtime.jp
Authorization: Bearer 937884df27884205b62b1eedc84e655c
少し注意したいのは、additionalFieldsというパラメータです。クエリパラメータで「?additionalFields=emailAddresses」を指定しなければ、EmailAddressのレスポンスが取得できませんので、注意しましょう。
また、退職済みの従業員を取得したい場合は「includeResigner=true」を指定する必要があります。デフォルトはFalseになっているので、現在の従業員しかレスポンスを返しません。
勤怠情報の取得
勤怠データは日別・月別で、「勤怠・打刻・費用」の観点からそれぞれ取得できます。
https://developer.kingtime.jp/#%E5%8B%A4%E6%80%A0-%E6%97%A5%E5%88%A5%E5%8B%A4%E6%80%A0%E3%83%87%E3%83%BC%E3%82%BF-get
https://developer.kingtime.jp/#%E5%8B%A4%E6%80%A0-%E6%9C%88%E5%88%A5%E5%8B%A4%E6%80%A0%E3%83%87%E3%83%BC%E3%82%BF-get
対象とした日付の範囲で全従業員分取得できるので便利です。ただ、従業員数が多い場合は、一度のレスポンスで取得されるデータ量が肥大化してしまうので、注意が必要です。
例えば、日別勤怠のデータを取得する場合は、以下のようなリクエストになります。デフォルトではリクエストを実行した日が対象となる点に気をつけましょう。
GET /v1.0/daily-workings HTTP/1.1
Host: api.kingtime.jp
Authorization: Bearer 937884df27884205b62b1eedc84e655c
以下のようにパスに日付を指定することで、任意の日付の勤怠データを取得することもできますし
GET /v1.0/daily-workings/2020-08-13 HTTP/1.1
Host: api.kingtime.jp
Authorization: Bearer 937884df27884205b62b1eedc84e655c
「start」と「end」のクエリパラメータで日付範囲を指定して取得することもできます。
GET /v1.0/daily-workings/?start=2020-08-01&end=2020-08-13 HTTP/1.1
Host: api.kingtime.jp
Authorization: Bearer 937884df27884205b62b1eedc84e655c
月別の勤怠データを取得したい場合は「monthly-workings」にリクエストします。
GET /v1.0/monthly-workings HTTP/1.1
Host: api.kingtime.jp
Authorization: Bearer 937884df27884205b62b1eedc84e655c
勤怠データでは、従業員のデータをemployeeKeyとしてレスポンスしますが、「?additionalFields=currentDateEmployee」として指定することで、従業員の付加情報も取得できます。
GET /v1.0/monthly-workings?additionalFields=currentDateEmployee HTTP/1.1
Host: api.kingtime.jp
Authorization: Bearer 937884df27884205b62b1eedc84e655c
申請情報の取得
申請情報は休暇申請や時間外勤務申請などのデータを取得することができます。
https://developer.kingtime.jp/#%E7%94%B3%E8%AB%8B-%E3%82%B9%E3%82%B1%E3%82%B8%E3%83%A5%E3%83%BC%E3%83%AB%E7%94%B3%E8%AB%8B%E3%83%87%E3%83%BC%E3%82%BF
GET /v1.0/requests/schedules/2020-08 HTTP/1.1
Host: api.kingtime.jp
Authorization: Bearer 937884df27884205b62b1eedc84e655c
「additionalFields=flow」をクエリパラメータで指定することで、申請フローのデータも取得することができます。
GET /v1.0/requests/schedules/2020-08?additionalFields=flow HTTP/1.1
Host: api.kingtime.jp
Authorization: Bearer 937884df27884205b62b1eedc84e655c
おわりに
勤怠データを様々な角度から取得することができるのが良いですね！
ちなみに、今回使用したPostman Collectionは以下のURLで公開しています。よかったら使ってみてください。
Postman Collection for KING OF TIME API · GitHub
関連コンテンツ
