kintoneのJavaScriptカスタマイズとAPI連携

JavaScriptを書くかどうかは、技術の問題ではなく保守の問題です。1行書いた瞬間に、「これを直せる人を、この先ずっと抱え続ける」という約束が発生します。 だから判断は「書けるか」ではなく、「書いたものを、3年後に誰が直すか」から始めます。ここが決まっていない案件では、当社は書きません。 この章は、書く前に通す問いを順番に並べ、書くと決めたあとに範囲をできるだけ狭めるための章です。

この章で分かること

• JavaScriptを書くべき場面・書かないほうがよい場面の分かれ目（標準 → プラグイン → JS の順に潰す手順）
• 公式APIの範囲で書くとはどういうことか。画面のHTMLに触ると何が起きるか
• 外部連携をCSVから順に広げる段取りと、APIトークン・Webhookの使い分け、閉域網で使える条件

書く前に、3つだけ先に決める

コードの話に入る前に、決まっていないと着手してはいけないものが3つあります。

1. 保守する人——社内の誰か、または契約している会社の誰か。「作った人」ではなく「来年も連絡が取れる人」で書きます
2. ソースコードの置き場所——自社の共有フォルダかGitに置きます。kintoneにアップロードしたファイルだけが唯一の原本、という状態にしない
3. 何をしているかの1行説明——「受注アプリの保存時に、納期が受注日より前ならエラーを出す」。これが書けないものは、書いた本人以外に直せません

×のまま書き始めたカスタマイズは、数年後に「誰も触れない箇所」として残ります。 引き継ぎの相談で最初に詰まるのはここで、「このJSが何をしているか分からないので、アプリを直せない」という形で出てきます。

標準 → プラグイン → JS の順に潰す

相談を受けたとき、当社が通す順番は毎回同じです。上から順に潰して、残ったものだけをJavaScriptで書きます。

順	手段	費用と保守	判断の基準
1	標準機能	追加費用なし・保守不要	計算フィールド・条件通知・プロセス管理・権限で足りないか
2	運用ルール	費用なし	月1件以下の例外なら、備考欄と運用で吸収できないか（5章）
3	プラグイン	設定だけ。作った人が辞めても動く	設定画面で完結するか（12章）
4	JavaScript	書いた人・直せる人が要る	上の3つで解けないものだけ
5	外部サービス＋API	サーバー代・監視・障害対応が増える	kintoneの外にデータを出す必要が本当にあるか

順番を飛ばすと、あとから戻れません。プラグインで済むものをJavaScriptで書いてしまうと、設定を変えるだけの改修にも毎回コードを触る人が要ります。

当社の見本3業種・18アプリは、無料プラグイン23本と標準機能だけで作っていて、JavaScriptは1行も書いていません。自動採番（SO-FY2026-0001）、期限の残日数、条件付き必須、条件付き入力禁止、重複チェック、期間の重なり警告、行番号、和暦表示、条件書式——現場でよく出る要望のほとんどは、ここで止まります。

逆に、4番まで落ちてくるのは次のようなものです。

JSまで落ちてくる典型	なぜプラグインで解けないか
自社独自の計算（社内の料金表・按分のルール）	会社ごとに式が違い、設定項目にできない
他アプリのデータを読んで保存前に判定する	「在庫が足りなければ保存させない」など、業務固有の条件
帳票のレイアウトが決まっている（指定様式）	様式が1社ごとに違う
外部サービスとのリアルタイム連携	相手の仕様に合わせる必要がある
一覧画面への独自ボタン・独自画面	画面そのものを足す要件

この5つに当てはまらない要望が来たら、標準とプラグインに戻ってください。 何でもできる道具を選んだ時点で、保守の負担も何でも背負うことになります。

公式APIの範囲で書く（DOMに触らない理由）

kintoneのカスタマイズはイベント駆動型で、「レコード追加画面を開いたとき」「保存するとき」といった場面にだけ処理を差し込みます。使うイベントは、実務ではこの6つでほぼ足ります。

イベント	いつ動くか
app.record.create.show	レコード追加画面を開いたとき
app.record.edit.show	レコード編集画面を開いたとき
app.record.create.submit	追加したレコードを保存するとき
app.record.edit.submit	編集したレコードを保存するとき
app.record.detail.show	詳細画面を開いたとき
app.record.index.show	一覧画面を開いたとき

保存を止めるなら submit のイベントで、止めたい項目の error に日本語のメッセージを入れます。これだけで保存が止まり、その項目の下にメッセージが出ます。

kintone.events.on('app.record.create.submit', (event) => {
  const record = event.record;
  if (Number(record['金額'].value) <= 0) {
    record['金額'].error = '金額は1以上で入力してください';
  }
  return event;
});

置き方は、アプリの設定 →「JavaScript / CSSでカスタマイズ」でファイルをアップロードし、「アプリを更新」を押すまでです。押すまで現場には反映されません（15章の変更手順の4番と同じです）。

問題は、公式が用意した入口の外に出るかどうかです。kintoneの画面はHTMLなので、その気になれば「クラス名 xxx の要素を探して書き換える」ことができます。それをやった瞬間に、そのカスタマイズは画面刷新で壊れる予約をしたことになります。 クラス名や構造は、サイボウズが自由に変えてよい場所だからです。しかも壊れ方が悪く、エラーは出ず静かに動かなくなります。入力チェックが効かなくなったことに、誰も気づきません。

当社は無料プラグイン23本をこの制約の中だけで書いています。開発ルールの1条めがこれです。

公式 API だけを使う：kintone.events.on、kintone.app.record.get/set、kintone.app.record.setFieldShown、kintone.app.getHeaderMenuSpaceElement など。kintone の画面の HTML（クラス名・DOM 構造）を直接読んだり書き換えたりしない（kintone の画面刷新で壊れる）。自前の要素を置く場合は、公式のスペース要素（ヘッダーメニュー・スペースフィールド）の中にだけ置く

この線を守ると、できないことが出ます。 条件書式は、サブテーブルの中のセルに色を付けられません。公式APIでテーブル内のセルの要素を取れないからです。DOMをたどれば実装できますが、やっていません。「今できること」より「来年も動いていること」を選んだ結果で、この判断をしているかどうかが、カスタマイズを発注するときに見るべき一番の点です。

何をしたいか	公式APIの範囲でできるか	書き方
保存を止めてエラーを出す	できる	submit イベントで、対象フィールドに error を入れる
値を自動で入れる・計算する	できる	change.<フィールドコード> イベントで record の値を書き換える
項目を出し分ける	できる	setFieldShown（※隠しても値は保存される。7章・10章）
一覧にボタンを足す	できる	kintone.app.getHeaderMenuSpaceElement() の中にだけ自前の要素を置く
詳細画面に表や図を足す	できる	スペースフィールドを先にアプリに置き、その中に入れる
テーブルのセルの色を変える	できない	色を付けたい値を親のフィールドに出し、そちらに条件書式をかける
標準のボタン・メニューを消す	できない（DOM操作になる）	権限で操作させない（10章）に置き換える
画面の配置を作り替える	できない（DOM操作になる）	フォームの配置・グループ・一覧の設計で近づける

下の3行が、「JSを書いても、やってはいけない」領域です。発注側は、見積の段階で「標準のUIをHTMLレベルで書き換えますか」と1問だけ聞けば見分けられます。

書くと決めたら、範囲を狭める

書く量を減らすほど、保守の負担は下がります。当社がプラグインで守っている決めごとのうち、受託のカスタマイズにもそのまま当てはまるのは次の4つです。1ファイル1目的にする／判定・計算はkintoneに依存しない関数に切り出してテストを書く（当社は core.js に集め、空欄・0・月末・うるう年・全角半角・大量データの境界を必ず入れます）／エラーでkintoneを止めない（設定が壊れていたら何もしない。APIが失敗したとき保存を止めるか通すかを先に決める）／エラー文は日本語で、何が起きたか・どうすればいいかを書く。

もう1つ、PCとスマホは別物です。レコード画面のイベントは PC（app.record...）とモバイル（mobile.app.record...）で別に登録するので、片方だけ書けば、もう片方では何も起きません。 当社の無料プラグインも0.1.0時点ではPCのみでモバイル未対応です。

そしてkintoneには本番と別のテスト環境がありません。 JavaScriptの入れ替えは影響範囲が読みにくいので、アプリをコピーして、コピー側で試してから本番に入れるのが実務的な回避策です。ソースを自社に保管していれば前の版に戻せます（していなければ、戻せません）。

外部連携は、CSVから始める

「基幹システムとつなぎたい」「会計ソフトと連携したい」という相談では、いきなりAPIの話にしません。連携には段階があり、下の段で運用が回るなら、上に上がる必要がないからです。

段	形	増える手間	向く場面
0	つながない（両方に入力する）	二重入力	件数が月に数件
1	CSVで書き出し・取り込み	人が月1回流す	まずここで1〜3か月回す
2	ノーコード連携ツール	月額と、つなぎ目の管理	相手側にもコネクタがある（Zapier・Make など汎用のもの、kintone専用の連携サービス。無料枠のあるものから月1万円台まで。価格は変わるので提供元で確認）
3	APIトークンで、こちらから取りに行く／入れに行く	スクリプトの保守・実行環境	定期的な同期
4	Webhookで、変わった瞬間に外へ知らせる	受け側のサーバーの運用・監視・障害対応	即時性が要る

段を上げるごとに、止まったときに直せる人が必要になります。 特に4は、受け側のサーバーが落ちていたときに通知が消えるので、失敗の記録と再送の仕組みまで作らないと「たまに連携されない」が起きます。

当社が「まずCSVで」と言うのは値切っているのではなく、CSVで数か月回すと、連携すべき項目が目に見えて減るからです。減ってから作るほうが、作る量も保守の量も小さくなります。見本3業種でも、外部システム（ポータルサイト、原価管理・会計ソフト、専用の生産管理システム）との関係はCSVでの受け渡しを基本としてご案内しています。

つなぐ相手がLINE公式アカウントの場合、この章を読む前に決めておくことがあります。項目ごとの正本をどちらに置くか、LINE側から何を渡すか（友だちの識別子・経路・受付ステータス）、その値にどんな性質があるか（識別子はアカウント単位でしか通用しない、友だち解除は業務側に伝わらない）です。LINEナーチャリングの教科書10章にまとめてあります。受け皿の形が決まっていないところに、自動で流し込むことはできません。

APIトークンとWebhookの使い分け

この2つは、よく同じ話として語られますが、向きが逆です。

	APIトークン（REST API）	Webhook
向き	外 → kintone（取りに行く・入れに行く）	kintone → 外（変わったことを知らせる）
きっかけ	こちらのプログラムが動いたとき	レコードの追加・編集・削除・コメントのとき
送られる中身	欲しいものを指定して取る	変更の通知（受け側でAPIを叩いて取りに行くのが基本）
向くもの	夜間の一括同期、外部フォームからの登録、集計の取り出し	Slack通知、即時の連携、他システムへの反映
要るもの	トークンと、実行する場所（サーバー等）	受け取るサーバーが必ず要る
失敗したとき	呼んだ側で気づける	気づけない。記録と再送を自分で作る

認証は3方式あり、用途で選びます。APIトークンはアプリごとに発行する手軽な方式、パスワード認証はそのユーザーの権限で操作する方式、OAuthはセキュリティが最も高い方式です。

APIトークンで最も多い事故は、権限を全部付けたトークンを作って、そのまま使い続けることです。トークンは「閲覧のみ」「追加のみ」のように権限を選べます。CSVを取り出すだけの用途に、削除の権限が付いたトークンを渡してはいけません。 トークンの一覧（どのアプリの・どの権限の・何に使うか）は、引き継ぎ資料に必ず入れます（15章）。

よく出るエラーは3つに集中します。403 はトークンの権限不足、520 は呼び出し回数の制限（レートリミット）超過でリクエストの間隔を空けるか一括処理用のAPIを使う、データの不整合は同時更新の競合でリビジョン番号を使って防ぎます。

件数の扱いにも決まりがあります。当社は一覧の全件処理は500件ずつ $id の昇順で取り、一括更新は100件ずつにしています（offset には10,000件の上限があり、ページをずらす方式では途中で取れなくなるため）。「全件取って更新する」スクリプトは、データが1万件を超えた日に静かに壊れます。

なお、APIもJavaScriptカスタマイズもプラグインも、スタンダードコース以上です。ライトコースでは設定できません（2章）。

閉域網（LGWAN）で使えるかは、「通信するか」で決まる

自治体・医療・金融では、インターネットに出られない閉域網から使う前提が入ります。判断の基準は1つだけです。

そのコードが、kintone以外のサーバーと通信するかどうか。

通信しなければ閉域網でも動きます。通信するものには外部API・地図・フォントのほか、CDNから読み込むライブラリが含まれます。ここが見落とされます。「グラフを描きたいのでJavaScriptライブラリをCDNから読む」は立派な外部通信で、動作確認をインターネット環境でやっていると気づかず、本番の閉域網で画面が真っ白になります。 ライブラリが要る場合は、CDNではなくファイルとしてkintoneにアップロードします（ライセンスの確認も要ります）。

当社の無料プラグイン23本はCDNのライブラリも読まない方針で作っているため、閉域網でもそのまま動きます。自社で書くコードにも同じ基準を当ててください。

AIにコードを書かせるときの注意

当社はAIでコードを書きます。速く正確になりますが、AIを使うと増えるリスクがあり、そこは人が受け持ちます。

1. 「動いた」と「正しい」は別。 AIは言われた条件のコードを書きますが、業務としてその条件でよいかは判断しません。 「完了なら編集不可」を頼むと、差し戻したときに編集できないコードが出てきます
2. DOM操作を平気で提案してくる。 学習元にはDOMをたどる古いサンプルが大量にあります。「公式APIの範囲だけで書いて。画面のHTMLには触らないで」を毎回指示に入れます
3. データを壊す操作は、件数を絞って試す。 一括更新・削除は、まずテスト用のアプリで、次に本番の数件で。いきなり全件に流さない
4. テストは短縮されない。 設計とコード生成は速くなりますが、動作確認は人が画面を触る必要があります（→AIでkintoneアプリを爆速構築する方法）
5. 読めないコードを納品しない。 AIが書いたものでも、1行説明と判定部分のテストは残します。書いた主体がAIでも、約束（誰が直すか）は変わりません

よくある間違いを5つ

1. プラグインで済むことをJavaScriptで書く——重複チェック、条件付き必須、採番、残日数の表示。よくある要件ほど、すでに設定だけで済む形になっています。 → 直し方：着手前に無料プラグインの一覧と標準機能を当たります。設定で済ませたものは、作った人が辞めても動き続けます。

2. 画面のHTMLを直接書き換える——今日は動きます。kintoneの画面が新しくなった日に、エラーも出さずに止まります。 → 直し方：公式のイベントAPIと、公式のスペース要素（ヘッダーメニュー・スペースフィールド）の中だけで作ります。それでできないことは、権限・一覧・フォームの設計で近づけます。

3. ソースコードがkintoneの中にしかない——アップロードしたファイルが唯一の原本という状態です。書いた会社との契約が切れたら、中身が読めても直せる人がいません。 → 直し方：ソースは自社の共有フォルダかGitに置く。納品物に含まれるかを契約前に確認します（3章の見積チェック）。あわせて「何をしているか」の1行説明を添えます。

4. APIトークンに全権限を付けて使い回す——取り出すだけの用途に削除権限が付いていると、スクリプトの1行の間違いでレコードが消えます。しかも誰の操作か追いにくい。 → 直し方：用途ごとにトークンを分け、権限は必要最小限にします。トークンの一覧を引き継ぎ資料に入れ、使わなくなったら消します。

5. スマホで確認していない——PCのイベントだけ書いて「完成」にすると、現場がスマホで開いたときに入力チェックが一切効きません。しかもエラーは出ないので、チェックが効いていると思ったまま運用が進みます。 → 直し方：現場がスマホで入力する業務なら、実機で1件登録して確かめます。 モバイルで動かないなら、その分の守りはサーバー側（必須・重複禁止）か運用に置き直します（7章）。

費用について

JavaScriptカスタマイズ・REST API・Webhookは、いずれもkintoneの標準の機能で、利用そのものに追加費用はかかりません（スタンダードコース以上が条件です）。費用が発生するのは、書く人の工数と、外部連携で必要になるサーバー・連携ツールの月額、そして保守です。見積では「開発」と「保守の範囲」が別項目になっているかを見ます（3章）。

当社の無料プラグイン23本は、無料・MITライセンス・会員登録不要で、外部と通信しません。当社との契約が終わってもそのまま使い続けられます。

kintoneのライセンス料はスタンダードコース 1ユーザー月1,800円（税抜）・最小10ユーザーでサイボウズ社とのご契約、当社の構築は1業務1アプリまで最大1か月0円、使うと決めていただいた段階で月5万円から（最低12ヶ月）です。

この章の出口

ここまでで、書くか書かないかの順番（標準 → 運用 → プラグイン → JS → 外部連携）、書くときの範囲（公式APIの中だけ）、つなぐときの段取り（CSVから）、そして保守の約束（誰が直すか・ソースはどこか）が決まりました。

ここまでの13章は、どの業種にも当てはまる判断を並べてきました。残っているのは「では自社の業種では、どのアプリから作るのか」です。業種ごとに、先に作るべき台帳とその次に足す記録の型があります。次の章では、当社が実際に作った不動産・建設・製造の6アプリ構成と、自治体での進め方を、そのまま型として示します。

次の章へ：14章 kintoneの業種別の型（不動産・建設・製造・自治体）