kaonavi API v2 を使うことで、カオナビの各種データの取得・更新ができます。 こちらのドキュメントで、APIの使い方をご確認ください。

kaonavi API v2 は下記のようなHTTPリクエストで各種リソースの操作ができます。構成は以下の通りです。

$ curl -X {メソッド} https://api.kaonavi.jp/api/{バージョン}/{リソース} \
    -H 'Content-Type: application/json' \
    -H 'Kaonavi-Token: {アクセストークン}'

• {アクセストークン} ・・・接続可能な顧客情報を特定します。
• {リソース} ・・・シートなどの各種情報を指定します。
• {メソッド} ・・・GETやPUTなどを指定することで、取得、更新などの操作を行えます。

メソッドとリソースの組み合わせは左メニューのAPIリファレンス以下をご確認ください。

バージョン

最新バージョンは v2.0 です。

操作対象の管理

APIを実行する前にまずAPIv2で操作出来る対象のチェックをしましょう。
カオナビにログインし、管理者機能トップ > 公開API v2 情報 > 操作対象の管理のメニューを開いて下さい。デフォルトは全てオフになっています。 このクイックスタートではメンバーの登録までを紹介しているので、画像のようにメンバー情報の「登録」にだけチェックを入れましょう。

実際の運用時にはメンバー情報やシート情報に必要な操作にだけチェックを入れて下さい。

認証のためのアクセストークンを発行しましょう。

認証情報の確認

アクセストークン発行のために必要な認証情報を事前に確認しておきます。 カオナビにログインし、 管理者機能トップ > 公開API v2 情報 > 認証情報 より、Consumer Key と Consumer Secret をご確認ください。

アクセストークン発行APIを実行

アクセストークン 発行 を参照して、アクセストークンを発行します。 アクセストークン発行に必要なcredentials の生成についてはBasicAuthを参照してください。

下記に記載されているような内容が返ってきたら成功です。

{
  "access_token": "25396f58-10f8-c228-7f0f-818b1d666b2e",
  "token_type": "Bearer",
  "expire_in": 3600
}

access_token に記載されているものが、アクセストークンです。

これで準備完了です。メンバー情報のレイアウト設定の内容を取得してみましょう。 メンバー情報 レイアウト設定取得 を参照して、次のようなリクエストをしてください。

$ curl -X GET https://api.kaonavi.jp/api/v2.0/member_layouts \
    -H 'Content-Type: application/json' \
    -H 'Kaonavi-Token: {アクセストークン}'

下記に記載されているような内容が返ってきたら成功です。

{
  "code": {
    "name": "社員番号",
    "required": true,
    "type": "string",
    "max_length": 50,
    "enum": []
  },
  "name": {
    "name": "氏名",
    "required": false,
    "type": "string",
    "max_length": 100,
    "enum": []
  },
  "name_kana": {
    "name": "フリガナ",
    "required": false,
    "type": "string",
    "max_length": 100,
    "enum": []
  },
  "mail": {
    "name": "メールアドレス",
    "required": false,
    "type": "string",
    "max_length": 100,
    "enum": []
  }
}

kaonavi API v2 によるデータの登録や更新の多くは、非同期で行われます。 メンバー情報 登録 API を使って、メンバーを登録してみましょう。

メンバー登録タスクの作成

メンバー情報 登録 を参照して、次のようなリクエストをしてください。

$ curl -X POST https://api.kaonavi.jp/api/v2.0/members \
    -H 'Content-Type: application/json' \
    -H 'Kaonavi-Token: {アクセストークン}' \
    -d '{
      "member_data": [
        {
          "code": "12345",
          "name": "カオナビ 太郎",
          "name_kana": "カオナビ タロウ"
        }
      ]
    }'

必須項目や最大文字数は先程取得したレイアウト設定取得APIの結果から確認できます。 下記に記載されているような内容が返ってきたら成功です。これでメンバー登録のタスクが作成されました。

{
  "task_id": 1
}

タスクの状況確認

次に、タスクの結果を確認してみましょう。

先程取得した task_id を利用して、タスク進捗状況 取得 を参照して、次のようなリクエストをしてください。

$ curl -X GET https://api.kaonavi.jp/api/v2.0/tasks/{task_id} \
    -H 'Content-Type: application/json' \
    -H 'Kaonavi-Token: {アクセストークン}'

下記に記載されているような内容が返ってきたら成功です。これで新しくメンバーが登録されたはずです。

{
  "id": 1,
  "status": "OK",
  "messages": []
}

以上でクイックスタートは終了です。左メニューのAPIリファレンス以下を参考に、様々なリソースを操作してみましょう。

※ 対象: メンバー情報, シート情報, 所属ツリー,マスター管理,拡張アクセス設定 が制限の対象になります。

深夜1:00~1:30の間にデータバックアップを行い、データバックアップの終了後、早朝にかけて日次バッチを実施しています。

データバックアップの静止点を考慮いただき、API更新のタイミングをご検討ください。

データバックアップは、処理を開始した時点でのデータが静止点となり、当日のデータバックアップとして保持されます。
そのため、当日のデータとしてAPI更新されたい場合は1:00より前に実施し、翌日のデータとして更新されたい場合は1:30以降をご検討ください。 ※データバックアップの復元は、データ安心パックをご利用のお客様が対象です。

また日次バッチ中にAPI更新を行った場合、開始時間の早い方から処理がされます。
先行された処理の間、もう一方の処理は待機状態となり、完了してから次の処理が実行されます。
日次バッチの開始時間及び終了時間はお客様ごとに異なります。
具体的な時間についてはサポートデスクまでお問い合わせください。

通常は本番モードで動作しますが、動作確認用にdryrunモードを用意しています。
通常のパラメータに加えて、ヘッダーに以下を設定することで、データベースの操作を行わず、リクエストの内容が適切であるかを検証することが出来ます。
※dryrunモードは登録・更新APIのみご利用いただけます。

リクエスト サンプル

$ curl -X POST https://api.kaonavi.jp/api/v2.0/members \
    -H 'Content-Type: application/json' \
    -H 'Kaonavi-Token: {アクセストークン}' \
    -H 'Dry-Run: 1' \
    -d '{
      "member_data": [
        {
          "code": "12345",
          "name": "カオナビ 太郎",
          "name_kana": "カオナビ タロウ"
        }
      ]
    }'

管理者機能トップ > レイアウト設定で設定したシートの項目情報はレイアウト設定APIにて custom_fields として取得できます。 レイアウト設定API、メンバー情報API、シート情報API で取得・更新可能なシートの項目は以下の通りです。

CSVアップロードによるファイル名の事前設定作業の置き換えになるAPIです。以下の流れでファイルを添付することができます。

1. アップロードする予定のファイル名を、APIで対象パーツに対して登録または更新する
2. ファイル入出力画面から1で設定したパーツが含まれる対象シートを選び、設定したファイル名のファイルをアップロードする

注意

以下の場合を除き、既にファイル添付されているパーツに対し更新を行うと、事前に添付されていたファイルは削除されますのでご注意ください。

• 単一レコードで、member_code , custom_fields.id , ファイル名 が一致している場合
• 複数レコードでは、上記に加え、custom_fields.id 内のファイル名がレコードごとにユニークである場合

直接値を更新することはできませんが、登録・更新API実行後、自動的に再計算処理が実行されます。

kaonavi Webhook は、メンバーの基本情報が更新された際に、指定した URL に HTTPリクエストを送信します。
Webhook を利用することで、定期的にメンバー情報を取得する必要がなく、通知をきっかけとした連携機能の開発ができるようになります。
※ Webhook は現在 β版として提供中です。

ご利用の際は以下の制限事項をご確認ください。

• 現在、Webhook は以下の機能でメンバー情報を更新した場合のみ送信します。
  • プロファイルブック
    • 基本情報の変更のみ
    • 基本情報の再計算は対象外
  • ワークフロー
    • 基本情報の変更のみ
  • APIv2
    • 所属ツリー 一括更新は対象外
  • 管理者メニュー > CSV入出力
    • 基本情報の変更のみ(アップロード)

Webhook を利用するには、Webhook 設定 API または 管理者機能トップ > 公開API v2 情報 > Webhook 設定をご利用ください。

Webhook で利用できるイベントは以下の通りです。

設定したイベントが発生した場合に送信する HTTPリクエスト内容は以下の通りです。

リクエストヘッダー

リクエストボディ

{
  "event": "member_created",
  "event_time": "2023-04-11 09:40:45",
  "member_data": [
    {
      "code": "A0001"
    },
    {
      "code": "A0002"
    }
  ]
}

レスポンス

• リクエストには常にステータスコード 200系 を返すようお願いします。
• リクエストには 10 秒以内に応答をお願いします。超過した場合、送信エラーとみなします。

再送信

送信が失敗した場合でも再送信は行われません。