いつもSmartHRをご利用いただきありがとうございます。
このたび、従業員の部署情報に関するAPIとWebhookの仕様を変更いたします。
APIまたはWebhookを使ったサービスをご利用いただいている場合、必ず以下の変更点をご確認、または開発担当者様へご共有の上、ご対応をお願いいたします。
※変更日を、2023年8月以降に変更しました。今後も変更の可能性がございますが、変更日の2週間以上前には、日時を確定して再更新いたします。
開発背景
現在、従業員の所属部署には「部署1」〜「部署3」の3つの部署を登録できますが、部署情報は「部署1」から順番に登録することしかできません。
（例：「部署1」〜「部署3」に部署情報が登録されている従業員の場合、「部署1」を削除すると、「部署2」が「部署1」に、「部署3」が「部署2」に詰まり、変更履歴も記録される）
これは、部署情報を「部署1」〜「部署3」に明示的に紐づけて管理していないためです。
これにより、従業員の所属部署を正しく管理できない場合があるため、部署情報を部署1〜部署3にそれぞれ明示的に紐づけて管理するように変更します。
それに伴い、従業員の部署情報に関するAPIとWebhookの仕様を変更いたします。
変更日
2023年8月以降を予定
※今後も変更の可能性がございますが、変更日の2週間以上前には、日時を確定して、本お知らせを更新いたします。
ご確認いただきたいこと
変更日以降は、現在の仕様のまま従業員の部署情報に関するAPI・Webhookをご利用いただくことができなくなります。
変更点をご確認の上、変更のご対応をお願いいたします。
変更日以前に、変更後のAPI・Webhookの仕様をSmartHR上で確認したい場合は、サンドボックス環境のサブドメインをチャットサポートまたは担当カスタマーサクセスまでご連絡ください。
変更後の仕様を順次反映の上、ご連絡いたします。
※事前の検証に当たっては、意図せず従業員の部署情報を書き換えてしまうことを防ぐため、サンドボックス環境をご利用ください。
新たにサンドボックス環境をご利用いただく場合や別のサンドボックス環境をご利用したい場合は、下記を参照の上、お申し込みをお願いいたします。
APIの変更点
対象
- 従業員取得
- 従業員リストの取得
- 従業員部分変更
- 従業員登録
- ユーザー取得
- ユーザーリストの取得
- 会社情報リストの取得
- 事業所リストの取得
変更内容
1.従業員取得, 2.従業員リストの取得
- 従業員取得: GET /v1/crews/{id}
- 従業員リストの取得: GET /v1/crews
レスポンスが一部変更になります。リクエストパラメータに変更はありません。
変更前
- department
- 所属部署の最初に取得できる部署情報を返します。
- departments
- 部署に所属していればその部署情報を返します。
- 所属部署が1つであれば、1つの部署情報のみ返します。
変更後
- department
- 「部署1の部署情報」を返すようになります。
- departments
- 部署に所属している/いないに関わらず必ず3つ返るようになります。
- 末所属の部署情報はnullを返します。
例1)部署に所属していない場合
{
"departments": [
null,
null,
null
]
}
例2)部署１だけ部署が入っている場合
{
"departments": [
{
"id": "string",
"name": "string",
"position": 0,
"code": "string",
"parent": {
},
"children": [
{
}
],
"updated_at": "2021-07-26T06:43:13.319Z",
"created_at": "2021-07-26T06:43:13.319Z"
},
null,
null
]
}
例3)部署１と部署３に部署が入っている場合
{
"departments": [
{
"id": "string",
"name": "string",
"position": 0,
"code": "string",
"parent": {
},
"children": [
{
}
],
"updated_at": "2021-07-26T06:43:13.319Z",
"created_at": "2021-07-26T06:43:13.319Z"
},
null,
{
"id": "string",
"name": "string",
"position": 0,
"code": "string",
"parent": {
},
"children": [
{
}
],
"updated_at": "2021-07-26T06:43:13.319Z",
"created_at": "2021-07-26T06:43:13.319Z"
}
]
}3.従業員部分更新, 4.従業員登録
- 従業員部分更新: PATCH /v1/crews/{id}
- 従業員登録: POST /v1/crews
リクエストパラメータとレスポンスが一部変更になります。
変更前
リクエストパラメータ
例1) { “department_ids”: [“#{部署ID}”] } をリクエストパラメータに指定した場合
指定したリクエストパラメータが部署1に設定されます。
部署2、部署3は部署の所属無しになります。
例2) { “department_ids”: [“#{部署ID}”,”” ,”” ] }をリクエストパラメータに指定した場合
対応していないリクエストパラメータの形式です。
指定すると「不明なリクエストパラメータです」のレスポンスが返却されます。
例3) { “department_ids”: [“#{部署ID}”,”” , “#{部署ID}”] }をリクエストパラメータに指定した場合
対応していないリクエストパラメータの形式です。
指定すると「不明なリクエストパラメータです」のレスポンスが返却されます。
レスポンス
- department
- 所属部署の最初に取得できる部署情報を返します。
- departments
- 部署に所属していればその部署情報を返します。
- 所属部署が1つであれば、1つの部署情報のみ返します。
変更後
リクエストパラメータ
例1) { “department_ids”: [“#{部署ID}”] } をリクエストパラメータに指定した場合
指定したリクエストパラメータが部署1に設定されます。
部署2、部署3は部署の所属無しになります。
例2) { “department_ids”: [“#{部署ID}”,”” ,”” ] }をリクエストパラメータに指定した場合
指定したリクエストパラメータが部署1、部署2、部署3に設定されます。
部署2と部署3は、リクエストパラメータの部署IDが指定されていないため、部署の所属は無しになります。
例3) { “department_ids”: [“#{部署ID}”, , “#{部署ID}”] }をリクエストパラメータに指定した場合
指定したリクエストパラメータが部署1、部署2、部署3に設定されます。
部署2は、リクエストパラメータの部署IDが指定されていないため、部署の所属は無しになります。
レスポンス
- department
- 「部署1の部署情報」を返すようになります。
- departments
- 部署に所属している/いないに関わらず必ず3つ返るようになります。
- 末所属の部署情報はnullを返します。
詳細は、1. 従業員取得の変更と同じになります。
5.ユーザー取得, 6.ユーザーリストの取得
- ユーザー取得: GET /v1/users/{id}
- ユーザーリストの取得: GET /v1/users
embed=crew オプションを指定した状態でのレスポンスが一部変更になります。リクエストパラメータに変更はありません。
変更前
- department
- 所属部署の最初に取得できる部署情報を返します。
- departments
- 部署に所属していればその部署情報を返します。
- 所属部署が1つであれば、1つの部署情報のみ返します。
変更後
- department
- 「部署1の部署情報」を返すようになります。
- departments
- 部署に所属している/いないに関わらず必ず3つ返るようになります。
- 末所属の部署情報はnullを返します。
詳細は、1. 従業員取得の変更と同じになります。
7.会社情報リストの取得
- 会社情報リストの取得: GET /v1/companies
embed=owner オプションを指定した状態でのレスポンスが一部変更になります。リクエストパラメータに変更はありません。
変更前
- department
- 所属部署の最初に取得できる部署情報を返します。
- departments
- 部署に所属していればその部署情報を返します。
- 所属部署が1つであれば、1つの部署情報のみ返します。
変更後
- department
- 「部署1の部署情報」を返すようになります。
- departments
- 部署に所属している/いないに関わらず必ず3つ返るようになります。
- 末所属の部署情報はnullを返します。
詳細は、1. 従業員取得の変更と同じになります。
8.事業所リストの取得
- 事業所リストの取得: GET /v1/biz_establishments
embed=soc_ins_owner または embed=lab_ins_owner オプションを指定した状態でのレスポンスが一部変更になります。リクエストパラメータに変更はありません。
変更前
- department
- 所属部署の最初に取得できる部署情報を返します。
- departments
- 部署に所属していればその部署情報を返します。
- 所属部署が1つであれば、1つの部署情報のみ返します。
変更後
- department
- 「部署1の部署情報」を返すようになります。
- departments
- 部署に所属している/いないに関わらず必ず3つ返るようになります。
- 末所属の部署情報はnullを返します。
詳細は、1. 従業員取得の変更と同じになります。
Webhookの変更点
レスポンスが一部変更になります。
Webhookの通知形式については、APIと同様の変更になります。
対象
- crew_created
- crew_updated
- crew_imported
- crew_deleted
変更内容
1. crew_created、2. crew_updated、3. crew_imported
変更前
- senderとcrew内のdepartment
- 所属部署の最初に取得できる部署情報を返します。
- senderとcrew内のdepartments
- 部署に所属していればその部署情報を返します。
- 所属部署が1つであれば、1つの部署情報のみ返します。
変更後
- senderとcrew内のdepartment
- 「部署1の部署情報」を返すようになります。
- senderとcrew内のdepartments
- 部署に所属している/いないに関わらず必ず3つ返るようになります。
- 末所属の部署情報はnullを返します。
4. crew_deleted
変更前
- senderとcrew内のdepartment
- 所属部署の最初に取得できる部署情報を返します。
- crew内のdepartments
- 削除した従業員の所属部署の状態に関わらず、必ずdepartmentsが空の状態で返却されます。
{ "event": "crew_deleted",
"sender": null,
"triggered_at": "2022-05-02T16:13:33+09:00",
"crew":
...,
"departments": [], // 従業員削除時の部署状態に関わらず、空が返却されます
"updated_at": "2021-07-26T06:43:13.319Z",
"created_at": "2021-07-26T06:43:13.319Z"
}
],
...
}変更後
- senderとcrew内のdepartment
- 「部署1の部署情報」を返すようになります。
- crew内のdepartments
- 従業員削除時の部署状態が返却されます。
{ "event": "crew_deleted",
"sender": null,
"triggered_at": "2022-05-02T16:13:33+09:00",
"crew":
...,
"departments": [ // 従業員削除時の部署状態が返却されます
{
"id": "string",
"name": "string",
"position": 0,
"code": "string",
"parent": {},
"children": [
{}
],
"updated_at": "2021-07-26T06:43:13.319Z",
"created_at": "2021-07-26T06:43:13.319Z"
},
null,
null],
}
],
...
}
ご利用中のお客様にはご迷惑をおかけいたしますが、何卒ご理解のほど、よろしくお願い申し上げます。
最後に
SmartHRでは、ご利用企業の声を積極的にサービス開発の参考にしていきたいと考えております。機能や画面のデザインなど、なにか気になることがございましたら、お気軽にお伝えください。
SmartHRの機能追加、改善に関する情報は「アップデート情報」や「リリースノート」にて、株式会社SmartHRの企業情報に関するニュースはFacebook・Twitterからもお知らせしています。
よろしければ「いいね！」「フォロー」をお願いします。
今後とも、SmartHRをよろしくお願いいたします。
Comments are closed.