kintone API連携の設計方法｜外部SaaS・基幹システムと安全につなぐ

kintone API連携は、実装だけを見るとシンプルに見えます。

REST APIでレコードを取得する。

REST APIでレコードを登録する。

REST APIでレコードを更新する。

JavaScript APIで画面上の操作に合わせて処理する。

Webhookでレコード追加や更新を外部へ通知する。

APIトークンやOAuthで認証する。

しかし、実務で問題になるのは、APIの呼び出し方そのものよりも、業務データの責任分界です。

どのシステムが顧客マスタの正本なのか。

kintoneで修正した金額を、外部SaaSへ反映してよいのか。

外部SaaSの古いデータでkintoneを上書きしてよいのか。

同じレコードが2回送られたとき、二重登録しないか。

APIトークンは、どのアプリにどの操作だけ許可するのか。

Webhookで通知した処理が外部側で失敗したとき、kintone側から再実行できるのか。

こうした設計が曖昧なままAPI連携を作ると、最初は動いても、件数増加、仕様変更、担当交代、障害対応で詰まります。

よくある失敗は、次のような状態です。

• kintoneと外部SaaSの両方で顧客名を編集でき、どちらが正しいか分からない
• 外部IDがなく、顧客名やメールアドレスで無理に突合している
• APIトークンに広い権限を持たせ、不要なアプリまで読める
• JavaScript APIで画面表示のたびに大量のAPIを呼んでいる
• Webhookから外部処理を直接実行し、失敗時の再実行単位がない
• 夜間バッチが全件取得を続け、レコード数の増加とともに処理時間が伸びる
• 失敗ログが通知文だけで、どのレコードをどこまで処理したか追えない
• 外部システムの項目変更に気づかず、連携だけが静かに止まる

kintone API連携で最初に設計するのは、APIの呼び出し順ではなく、正本データ、更新キー、同期方向、認証方式、失敗時の戻し方です。

この記事では、kintone API連携を、REST API、JavaScript API、Webhook、APIトークン、OAuthの機能説明で終わらせず、外部SaaSや基幹システムと安全につなぐための業務設計として整理します。

kintone連携の全体設計はこちら
kintone外部連携の設計方法はこちら
kintoneデータ連携の設計方法はこちら

API連携は実装前の設計で決まる

kintone API連携の成否は、コードを書く前にほぼ決まります。

実装前に、少なくとも次を決めます。

設計項目	決めること	決まっていないと起きること
連携目的	入力、出力、同期、通知、集計のどれか	余計な双方向連携を作る
正本データ	どのシステムの値を正式値にするか	古い値で上書きされる
同期方向	kintoneから外部へ、外部からkintoneへ、双方向か	更新競合が起きる
更新キー	外部ID、顧客番号、請求番号など	重複登録や誤更新が起きる
認証方式	APIトークン、OAuth、セッション、ユーザー権限	権限が広すぎる
実行タイミング	即時、数分ごと、夜間、手動	業務が待つか、上限に近づく
失敗時対応	通知、保留、再実行、手動修正	途中停止を復旧できない
監視ログ	件数、対象、外部ID、結果、エラー	原因調査に時間がかかる

API連携は、外部サービスとkintoneの間に「自動で値を流す通路」を作る作業です。

通路を作る前に、何を流してよいかを決めます。

たとえば、請求データを会計システムへ送る場合、kintone側で承認済みになったものだけ送るのか、下書きも送るのかで設計は変わります。

請求番号は会計側で発番するのか、kintone側で仮番号を持つのかも決めます。

会計側へ送った後にkintoneで金額を直せるようにするなら、修正依頼、取消、再送のルールが必要です。

単にレコード更新APIを呼ぶだけでは、この問題は解けません。

API連携は「できること」から考えるより、「流してよいデータ」と「流してはいけない状態」を分ける方が失敗しにくいです。

連携対象と正本データを決める

API連携で最初に決めるのは、連携対象と正本です。

連携対象は、外部SaaS、基幹システム、データ基盤、チャット、フォーム、会計、販売管理、CRMなどです。

ただし、対象サービス名だけでは足りません。

そのシステムが、業務上どのデータの正本なのかを決めます。

データ	正本になりやすい場所	kintone側の役割例
顧客マスタ	CRM、販売管理、kintone	現場入力、照会、案件紐付け
商品マスタ	販売管理、会計、EC	参照、見積明細、受付
案件	kintone、CRM	進捗、見積、作業依頼
請求	会計、販売管理	請求前確認、承認、送信履歴
在庫	販売管理、倉庫システム	現場照会、引当依頼
対応履歴	kintone、CRM、問い合わせ管理	追記、検索、担当引継ぎ
集計データ	BI、データ基盤、kintone	会議用一覧、確認用サマリ

正本を決めると、同期方向が決まります。

外部SaaSが顧客マスタの正本なら、kintoneは顧客情報を参照または限定的に更新します。

kintoneが案件の正本なら、外部側では案件番号や状態を勝手に変えないようにします。

会計システムが請求の正本なら、kintoneで送信後の金額を直接書き換えないルールが必要です。

正本が決まらないまま双方向同期を作ると、最後に更新された値が残るだけになります。

それは業務上の正しさではありません。

kintoneアプリ間データ連携の設計方法はこちら

REST API・JavaScript API・Webhookの違い

kintone API連携では、REST API、JavaScript API、Webhookを分けて考えます。

方式	役割	向いている処理	注意点
REST API	外部やカスタマイズからkintoneデータを操作する	取得、登録、更新、削除、状態更新	認証、権限、API制限、エラー処理が必要
JavaScript API	kintone画面上の操作に合わせて処理する	入力補助、表示制御、画面内のAPI呼び出し	画面表示時の大量呼び出しに注意
Webhook	kintone上の変化を外部へ通知する	レコード追加、更新、ステータス変更の外部通知	通知先の失敗や再実行を別途設計する

Kintone Developer ProgramのREST API概要では、kintone REST APIでアプリレコードの作成、取得、更新、削除やスペース操作ができることが説明されています。

Kintone Developer Program：Kintone REST API Overview

JavaScript APIは、kintoneの画面上で動くカスタマイズに使います。

Kintone Developer Program：Kintone JavaScript API

使い分けの目安は次の通りです。

やりたいこと	まず見る方式
外部SaaSからkintoneへレコードを登録したい	REST API
kintoneの一覧や詳細画面で入力補助したい	JavaScript API
kintoneでレコード更新されたら外部へ知らせたい	Webhook
夜間に外部システムと差分同期したい	REST API + バッチ
レコード保存時に外部APIへ問い合わせたい	JavaScript APIまたは外部処理
複数件を順番に処理し、失敗分を再実行したい	REST API + キュー + ログ

Webhookは、外部処理を起動するきっかけです。

Webhookだけで安全な同期が完成するわけではありません。

Webhookで受けた後に、外部側でキューへ入れる、重複を防ぐ、処理ログを残す、失敗分だけ再実行する、という設計が必要です。

次の記事ではWebhook単体の設計を扱いますが、この時点でも「Webhookは通知、APIは操作」と分けておくことが重要です。

APIトークンとOAuthの権限設計

kintone API連携では、認証方式を雑に選ぶと危険です。

よく使うのは、APIトークンとOAuthです。

認証方式	向いているケース	設計上の注意点
APIトークン	サーバー間連携、定期バッチ、固定アプリの連携	アプリ単位で権限を絞る、トークンを安全に保管する
OAuth	外部アプリがユーザー許可を得てAPIを使う	クライアント管理、スコープ、許可ユーザー、トークン期限を扱う
セッション認証	kintone画面上のカスタマイズ	操作者の権限で動く前提を理解する
ユーザー認証	管理スクリプトや限定用途	パスワード管理や多要素認証との関係に注意する

kintone REST API概要では、APIトークン認証でX-Cybozu-API-Tokenヘッダーを使うことが示されています。

Kintone Developer Program：Kintone REST API Overview

OAuthクライアント追加手順では、外部アプリケーションがOAuth 2.0でkintone APIを実行するために、kintone側でアプリケーションを登録し、認可フローでアクセストークンを取得する流れが説明されています。

Kintone Developer Program：How to Add OAuth Clients

権限設計では、次を確認します。

確認項目	見ること
対象アプリ	本当に読む・書く必要があるアプリだけか
操作権限	取得だけか、登録・更新・削除も必要か
対象フィールド	外部へ渡してよい項目だけか
実行者	システム連携か、ユーザーごとの許可か
保管場所	トークンやシークレットをどこに保存するか
変更時対応	トークン再発行、権限変更、退職者対応の手順

APIトークンは便利ですが、広すぎる権限を持たせると事故の範囲が広がります。

読み取りだけでよい連携に、登録・更新・削除権限を付けない。

単一アプリだけ使う連携に、複数アプリのトークンをまとめない。

本番と検証でトークンを分ける。

退職者の個人環境やローカルPCにトークンを残さない。

このあたりは、API連携の実装品質というより、運用設計です。

kintoneセキュリティ設計はこちら

リアルタイム連携とバッチ連携

API連携では、リアルタイムにすべき処理と、バッチでよい処理を分けます。

すべてを即時連携にすると、API制限、外部SaaSの障害、ネットワーク遅延の影響を受けやすくなります。

一方、すべてを夜間バッチにすると、現場が待てない業務が出ます。

連携タイミング	向いている業務	設計のポイント
即時	承認後通知、在庫引当、受付完了通知	失敗時に業務を止めるか、保留にするか
数分ごと	CRMリード同期、ステータス反映	差分条件、重複防止、再実行単位
夜間	マスタ同期、大量集計、外部DB退避	全件ではなく差分、処理時間、ログ確認
手動	締め後送信、重要データの再送	実行者、対象条件、確認画面

リアルタイム連携で重要なのは、失敗時の扱いです。

たとえば、kintoneで受注確定した瞬間に外部へ送信する場合、外部SaaSが一時的に落ちていたらどうするかを決めます。

選択肢は大きく3つです。

失敗時の扱い	向いているケース
保存を止める	外部送信できないと業務上成立しない処理
保存は通し、連携待ちにする	後で再送できる処理
手動確認へ回す	金額や顧客情報など重要な処理

多くの業務では、保存を止めるより、連携待ちの状態を作り、失敗分だけ再実行できる構成の方が運用しやすいです。

リアルタイム連携は速さだけで選ばず、外部側が失敗したときに業務を止めるか、保留にして再実行するかで決めます。

API制限・リトライ・エラー処理

kintone API連携では、API制限を前提にします。

kintone REST API概要では、同時APIリクエスト数、1日あたりのAPIリクエスト数、レコード操作APIの制限などが整理されています。

Kintone Developer Program：Kintone REST API Overview

連携設計では、少なくとも次を入れます。

設計項目	内容
差分取得	更新日時、ステータス、同期フラグで対象を絞る
件数分割	一度に処理する件数を決める
同時実行制御	同じ時間帯に処理を走らせすぎない
リトライ	すぐ再試行せず、時間を空ける
エラー分類	認証、権限、項目不整合、外部障害を分ける
ログ	処理ID、対象アプリ、レコードID、外部ID、結果を残す
再実行	失敗分だけ再実行できるようにする

リトライは、単に同じAPIをもう一度呼ぶことではありません。

外部SaaSが落ちている時に即時リトライを連打すると、状況を悪化させます。

エラー種別ごとに、扱いを分けます。

エラー種別	例	対応
認証エラー	トークン期限切れ、権限不足	管理者通知、設定確認
データ不備	必須項目不足、選択肢不一致	対象レコードを保留、担当者へ確認
重複	更新キー重複、外部ID重複	マスタ統合、手動判断
API制限	429、上限到達	待機、時間を空けた再実行
外部障害	外部SaaSの5xx、タイムアウト	キューで保留、復旧後に再実行
仕様変更	外部項目名変更、型変更	マッピング修正、テスト再実行

kintone API上限の設計方法はこちら
kintone API制限の回避設計はこちら

Bulk Request・Cursor・更新キーの使いどころ

kintone API連携では、大量処理や複数操作を扱う場面があります。

このとき、Bulk Request、Cursor、更新キーを理解しておくと設計しやすくなります。

仕組み	使いどころ	注意点
Bulk Request	複数のレコード操作を順番にまとめたい	失敗時のロールバック範囲を理解する
Cursor	多数のレコードを分割取得したい	取得サイズ、継続取得、終了処理を設計する
更新キー	外部IDなどで既存レコードを更新したい	一意性、変更不可のルールを決める

Bulk Request APIでは、複数APIリクエストを順番に実行できます。

公式ドキュメントでは、1回に含められるリクエスト数の上限や、いずれかのAPIが失敗した場合にすべての操作がロールバックされることが説明されています。

Kintone Developer Program：Bulk Request

Cursor APIは、多数のレコードをまとめて取得するときに使います。

公式ドキュメントでは、カーソルから1回で取得できる件数上限などが説明されています。

Kintone Developer Program：Create Cursor

更新キーは、外部IDや顧客番号で既存レコードを更新したいときに重要です。

Update Records APIでは、updateKeyを指定して更新する方法が説明されています。

Kintone Developer Program：Update Records

ただし、これらは魔法の道具ではありません。

Bulk Requestを使っても、業務上の正本や更新順が曖昧なら誤更新は防げません。

Cursorを使っても、毎回全件取得する設計なら処理時間は増え続けます。

更新キーを使っても、そのキーが後から変わる項目なら突合は壊れます。

設計では、次を決めます。

項目	決めること
Bulk Request	どの操作を同じ単位として扱うか
Cursor	何件ずつ取得し、どこまで取得したかをどう残すか
更新キー	外部ID、顧客番号、注文番号など、変わらないキーを使えるか
再実行	失敗時に同じキーで重複せず再送できるか

保守体制と監視ログ

kintone API連携は、作って終わりではありません。

外部SaaSの仕様変更、APIトークンの更新、項目追加、業務フロー変更、担当者変更に追従する必要があります。

保守で必要なのは、処理ログと責任者です。

ログ項目	残す理由
処理ID	1回の連携処理を追うため
実行日時	いつ起きたかを確認するため
起点	手動、Webhook、バッチ、画面操作のどれか
対象アプリ	どのkintoneアプリかを特定するため
レコードID	kintone側の対象を確認するため
外部ID	外部SaaS側の対象を確認するため
件数	何件処理したかを見るため
結果	成功、保留、失敗を分けるため
エラーコード	原因分類に使うため
再実行可否	手動で戻せるかを判断するため

ログは、開発者だけが読むものにしない方がよいです。

業務担当者が見る連携ログアプリをkintone側に用意し、失敗分だけを絞り込めるようにします。

たとえば、次のような状態を持たせます。

状態	意味
送信待ち	対象だがまだ処理していない
送信中	外部へ処理中
送信済み	正常に連携できた
保留	入力不備や確認待ち
失敗	外部エラーや認証エラー
再実行済み	失敗後に再処理した

保守担当も決めます。

役割	担当すること
業務責任者	正本、承認条件、送信条件を決める
kintone管理者	アプリ、権限、APIトークンを管理する
開発/保守担当	連携処理、ログ、エラー通知を管理する
外部SaaS管理者	外部側の項目、権限、仕様変更を管理する

この役割分担がないと、障害時に「誰が直すのか」が曖昧になります。

kintoneバックアップ設計はこちら

よくある失敗

kintone API連携でよくある失敗を、設計観点で整理します。

失敗	原因	対策
同じ顧客が重複する	更新キーがない	外部IDや顧客番号を一意キーにする
古い値で上書きされる	正本と同期方向が曖昧	項目ごとに正本を決める
APIトークンの権限が広い	最初に動かすことを優先した	読取/登録/更新/削除を分ける
画面が遅い	JavaScript APIで毎回大量取得	キャッシュ、条件絞り込み、サーバー処理へ移す
Webhookが二重処理する	冪等性の設計がない	外部ID、処理ID、受付済み判定を持つ
バッチが止まる	全件取得と一括処理	差分、分割、途中再開を入れる
障害対応できない	ログが通知文だけ	連携ログアプリと再実行ボタンを用意する
外部項目変更で壊れる	マッピング管理がない	項目対応表と検証環境を持つ

特に危ないのは、API連携を「裏側の処理」として扱いすぎることです。

業務担当者から見ると、API連携も業務フローの一部です。

どの状態で外部へ送られるのか。

送られなかったとき、どこで止まっているのか。

再送してよいのか。

外部側の番号はどこで確認できるのか。

これらが画面上で追えないと、API連携は属人的なブラックボックスになります。

実装前チェックリスト

kintone API連携を作る前に、次を確認します。

チェック	確認内容
目的	入力、出力、同期、通知、集計のどれか
対象	どのkintoneアプリと外部システムをつなぐか
正本	項目ごとにどちらの値を正式にするか
更新キー	外部ID、顧客番号、注文番号など一意キーがあるか
状態条件	承認済み、送信待ち、締め前後などの条件
認証	APIトークン、OAuth、ユーザー権限のどれを使うか
権限	読取、登録、更新、削除を必要最小限にしているか
実行方法	即時、Webhook、定期バッチ、手動のどれか
API制限	件数、同時実行、日次リクエスト数を見積もったか
エラー	認証、権限、データ不備、外部障害を分けるか
ログ	レコードID、外部ID、件数、結果、エラーを残すか
再実行	失敗分だけ重複なく再実行できるか
保守	仕様変更、トークン更新、担当交代の手順があるか

チェックリストの中で、特に重要なのは更新キーと再実行です。

API連携は、一度で必ず成功する前提にしない方がよいです。

外部SaaSは止まることがあります。

ネットワークも失敗します。

項目変更も起きます。

そのため、失敗しても、どのデータをどこから再開するかを決めておきます。

Bitlightに相談できること

Bitlightでは、kintone API連携を、単なる実装ではなく業務設計から支援します。

たとえば、次のような相談に対応できます。

• kintoneと外部SaaS・基幹システムの正本整理
• APIトークン、OAuth、Webhook、REST API、JavaScript APIの使い分け設計
• 顧客、案件、請求、在庫、対応履歴の更新キー設計
• Webhook、キュー、バッチ、手動再実行を組み合わせた連携構成
• API制限を前提にした差分同期、分割処理、リトライ設計
• 連携ログアプリ、エラー通知、再実行画面の設計
• Power Automate、iPaaS、個別API開発の切り分け
• 既存のkintone連携が止まる、重い、追えない状態の見直し

kintone API連携で大事なのは、「APIでつながるか」ではありません。

つないだ後に、業務担当者が何を見て判断し、失敗時にどこから戻せるかです。

kintone API連携は、正本、認証、更新キー、ログ、再実行まで設計して初めて、業務システムとして使い続けられます。