【重要】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社につき60分毎に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"
}