- 【重要】v1のサポートは終了しました
- 1.1事前準備
- 1.2.認証
- 1.3.リクエスト制限
- 1.4.通信条件
- 1.5.dryrunモード
- 1.6.ベースURI
- 1.7.バージョン
- 2. APIリファレンス
- 2.1.アクセストークン取得
- 2.2.ユーザー一括取得
- 2.3.ユーザー一括更新
- 2.4.ユーザー追加
- 2.5.所属一括取得
- 2.6.所属一括更新
- 2.7.所属追加
- 2.8.基本情報・シート情報一括取得
- 2.9.基本情報・シート情報一括更新
- 2.10.基本情報・シート情報追加
- 2.11.タスク進捗状況取得
- 2.12.基本情報・シート情報作成依頼(非同期取得用)
- 2.13.基本情報・シート情報作成進捗状況取得(非同期取得用)
- 2.14.基本情報・シート情報取得(非同期取得用)
- 2.15.基本情報・シート情報部分更新
- 2.16.基本情報・シート情報部分削除
【重要】v1のサポートは終了しました
バージョン1のサポートは2023年3月31日で終了となりました。
お客様におかれましては、バージョン2をご利用いただきますようお願い申し上げます。
バージョンの違いにつきましては、「公開APIのバージョン」をご覧ください。
1.1事前準備
①管理者機能の「公開API情報確認」を開きます。
②画面に「Consumer Key」、及び「Consumer Secret」が表示されることを確認してください。
「公開API情報確認」が表示されない場合は、カオナビサポートデスクまでお問い合わせください。
1.2.認証
API実行にはアクセストークンが必要です。詳しくはAPIリファレンスのアクセストークンの取得を確認してください。
レスポンスから取得したアクセストークンは、API実行時にHTTPヘッダー（X-KAONAVI-TOKEN）にセットしてご利用ください。
1.3.リクエスト制限
制限名称説明| アクセストークンの有効期限 | 1時間 |
| アクセストークンの最大同時払い出し数 | 1社につき６０分毎に5つまで |
| リクエスト制限 | 1社につき1時間で最大60回のリクエスト |
1.4.通信条件
条件値| プロトコル | HTTPS |
| メソッド | POST |
1.5.dryrunモード
通常は本番モードで動作しますが、テスト用モードとしてdryrunモードを用意しております。
| データ取得 | ヘッダー部分のみ取得 |
| データ更新 | 実データを更新せずエラー有無のみ返却 |
| データ追加 | 実データを更新せずエラー有無のみ返却 |
通常のパラメータに加えて、クエリパラメータもしくはリクエストパラメータに以下を設定してください。
| 指定なし | 本番モード |
| dryrunに0を指定 | 本番モード |
| dryrunに1を指定 | dryrunモード |
■サンプル
{
"dryrun":1
"data":[
{
"member_code":"a0262"
"member_name":"カオナビ太郎"
"definition_46":"2017-04-12"
"definition_47":"TOEIC 950点"
}
]
}
エラーの場合、エラー詳細はレスポンスの"errors"に配列形式でセットして返却します。
1.6.ベースURI
ベースURIは、https://api.kaonavi.jp/api/{バージョン} です。
ベースURIの末尾に機能毎のURIを追加して記述してください。
（例）ユーザー一括取得を利用する場合
https://api.kaonavi.jp/api/v1.2/user）
1.7.バージョン
API v1の最新バージョンはv1.2です。
API v1の利用可能な機能と対応するバージョンは2.APIリファレンスの機能一覧をご確認ください。
2. APIリファレンス
＜機能一覧＞
| # | 取扱リソース |
HTTP メソッド |
操作種別 | 機能ごとのURI |
利用可能 バージョン |
| 1 | アクセストークン | POST | 取得 | /get_token | v1.0〜 |
| 2 | ユーザー | POST | 一括取得 | /user | v1.0〜 |
| 3 | ユーザー | POST | 一括更新 | /user/overwrite | v1.0〜 |
| 4 | ユーザー | POST | 追加 | /user/add | v1.0〜 |
| 5 | 所属 | POST | 一括取得 | /department | v1.0〜 |
| 6 | 所属 | POST | 一括更新 | /department/overwrite | v1.0〜 |
| 7 | 所属 | POST | 追加 | /department/add | v1.0〜 |
| 8 | 基本情報・シート情報 | POST | 一括取得 | /sheet/{sheet_id} | v1.0〜 |
| 9 | 基本情報・シート情報 | POST | 一括更新 | /sheet/{sheet_id}/data/overwrite | v1.0〜 |
| 10 | 基本情報・シート情報 | POST | 追加 | /sheet/{sheet_id}/data/add | v1.0〜 |
| 11 | タスク | POST | 進捗状況取得 | /task/{task_id} | v1.0〜 |
| 12 | 基本情報・シート情報 | POST | 作成依頼(非同期取得用) | /sheet/{sheet_id}/preset/ | v1.1〜 |
| 13 | 基本情報・シート情報 | POST | 作成進捗状況取得(非同期取得用) | /sheet/{sheet_id}/task/{progress_id} | v1.1〜 |
| 14 | 基本情報・シート情報 | POST | 取得(非同期取得用) | /sheet/{sheet_id}/get/{progress_id} | v1.1〜 |
| 15 | 基本情報・シート情報部分更新 | POST | 部分更新 | /sheet/{sheet_id}/data/update | v1.2〜 |
| 16 | 基本情報・シート情報部分削除 | POST | 部分削除 | /sheet/{sheet_id}/data/delete | v1.2〜 |
2.1.アクセストークン取得
POST https://api.kaonavi.jp/api/{バージョン}/get_token
API実行に必要なアクセストークンを取得します。
※有効期限が切れた場合は、再度アクセストークンを取得してください
■リクエストパラメータ
なし
■リクエストボディ
{
"consumer_key":"1234567890abcdef"
"consumer_secret":"1234567890abcdef"
}
■レスポンス
{
"data": {
"access_token": "b4c6067169b818ee5f114cd11be060ebd5056c5d"
"expires_in": 3600
}
}
2.2.ユーザー一括取得
POST https://api.kaonavi.jp/api/{バージョン}/user
ユーザー情報を取得します。
ユーザー一括ダウンロードと同様の処理です。
※パスワードは"****"でマスクされています。
■リクエストパラメータ
なし
■レスポンス
{
"headers":{
"email":"ログインid"
"password":"パスワード"
"member_code":"社員番号"
"name":"氏名"
"type":"アカウント種別"
"role":"ロール"
"is_active":"アカウント状態"
"password_locked":"パスワードロック"
"use_smartphone":"スマホオプション"
"use_secure":"セキュアアクセス"
"last_logined_at":"最終ログイン日時"
"password_modified_at":"パスワード変更日時"
"created_at":"アカウント作成日時"
"last_modified_by":"最終更新ユーザー"
"last_modified_at":"最終更新日時"
}
"users":[
{
"email":"taro.kaonavi@kaonavi.jp"
"password":"****"
"member_code":"a0088"
"name":"顔那比 太郎"
"type":"Adm"
"role":"カオナビ管理者"
"is_active":true
"password_locked":false
"use_smartphone":false
"use_secure":false
"created_at":"2016-10-07 10:54:12"
"last_logined_at":"2016-10-07 10:54:32"
"password_modified_at":"2016-10-07 10:55:19"
"last_modified_by":"Kaonavi Supoort"
"last_modified_at":"2017/06/13 17:56:53"
}
]
}
2.3.ユーザー一括更新
POST https://api.kaonavi.jp/api/{バージョン}/user/overwrite
ユーザー情報をリクエストパラメータの内容で更新します。
ユーザー一括アップロードの全入れ替えモードと同様の処理です。
更新データに含まれないユーザーは削除されます。
タスク進捗状況取得APIにて結果を取得してください。
■リクエストパラメータ
| パラメータ | 説明 | 必須 |
| users[i].email | ログインID | 〇 |
| users[i].password | パスワード | 〇 |
| users[i].member_code | 社員番号 | 〇 |
| users[i].name | 氏名 | |
| users[i].type | アカウント種別 | 〇 |
| users[i].role | ロール | 〇 |
| users[i].is_active | アカウント利用(false:無効 true:有効) | 〇 |
| users[i].password_locked | パスワードロック(false:不可 true:可) | 〇 |
| users[i].use_smartphone | スマホオプションフラグ(false:不可 true:可) | 〇 |
| users[i].use_secure | セキュアアクセスフラグ(false:不可 true:可) | 〇 |
■リクエストボディ
{
"users":[
{
"email":"jiro.kaonavi+2@kaonavi.jp"
"password":"Test1234"
"member_code":"a0262"
"name":"テストカオナビ"
"type":"Adm"
"role":"カオナビ管理者"
"is_active":"-"
"password_locked":"-"
"use_smartphone":"-"
"use_secure":"-"
}
]
}
■レスポンス
{
"progress_id":1
"status":"OK"
}
2.4.ユーザー追加
POST https://api.kaonavi.jp/api/{バージョン}/user/add
ユーザー情報をリクエストパラメータの内容分、追加します。
ユーザー一括アップロードの部分追加モードと同様の処理です。
タスク進捗状況取得APIにて結果を取得してください。
■リクエストパラメータ
| パラメータ | 説明 | 必須 |
| users[i].email | ログインID | 〇 |
| users[i].password | パスワード | 〇 |
| users[i].member_code | 社員番号 | 〇 |
| users[i].name | 氏名 | |
| users[i].type | アカウント種別 | 〇 |
| users[i].role | ロール | 〇 |
| users[i].is_active | アカウント利用 (false:無効 true:有効) |
〇 |
| users[i].password_locked | パスワードロック (false:不可 true:可) |
〇 |
| users[i].use_smartphone | スマホオプションフラグ (false:不可 true:可) |
〇 |
| users[i].use_secure | セキュアアクセスフラグ (false:不可 true:可) |
〇 |
| users[i].created_at | アカウント作成日時 |
■リクエストボディ
{
"users":[
{
"email":"jiro.kaonavi+2@kaonavi.jp"
"password":"Test1234"
"member_code":"a0262"
"name":"テストカオナビ"
"type":"Adm"
"role":"カオナビ管理者"
"is_active":"-"
"password_locked":"-"
"use_smartphone":"-"
"use_secure":"-"
}
]
}
■レスポンス
{
"progress_id":1
"status":"OK"
}
2.5.所属一括取得
POST https://api.kaonavi.jp/api/{バージョン}/department
所属の情報を取得します。
所属一括ダウンロードと同様の処理です。
■リクエストパラメータ
なし
■レスポンス
{
"status":OK
"departments":[
{
"department_code1":"200"
"department_name1":"営業本部(salesDiv.)"
"leader_member_code":"a0001"
"leader_member_name":"カオナビ太郎"
"memo":"2017年度売上目標：100億"
}
{
"department_code1":"200"
"department_name1":"営業本部(salesDiv.)"
"department_code2":"201"
"department_name2":"第一営業部"
"leader_member_code":"a0002"
"leader_member_name":"カオナビ次郎"
"memo":"2017年度売上目標：30億"
}
]
}
2.6.所属一括更新
POST https://api.kaonavi.jp/api/{バージョン}/department/overwrite
所属情報をリクエストパラメータの内容で更新します。
所属一括アップロードの全入れ替えモードと同様の処理です。
更新データに含まれない所属は削除されます。
タスク進捗状況取得APIにて結果を取得してください。
■リクエストパラメータ
| パラメータ | 説明 | 必須 |
| departments[i].department_code1 | 所属コード1 | 〇 |
| departments[i].department_name1 | 所属名1 | |
| departments[i].department_code2 | 所属コード2 | |
| departments[i].department_name2 | 所属名2 | |
| …階層分続く | ||
| departments[i].leader_member_code | 責任者社員番号 | |
| departments[i].leader_member_name | 責任者氏名 | |
| departments[i].memo | メモ |
■リクエストボディ
{
"departments": [
{
"department_code1":"1000"
"department_name1":"営業本部"
"department_code2":"1100"
"department_name2":"第一営業部"
"department_code3":"1110"
"department_name3":"金融グループ"
"department_code4":"1111"
"department_name4":"ITグループ"
"leader_member_code":"a0001"
"leader_member_name":"カオナビ太郎"
"memo":"2017年度売上目標：3億"
}
]
}
■レスポンス
{
"progress_id":"1"
"status":"OK"
}
2.7.所属追加
POST https://api.kaonavi.jp/api/{バージョン}/department/add
所属情報をリクエストパラメータの内容分、追加します。
所属一括アップロードの部分追加モードと同様の処理です。
■リクエストパラメータ
| パラメータ | 説明 | 必須 |
| departments[i].department_code1 | 所属コード1 | 〇 |
| departments[i].department_name1 | 所属名1 | |
| departments[i].department_code2 | 所属コード2 | |
| departments[i].department_name2 | 所属名2 | |
| …階層分続く | ||
| departments[i].leader_member_code | 責任者社員番号 | |
| departments[i].leader_member_name | 責任者氏名 | |
| departments[i].memo | メモ |
■リクエストボディ
{
"departments": [
{
"department_code1":"1000"
"department_name1":"営業本部"
"department_code2":"1100"
"department_name2":"第一営業部"
"department_code3":"1110"
"department_name3":"金融グループ"
"department_code4":"1111"
"department_name4":"ITグループ"
"leader_member_code":"a0001"
"leader_member_name":"カオナビ太郎"
"memo":"2017年度売上目標：3億"
}
]
}
■レスポンス
{
"progress_id":"1"
"status":"OK"
}
2.8.基本情報・シート情報一括取得
POST https://api.kaonavi.jp/api/{バージョン}/sheet/{sheet_id}
パスパラメータで指定したシートIDの情報を全メンバー分取得します。
メンバー情報一括ダウンロードと同様の処理です。
シートID・カラムIDは「公開API情報確認」画面でご確認ください。
タイムアウトエラーが発生する場合は、非同期取得用API(2.12〜2.14)をご利用ください。
■シート定義情報サンプル
{
"sheet_id":"0"
"name":"基本情報"
"definitions": [
{
"id":0
"name":"所属"
"type":"enum"
}
{
"id":1
"name":"名前"
"type":"String"
}
]
}
- シートID：sheet_idの値
- カラムID：definitions項目のidの値
■リクエストパラメータ
なし
■パスパラメータ
| sheet_id | シート情報のID |
■レスポンス
{
"status":OK
"data":[
{
"member_code":"a0001"
"member_name":"藤井 健"
"definition_46":"2017/04/12"
"definition_47":"TOEIC 950点"
"last_modified_by":""
"last_modified_at":""
}
]
}
レーダーチャートパーツに相当するカラムIDを指定した場合はエラーとなります。
2.9.基本情報・シート情報一括更新
POST https://api.kaonavi.jp/api/{バージョン}/sheet/{sheet_id}/data/overwrite
指定したシートIDの情報を全メンバー分変更します。
メンバー情報一括アップロードの全入れ替えモードと同様の処理です。
更新データに含まれない基本情報・シート情報は削除されます。また、メンバに紐づいている各種データも全て削除されます。
更新データに含まれない基本情報・シート情報は削除されます。
シートID・カラムIDは「公開API情報確認」画面でご確認ください。
社員番号はキー項目になるため更新できません。
※兼務情報を主務と同じ所属に更新することはできません。
タスク進捗状況取得APIにて結果を取得してください。
■シート定義情報サンプル
{
"sheet_id":"0"
"name":"基本情報"
"definitions":[
{
"id":0
"name":"所属"
"type":"enum"
}
{
"id":1
"name":"名前"
"type":"String"
}
]
}
- シートID：sheet_idの値
- カラムID：definitions項目のidの値
■リクエストパラメータ
| パラメータ | 説明 | 必須 |
| data[i].member_code | 社員番号 | 〇 |
| data[i].member_name | 氏名 | |
| data[i].definition_XX(XXはカラムid) | シート定義による |
■パスパラメータ
| sheet_id | シートID |
■リクエストボディ
{
"data":[
{
"member_code":"a0262"
"member_name":"カオナビ太郎"
"definition_46":"2017/04/12"
"definition_47":"TOEIC 950点"
}
]
}
■レスポンス
{
"progress_id":"1"
"status":"OK"
}
- 兼務情報に主務と同じ所属を登録することはできません
2.10.基本情報・シート情報追加
POST https://api.kaonavi.jp/api/{バージョン}/sheet/{sheet_id}/data/add
指定したシートIDの情報を追加します。
メンバー情報一括ダウンロードの部分追加モードと同様の処理です。
シートID・カラムIDは「公開API情報確認」画面でご確認ください。
※兼務情報に主務と同じ所属を追加することはできません。
■シート定義情報サンプル
{
"sheet_id":"0"
"name":"基本情報"
"definitions": [
{
"id":0
"name":"所属"
"type":"enum"
}
{
"id":1
"name":"名前"
"type":"String"
}
]
}
- シートID：sheet_idの値
- カラムID：definitions項目のidの値
■リクエストパラメータ
| パラメータ | 説明 | 必須 |
| data[i].member_code | 社員番号 | 〇 |
| data[i].member_name | 氏名 | |
| data[i].definition_XX(XXはカラムid) | シート定義による |
■パスパラメータ
| sheet_id | シートID |
■リクエストボディ
{
"data":[
{
"member_code":"a0262"
"member_name":"カオナビ太郎"
"definition_46":"2017/04/12"
"definition_47":"TOEIC 950点"
}
]
}
■レスポンス
{
"progress_id":"1"
"status":"OK"
}
2.11.タスク進捗状況取得
POST https://api.kaonavi.jp/api/{バージョン}/task/{task_id}
処理の進捗状況を取得します。
■リクエストパラメータ
なし
■パスパラメータ
| task_id | API実行時のレスポンス"progress_id"で返却するタスクID |
■レスポンス
{
"progress_id":"1"
"status":"OK"
}
■status
- OK: 正常に処理が完了
- NG: 既知のエラー発生(バリデーションエラー等)、エラー内容を返す
- ERROR: 未知のエラー発生、サポート問い合わせが必要
- WAITING: 処理の実行待ち
- RUNNING: 処理中
2.12.基本情報・シート情報作成依頼(非同期取得用)
POST https://api.kaonavi.jp/api/{バージョン}/sheet/{sheet_id}/preset
2.8.基本情報・シート情報一括取得(/sheet/{sheet_id})を利用した際にタイムアウトエラーが発生する場合、2.12〜2.14の非同期取得用APIでのデータ取得をお試しください。
パスパラメータで指定したシートIDの情報を全メンバー分取得する処理を開始させます。
開始した処理IDが返却されます。
シートIDは「公開API情報確認」画面でご確認ください。
■リクエストパラメータ
なし
■パスパラメータ
| sheet_id | シートID |
■レスポンス
{
??"data":{
??????"progress_id":3
??????"status":"OK"
?????}
}
2.13.基本情報・シート情報作成進捗状況取得(非同期取得用)
POST https://api.kaonavi.jp/api/{バージョン}/sheet/{sheet_id}/task/{2.12.のprogress_id}
基本情報・シート情報作成依頼(非同期取得用)で開始させた処理の進捗状況を取得します。
■リクエストパラメータ
なし
■パスパラメータ
| sheet_id | シートID |
| progress_id | 基本情報・シート情報作成依頼(非同期取得用)で返却されるprogress_id |
■レスポンス
{
"status":"OK"
"message":"正常に処理が完了しました"
}
■status
- OK: 正常に処理が完了
- NG: 既知のエラー発生(バリデーションエラー等)、エラー内容を返す(※)
- ERROR: 未知のエラー発生、サポート問い合わせが必要
- WAITING: 処理の実行待ち
- RUNNING: 処理中
2.14.基本情報・シート情報取得(非同期取得用)
POST https://api.kaonavi.jp/api/{バージョン}/sheet/{sheet_id}/get/{2.12.のprogress_id}
基本情報・シート情報作成依頼(非同期取得用)で開始させた処理結果を取得します。
メンバー情報一括ダウンロードと同様の結果を取得します。
シートID・カラムIDは「公開API情報確認」画面でご確認ください。
- シートID：sheet_idの値
- カラムID：definitions項目のidの値
■リクエストパラメータ
なし
■パスパラメータ
| sheet_id | シートID |
| progress_id | 基本情報・シート情報作成依頼(非同期取得用)で返却されるprogress_id |
■レスポンス
{
"data":{
"headers":{
"member_code":"社員番号"
"member_name":"氏名"
"member_kana":"フリガナ"
"definition_794":"LABEL"
"definition_796":"顔写真"
"definition_801":"ラベル"
"definition_778":"テスト"
"definition_803":"ラベル"
"definition_804":"ラベル"
"last_modified_by":"最終更新ユーザー"
"last_modified_at":"最終更新日時"
}
vdata":[
{
"member_code":"30"
"member_name":"テスト三郎"
"member_kana":"テストサブロウ"
"definition_794":"0000040"
"definition_796":"a0005"
"definition_801":""
"definition_778":""
"definition_803":""
"definition_804":""
"last_modified_by":"パートナーサポート"
"last_modified_at":"2018/03/13 17:50:43"
}
]
}
}
処理が完了していないときは現状の進捗状況を返します。
{
"status":"WAITING"
"message":"処理の実行を待っています。"
}
■status
- OK: 正常に処理が完了
- NG: 既知のエラー発生(バリデーションエラー等)、エラー内容を返す(※)
- ERROR: 未知のエラー発生、サポート問い合わせが必要
- WAITING: 処理の実行待ち
- RUNNING: 処理中
※非同期取得用エラーメッセージ
sheet_idが存在しない・不正値の場合、progress_idが存在しないprogress_id発行時のsheet_idと合致しない場合、status:NGを返します
2.15.基本情報・シート情報部分更新
POST https://api.kaonavi.jp/api/{バージョン}/sheet/{sheet_id}/data/update
指定したシートIDの情報を、指定したメンバーのみ変更します。
リクエストパラメータは2.9.基本情報・シート情報一括更新と同じです。
シートID・カラムIDは「公開API情報確認」画面でご確認ください。
社員番号はキー項目になるため更新できません。
※兼務情報を主務と同じ所属に更新することはできません。
■シート定義情報サンプル
{
"sheet_id":"0"
"name":"基本情報"
"definitions":[
{
"id":0
"name":"所属"
"type":"enum"
}
{
"id":1
"name":"名前"
"type":"String"
}
]
}
- シートID：sheet_idの値
- カラムID：definitions項目のidの値
■リクエストパラメータ
| パラメータ | 説明 | 必須 |
| data[i].member_code | 社員番号 | 〇 |
| data[i].member_name | 氏名 | |
| data[i].definition_XX(XXはカラムID) | シート定義による |
■パスパラメータ
| sheet_id | シートID |
■リクエストボディ
{
"data":[
{
"member_code":"a0262"
"member_name":"カオナビ太郎"
"definition_46":"2017/04/12"
"definition_47":"TOEIC 950点"
}
]
}
■レスポンス
{
"progress_id":"1"
"status":"OK"
}
2.16.基本情報・シート情報部分削除
POST https://api.kaonavi.jp/api/{バージョン}/sheet/{sheet_id}/data/delete
指定したシートIDの情報を、指定したメンバーのみ削除します。
・シートIDが0の場合:指定したメンバーを削除
・シートIDが0以外の場合:指定したメンバーのシート情報を削除
リクエストパラメータは社員番号を指定してください。
■リクエストパラメータ
| パラメータ | 説明 | 必須 |
| data[i].member_code | 社員番号 | 〇 |
■パスパラメータ
| sheet_id | シートID |
■リクエストボディ
{
"data":[
{
"member_code":"a0262"
}
]
}
■レスポンス
{
"progress_id":"1"
"status":"OK"
}