管理者機能

一覧へ戻る
その他
カテゴリー

公開API情報確認

APIドキュメント

1.1事前準備

管理者機能の「公開API情報確認」を開きます。
画面にConsumer Key/Consumer Secretが表示されることを確認してください。
表示されない場合、もしくは、「公開API情報確認」に遷移できない場合、API利用開始にあたって設定作業が必要となりますのでカオナビサポートデスクまでお問い合わせください。

1.2.認証

API実行にはアクセストークンが必要です。詳しくはAPIリファレンスのアクセストークンの取得をご覧ください。
レスポンスから取得したアクセストークンは、API実行時にHTTPヘッダー(X-KAONAVI-TOKEN)にセットしてご利用ください。

1.3.リクエスト制限

アクセストークンの有効期限:60分
アクセストークンの最大同時払い出し数:1社につき5つまで
READ/WRITEの入出力サイズ上限:なし

カオナビAPIでは1社につき1時間で最大60回のリクエストを受け付けます。

1.4.通信条件

リクエストはHTTPSのみ許可しています。

1.5.dryrunモード

テスト用モードとしてdryrunモードを用意しております。
このモードでは、データ取得:ヘッダー部分のみ取得、データ更新・追加:実データを更新せずエラー有無のみ返却、という動きをします。
通常のパラメータに加えて、クエリパラメータもしくはリクエストパラメータに以下を設定してください。

dryrun なし:本番実行、0:本番実行、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を記述してください。
(例./userを利用する場合は、https://api.kaonavi.jp/api/v1.2/user)

1.7.バージョン

APIの最新バージョンはv1.2です。
利用可能なバージョンは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 公開API情報確認画面のConsumer key
consumer_secret 公開API情報確認画面のConsumer secret

■リクエストボディ

{
  "consumer_key":"1234567890abcdef",
  "consumer_secret":"1234567890abcdef"
}

■レスポンス

{
  "access_token":"2639a5c57dd2ebe1ccbe317cd84fsdu93dsjf",
  "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

ユーザー情報をリクエストパラメータの内容で更新します。
ユーザー一括アップロードの全入れ替えモードと同様の処理です。

■リクエストパラメータ

パラメータ 説明 必須
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

ユーザー情報をリクエストパラメータの内容分、追加します。
ユーザー一括アップロードの部分追加モードと同様の処理です。

■リクエストパラメータ

パラメータ 説明 必須
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

所属情報をリクエストパラメータの内容で更新します。
所属一括アップロードの全入れ替えモードと同様の処理です。

■リクエストパラメータ

パラメータ 説明 必須
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":""
    }
  ]
}

2.9.基本情報・シート情報一括更新

POST https://api.kaonavi.jp/api/{バージョン}/sheet/{sheet_id}/data/overwrite

指定したシート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.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":"カオナビ太郎",
      vdefinition_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"
}

問題は解決しましたか?

※こちらに記載いただいた内容にはご返信しておりません。ご要望・ご質問等ございましたら「お問合わせ」よりお願いいたします。