クラウド労務管理ソフト SmartHR の Web API を使ってみる
去年もいろいろなAPIを試してきたこのBlogですが、今年もはりきっていろんなAPIを試していきたいと思います。
新年一発目は、クラウド労務管理で最近かなり見かけるようになったなーと感じているSmartHRです！
公式サイトは以下からどうぞ。
Developer 向けの サイトも公開されています。
まず、SmartHR を触ってみた
とりあえず、まずサービスとして SmartHR を少し触ってみました！
人事・労務の専門家ではないのであまり詳しくは解説できないのですが、フロー形式で、新入社員の入社手続きが完了し、かつ電子申請までサポートしているので、あまり業務に詳しくない私でも、直感的に使えそうでいいなー！と思いました。
以下は入社手続きを行うための画面です。プロセスがどこまで完了しているのかも、一目瞭然ですねぇ。
SmartHR APIの利用方法
それでは実際にAPIを触ってみたいと思います。今回はシンプルにPostmanから従業員一覧を取得する方法でいきます。
SmartHR API ドキュメント
以下のURLでAPIドキュメントが公開されています。Web公開、ありがたいです。
https://developer.smarthr.jp/api/index.html
ドキュメント上から直接リクエスト検証も実施できるタイプで、簡単な検証であればこれで済みますね。
何で作られているのかなー？ と思って、開発者ツールでHTMLを探ってみたら、OpenAPI（Swagger）ベースで作られているようでした。
基本機能
アクセスできるリソースは9種類＋Webhook
・従業員
・従業員カスタム項目グループ
・従業員カスタム項目テンプレート
・部署
・雇用形態
・従業員情報収集フォーム
・メールフォーマット
・ユーザ
・事務所
・Webhook
従業員リソースは以下のような構成になっていて、かなりREST fulに従っていて、わかりやすいです！
1レコード取得：GET /v1/crews/{id}
リスト取得：GET /v1/crews
登録：POST /v1/crews/{id}
更新：PUT /v1/crews/{id}
部分更新：PATCH /v1/crews/{id}
削除：DELETE /v1/crews/{id}
招待：PUT /v1/crews/{id}/invite
更新をPUTとPATCHで分けているのが、個人的に嬉しいです！
ちょっとクセがあるのは、カスタム項目のところでしょうか。配列構造で受け渡しを行うので、注意が必要です。
{
"custom_fields": [
{
"template_id": 1,
"value": "string"
},
{
"template_id": 2,
"value": "text"
},
{
"template_id": 6,
"value": "/9j/4AAQSkZJRgABAQAASABIAAD/4QCMRXhpZgAATU0AK...",
"file_name": "awesome_image.jpg"
}
]
}
API エンドポイント
本番環境の場合は以下のようなURL
サンドボックス環境の場合は、以下のようになるみたいです。
認証方法
認証方法は3パターン
事前に取得したアクセストークンを「BASIC認証」「リクエストURLパラメータ」「リクエストヘッダパラメータ」のいずれかで渡す方式です。
渡す方法が違うだけで、基本的にどれも大きな違いは無いですね。
リクエスト制限
リクエスト制限は「1時間で最大5,000回」と比較的やさしい部類の制限に入るのかなと思います。
機能が限定されているので、よほど一括でユーザー登録などをしたい！ と言った要望でも無い限りは、制限に達さないのではないかなと思います。
検証環境の入手。サンドボックスの申し込み
APIを試す場合は、サンドボックス環境を利用するのがいいみたいです。
以下のURLから申し込みが可能で、2～3営業日以内にSmartHRの担当の方から連絡が来ます。
https://docs.google.com/forms/d/e/1FAIpQLSfX0A6AtB0QWhUPJAkMzrE-LtSQmHRYScVdT4NHL2wnGWMnIg/viewform
アクセストークンの取得方法
SmartHR APIは、SmartHRのWeb Siteから発行するアクセストークンが必要となります。
SmartHRの画面にアクセスして、右上のユーザー画面から「共通設定」をクリックし
メニュー一覧から「アプリケーション連携」を選択します。
この画面からアクセストークンの発行・管理が実施できます。
Webhookや通知連携も行えますね。今回はWeb APIを利用するので、「アクセストークン」をクリックして
「アクセストークンを発行する」画面へどうします。
この画面で、アクセストークンの用途に合わせて、任意の名称を入力し、
払い出したアクセストークンにどこまで権限を付与するか選択します。今回はとりあえず、全部選択しておきました。
発行すると、以下のようにアクセストークンが採取できます。
あとは、URLに含まれているテナントIDを確認して準備完了です。
POSTMANからリクエスト
というわけで、Sandbox環境が入手できたのでPOSTMANからリクエストしてみました。
従業員リストの取得だけですが、かなり手軽に実施できます。
GET /api/v1/crews?page=1& per_page=10 HTTP/1.1 Host: XXXXXXX.daruma.space Authorization: Bearer XXXXXXXXXXXXXXXXX
Webサイトからでも以下のようにTenant IDへ「https://XXXXXXX.daruma.space/」Tokenに取得したアクセストークンを指定し
対象のエンドポイントを選択して、「TRY」ボタンをクリックすれば
以下のように試すことができます。
おわりに
それでは、次回はもう少しユースケースベースで記事を書いてみたいと思います！
