kintone CSVインポートの設計方法｜文字コード・更新キー・添付ファイルまで

kintoneへCSVをインポートする作業は、最初は簡単に見えます。

Excelや外部システムからCSVを出す。

kintoneのファイル読み込み画面で、アプリの項目に合わせる。

読み込みボタンを押す。

これだけで登録できるデータもあります。

しかし、実務で問題になるのは、操作そのものではありません。

顧客番号の先頭ゼロが消える。

日付形式がアプリと合わない。

金額にカンマや通貨記号が混ざる。

外部CSVの列名が毎回少し変わる。

更新キーがなく、同じ顧客や案件が重複登録される。

新規登録と既存更新が混ざり、どのレコードが変わったか追えない。

添付ファイルも一緒に入ると思っていたが、標準のファイル読み込みでは扱えない。

読み込みエラーを修正した担当者しか、次回の直し方が分からない。

承認済み、請求済み、締結済みのレコードまで上書きしてしまう。

CSVインポートは、単なるデータ投入ではありません。

外部から入ってくるデータを、kintoneのアプリ構造、権限、業務状態、証跡に合わせて受け入れる作業です。

kintone CSVインポートで最初に決めるべきなのは、読み込み手順ではなく、「どのCSVを、どのキーで、どの範囲へ、どの検証後に入れるか」です。

この記事では、kintone CSVインポートを、文字コード、更新キー、新規登録と更新の分離、項目マッピング、先頭ゼロ、日付、数値、添付ファイル、検証環境、エラー再取込、定期取込まで含めて設計する方法を整理します。

kintone一括更新の設計方法はこちら
kintoneバックアップの設計方法はこちら
kintone添付ファイルの設計方法はこちら

CSVインポートはデータ入口の設計

CSVインポートで最初に見るべきものは、CSVファイルではありません。

そのCSVが、どの業務イベントから出ているかです。

CSVの発生元	典型例	kintone側で決めること
基幹システム	顧客、商品、受注、請求	外部ID、更新キー、差分取込
Excel管理表	案件一覧、対応履歴、台帳	列名、型、必須項目、重複排除
フォーム	問い合わせ、申込、アンケート	受付番号、担当割当、重複確認
EC/予約システム	注文、在庫、来店予約	取込頻度、キャンセル、状態遷移
他部署ファイル	月次報告、棚卸、点検結果	承認済みデータとの分離

同じ「CSVインポート」でも、設計は変わります。

初回移行なら、既存レコードがないため、新規登録が中心です。

月次更新なら、既存レコードの更新と、新規追加が混ざります。

外部システムから毎日届くCSVなら、人が画面で毎回確認する前提では続きません。

棚卸や点検のCSVなら、入力ミスをそのまま本番に入れないための検証一覧が必要です。

まず、CSVの役割を分類します。

取込種別	目的	設計の重点
初回移行	旧台帳をkintoneへ移す	項目整理、重複削除、必須項目
マスタ更新	顧客、商品、部門を更新する	更新キー、重複禁止、除外条件
明細追加	受注、作業、点検結果を追加する	受付番号、取込単位、重複防止
差分反映	外部システムの変更分を入れる	差分判定、ログ、再取込
復元	更新前CSVから戻す	復元先、戻す項目、検証手順

kintoneヘルプでは、アプリに読み込みできるファイルとして、Excel、CSV、TXT、TSVが説明されています。

また、CSV/TXT/TSVは最大100MB、10万行まで、Excelは最大1MB、1,000行までという上限も示されています。

kintoneヘルプ：レコード登録・上書き用のファイルの記載形式

上限に収まっていても、すぐ本番に入れるべきとは限りません。

件数が多いほど、1行の誤りが後で見つけにくくなります。

更新が混ざるほど、どのレコードが変わったか説明しにくくなります。

添付ファイルや承認状態が絡むほど、CSVだけでは完結しにくくなります。

CSVインポートは、ファイルの入口を作るだけでなく、取込前、取込中、取込後の運用まで決めます。

インポート前に決める更新キー

既存レコードを更新する可能性があるなら、更新キーを先に決めます。

更新キーが曖昧なままCSVを読み込むと、同じ顧客、同じ案件、同じ注文が重複して増えます。

逆に、誤ったキーで更新すると、別のレコードを上書きします。

更新キー候補	向いている場面	注意点
レコード番号	kintoneから書き出したCSVを戻す	外部CSVには通常含まれない
顧客番号	顧客マスタ、取引先マスタ	先頭ゼロ、重複禁止、廃番を確認する
案件番号	案件、見積、契約	採番ルールと枝番を決める
注文番号	受注、出荷、請求	キャンセルや分納を分ける
外部システムID	基幹、EC、会計との連携	連携元でIDが変わらないか確認する
メールアドレス	会員、問い合わせ	共有アドレスや変更履歴に注意する

更新キーに求める条件は、次の通りです。

条件	見ること
重複しない	同じキーが複数行に出ない
空欄にならない	キー未設定の行を本番へ入れない
途中で変わらない	顧客名や担当者名のような変わる値をキーにしない
外部CSVに入っている	毎回人が補完しない
kintone側で確認できる	一覧や検索で照合できる

cli-kintoneのrecord importでは、--update-keyを指定すると、更新キーに一致するレコードを更新し、存在しない行は新規登録するUPSERTの動きになります。

その更新キーは、レコード番号、または「値の重複を禁止する」を有効にした文字列1行・数値フィールドが対象です。

cli-kintone：record import

REST APIで複数レコードを更新する場合も、updateKeyでフィールドコードと値を指定できます。

cybozu developer networkでは、updateKeyに指定できるフィールドは、重複禁止を設定した文字列1行または数値フィールドと説明されています。

cybozu developer network：複数のレコードを更新する

CSVインポートで更新を扱うなら、更新キーは「人が見て分かる項目」ではなく、「重複せず、空欄にならず、外部データと照合できる項目」として設計します。

更新キーを決めたら、本番取込前に次の一覧を作ります。

一覧	条件例
キー空欄一覧	顧客番号、案件番号、外部IDが空欄
キー重複一覧	同じキーが複数レコードに存在
外部CSV側の重複一覧	1つのキーが複数行に出ている
kintone未登録一覧	更新キーに一致するレコードがない
更新対象一覧	キー一致かつ更新してよい状態
除外一覧	承認済み、請求済み、締結済み、完了済み

更新キーは、記事や設計書に書いて終わりではありません。

アプリのフィールド設定、CSVテンプレート、取込手順、検証一覧、エラー修正ルールまで同じキーでそろえます。

新規登録と更新を分ける

CSVインポートでは、新規登録と更新を混ぜない方が扱いやすいです。

完全に分けられない場合でも、取込前に件数と扱いを分けて確認します。

分類	扱い	確認すること
新規登録	kintoneにない行を追加	必須項目、採番、初期ステータス
既存更新	更新キーが一致する行を更新	更新対象フィールド、除外条件
要確認	キー重複、キー空欄、形式不一致	人が修正してから再取込
除外	変更してはいけない行	承認済み、請求済み、締結済み
保留	判断材料が足りない行	担当部署へ確認

新規登録と更新を分ける理由は、失敗時の戻し方が違うからです。

新規登録を誤った場合は、登録されたレコードを削除または無効化します。

既存更新を誤った場合は、更新前の値へ戻します。

同じCSVに混ざっていると、どちらの処理をしたのか追いにくくなります。

CSVインポート前には、少なくとも次を残します。

残すもの	用途
元CSV	受領時点の証跡
整形後CSV	実際に読み込むファイル
新規登録予定一覧	追加される件数の確認
更新予定一覧	変わるレコードの確認
除外一覧	変えない理由の説明
エラー修正一覧	再取込時の差分管理
取込ログ	実行者、日時、件数、結果

CSVインポートは「成功したか」だけでなく、「新規、更新、除外、エラーがそれぞれ何件だったか」を残すと、後から説明できる作業になります。

特に、売上、契約、請求、承認が絡むアプリでは、更新と新規の混在を軽く扱わない方がよいです。

請求済みの金額を更新してよいのか。

承認済みの申請を再取込で変えてよいのか。

契約締結済みの契約先名を現時点の名称へ変えてよいのか。

この判断は、CSVの列ではなく業務ルールです。

kintone一括更新の設計方法はこちら

文字コード・日付・数値・先頭ゼロの注意点

CSVインポートでよく起きる問題は、項目マッピングより前の段階で起きます。

文字コード、日付形式、数値形式、先頭ゼロです。

項目	起きる問題	設計すること
文字コード	文字化け、機種依存文字の崩れ	UTF-8/SJISのどちらで受けるか決める
日付	2026/6/1、2026-06-01、令和表記が混ざる	取込前に形式を統一する
時刻	9:00、09:00、空欄が混ざる	必須か任意かを決める
数値	カンマ、円記号、小数、空欄が混ざる	数値フィールドへ入れる前に整形する
先頭ゼロ	顧客番号、郵便番号、電話番号が壊れる	文字列として扱う項目を決める
改行	住所、備考、複数選択が崩れる	セル内改行と区切り方を検証する
空欄	既存値を空で上書きする	空欄上書きしてよい項目を分ける

cli-kintoneのrecord importでは、--encodingで文字エンコーディングを指定でき、デフォルトはutf8、指定できる値としてutf8とsjisが示されています。

cli-kintone：record import

画面からのファイル読み込みでも、CSVの作り方が曖昧だと同じ問題が起きます。

外部システムはSJISでCSVを出す。

GoogleスプレッドシートはUTF-8でCSVを出す。

Excelで開いて保存すると、値の見え方が変わる。

このような違いを作業者の勘に任せると、毎回の確認が属人化します。

先頭ゼロは特に重要です。

顧客番号、商品コード、郵便番号、電話番号、部署コードなどは、数値ではなくコードです。

計算しない項目なら、kintone側も文字列1行として持つ方が安定します。

項目例	推奨しやすい型	理由
顧客番号	文字列1行	先頭ゼロ、枝番、英字を保持する
商品コード	文字列1行	JAN以外の社内コードも扱う
郵便番号	文字列1行	先頭ゼロを保持する
電話番号	文字列1行	ハイフン、国番号、先頭ゼロを保持する
金額	数値	集計や計算に使う
数量	数値	合計や比較に使う
日付	日付	絞り込みや期限管理に使う

日付も同じです。

画面では読める日付でも、CSVでは形式が揺れます。

「2026/6/1」と「2026-06-01」と「2026年6月1日」が混ざると、取込前の確認が難しくなります。

CSVテンプレートには、入力例ではなく、取り込める形式を明記します。

項目マッピングとテンプレート化

CSVインポートを毎回つらくする原因は、項目マッピングが手作業になることです。

外部CSVの列名とkintoneのフィールド名が違う。

列の順番が変わる。

使わない列が混ざる。

人によって列名の表記が違う。

同じ列でも、ある月だけ値の意味が変わる。

この状態で毎回読み込み画面に進むと、作業者が列の意味を判断することになります。

先にマッピング表を作ります。

外部CSV列	kintoneフィールド	型	必須	変換ルール	備考
customer_id	顧客番号	文字列1行	必須	前後空白を削除	更新キー
customer_name	顧客名	文字列1行	必須	全角半角は変えない	正式名称
order_date	受注日	日付	必須	YYYY-MM-DDへ統一	空欄不可
amount	金額	数値	任意	カンマと円記号を削除	税込/税抜を明記
owner_email	担当者	ユーザー選択	任意	ログイン名へ変換	未登録ユーザーはエラー
note	備考	文字列複数行	任意	改行を保持	長文確認

マッピング表には、列名だけでなく、変換ルールとエラー時の扱いを書きます。

エラー	扱い
必須列がない	取込しない
更新キーが空欄	エラー一覧へ回す
更新キーが重複	人が確認する
担当者が存在しない	取込前にユーザーへ変換する
金額が文字列	記号を削除して数値化する
日付が不正	元CSVへ戻して修正する
選択肢にない値	選択肢を追加するか、値を変換する

kintoneヘルプでは、読み込みできないフィールドとして、ラベル、計算、添付ファイル、関連レコード一覧、レコード番号が示されています。

kintoneヘルプ：レコード登録・上書き用のファイルの記載形式

つまり、CSVに列を用意すれば何でも入るわけではありません。

計算フィールドは、元データを入れるのではなく、kintone側の計算式で表示します。

関連レコード一覧は、取り込む対象ではなく、別アプリのレコードを参照する設計です。

レコード番号は、既存レコードと照合する用途では重要ですが、通常の新規登録で任意の番号を入れる項目ではありません。

添付ファイルは、次の章のように別で考えます。

CSVテンプレートは、列名の一覧ではなく、フィールド型、必須条件、変換ルール、エラー時の扱いまで含めた取込仕様として管理します。

添付ファイルを含む取込

CSVインポートで誤解が起きやすいのが、添付ファイルです。

標準のファイル読み込みでは、添付ファイルフィールドへ値を読み込めないとkintoneヘルプに示されています。

kintoneヘルプ：レコード登録・上書き用のファイルの記載形式

そのため、CSVにファイル名やパスを書けば、標準画面から自動で添付される、とは考えない方がよいです。

添付ファイルを含む取込は、別の設計に分けます。

方針	向いているケース	注意点
CSVとは別に手動添付	初回件数が少ない	添付漏れ、担当者負荷
ファイル管理アプリに分ける	契約書、請求書、写真が多い	業務レコードとの紐づけが必要
cli-kintoneで添付込み取込	定型CSVとファイル群をまとめて入れる	実行環境、パス、ログが必要
REST APIでアップロード	外部システムから自動連携	fileKey、権限、再実行が必要
外部ストレージ連携	大容量、共同編集、長期保管	URL管理、アクセス権、削除方針

cli-kintoneのrecord importでは、添付フィールドを含むレコードをインポートする場合に--attachments-dirを使う説明があります。

CSV内のローカルファイルパスは、指定した添付ファイルディレクトリからの相対パスとして扱われます。

cli-kintone：record import

REST APIで添付ファイルを扱う場合は、先にファイルアップロードAPIで一時保管領域へアップロードし、レスポンスとして取得したfileKeyを添付ファイルフィールドの値として使います。

cybozu developer network：ファイルをアップロードする

この設計で重要なのは、CSV本体とファイル本体を同じ作業として見ないことです。

CSV行は成功したが、添付ファイルだけ失敗した。

添付ファイルはアップロードできたが、レコード更新に失敗した。

同じファイル名が複数あり、別のレコードに紐づいた。

日本語ファイル名や空白を含むパスで失敗した。

添付済みファイルを再取込で上書きしてよいか分からない。

こうした問題に備えて、添付ファイル取込には専用のログを持ちます。

ログ項目	内容
取込ID	CSV取込と添付処理を紐づける
更新キー	どのレコードへ添付したか
ファイル名	元ファイル名
ファイルパス	取込元の保存場所
fileKey	API利用時の処理結果
処理結果	成功、失敗、再実行待ち
エラー内容	権限、容量、パス、拡張子など

kintone添付ファイルの設計方法はこちら

検証環境・エラー対応・取込ログ

CSVインポートは、本番で初めて試す作業ではありません。

特に、既存レコードの更新、添付ファイル、承認済みデータ、金額、請求、契約が絡む場合は、検証環境を作ります。

検証対象	確認すること
件数	元CSV、整形後CSV、kintone取込後の件数が合う
更新キー	想定したレコードだけ更新される
新規登録	追加される件数が想定通り
除外条件	承認済み、請求済み、締結済みが変わらない
文字コード	文字化けがない
先頭ゼロ	顧客番号、郵便番号、電話番号が保持される
日付	絞り込みや期限計算に使える
数値	合計、税区分、数量が崩れない
選択肢	存在しない選択肢で止まらない
ユーザー	ログイン名、退職者、ゲストの扱いが正しい
添付	ファイル名、紐づけ、閲覧権限が正しい

エラー対応も、現場任せにしない方がよいです。

CSV読み込みに失敗したとき、作業者がその場でExcelを開いて直すと、元CSV、修正CSV、再取込CSVの区別が崩れます。

取込前に、エラー一覧を持ちます。

ステータス	意味	次の処理
未確認	まだ原因を見ていない	担当者が確認
CSV修正	元データの形式が悪い	整形ルールへ反映
アプリ修正	選択肢やフィールド設定が足りない	アプリ設定を変更
業務確認	更新してよいか判断が必要	担当部署へ確認
再取込待ち	修正済み	再取込対象へ入れる
完了	取込済み	ログへ残す

取込ログは、最低限次を残します。

項目	内容
取込ID	作業単位の番号
対象アプリ	kintoneアプリ名、アプリID
元CSV	受領ファイル名、保存先
整形後CSV	実際に読み込んだファイル
実行者	作業者、APIトークン管理者
実行日時	取込開始、完了
新規件数	追加された件数
更新件数	更新された件数
除外件数	更新しなかった件数
エラー件数	再取込対象の件数
戻し方	更新前CSV、復元先、差分修正

このログは、トラブル対応だけでなく、次回の取込設計にも使います。

毎回同じ列でエラーになるなら、CSVテンプレートを直す。

毎回同じユーザー変換で止まるなら、変換表を用意する。

毎回同じ選択肢が不足するなら、マスタ管理を見直す。

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

定期取込を自動化する判断

CSVインポートが月1回だけなら、管理者が手動で検証して読み込む運用でも成立します。

しかし、頻度が上がると、手動運用は崩れます。

状態	判断
年数回の棚卸	標準画面からの手動取込でよいことが多い
月次のマスタ更新	テンプレート、検証一覧、ログを固定する
週次の外部CSV	cli-kintoneやバッチを検討する
日次の受注取込	API連携、失敗ログ、再実行を設計する
リアルタイムに近い更新	CSVではなく直接連携を検討する

自動化の判断で見るのは、件数だけではありません。

頻度。

失敗時の影響。

更新対象の業務リスク。

人が判断すべき行の割合。

再取込の難しさ。

添付ファイルや権限の有無。

API制限や処理時間。

これらを見て決めます。

自動化する場合でも、人の確認をゼロにする必要はありません。

むしろ、次のように分けます。

処理	自動化しやすい	人が確認すべき
文字コード変換	しやすい	文字化けの初回確認
列名変換	しやすい	新しい列が出たとき
更新キー照合	しやすい	重複、空欄、未登録
数値/日付整形	しやすい	形式が想定外のとき
新規/更新分離	しやすい	重要レコードの更新判断
添付ファイル処理	条件次第	紐づけ不明、失敗ファイル
本番反映	条件次第	金額、契約、承認済みデータ

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

よくある失敗

kintone CSVインポートでよくある失敗を整理します。

失敗	原因	対策
文字化けする	文字コードが決まっていない	UTF-8/SJISを取込仕様に書く
先頭ゼロが消える	コードを数値として扱った	文字列1行で持つ
重複レコードが増える	更新キーがない	重複禁止フィールドを設計する
別レコードを上書きする	キーの意味が曖昧	外部IDや採番ルールを固定する
空欄で上書きする	空欄の扱いを決めていない	空欄許可項目と禁止項目を分ける
選択肢で止まる	CSVの値が選択肢にない	値変換表を作る
ユーザー選択で止まる	氏名とログイン名が混ざる	ログイン名へ変換する
添付ファイルが入らない	標準取込で扱えると誤解した	添付処理を別設計にする
戻せない	更新前CSVがない	取込前バックアップを残す
次回も同じエラーが出る	修正ルールが残っていない	エラー一覧と変換表を更新する

多くの失敗は、kintoneの操作ミスというより、取込仕様がないことから起きます。

CSVを受け取る前に、受け入れる形式を決める。

読み込む前に、整形と検証を通す。

本番反映前に、更新対象と除外対象を確認する。

失敗後に、同じエラーを次回に残さない。

この流れを作ると、CSVインポートは毎回のイベントではなく、運用できる業務手順になります。

実装前チェックリスト

kintone CSVインポートを設計する前に、次を確認します。

チェック	確認内容
取込目的	初回移行、マスタ更新、明細追加、復元のどれか
元CSV	発生元、担当部署、出力条件、保存先
文字コード	UTF-8/SJIS、Excel経由の有無
更新キー	重複禁止、空欄禁止、外部CSVとの照合
新規/更新	件数を分けて確認できるか
除外条件	承認済み、請求済み、締結済み、完了済み
項目マッピング	外部列、kintoneフィールド、型、変換ルール
先頭ゼロ	コード、郵便番号、電話番号を文字列で扱うか
日付/数値	形式、通貨記号、カンマ、小数
添付ファイル	標準取込とは別に扱うか
検証環境	本番前に試すアプリや一覧があるか
取込ログ	実行者、日時、件数、エラー、再取込
戻し方	更新前CSV、復元先、差分修正
定期化	手動、cli-kintone、API、プラグインの判断

このチェックリストを埋めると、単発のCSVインポートでも、後から説明しやすくなります。

定期的に同じCSVを取り込む場合は、この内容をそのまま運用手順書にします。

CSVの列が変わったとき、どこを更新するのか。

外部システムのIDが変わったとき、どう扱うのか。

エラーが出たとき、誰が確認するのか。

本番反映前に、誰が承認するのか。

ここまで決めると、CSVインポートは担当者依存の作業ではなくなります。

Bitlightに相談できること

Bitlightでは、kintone CSVインポートを、単なる読み込み作業ではなく、業務データの入口として設計します。

たとえば、次のような整理を支援できます。

• 元CSVの発生元、出力条件、担当部署の整理
• 更新キー、重複禁止フィールド、外部IDの設計
• 新規登録、既存更新、除外、要確認の分離
• 文字コード、日付、数値、先頭ゼロの変換ルール作成
• 項目マッピング表とCSVテンプレートの作成
• 添付ファイルを含む取込方式の設計
• 検証用アプリ、確認一覧、エラー一覧の作成
• 更新前バックアップと戻し方の設計
• cli-kintoneやREST APIを使う定期取込の実装
• 取込ログアプリ、再取込フロー、運用手順書の整備

kintoneへのCSVインポートは、1回だけなら手作業で乗り切れることがあります。

しかし、業務で繰り返すCSVは、少しずつ例外が増えます。

列が増える。

選択肢が増える。

担当者が変わる。

外部システムの出力形式が変わる。

取込対象アプリの権限や状態が変わる。

そのたびにExcelを開いて直す運用は、長く続きません。

CSVインポートを安定させるには、kintoneの項目だけでなく、CSVが出る前、kintoneへ入る前、本番反映後の確認まで含めて設計する必要があります。

kintone CSVインポートは、ファイルを入れる作業ではなく、外部データを業務レコードとして受け入れる設計です。