CData Software Blog

クラウド連携のCData Software の技術ブログです。

クラウド勤怠管理システム KING OF TIME の API の使い方

こんにちは。CData Software Japan リードエンジニアの杉本です。

今回は国産のクラウド勤怠管理システムである KING OF TIME から提供されているAPIの使い方を解説していきたいと思います。

KING OF TIME とは?

KING OF TIMEは誰でも簡単に使えるシンプルなUIのクラウド型勤怠管理システムです。

https://www.kingtime.jp/

f:id:sugimomoto:20200814002720p:plain

とても充実した機能のAPIを提供しており、企業情報や従業員情報などのマスタデータ操作や日別、月別の勤怠・打刻データを取得できるAPIを提供しています。

https://developer.kingtime.jp/

f:id:sugimomoto:20200814002729p:plain

現在対応している機能群は以下のとおりです。

https://developer.kingtime.jp/#header-%E3%83%87%E3%83%BC%E3%82%BF%E5%BD%A2%E5%BC%8F

f:id:sugimomoto:20200814002735p:plain

それでは使い方について解説していきましょう。

認証方法について

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の管理画面にアクセスし「その他」をクリックします。

f:id:sugimomoto:20200814002746p:plain

その他の設定一覧から「オプション」へ移動し

f:id:sugimomoto:20200814002751p:plain

一番したの外部サービス連携の中にある「KING OF TIME Web API連携設定」を「使用する」にチェックを入れて、「登録」します。その後「連携設定」が表示されるので、このボタンをクリックします。

f:id:sugimomoto:20200814002757p:plain

この連携設定の画面からアクセストークンの管理を行います。

まず「+新規アクセストークン発行」をクリックします。

f:id:sugimomoto:20200814002803p:plain

アクセストークンの用途名を入力し、このアクセストークンへ付与するAPI権限を選択します。

最後に接続元のIPアドレスを指定して、「登録」をクリックすればOKです。

f:id:sugimomoto:20200814002812p:plain

再度設定画面に戻ってくると、アクセストークンが表示されるので、これを使ってAPIリクエストを行うことができます。

f:id:sugimomoto:20200814002818p:plain

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

f:id:sugimomoto:20200814002826p:plain

少し注意したいのは、additionalFieldsというパラメータです。クエリパラメータで「?additionalFields=emailAddresses」を指定しなければ、EmailAddressのレスポンスが取得できませんので、注意しましょう。

f:id:sugimomoto:20200814002834p:plain

また、退職済みの従業員を取得したい場合は「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

f:id:sugimomoto:20200814002844p:plain

以下のようにパスに日付を指定することで、任意の日付の勤怠データを取得することもできますし

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

f:id:sugimomoto:20200814002853p:plain

月別の勤怠データを取得したい場合は「monthly-workings」にリクエストします。

GET /v1.0/monthly-workings HTTP/1.1
Host: api.kingtime.jp
Authorization: Bearer 937884df27884205b62b1eedc84e655c

f:id:sugimomoto:20200814002902p:plain

勤怠データでは、従業員のデータをemployeeKeyとしてレスポンスしますが、「?additionalFields=currentDateEmployee」として指定することで、従業員の付加情報も取得できます。

GET /v1.0/monthly-workings?additionalFields=currentDateEmployee HTTP/1.1
Host: api.kingtime.jp
Authorization: Bearer 937884df27884205b62b1eedc84e655c

f:id:sugimomoto:20200814002910p:plain

申請情報の取得

申請情報は休暇申請や時間外勤務申請などのデータを取得することができます。

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

f:id:sugimomoto:20200814002923p:plain

「additionalFields=flow」をクエリパラメータで指定することで、申請フローのデータも取得することができます。

GET /v1.0/requests/schedules/2020-08?additionalFields=flow HTTP/1.1
Host: api.kingtime.jp
Authorization: Bearer 937884df27884205b62b1eedc84e655c

f:id:sugimomoto:20200814002934p:plain

おわりに

勤怠データを様々な角度から取得することができるのが良いですね!

ちなみに、今回使用したPostman Collectionは以下のURLで公開しています。よかったら使ってみてください。

Postman Collection for KING OF TIME API · GitHub