電子契約API連携で失敗しない設計｜二重送信・同期漏れ・再送・権限管理
電子契約APIの連携では、エラーが出たら同じ処理を再実行するだけでは済みません。送信要求の応答が返らなくても、相手への依頼は既に送られている場合があります。二重送信や更新漏れを避けるには、外部に影響する操作と社内データの更新を分け、応答不明の状態を扱える設計が必要です。
電子契約APIは、タイムアウトを未実行と見なさず、書類IDで提供元の状態を照合してから再実行します。文書作成・外部送信・CRM更新・PDF保存を別工程にし、処理ID、状態、確認時刻を記録します。重複通知、古い通知、認証失効、手動対応後の再開まで試験し、失敗を担当者が確認できる一覧を用意します。
本記事のAPI仕様確認日は2026年9月11日です。クラウドサインについては公式Web APIヘルプの具体的な注意点を記載し、他サービスに共通すると確認していない挙動は一般化していません。実際の再試行条件は提供元のAPI仕様で確認してください。
本記事のポイント
- タイムアウトを未送信と断定せず、書類IDで元サービスの状態を確認してから再実行する。
- 文書作成・送信・CRM更新・PDF保存を分けることで、失敗した工程だけを再開できる。
- 処理記録と復旧担当者を残し、重複通知、認証失効、手動対応後の再開まで導入前に試験する。
二重送信は「応答がない＝送られていない」から起こる
APIの通信には、要求が届く前に失敗する場合、処理中に接続が切れる場合、処理は完了したが応答だけ受け取れない場合があります。送信側から見たタイムアウトだけでは、どの段階で止まったか分かりません。これらをすべて「失敗」として同じ要求を送り直すと、相手へ複数の通知が届く可能性があります。
クラウドサインの公式ヘルプは、504エラーが返っても処理が継続している場合があると説明しています。また、文書への送信操作は、下書きであれば送信、既に送信済みであればリマインドとして扱われます。同じURLへの同じ操作でも文書の状態によって意味が変わるため、単純な自動再送は避けます。
送信前に書類IDと社内の処理IDを保存し、送信を開始した時点で状態を「結果確認中」にします。応答が得られなければ元サービスの文書状態を取得し、送信済みか、未送信か、まだ判断できないかを区別します。判断できない間は新しい依頼を作らず、一定時間後の再照合または担当者確認に進みます。
冪等キーが正式に提供されるAPIではその契約に従います。ただし、どの電子契約APIにも同じ仕組みがあるとは限りません。利用できない場合は、社内の処理記録と書類IDの対応を使って重複実行を防ぎます。独自にヘッダー名を付けても提供元が重複を抑止するとは限らないため、仕様にない保証を前提にしません。
処理を分けると、再実行する範囲を限定できる
| 工程 | 保存する結果 | 失敗したときの確認 |
|---|---|---|
| 文書作成 | 書類ID、テンプレート版、入力の版 | 既に文書が作られていないか |
| 承認・送信 | 承認者、宛先、送信要求時刻、文書状態 | 外部への依頼が成立していないか |
| 状態同期 | 提供元状態、最終取得日時 | CRM更新だけをやり直せるか |
| PDF保存 | 書類ID、保存先ファイルID | 同じ完成文書が保存済みか |
文書作成からCRM更新までを一つの処理として最初から再実行すると、最後のCRM更新だけが失敗した場合にも文書作成と送信を繰り返してしまいます。各工程に完了記録を残し、未完了の工程だけを再開できる構成にします。取得APIの再試行と、外部へ依頼を送るAPIの再試行も分けます。
契約条件を変更した場合は、同じ処理の再試行ではなく、新しい契約版として扱います。案件ID、契約版、書類IDを対応させ、旧依頼を取消したか、追加文書なのかを明示します。入力データの版が変わったのに以前の承認結果を再利用しないことも重要です。
送信直前には、承認済みのPDF、宛先、署名者の役割が変わっていないかを照合します。営業がCRM上で宛先を変更した後に、古い確認画面のまま送信するケースを想定します。承認に結び付けた文書と宛先の組み合わせが変われば、再確認を求める処理を設けます。
クラウドサインのヘルプは、前の処理結果に依存するAPIを順番に実行することや、APIごとの利用制限も説明しています。文書の作成結果を待たずにファイル登録や送信を進めると失敗の原因になります。並列化は独立した処理に限定し、相手側の完了条件を確認してから次に進みます。
通知・認証・権限の失敗を見分ける
Webhookは同じ通知が複数届く場合や、到着順が入れ替わる場合を想定します。処理済みイベントの記録、書類ID、提供元の更新日時を確認し、必要に応じて最新状態を取得します。古い「送信済み」で新しい「締結済み」を上書きしないようにします。ただし正当な取消等はあるため、状態名だけを固定の順序に並べて判断しません。
受信した通知の送信元は、提供元が定める方法で確認します。署名検証や認証の仕様がある場合は、それに従って実装します。GMOサインなどの具体的なWebhook契約を公開資料で確認できていない場合は、他社のヘッダー名や検証方式を流用せず、仕様開示を受けて判断します。
認証失効と権限不足も分けます。クラウドサインのAPIヘルプではアクセストークンの有効期間は3,600秒と説明されています。トークン更新の失敗、対象文書へのアクセス不足、契約プランによる機能制限は異なる原因です。すべてを再試行しても解決しないため、エラーコードと発生工程を記録します。
認証情報はソースコード、CRMの一般プロパティ、共有スプレッドシート、通常ログへ残さないようにします。連携処理の実行権限は、必要な文書の取得・送信・保存に限定します。管理者権限で試験に成功した後、一般担当者の権限では動かないという差も確認してください。
ログには、処理ID、案件ID、書類ID、工程、結果、日時、提供元のリクエストIDなどを残します。契約書本文や署名者の個人情報を無制限に出力すると、調査ログ自体が新たな機密情報の保管先になります。原因調査に必要な項目を絞り、閲覧者と保持期間を決めます。
障害試験と手動復旧を導入前に通す
試験では、送信要求の直後に応答を失うケース、CRM更新だけが失敗するケース、同じ通知を二度受信するケース、古い通知が後から届くケースを確認します。契約相手へ本当に依頼を送る必要がないテストは検証環境で行い、検証環境で実契約を結ばないという提供元の条件を守ります。
PDF保存の試験では、同じ書類を再取得しても不要な重複ファイルが増えないことを確認します。保存した完成PDFを開けるか、必要な証跡が揃っているか、保存先の権限が適切かも確認します。APIの成功応答だけを保存完了の証拠にせず、実ファイルと対応表を確認してください。
自動処理を止めて担当者が対応する入口を用意します。担当者は書類の現状を確認し、手動送信した場合は書類IDと対応内容を処理記録へ残します。自動処理の再開時にはその記録を読み、同じ依頼を再度送らないことを確認します。エラーを消すためだけに処理記録を削除しないでください。
運用開始後は、毎日失敗一覧を確認し、月次で締結済み一覧とCRM・保存台帳を照合します。通知が届かなかった文書や、処理途中で放置された書類は、正常終了の割合だけでは見つかりません。未完了の書類IDと担当者を一覧にし、対応期限を決めます。
追加開発の要件はCRMのAPIとMCP、顧客・案件の項目はCRMの要件整理、保存先設計は顧客フォルダの設計例で整理できます。復旧時にどの処理だけを再実行すべきか説明できる構成が、契約業務の自動化を安定させます。
障害対策と合わせて整理したい工程は、電子契約とCRMの連携方法、締結状況をCRMへ同期する方法で詳しく確認できます。
電子契約API連携の失敗対策FAQ
504エラーなら送信は失敗していますか？
そうとは限りません。クラウドサインの公式ヘルプは処理が継続する場合を説明しています。書類IDで現在の状態を確認してから再実行を判断します。
同じ送信APIを再実行しても大丈夫ですか？
提供元の仕様と文書状態によります。クラウドサインでは送信済み文書への操作がリマインドになるため、無条件に繰り返さないでください。
CRMの更新だけ失敗した場合はどうしますか？
契約の送信処理を繰り返さず、提供元の最新状態を取得してCRMへの書き戻しだけを再実行します。
ログに契約書全文を残すべきですか？
通常は処理ID、書類ID、工程、時刻、結果などに絞ります。本文や認証情報を残すと情報の保管範囲が広がるため、必要性とアクセス権を明確にします。
一次情報：クラウドサインWeb APIの注意事項、GMOサインAPI連携。
二重送信や同期漏れを防ぐ運用を整えたい場合は、ファネルAiへ電子契約APIとCRMの設計を相談することができます。
