目次
会計ソフトと自社システムをつなぎたい——中小企業のDXで、これは非常によくあるご相談です。仕訳や取引先データを手で二重入力している状態は、時間もかかりミスも起きます。API（システム同士をつなぐ入口）が公開されているなら、つないでしまえばいい。理屈はそのとおりです。
ただ、実際にやってみると、公式ドキュメントに書いてあることと、現物の挙動が食い違う場面に出くわします。私たちも実案件（匿名）で、会計ソフトのWeb-API連携に取り組み、3つの落とし穴にぶつかりました。
この記事では、その3点と、そこから得た「外部APIとの付き合い方」の判断軸を整理します。
この記事の結論
- 外部APIの仕様は仕様書ではなく実測で確定させる
- Find系APIには取得件数の上限がある前提で設計する
- Logoutなど破壊的な操作は最小限に留める
ハマった1：Find系APIに50件の取得上限がある
最初につまずいたのは、データの取得件数です。
取引データを一覧で取ってくるFind系のAPIを呼んだところ、1回のリクエストで返ってくるのは50件まででした。会計データは月次でも数百件、年間なら相当な量になります。「全件取ってきて突合する」という素朴な設計は、この時点で成立しません。
厄介なのは、呼び出し自体はエラーにならないことです。正常なレスポンスとして50件が返ってくるので、テストデータが少ないうちは誰も気づきません。本番データで動かした瞬間に「なぜか一部のデータが連携されていない」という形で表面化します。
対策はシンプルで、開発の初期段階から、上限を超える件数の実データで試すこと。50件を境に挙動が変わるなら、49件と51件で試せばすぐ分かります。
なお、こうした上限値は改定されることがあります。最新の条件は必ず公式ドキュメントで確認してください。
ハマった2：$skipを指定しても同じ50件が返る（ページングの原因と対策）
上限があるなら、続きを取りに行けばいい。そう考えて、開始位置をずらす$skipパラメータを指定しました。ところが、何を指定しても同じ先頭50件が返ってくるのです。
エラーは出ません。パラメータは受け付けられ、正常応答が返り、中身だけが変わらない。これが一番たちの悪いパターンです。ログを見ても異常はなく、「ちゃんと動いている」ように見えてしまいます。
なぜ気づけたか
気づけたのは、実データで件数を突合していたからです。会計ソフト側の画面で見える件数と、APIで取得できた件数が合わない。この差分から、ページングが効いていないと判断できました。
逆に言えば、件数突合をしていなければ、そのまま本番に出していた可能性があります。「取得できた件数が、あるべき件数と一致するか」を毎回確かめる——これを工程に組み込むかどうかで、事故の確率が大きく変わります。
対策：別の切り口で分割する
ページングが期待どおりに動かない場合、取り方そのものを変えます。
| 方式 | 内容 | 向くケース |
|---|---|---|
| 期間で分割 | 日次・週次など短い期間で区切って取得 | 件数が期間に比例するデータ |
| ID範囲で分割 | 前回取得した最終IDより後ろを指定 | 連番のIDが振られている場合 |
| 条件で絞る | 部門・区分などで母集団を小さくする | 業務上、分けて扱える場合 |
いずれも「1回のリクエストで上限を超えないようにする」という発想です。仕様書に書かれた便利な機能に頼らず、確実に動く範囲で分割するほうが、結果的に早く安定します。
ハマった3：Logoutを連発するとクライアントIDがブロックされる
3つ目が、もっとも痛手が大きいものでした。
開発中は、動作確認のために何度もログイン・ログアウトを繰り返します。丁寧に後始末をするつもりで、処理のたびにLogoutを呼ぶ実装にしていました。ところがある時点から、認証に使うクライアントIDがブロックされ、一切APIを呼べなくなったのです。
さらに困ったのは、待っても解除されなかったこと。復旧には、アプリケーションを新規に作り直し、クライアントIDを取り直す必要がありました。開発中に一時的にIDが使えなくなるだけでも、検証は完全に止まります。
教訓：破壊的な操作は必要最小限に
ここから得た判断軸は明確です。セッションや認証に関わる操作は「丁寧にやるほど良い」わけではない。
- Logoutは、処理のたびではなく一連の処理の最後に1回
- 開発中の試行錯誤では、そもそも呼ばない選択も検討する
- 認証情報を壊す可能性のある操作は、本番前に洗い出しておく
一般的なプログラミングの感覚では「使い終わったら閉じる」が正しい作法です。しかし外部APIでは、その作法が回数制限や不正利用検知に引っかかることがあります。相手のシステムのルールが優先されます。
3つの落とし穴と対策のまとめ
1と2は「取れているつもりで取れていない」問題、3は「壊してしまう」問題です。前者は件数突合で、後者は操作の抑制で防げます。
外部API連携の進め方（見積り前にやること）
同じ轍を踏まないための進め方を、3ステップで整理します。
1. 実データで挙動を実測する
仕様書を読むのは当然として、書いてあるとおりに動くかを実データで確かめる工程を必ず置きます。特に確認すべきは、件数の上限、ページングの挙動、エラー時の返り方の3点です。テストデータは、上限値を超える件数を用意します。
2. 上限と制約を一覧化する
実測で分かったことを、「仕様書の記述」と「実際の挙動」を並べた表にまとめます。ここが食い違っている項目は、後工程で必ず問題になります。チーム内で共有し、設計の前提に組み込みます。
3. 設計・見積りを確定する
制約が見えてから、はじめて設計と見積りを固めます。逆に言えば、実測前の見積りは当たりません。「APIがあるから2週間でつながります」という見立ては、上限やページングの罠を踏んだ瞬間に崩れます。
判断のコツ：外部API連携の案件では、検証期間を工程に明示して確保する。ここを削ると、後半で必ず取り返しのつかない形で跳ね返ってきます。
中小企業がこの話から持ち帰るべきこと
「うちはシステムを作る側ではないから関係ない」と思われるかもしれません。しかし、発注する側にこそ関係があります。
- 「APIがあるからすぐつながる」という提案は疑う。上限や制約の実測が済んでいるかを確認する
- 検証期間が工程に入っているかを見る。入っていない見積りは、後で膨らむ可能性が高い
- 連携後の件数チェックを運用に組み込む。取れているつもりで取れていない事故は、運用側でしか気づけないことがある
外部サービスとの連携は、自社だけで完結しない分、想定外が起きます。想定外が起きる前提で工程を組む——これが、失敗しない発注の条件です。
よくある質問
Q. 会計ソフトのAPIで全件取得できないのはなぜですか？ Find系APIに1回あたりの取得上限が設けられている場合があります。上限を超える分はページング指定で追加取得する設計が必要です。仕様は変わるため最新は公式ドキュメントで確認してください。
Q. $skipを指定しても同じデータが返るときはどうすればいいですか？ パラメータが無視されている可能性があります。実データで件数と中身を突合し、ID順の絞り込みや日付での分割取得など、別の切り口でページングを代替する設計に切り替えます。
Q. API連携の開発期間はどう見積もればいいですか？ 仕様書どおりに動く前提では見積もれません。実データで挙動を確かめる検証期間を工程に組み込み、上限やページングの実測を終えてから本実装に入るのが安全です。
まとめ
- Find系APIには取得件数の上限があることがある。エラーにならないため気づきにくい
- ページング指定が無視されるケースがある。実データでの件数突合が唯一の防波堤
- Logoutなどの操作を繰り返すとクライアントIDがブロックされ、作り直しが必要になることがある
- 外部APIの仕様は仕様書ではなく実測で確定させ、破壊的な操作は最小限に留める
RENOYでは、会計ソフトや基幹システムとのAPI連携について、実現可能性の検証から設計・開発、運用までを一貫してお手伝いしています。「つなげると言われたが本当にできるのか分からない」という段階のご相談も歓迎です。まずはお気軽に無料個別相談（オンライン・60分）をご利用ください。サービス内容をまとめた資料は資料請求からご覧いただけます。