株式会社renue
AI導入・DXの悩みをプロに相談してみませんか？
AIやDXに関する悩みがありましたら、お気軽にrenueの無料相談をご利用ください。 renueのAI支援実績、コンサルティングの方針や進め方をご紹介します。
電子契約サービスのデファクト「クラウドサイン」にはWeb APIが用意されているが、公式ドキュメントはSwagger仕様ベースで本番品質の実装パターンまでは踏み込んでいない。本記事では一般的なAPIクライアント実装の考え方をもとに、アクセストークン自動更新・401リトライ・429レート制限対応・ページネーション・PDFダウンロードまで含むプロダクション実装を解説する。
クラウドサイン Web APIの基礎
クラウドサイン Web APIはRESTfulなHTTP APIで、管理画面から書類作成・取得・ダウンロード・合意締結証明書取得まで可能な操作をプログラム経由で実行できる。認証はクライアントID→アクセストークン交換方式で、トークンの有効期限は数時間程度とされています（最新の仕様は公式情報をご確認ください）。
| 項目 | 仕様 |
|---|---|
| 認証 | client_id → access_token (1時間有効) |
| 認証ヘッダ | Authorization: Bearer {token} |
| レート制限 | 429エラー時は Retry-After ヘッダに従う |
| ページネーション | page / per_page (最大100) |
| 書類取得 | GET /documents, /documents/{id} |
| PDFダウンロード | GET /documents/{id}/files/{file_id} |
| 合意締結証明書 | GET /documents/{id}/certificate |
レイヤー1: クライアント初期化とSSL設定
プロダクション実装で最初に考えるべきは「ローカル開発環境と本番環境の切り替え」。SSL検証は環境を問わず有効にするのが原則で、無効化する設定は避けるべきです。
ポイントはトークンと有効期限をインスタンス変数として持ち、トークンをメモリキャッシュすること。リクエストごとにトークン再発行するとレート制限に抵触する。
レイヤー2: アクセストークンの自動更新(300秒バッファ)
トークン管理で最も多いバグが「有効期限ギリギリでリクエストを投げて401エラー」パターン。これを防ぐために失効300秒前に再取得するバッファ設計を採用する。
300秒バッファの根拠
- リクエスト処理時間: 大きなPDFダウンロードは10-30秒かかることがある
- 時計ズレ: サーバー間の時刻差を考慮して数十秒の余裕が必要
- 429リトライ: Retry-Afterで待機中にトークンが切れるケース
- 300秒 = 5分: これらを合算してもまず足りるマージン
レイヤー3: 401/429自動リトライ
本番運用で最も頻発するエラーは「401 Unauthorized(トークン失効)」と「429 Too Many Requests(レート制限)」。両者を透過的にリトライする実装が共通リクエスト処理の要。
この実装の勘所
- 再送処理を内部で共通化: 同じurl/method/paramsを使いまわせる
- 401は強制再取得: キャッシュのトークンがサーバー側で無効化されている可能性
- 429のRetry-After: デフォルト60秒にフォールバック
- return_raw フラグ: PDFダウンロードではbytes、通常はJSON
レイヤー4: 全件取得のページネーション
CloudSign APIはper_page最大100の制限があるため、全書類を取得するにはページネーションが必要。ただし「終了判定」を誤ると無限ループに陥る。
3重の終了判定
max_pages(デフォルト100)で上限ガード — 無限ループ防止- 取得件数がper_page未満 → 最終ページ
- total_count到達 → 最終ページ(サーバーが total_count を返す場合のみ)
「どれか1つでも満たせば終了」にすることで、APIレスポンスの揺らぎや空配列パターンにも強くなる。
レイヤー5: 例外設計(Token / API 2層)
エラーハンドリングでは「トークン取得失敗」と「APIリクエスト失敗」を別例外にする設計が有効だ。呼び出し側はトークン取得エラー例外を「設定ミス/サーバー側障害」として扱い、APIリクエストエラー例外を「書類ID不正/権限不足/一時的障害」として扱える。
APIリクエストエラー例外にはstatus_codeとresponse_bodyを持たせることで、呼び出し側で「404なら新規作成にフォールバック」「403ならSlack通知」のような分岐が書きやすくなる。
運用Tips: 合意締結証明書の永続化
実務で最も重要なのが合意締結証明書(certificate)のダウンロードと永続化だ。クラウドサイン側でも保管されているが、社内の法務/経理ワークフローの独立性を保つために自社ストレージ(Azure Blob/GCS/S3)にも冷凍保存するのが鉄則。
まとめ
- トークンは300秒バッファで自動更新(リクエスト処理時間と時計ズレを吸収)
- 401自動リトライでサーバー側トークン失効に対応
- 429自動リトライでRetry-Afterに従う
- ページネーションは3重の終了判定で無限ループ防止
- 例外は Token / API の2層で呼び出し側の分岐を簡潔に
- 合意締結証明書は自社ストレージにも冷凍保存
この設計でrenueは契約書の一括インポート・AI分析・社内検索システムを本番運用している。電子契約APIは「つながる」だけでは不十分で、長期運用に耐える堅牢性が鍵だ。
