その他
公開API情報確認
カテゴリー

(v1)APIドキュメント※サポート終了

【重要】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"
}