業務システム

クラウドサイン APIの使い方:トークン取得・テンプレート送信・差分同期をPythonで実装する手順

クラウドサイン APIの使い方:トークン取得・テンプレート送信・差分同期をPythonで実装する手順

クラウドサインのWeb APIは、client_idでトークンを取り、書類の作成から宛先の追加、送信、締結済み書類の一覧取得までをRESTで呼べる仕組みです。仕様書はOpenAPI形式で公開されており、2026年11月時点の版は0.37系です。この記事では、APIを使える契約とサンドボックスの準備、トークンの使い回し、テンプレートから宛先と入力項目を差し替えて送るPythonコード、1分800回の制限と180秒のタイムアウトへの備え、締結済み書類を差分で取り込む夜間ジョブまでを、公式の仕様書と利用ガイドに沿って順に説明します。

まとめ:クラウドサイン APIはトークン再利用・テンプレート起点・差分取得で組む

実装を始める前に、契約中のプランでWeb APIが有効かを確かめます。APIオプションの無い契約で呼ぶと、返される応答は403と webapi_option_required です。開発は本番と切り離されたサンドボックスで進め、クライアントIDも環境ごとに発行します。

送信処理は、白紙の書類にPDFを添付する作りより、管理画面で作ったテンプレートを起点にするほうが短く済みます。テンプレートから書類を作り、宛先の連絡先、送信者が入れる金額欄、管理番号などの書類情報だけをAPIで差し替えて送ります。

トークンは1時間有効で、期限内は同じ値を使い回します。1分800回を超えると429で1分止められ、180秒を超える処理は504を返しつつ裏で続行します。締結結果はWebhookを合図にしつつ、GET /documents の最終処理日時で差分を取る夜間ジョブで取りこぼしを拾う構成が堅実です。

クラウドサイン APIを使い始める前に確認するプラン・サンドボックス・クライアントID

Web APIが使える契約かを料金ページの機能一覧と403の応答で確かめる

クラウドサインの料金ページでは、2026年11月18日時点で Corporate(月額28,000円・税抜)の機能一覧にWeb APIが載っています。Business と Enterprise は「提案内容によって利用できる機能が異なる」という注記付きです。送信1件ごとの費用(Light・Corporateは220円・税抜)はAPI経由の送信にも掛かるため、自動送信で件数が増える分を見積もりに入れておきます。

APIの紹介ページには対象プランとして旧称のスタンダードを含む4プランが並んでおり、料金ページとプラン名がそろっていません。名称で判断せず、契約中のアカウントで一度トークンを取り、GET /documents が403の webapi_option_required を返さないかで確かめるのが確実です。Free Plan(月2件・1名)はAPIの対象外です。

サンドボックスの申込みと、本番・サンドボックスで分かれるホストとID発行画面

Web API利用ガイドによると、サンドボックスは営業担当かチャットで申し込みます。データベースとストレージは本番と完全に分かれており、サンドボックスで作った書類は実際の契約締結には使えません。テンプレートや書類、ユーザーを本番から移す手段も無いので、検証用のテンプレートはサンドボックス側で作り直します。

項目 本番 サンドボックス
APIのホスト api.cloudsign.jp api-sandbox.cloudsign.jp
クライアントIDを発行する画面 www.cloudsign.jp sandbox.cloudsign.jp
Webhookの送信元IP 3件(各 /32) 52.197.119.179/32

発行画面はどちらのホストも /api/clients のパスです。クライアントIDは英数字とハイフンの36桁で、利用者ごとに発行されます。漏れると第三者がその利用者として書類を作れてしまうため、環境変数やシークレット管理に置き、リポジトリには入れません。発行ボタンが見えないときは、管理者に発行を頼みます。LGWAN向けには lgwan-api.cloudsign.jp という別ホストも仕様書に載っています。

client_idだけでトークンを取得し、1時間の有効期限内は同じ値を使い回す

クラウドサインのトークン取得は、クライアントシークレットを使いません。Web APIの仕様書(OpenAPI 0.37.5)の POST /token は、フォーム形式の client_id だけを受け取ります。

curl -s -X POST https://api-sandbox.cloudsign.jp/token \
  -d "client_id=${CLOUDSIGN_CLIENT_ID}"
# 応答例:{"access_token":"01234567-...","expires_in":3600,"token_type":"Bearer"}

curl -s "https://api-sandbox.cloudsign.jp/documents?status=2&page=1" \
  -H "Authorization: Bearer ${TOKEN}"

トークンの有効期限は発行から3,600秒です。期限内に取り直しても新しい値は出ず、expires_in は残り秒数として返ります。呼び出しのたびに取得するより、値と失効時刻をプロセス内に保持し、残りが1分を切ったら取り直す作りにします。管理画面の「Web API設定」が「利用しない」のままだと、APIもWebhookも動きません。

クラウドサイン APIのエンドポイントを書類・宛先・入力項目・一覧の4系統で把握する

下書きの間しか変更できない操作と、送信後に使える操作の判断基準

エンドポイントは40近くありますが、業務システムからの連携で使うものは次の表でほぼ足ります。押さえどころは、宛先・ファイル・入力項目の追加と変更と削除が、書類が下書き(status 0)の間しかできない点です。

系統 主な操作 使える状態
書類 作成・送信・取消 送信は下書き、再実行はリマインド
宛先 追加・変更・削除 下書きのみ
入力項目 追加・変更・削除 下書きのみ
書類情報 作成・更新 送信後も更新できる
一覧 自分の書類・チーム全体 常時
締結物 PDF・合意締結証明書 締結済みで取得

パスは、書類が /documents と /documents/{id}、宛先が …/participants、入力項目が …/files/{fileID}/widgets、書類情報が …/attribute、チーム全体の一覧が /team_documents、合意締結証明書が …/certificate です。

送信後に宛先のメールアドレスを誤っていたと分かった場合、APIで直す手段はありません。PUT /documents/{id}/decline で取り消し、新しい書類を作り直します。送信前の検証(メールアドレスの形式、宛先の件数、金額欄の入力漏れ)は連携側で済ませておく設計が前提です。

書類のstatus 0〜4と13、宛先のorderから読み取る送信順と締結状態

書類の status は、0が下書き、1が先方確認中、2が締結済、3が取消または却下、4がテンプレート、13がインポート書類です。一覧の絞り込みでは status=-1 で0〜4を全部取れます。

宛先は participants 配列に入り、order が0の要素が送信者自身です。確認依頼は order の昇順に届き、この値を直接指定するパラメータはありません。追加した宛先は最後尾に付くため、社内の承認者を先、取引先を後に並べたいときは、追加する順番で制御します。宛先ごとの status は8が押印または入力済み、9が却下で、誰の段階で止まっているかを画面に出したいときに使えます。

テンプレートから書類を作り、宛先と入力項目を差し替えて送信するPythonコード

template_id指定で作成し、宛先IDと入力項目IDを書類の応答から引き直す

契約書の雛形、押印欄の位置、取引先の宛先枠は、管理画面でテンプレートとして作っておきます。APIでは POST /documents に template_id を渡して書類を複製し、返ってきた書類の participants と files[].widgets から、差し替える宛先と入力項目のIDを取り出します。

入力項目は座標で指定するため、PDFのレイアウトが変わるたびにコード側の x と y を直す作りは保守が重くなります。テンプレート側で入力項目に「契約金額」などの label を付けておき、コードはラベルで項目を探す形にすると、雛形を差し替えてもコードは変わりません。

送信者が入れる金額欄の事前入力と、書類情報へ管理番号と契約期間を登録する手順

入力項目ごとに値を入れる担当者が決まる仕様です。送信者に割り当てた項目は text が必須で、送信前にAPIから値を入れられます。取引先など送信者以外に割り当てた項目は text を空にする決まりで、値を入れると400になります。250文字を超える値もエラーです。

基幹の受注番号や契約期間を入れる先は、書類情報(attribute)です。local_id(管理番号)、counterparty(契約相手)、amount(取引金額)、validity_start_at と validity_end_at(契約期間)、validity_end_notice_at(解約通知期限)、auto_update(自動更新の有無)が使え、このエンドポイントだけはJSONで送ります。local_id に受注番号を入れておくと、締結後に基幹側の受注と突き合わせるキーになります。

トークンの保持・429の待機・下書きの再利用を組み込んだ送信スクリプト

以下は、テンプレートから書類を作り、2番目の宛先を取引先に差し替え、送信者の金額欄と書類情報を埋めて送るまでのスクリプトです。Python 3.10以上と requests で動きます。

import os, time, requests

BASE = os.environ.get("CLOUDSIGN_BASE", "https://api-sandbox.cloudsign.jp")


class CloudSign:
    def __init__(self, client_id):
        self.client_id, self.token, self.expires = client_id, None, 0.0
        self.http = requests.Session()

    def _bearer(self):
        if self.token is None or time.time() > self.expires - 60:
            r = self.http.post(f"{BASE}/token", data={"client_id": self.client_id}, timeout=30)
            r.raise_for_status()
            body = r.json()
            self.token = body["access_token"]
            self.expires = time.time() + body["expires_in"]  # 残り秒数で返る
        return "Bearer " + self.token

    def call(self, method, path, **kw):
        for _ in range(3):
            r = self.http.request(method, BASE + path, timeout=190,
                                  headers={"Authorization": self._bearer()}, **kw)
            if r.status_code == 429:   # 1分800回超。1分で解除される
                time.sleep(61)
                continue
            if r.status_code == 401:   # 失効していたら取り直す
                self.token = None
                continue
            r.raise_for_status()
            return r.json() if r.content else None
        raise RuntimeError(f"{method} {path} failed: {r.status_code} {r.text}")


def send_from_template(cs, order, template_id):
    doc = cs.call("POST", "/documents",
                  data={"template_id": template_id, "title": f"業務委託契約書({order['no']})"})
    doc_id = doc["id"]
    time.sleep(3)  # 作成直後は反映に数秒かかることがある
    doc = cs.call("GET", f"/documents/{doc_id}")

    client = next(p for p in doc["participants"] if p["order"] == 1)
    cs.call("PUT", f"/documents/{doc_id}/participants/{client['id']}",
            data={"email": order["email"], "name": order["name"], "organization": order["company"]})

    for f in doc["files"]:
        for w in f.get("widgets", []):
            if w.get("label") == "契約金額":   # 送信者に割り当てた項目だけ text を入れられる
                cs.call("PUT", f"/documents/{doc_id}/files/{f['id']}/widgets/{w['id']}",
                        data={"text": f"{order['amount']:,}円"})

    cs.call("PUT", f"/documents/{doc_id}/attribute",
            json={"local_id": order["no"], "counterparty": order["company"],
                  "amount": order["amount"], "validity_start_at": order["start"],
                  "validity_end_at": order["end"], "auto_update": 1})
    cs.call("POST", f"/documents/{doc_id}")  # 下書きなら送信、送信済みならリマインド
    return doc_id


if __name__ == "__main__":
    cs = CloudSign(os.environ["CLOUDSIGN_CLIENT_ID"])
    order = {"no": "SO-2026-0412", "email": "[email protected]", "name": "山田 太郎",
             "company": "株式会社サンプル", "amount": 1650000,
             "start": "2026-12-01", "end": "2027-11-30"}
    print(send_from_template(cs, order, os.environ["CLOUDSIGN_TEMPLATE_ID"]))

本番で使う前に、受注番号ごとに書類IDを自社のテーブルへ記録する処理を足してください。最後の送信を再実行すると取引先にリマインドが飛ぶため、記録済みの書類IDの status が1以上なら送信を呼ばない判定が要ります。テンプレートを使わずPDFを毎回添付して送る素の手順と、稟議の承認判定を連携側に置く理由は電子署名の連携実装でクラウドサインへ送るcurl手順で扱っています。

1分800回の429と180秒の504を前提にしたクラウドサイン APIの呼び出し設計

同一トークンで1分800回を超えると1分止まる制限と、並列数の決め方

仕様書の429の説明では、同じトークンでの要求が1分間に800回を超えると以降が止められ、1分の停止を挟んで自動で解除されます。上の送信スクリプトは1通あたり6〜7回呼ぶので、単純計算で1分に100通強が上限です。

月末の一斉送信などで数百通を流すときは、並列で投げるより、1本の作業キューで順番に流します。利用ガイドは、前の応答を受け取ってから次を送るよう求めており、応答前に次を送ると処理が競合して正しく反映されないことがあると書いています。同じ書類への呼び出しを並列にしないことは、レート制限より先に守るべき条件です。

180秒で504が返ってもサーバー側の処理は続くため、作成系の再実行前に一覧で確かめる

接続は最大180秒まで保たれ、超えると504が返ります。ただしサーバー側では、そのまま処理が続く仕様です。ここで書類の作成をそのまま再実行すると、同じ契約の下書きが2通できます。

504や接続断のあとは、作成を呼び直す前に GET /documents?status=0 で下書きの一覧を引き、タイトルに入れた受注番号で既存の書類を探します。見つかればその書類IDで続きの宛先差し替えから再開します。スクリプトでタイトルに受注番号を入れているのは、この照合のためです。作成・更新・削除の直後は反映に数秒〜10秒程度かかる場合があるとガイドにあり、直後の取得で古い内容が返ることも想定しておきます。

GET /documentsで締結済み書類を差分取得し、基幹へ同期する夜間ジョブ

最終処理日時のfromとtoで絞り、100件ずつpageを進める差分取得のコード

締結の知らせはWebhookで受けられますが、受信口の障害で取りこぼした分を拾う仕組みは別に要ります。GET /documents は from と to に最終処理日時(RFC3339)を渡して絞り込め、1ページ最大100件、page は1から始まります。範囲を超えたページを指定すると documents が空配列で返るので、それが取得を終える合図です。

def fetch_changed(cs, since, until):
    page = 1
    while True:
        res = cs.call("GET", "/documents", params={
            "status": 2, "from": since, "to": until, "page": page,
            "with_files": "n", "with_participants": "n"})
        if not res["documents"]:
            break
        for doc in res["documents"]:
            yield doc["id"], doc["last_processed_at"]
        page += 1

# 例:前回の実行時刻から今回の実行時刻まで(JST)
for doc_id, at in fetch_changed(cs, "2026-11-17T02:00:00+09:00", "2026-11-18T02:00:00+09:00"):
    print(doc_id, at)

ファイルと宛先の情報が不要なら with_files と with_participants に y 以外を渡すと応答が軽くなります。取り込んだ書類IDは、契約書管理側に未登録のものだけ締結PDFと合意締結証明書を取りに行きます。PDFの取得と冪等な格納、基幹の契約マスタへの書き戻しは契約書管理システムのAPI連携の実装手順に掲載したコードで確認可能です。

team_documentsの管理者権限要件とエンタープライズ・複数部署管理の利用制限

GET /documents が返すのは、APIを実行したユーザーが関係者に入っている書類だけです。営業担当が個別に送った書類まで含めてチーム全体を取り込みたいときは GET /team_documents を使います。

こちらは管理者権限を持つアカウントのクライアントIDでしか呼べず、複数部署管理機能を使うアカウントと Enterprise プランでは使えません。返る書類も先方確認中・締結済・取消または却下・インポート書類に限られ、下書きとテンプレートは入りません。親展書類を含めるには、親展書類管理の権限も必要です。連携用には人の異動に左右されない管理者の専用アカウントを用意し、そのクライアントIDを夜間ジョブに持たせます。

Webhookは署名が無く5xxのときだけ再送されるため、受信後にAPIで状態を取り直す

Webhook実行時の挙動には、本文が documentID・status・text などのJSONで届くこと、送信元IPが公開されていることが書かれています。一方で署名の仕組みについての記載は無く、2xxと4xxは成功扱い、5xxのときだけ10分間隔で最大3回再送されます。

受信口では送信元IPで絞り、通知の書類IDで GET /documents/{id} を呼んで状態を取り直します。一時的に処理できなかった通知に4xxを返すと二度と届かないので、その場合に返すべき応答は5xxです。再送が3回で尽きた分は、前のh3の夜間ジョブが拾います。受信側の冪等性の考え方はWebhookの受信側実装の解説にまとめています。

クラウドサイン APIを自前で実装する条件と、標準連携やiPaaSで済ませる場面の判断

受注番号で送る・入力値を業務データから埋める・締結結果を書き戻すなら自前で作る

自前のAPI実装に進む価値があるのは、次のどれかが要件に入る場合です。基幹やCRMの受注を起点に、受注番号つきで書類を自動で作って送りたい。金額・契約期間・管理番号をテンプレートへ業務データから埋めたい。締結結果を受注や請求の状態へ書き戻したい。3つとも、業務データの構造を知っている連携側でしか作れない処理です。

月に数百通を送る運用では、送信者の手入力を減らす効果も大きくなります。宛先の打ち間違いで取り消して作り直す手間は、APIで基幹の取引先マスタから宛先を埋めるだけで減らせます。

月数十通で書き戻しが無ければ見送り、iPaaSや手作業で足りる規模の目安

反対に、送信が月数十通、締結後の処理がPDFの保存とチャットへの通知だけなら、自前の実装は過剰です。トークン管理、429と504への備え、夜間の照合ジョブ、仕様変更への追従を抱えるわりに、削れる作業が少ないためです。利用ガイドによると、破壊的な仕様変更は技術担当者へ1か月以上前にメールで知らされますが、その連絡を受けて直す担当者を社内に置き続ける必要があります。

この規模なら、iPaaSのクラウドサイン連携か、管理画面でのテンプレート送信で十分です。電子契約サービスの乗り換えも含めて検討しているなら、電子契約システムの比較と選び方でAPIの有無を含む判断軸を先に整理してください。基幹やCRMから送信して締結結果を書き戻すところまで作る場合は、API開発・システム連携で、送信件数と書き戻し先を伺ったうえで構成をご提案します。

よくある質問

クラウドサイン APIを使い始める段階で、よく確認される点をまとめました。

クラウドサイン APIの認証にクライアントシークレットは必要ですか?

必要ありません。仕様書の POST /token が受け取るのは client_id だけで、OAuthのクライアントシークレットやリダイレクトの手順はありません。その分、クライアントIDの漏えいは、第三者がそのユーザーとして書類を作れる状態につながる問題です。IDは環境変数やシークレット管理に置き、漏れた疑いがあれば管理画面で新しいIDを発行して切り替えます。Business と Enterprise ではIPアドレス制限機能を併用でき、設定外のIPからの呼び出しは403になります。

サンドボックスで作ったテンプレートや書類を本番に移せますか?

移せません。利用ガイドには、サンドボックスと本番はデータベースもストレージも分かれており、テンプレート・書類・ユーザーは本番から移行できないと書かれています。本番では同じ雛形のテンプレートを管理画面で作り直し、その template_id を設定ファイルで環境ごとに切り替えます。入力項目をラベルで探す作りにしておくと、本番とサンドボックスでIDが違っていてもコードの共通利用が可能です。

過去の紙の契約書や他サービスで締結したPDFもAPIで取り込めますか?

POST /imported_documents で取り込めます。1回の要求で1ファイル、形式はPDFのみで、容量は50MBまでです。取り込んだ書類は status が13(インポート書類)になり、書類情報(attribute)に契約相手や契約期間を登録すれば、クラウドサインで締結した書類と同じ一覧で期限を管理できます。複数部署管理機能を使うアカウントでは、格納先のキャビネットを指定します。

自社のWeb画面の中で取引先に署名してもらうことはできますか?

この用途に対応する機能は組込み署名です。宛先に電話番号(tel)と callback を設定し、POST /documents/{id}/participants/{participantID}/signing_url で署名URLを取得すると、SMS認証で署名する画面を自社サービスから開けます。連携システム側の利用者ID(recipient_id)で本人を識別する簡易認証の方式もあります。どちらもチームの設定で有効になっていることが前提です。受け取り側の通常の操作手順は電子契約の送信側と受信側の締結手順で確認できます。

DocuSignなど海外の電子署名サービスのAPIとは何が違いますか?

大きな違いは認証とWebhookの真正性の確かめ方です。クラウドサインは client_id だけでトークンを取り、Webhookに署名はありません。DocuSignはJWTによる認証で、Connectの通知にHMAC署名を付けられます。宛先の順番を order で直接指定できない点も、クラウドサイン固有の作法です。DocuSign側の実装はDocuSign APIの実装手順にまとめています。

関連記事

お気に入りに入れた記事の一覧

一創の公式 SNS

X では毎朝の新着記事と IT ニュースの速報を、YouTube・TikTok・Instagram・LinkedIn・Facebook では記事の解説動画を配信しています。

この記事は以下の記事からリンクされています

資料請求

今日のトレンド記事 直近 24 時間で、いつもより多く読まれている記事

  1. 2026.11.18 テックブログ Java脆弱性CVE-2026-114938(Java4Shell)とは?影響版・修正版と回避フラグの実装手順
  2. 2026.11.17 テックブログ チャットプラスの不正アクセス:導入企業がチャット履歴の個人データと報告準備を確かめる手順
  3. 2025.08.05 コラム SXG(Signed Exchange)とは?仕組みと広まらなかった理由・2026年の撤去手順
  4. 2026.11.11 テックブログ JANISの不正アクセス:漏えい疑いは最大21,023名に拡大、停止中の参加登録の扱いと情報窃取プログラムの検知設定
  5. 2026.11.18 テックブログ 楽天証券の不正アクセス:最大約447万口座の対象確認と、テスト環境に本番データを置かない実装

RELATED POSTS 関連記事

目次