kintone APIを外部システムから呼ぶ方法は、アプリで発行したAPIトークンをヘッダーに付けて/k/v1/records.jsonなどのURLへHTTPリクエストを送る、という形が基本です。この記事では、APIトークンの生成と権限の絞り方、curlでのレコード取得・登録・更新、クエリの書き方、ファイル添付、500件・100件の上限を越える一括処理、エラーとリクエスト上限への対処までを、cybozu developer networkの公式ドキュメントとそのまま動かせるコードで解説します。最後に、自前で実装すべき条件とiPaaSや委託に任せる場面も言い切ります。
まとめ|kintone APIはトークン認証のcurlで試し、本番はクライアントで組む
外部システムからkintoneを操作するときは、アプリごとに発行するAPIトークンをX-Cybozu-API-Tokenヘッダーで送る方式を第一候補にします。権限をレコード閲覧・追加・編集などに絞れるうえ、ユーザーのパスワードを連携先に保存せずに済みます。2要素認証のユーザーはパスワード認証を使えない点も、トークンを選ぶ理由の1つです。
まずcurlで1件取得と登録を確かめ、本番の処理はNode.jsの公式クライアント@kintone/rest-api-clientで組みます。取得は1回500件、登録・更新は1回100件が上限なので、件数が読めない処理はgetAllRecordsやupdateAllRecordsに分割を任せます。重複登録を避けるには、重複禁止フィールドをupdateKeyにしたupsertが近道です。1日のリクエスト数はスタンダードコースで1アプリ10,000件なので、差分取得で回数を抑える設計を最初から入れてください。
kintone APIの種類と外部システムから呼ぶREST APIの共通仕様
「kintone API」と呼ばれるものは2系統あります。どちらを使うかで、認証方法もリクエスト数の数え方も変わります。
REST APIとJavaScript APIの違いと外部連携での選択理由
外部連携で使うのはREST APIだけです。JavaScript APIは、kintoneの画面に読み込ませたカスタマイズやプラグインの中で動く関数群です。画面の表示やイベントを扱うもので、外部のサーバーからは呼べません。外部の基幹システム・バッチ・Webサービスからデータを読み書きする手段は、HTTPで呼ぶkintone REST APIです。
2つの違いは、上限の扱いにも出ます。1日のAPIリクエスト数の上限超過ガイドでは、JavaScript APIはリクエスト数のカウント対象外という扱いです。画面内で完結する処理をREST APIで書くと、それだけで上限を消費します。画面のカスタマイズ側の書き方はkintone一覧カスタマイズの実装手順で扱っているので、この記事では外部からのREST APIに絞ります。
リクエストURLの形式とゲストスペース、日時と応答JSONの決まりごと
kintone REST APIの共通仕様によると、URLは次の2形式です。末尾のリソース名を変えて各APIを呼び分け、ゲストスペース内のアプリは2行目の形式でないと見つかりません。
# 通常のアプリ
https://サブドメイン.cybozu.com/k/v1/records.json
# ゲストスペース内のアプリ
https://サブドメイン.cybozu.com/k/guest/スペースID/v1/records.json
本文はUTF-8のJSONで、ファイルのアップロードだけがマルチパート形式です。日時は取得時にUTCの2026-11-16T00:00:00Z形式で返り、登録時は+09:00付きで送れますが、秒は無視されて00になります。日本時間の9時より前のデータが「前日」に見える不具合は、ほとんどがこのUTC表記の読み違いです。
kintone APIの認証方式を選ぶ|APIトークン・パスワード・OAuthの使い分け
認証はkintone REST APIの認証に4方式が載っています。外部連携で使うのは実質APIトークンかパスワード認証で、ユーザー単位の操作が要るときだけOAuthを選びます。
APIトークンを生成してアクセス権を絞り、アプリを更新するまでの手順
APIトークンはアプリの設定画面で発行します。APIトークンの使い方を解説した公式Tipsの手順は次のとおりです。
- アプリの設定画面で「設定」タブを開き、「カスタマイズ/サービス連携」の「APIトークン」を選ぶ
- 「生成する」を押し、表示されたアクセス権のチェックボックスで必要な操作だけを選ぶ(初期値はレコード閲覧のみ)
- 「保存」を押したあと、「アプリを更新」で設定を反映する
最後の「アプリを更新」を忘れると、トークンは画面に出ているのに認証エラーになります。トークンは1アプリ20個まで生成でき、操作の記録上の実行者はAdministratorです。取得だけの連携と書き込みの連携でトークンを分けておけば、片方が漏れたときの被害を閲覧だけに留められます。
パスワード認証とOAuthが必要な場面、2要素認証とSAMLの制約
APIトークンで呼べるのは、レコード・ファイル・アプリ設定系のAPIです。スペースやユーザー情報を扱う場合、複数アプリをまたいでユーザーの権限どおりに動かしたい場合はパスワード認証かOAuthを使います。パスワード認証は「ログイン名:パスワード」をBase64にしてX-Cybozu-Authorizationヘッダーで送ります。
# パスワード認証:ログイン名:パスワード をBase64にしてヘッダーに入れる
AUTH=$(printf '%s' 'api-user:change-me' | base64)
curl -s "https://example.cybozu.com/k/v1/record.json?app=12&id=5" \
-H "X-Cybozu-Authorization: ${AUTH}"
# ルックアップ先のアプリも参照する登録では、トークンをカンマで並べる(最大9個)
curl -s -X POST "https://example.cybozu.com/k/v1/record.json" \
-H "X-Cybozu-API-Token: ${TOKEN_ORDERS},${TOKEN_CUSTOMERS}" \
-H "Content-Type: application/json" \
-d '{"app": 12, "record": {"顧客コード": {"value": "C-001"}}}'
制約もあります。2要素認証を有効にしたユーザーはパスワード認証でREST APIを実行できません。SAML認証だけでログインする設定の環境では、パスワード認証できるのはcybozu.com共通管理者に限られます。連携用に専用ユーザーを作る場合も、こうした設定と衝突しないかを先に確認しておくと、本番切り替えの日に止まりません。
curlでレコードを取得・登録・更新する手順とクエリの書き方
実装に入る前に、curlで1往復させて権限とフィールドコードを確かめます。Windowsでも、PowerShell 7やGit Bashからなら以下をそのまま実行できます。
1件取得と複数取得をcurlで試し、日本語のクエリをURLエンコードする
1件取得はGETでrecord.json、複数取得はrecords.jsonを呼びます。複数のレコードを取得するAPIでは、パラメーターはURLエンコードしてクエリ文字列で送るのが一般的な方法とされています。日本語の条件を手でエンコードするより、curlの-Gと--data-urlencodeに任せるほうが崩れません。
export KINTONE_API_TOKEN="アプリで生成したトークン"
# 1件取得(アプリ12のレコード番号5)
curl -s "https://example.cybozu.com/k/v1/record.json?app=12&id=5" \
-H "X-Cybozu-API-Token: ${KINTONE_API_TOKEN}"
# 複数取得:未対応で11月以降に更新されたレコードを更新日時の昇順で500件
curl -s -G "https://example.cybozu.com/k/v1/records.json" \
-H "X-Cybozu-API-Token: ${KINTONE_API_TOKEN}" \
--data-urlencode "app=12" \
--data-urlencode 'query=対応状況 in ("未対応") and 更新日時 > "2026-11-01T00:00:00+09:00" order by 更新日時 asc limit 500' \
--data-urlencode "fields[0]=レコード番号" \
--data-urlencode "fields[1]=顧客名" \
--data-urlencode "totalCount=true"
1回で取れるのは最大500件、limitを省くと100件です。fieldsを省くと閲覧できる全フィールドが返るので、項目の多いアプリでは応答が重くなります。totalCount=trueを付けると条件に合う総件数が文字列で返り、次の取得を続けるかの判断に使えます。
クエリの演算子・関数・order byの書き方とエスケープでつまずく箇所
クエリの書き方で押さえる規則は多くありません。実装で問題になる順に並べます。
| 規則 | 書き方の例 | つまずき方 |
|---|---|---|
| ドロップダウン等は in で比較 | 対応状況 in (“未対応”, “保留”) | = で書くとエラーになる |
| テーブル内・関連レコードも in | 明細品目 in (“部品A”) | = や != は使えない |
| order by を先に書く | order by 番号 asc limit 100 | limit を先に書くと構文エラー |
| 日付の関数 | 締切日 < TODAY() | 関数名は大文字で書く |
| 値の中の ” と \ | 顧客名 like “\”特急\”” | JSON本文ではさらに二重のエスケープが要る |
order byを省くとレコード番号の降順で返ります。差分取得をするなら、必ず更新日時 ascで並べて最後の更新日時を次回の起点にしてください。likeは単語単位の検索で、該当が10万件に達すると打ち切られ、応答ヘッダーのX-Cybozu-Warningに印が付きます。
レコードの登録と更新、updateKeyとupsertで二重登録を防ぐ書き方
登録はPOST、更新はPUTでrecords.jsonを呼びます。複数のレコードを登録するAPIも複数のレコードを更新するAPIも1回100件までで、1件でも失敗するとそのリクエストの全件が取り消されます。
# 登録:2件をまとめて登録する
curl -s -X POST "https://example.cybozu.com/k/v1/records.json" \
-H "X-Cybozu-API-Token: ${KINTONE_API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"app": 12,
"records": [
{ "注文番号": { "value": "A-1001" }, "顧客名": { "value": "株式会社サンプル" }, "金額": { "value": "12000" } },
{ "注文番号": { "value": "A-1002" }, "顧客名": { "value": "サンプル商事" }, "金額": { "value": "8500" } }
]
}'
# 応答例:{"ids":["101","102"],"revisions":["1","1"]}
# 更新:注文番号(重複禁止)で対象を指定し、無ければ登録する
curl -s -X PUT "https://example.cybozu.com/k/v1/records.json" \
-H "X-Cybozu-API-Token: ${KINTONE_API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"app": 12,
"upsert": true,
"records": [
{ "updateKey": { "field": "注文番号", "value": "A-1001" },
"record": { "金額": { "value": "13000" } } }
]
}'
# 応答例:{"records":[{"id":"101","revision":"2","operation":"UPDATE"}]}
updateKeyに使えるのは、重複禁止を設定した文字列(1行)か数値のフィールドだけです。外部システム側の主キーをこのフィールドに持たせておけば、同じデータを2回送っても2件目は更新で済みます。upsertは2025年1月の定期メンテナンスで加わった機能で、新規登録が起きる分、トークンにはレコード追加の権限も必要です。テーブルを部分的に直すときは既存の全行を送らないと、送らなかった行が消えます。
添付ファイルをアップロードしてfileKeyでレコードに紐づける手順
ファイルは2段階で添付します。ファイルをアップロードするAPIで一時領域に上げてfileKeyを受け取り、そのキーをレコードの添付ファイルフィールドに入れます。
# 1. 一時領域へアップロードし、fileKey を受け取る
curl -s -X POST "https://example.cybozu.com/k/v1/file.json" \
-H "X-Cybozu-API-Token: ${KINTONE_API_TOKEN}" \
-F "[email protected]"
# 応答例:{"fileKey":"c15b3870-7505-4ab6-9d8d-b9bdbc74f5d6"}
# 2. 受け取った fileKey を添付ファイルフィールドに入れて更新する
curl -s -X PUT "https://example.cybozu.com/k/v1/record.json" \
-H "X-Cybozu-API-Token: ${KINTONE_API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"app": 12,
"updateKey": { "field": "注文番号", "value": "A-1001" },
"record": { "請求書": { "value": [ { "fileKey": "c15b3870-7505-4ab6-9d8d-b9bdbc74f5d6" } ] } }
}'
一時領域のファイルは、どこにも添付されないと3日後に削除され、それまではディスク使用量にも数えられます。レコード取得で返る添付ファイルのfileKeyはダウンロード用で、別のレコードへの添付には使えません。アップロードは1回1ファイルなので、複数ファイルは1つずつ上げてキーを配列に並べます。
500件・100件の上限を越える一括処理をNode.jsとカーソルで組む手順
件数が増えると、curlで回数を重ねる書き方は破綻します。ここからは公式クライアントで、分割と再開を前提にした処理を組みます。
rest-api-client 7.0による全件取得・一括更新の実装コード
Node.jsでgetAllRecordsとupdateAllRecordsを書くコードを示します。@kintone/rest-api-clientは、2026年11月10日リリースの7.0.0で最小対応がNode.js 22に引き上げられました(npm registryで確認した最新版・2026年11月時点)。Node.js 20の環境に残す場合は6.x系の最終版6.6.1を固定します。record.mdの説明では、getAllRecordsは上限を超える件数を取得でき、orderByを指定すると内部でカーソルAPIを使います。
// sync-orders.mjs:node sync-orders.mjs 2026-11-01T00:00:00+09:00 で実行する(Node.js 22以上)
import { KintoneRestAPIClient, KintoneAllRecordsError } from "@kintone/rest-api-client";
const client = new KintoneRestAPIClient({
baseUrl: process.env.KINTONE_BASE_URL, // 例:https://example.cybozu.com
auth: { apiToken: process.env.KINTONE_API_TOKEN },
});
const app = process.env.KINTONE_APP_ID;
const since = process.argv[2];
// 1. 前回以降に更新されたレコードを、件数の上限を気にせず取得する
const records = await client.record.getAllRecords({
app,
fields: ["レコード番号", "注文番号", "対応状況"],
condition: `更新日時 > "${since}"`,
orderBy: "更新日時 asc",
});
console.log(`取得: ${records.length}件`);
// 2. 基幹システムの出荷結果を、注文番号をキーにまとめて反映する
const shipped = [{ orderNo: "A-1001" }, { orderNo: "A-1002" }]; // 実際は連携元から読む
try {
const result = await client.record.updateAllRecords({
app,
upsert: true,
records: shipped.map((s) => ({
updateKey: { field: "注文番号", value: s.orderNo },
record: { 対応状況: { value: "出荷済" } },
})),
});
console.log(`反映: ${result.records.length}件`);
} catch (e) {
if (e instanceof KintoneAllRecordsError) {
// 成功したチャンクは確定済み。残りだけを保存して再実行に回す
console.error(`${e.numOfProcessedRecords} / ${e.numOfAllRecords}件で停止: ${e.error.code}`);
console.error(JSON.stringify(e.unprocessedRecords));
}
process.exitCode = 1;
}
conditionにはorder by・limit・offsetを書けません。並び順はorderByに分けて渡します。APIトークンは環境変数から読み、コードやリポジトリに直接書かないでください。
2,000件単位のロールバックとKintoneAllRecordsErrorの再開設計
addAllRecordsとupdateAllRecordsは、件数の上限なく受け付ける代わりに2,000件ごとのチャンクに分けて順に処理します。ロールバックはチャンク単位なので、5,000件の更新が3つ目のチャンクで失敗した場合も、最初の4,000件は反映済みの状態です。「全件が成功か全件が取り消しか」のどちらかになると思い込むと、ここで不整合が出ます。
エラー処理の説明にあるとおり、KintoneAllRecordsErrorは処理済み件数・全件数・未処理のレコード・原因のKintoneRestAPIErrorを持っています。未処理分をファイルやキューに残し、原因を直してから同じ処理を再実行する作りにします。updateKeyとupsertで書いておけば、処理済みの行を送り直しても重複は生まれません。
カーソルの10個上限と10分の有効期限で詰まる場面と後始末の書き方
自前でカーソルを使う場合、カーソルを作成するAPIの制約に注意します。有効なカーソルは1ドメインあたり10個までで、作成または最後の取得から10分で失効します。1回の取得件数はsizeで1〜500を指定し、queryにlimitやoffsetを入れるとエラーです。
詰まるのは、取得の途中で例外を投げて終了するバッチです。カーソルが全件取得も削除もされずに残り、10分間は枠を占有します。同じドメインで複数のバッチが同時に走ると、11個目の作成で失敗します。途中終了の経路ではDELETE /k/v1/records/cursor.jsonでカーソルを消す処理をfinallyに置いてください。offsetの上限10,000件とカーソルのどちらで設計するかの判断は、kintoneのデータ連携を4方式の判定表とAPI制限から設計する記事で件数別に整理しています。
エラーとリクエスト上限への対処|429・1日1万件・リビジョン競合
本番で止まる原因の大半は、コードの誤りよりも上限と競合です。失敗したときに再試行してよいかを、応答から機械的に判断できるようにしておきます。
エラー応答のcodeとHTTPステータスで再試行するかを分ける基準
失敗時は200番台以外のステータスと、id・code・messageを持つJSONが返ります。messageはユーザーの表示言語で変わるため、分岐はcodeとステータスで書きます。
| 状況 | 目安となる応答 | 対処 |
|---|---|---|
| 同時接続が1ドメイン100を超えた | HTTP 429 | 待ってから再試行する |
| リビジョン番号が一致しない | 4xxのエラー | 最新を取り直してから判断する |
| 権限・トークンの不足 | 4xxのエラー | 再試行しない。設定を直す |
| フィールドの値が不正 | 4xxのエラー | 再試行しない。元データを直す |
再試行するのは429と一時的な5xxだけにします。値の誤りや権限不足を自動で繰り返すと、成功しないまま1日の上限だけを使い切ります。応答ヘッダーのX-ConcurrencyLimit-Runningには現在の同時接続数が出るので、並列数を決めるときに使える実測値です。同時接続の上限は利用者の画面操作と合算で、超えるとドメイン全体のAPIが止まる点も覚えておいてください。
1日10,000リクエストの上限を超えないための差分取得と呼び出しの削減
1日のリクエスト数は1アプリあたりスタンダードコースで10,000件、ワイドコースで100,000件です。カウントは日本時間の毎日9時にリセットされ、アプリの管理画面でリアルタイムに確認できます。
- 前回の最終更新日時を保存し、
更新日時 > "前回値"の差分だけを取得する - 1件ずつの登録・更新をやめ、100件単位の一括APIか
updateAllRecordsに寄せる - 存在確認のGETを省き、updateKeyとupsertで1回の呼び出しに畳む
- 画面内で完結する処理はREST APIでなくJavaScript APIで書く
効果が大きいのは最初の2つです。5分ごとに全件を取り直すポーリングは、1回500件の取得でも1日288回を下回りません。件数が増えれば上限に近づきます。差分取得に変えるだけで、更新が無い時間帯の呼び出しはほぼ1回で済みます。
kintone APIを自前で実装すべき条件と、iPaaSや委託に任せる場面
ここまでのコードは数十行で書けます。それでも、書くべきかどうかは別の問題です。判断の材料は件数・頻度・失敗時の責任の3つで、どれか1つでも重ければ自前実装に寄せます。判断側の全体像は、kintoneカスタマイズ・開発の手段と費用相場、内製外注の判断で整理しています。
REST APIを自前で書くべき条件と、iPaaSで済ませるべき条件
自前で書くべきなのは、1回の同期が数千件を超える場合、upsertや再開処理で重複と欠落を防ぐ必要がある場合、基幹システム側の処理と同じトランザクションの感覚で失敗を扱う必要がある場合です。iPaaSの標準の部品では、失敗したチャンクから再開するような制御までは組みにくいのが実情です。
逆に、Slackへの通知やフォーム入力の転記のように1日数十件で、失敗しても人が手で直せる連携なら、自前のコードは過剰です。保守する人がいないコードを残すより、国産iPaaSのYoomによるkintone連携のようなサービスに任せるほうが安く済みます。Shopifyなど特定のサービスとつなぐ場合は、ShopifyとkintoneのAPI連携の料金比較のように、連携アプリを先に探すのが順番です。
外部システム連携を委託するときに決めておく受け渡し範囲と検証環境
連携の実装を外部に任せるときは、契約前に次を決めておきます。どのアプリに何のトークンを発行し、誰が保管するか。失敗したレコードを誰がどこで確認して再実行するか。1日の上限に近づいたときの連絡先はどこか。検証用の別ドメインをどちらが用意するか。検証環境の作り方はkintone開発者ライセンスと開発環境の作り方で解説しています。
トークンの権限を最小に絞らず、全権限のトークン1本で納品される例は珍しくありません。受け入れ時に、アプリの設定画面でトークンごとのアクセス権を必ず確かめてください。一創ではAPI開発・システム連携として、kintoneと基幹システム・ECサイトとのREST API連携を、差分同期と再開処理を含めて設計から実装まで請け負っています。kintoneのアプリ設計から見直したい場合はkintone導入支援で相談できます。
よくある質問
kintone APIを使い始めるときによく出る疑問に答えます。
kintone APIは追加料金なしで使えますか?
REST APIとJavaScript APIは、スタンダードコース以上の契約であれば追加料金なしで使えます。ライトコースではAPIやJavaScriptカスタマイズを使えないため、外部連携を組むならコースの確認が先です。費用がかかるのは、1日のリクエスト数が足りずにワイドコースへ上げる場合や、iPaaSなど連携サービス側の利用料です。
APIトークンとパスワード認証はどちらを使うべきですか?
レコードとファイルを扱う連携なら、APIトークンを選びます。アプリ単位で権限を絞れ、ユーザーのパスワードを連携先に保存する必要もありません。スペースやユーザー情報など、トークンで呼べないAPIが要る場合や、操作をユーザーごとに記録したい場合にだけ、パスワード認証かOAuthを使います。2要素認証を有効にしたユーザーはパスワード認証を使えません。
kintone APIで一度に取得・登録できる件数の上限は何件ですか?
複数レコードの取得は1回500件まで、offsetは10,000件までです。登録・更新・削除は1回100件までで、1件でも失敗するとそのリクエストの全件が取り消されます。これを超える件数は、カーソルAPIか、rest-api-clientのgetAllRecords・addAllRecords・updateAllRecordsで分割して処理します。
PythonやPHPからkintone REST APIを呼べますか?
呼べます。REST APIはHTTPとJSONだけで動くので、言語は問いません。PythonならrequestsやurllibでURL・ヘッダー・JSON本文を組み立てれば、この記事のcurlと同じリクエストになります。ただし公式のクライアントライブラリはJavaScript向けの@kintone/rest-api-clientです。他の言語ではチャンク分割と再開処理を自分で書くことになります。
kintone APIでエラー「429」が返ったときはどうすればよいですか?
429は、ドメインの同時接続数が100を超えたことを示します。数秒待ってから再試行し、並列で動かしている処理の数を減らしてください。同時接続数は利用者の画面操作と合算されるため、業務時間中に大量の並列処理を走らせると、利用者の画面まで遅くなります。重い一括処理は、夜間に並列数を絞って動かすのが安全です。
関連記事
- kintoneのデータ連携を実装視点で選ぶ|4方式の判定表とAPI制限の設計:REST API・プラグイン・iPaaSのどれで連携するかと、制限値から逆算する設計
- kintone開発者ライセンスの取り方と開発環境の作り方|cli-kintoneで検証環境を分ける手順:本番を汚さずにAPIを試す検証環境の用意
- kintoneカスタマイズ・開発とは?できること・手段・費用相場と内製外注の判断:API連携を含む開発を内製するか外注するかの判断
- kintoneプラグイン開発とは|manifest構成から配布・内製外注の判断まで:連携の設定画面をプラグインとして配布する場合の作り方
- kintoneとは?できること・料金・プラグインからノーコードで内製する判断まで解説:コースごとのAPI可否と料金を確かめる親ガイド