docuseal-code

リファレンスの構成

リファレンスファイルは、references/ 以下の2つのサブディレクトリにあります。

• references/embed/ — 埋め込みUIコンポーネント（署名フォーム、テンプレートビルダー）。各ファイルは単独で完結しているため、ユーザーのスタックに合ったものだけを読み込んでください。
• references/api/ — REST API エンドポイントとウェブフック。各エンドポイント／ウェブフックにつき1ファイルで、パラメーター、スキーマ、コード例、レスポンスのサンプルを記載しています。

埋め込みUIコンポーネント

コンポーネント	タグ	目的	JWT
署名フォーム	<docuseal-form>	ページに文書署名UIを埋め込みます	任意
フォームビルダー	<docuseal-builder>	完全なテンプレート／文書ビルダーを埋め込みます	必須

各コンポーネントには、4種類のフロントエンド実装が用意されています。JavaScript / React / Vue / Angular。

署名フォーム（<docuseal-form>）

• JavaScript / HTML → references/embed/signing-form-js.md
• React → references/embed/signing-form-react.md
• Vue → references/embed/signing-form-vue.md
• Angular → references/embed/signing-form-angular.md
• モバイル（WebView 経由の Android/iOS/React Native/Flutter）→ references/embed/signing-form-mobile-integration.md

フォームビルダー（<docuseal-builder>）

• JavaScript / HTML → references/embed/form-builder-js.md
• React → references/embed/form-builder-react.md
• Vue → references/embed/form-builder-vue.md
• Angular → references/embed/form-builder-angular.md

メインコンポーネントのリファレンスを読み込んだ後、## Guides セクションのリンクから、手順ごとのガイドを参照してください。

横断的な項目

• JWT トークンの生成 — フォームビルダー（Node/TypeScript/Ruby/Python/PHP/Java/C#/Go）→ references/embed/form-builder-jwt-token.md
• JWT トークンの生成 — 署名フォームの完了／プレビューモード → references/embed/signing-form-completed-preview-jwt-token.md
• EU Cloud／セルフホスト可能な環境の host 設定 — 署名フォーム → references/embed/signing-form-hosts.md
• EU Cloud／セルフホスト可能な環境の host 設定 — フォームビルダー → references/embed/form-builder-hosts.md
• カスタムCSSのテーマ設定 — 署名フォーム（ダークテーマのリファレンス）→ references/embed/signing-form-custom-css.md
• カスタムCSSのテーマ設定 — フォームビルダー（ダークテーマのリファレンス）→ references/embed/form-builder-custom-css.md
• 署名フォームのセキュリティに関する推奨事項 → references/embed/signing-form-security-recommendations.md
• フォームビルダーのセキュリティに関する推奨事項 → references/embed/form-builder-security-recommendations.md

パッケージ

フレームワーク	パッケージ	CDN
JavaScript	—	https://cdn.docuseal.com/js/form.js, https://cdn.docuseal.com/js/builder.js
React	@docuseal/react	—
Vue	@docuseal/vue	—
Angular	@docuseal/angular	—
React Native	react-native-webview を使用（ネイティブSDKなし）	—
Flutter	webview_flutter を使用（ネイティブSDKなし）	—

よくある埋め込み時の間違い

#	間違い	修正方法
1	ブラウザーで JWT を生成する	JWT は バックエンド で署名する必要があります。API キーをクライアントに送信してはいけません。form-builder-jwt-token.md / signing-form-completed-preview-jwt-token.md を参照してください。
2	API キーを data-token として渡す	data-token に設定するのは、API キー で署名された JWT であり、API キーそのものではありません。
3	EU またはセルフホスト環境で host / data-host を設定しない	EU Cloud の場合は data-host="cdn.docuseal.eu" を、セルフホストの場合は独自のホスト名を設定してください。signing-form-hosts.md / form-builder-hosts.md を参照してください。
4	/d/{slug} と /s/{slug} を混同する	/d/{slug} はテンプレート URL です（署名者が 1 人のテンプレート）。/s/{slug} は、/submissions API で作成された個別の署名者 URL です。
5	複数当事者のテンプレートに data-src URL を使用する	署名者が複数いるテンプレートは、/submissions API 経由で開始する必要があります。直接指定する /d/{slug} URL が機能するのは、署名者が 1 人のテンプレートのみです。
6	HTML で camelCase のプロパティを使用する	Web コンポーネントでは data-* のケバブケース属性を使用します。camelCase のプロパティを使用するのは React、Vue、Angular のみです。
7	ネイティブのモバイル SDK があると期待する	ネイティブのモバイル SDK はありません。WebView で埋め込んでください。signing-form-mobile-integration.md を参照してください。
8	customCss にスタイルシートのリンクを渡す	customCss / data-custom-css に渡すのは CSS 文字列であり、URL ではありません。signing-form-custom-css.md / form-builder-custom-css.md を参照してください。
9	推測可能な URL の背後に署名フォームを埋め込む	DocuSeal のスラッグはランダムですが、https://yourapp.com/contracts/123/sign のような埋め込みページでは、攻撃者が整数 ID を順に試して、他のユーザーの署名フォームにアクセスできてしまいます。DocuSeal のスラッグまたは UUID を URL に含めるか、埋め込みページに認証を必須にしてください。signing-form-security-recommendations.md を参照してください。
10	認証なしでフォームビルダーを公開する	<docuseal-builder> をレンダリングするページには、アプリの認証を適用する必要があります。JWT 発行エンドポイントでは、リクエストしたユーザーが external_id で参照されるテンプレートを所有していることを確認してください。そうしないと、ログイン済みのユーザーなら誰でも任意のテンプレートを編集できてしまいます。form-builder-security-recommendations.md を参照してください。
11	クライアント側の completed イベントに基づいて処理する	ブラウザーイベントは偽装できます。<docuseal-form> の JavaScript コールバックではなく、HMAC 検証を行った form.completed Webhook に基づいて状態を変更してください。signing-form-security-recommendations.md を参照してください。

REST API

認証

すべてのリクエストでは、X-Auth-Token ヘッダーで API キーを渡す必要があります。

X-Auth-Token: YOUR_API_KEY

API キーはこちらから取得できます：https://console.docuseal.com/api

ベース URL

環境	ベース URL
グローバル Cloud	https://api.docuseal.com
EU Cloud	https://api.docuseal.eu
セルフホスト	https://docuseal.yourdomain.com/api

API クライアント SDK

公式 SDK ライブラリは REST API をラップし、認証、リクエストの構築、レスポンスの解析を処理します。ユーザーの使用言語に対応する SDK がある場合は、生の HTTP より SDK を優先してください。

言語	パッケージ	インストール
JavaScript / TypeScript	@docuseal/api	npm install @docuseal/api
Python	docuseal	pip install docuseal
Ruby	docuseal	gem install docuseal
PHP	docusealco/docuseal	composer require docusealco/docuseal

各エンドポイントのリファレンスファイルには、SDK の使用例が含まれています（見出しに「SDK」と記載されています）。

エンドポイント

テンプレート

• GET /templates — すべてのテンプレートを一覧表示
• GET /templates/{id} — テンプレートを取得
• DELETE /templates/{id} — テンプレートをアーカイブ
• PUT /templates/{id} — テンプレートを更新
• PUT /templates/{id}/documents — テンプレートのドキュメントを更新
• POST /templates/{id}/clone — テンプレートを複製
• POST /templates/html — HTML からテンプレートを作成
• POST /templates/docx — DOCX からテンプレートを作成
• POST /templates/pdf — PDF からテンプレートを作成
• POST /templates/merge — テンプレートを結合

提出

• GET /submissions — すべての提出を一覧表示
• GET /submissions/{id} — 提出を取得
• GET /submissions/{id}/documents — 提出書類を取得
• DELETE /submissions/{id} — 提出をアーカイブ
• PUT /submissions/{id} — 提出を更新
• POST /submissions/emails — メールから提出を作成
• POST /submissions/pdf — PDF から提出を作成
• POST /submissions/docx — DOCX から提出を作成
• POST /submissions/html — HTML から提出を作成
• POST /submissions — 提出を作成

提出者

• GET /submitters/{id} — 提出者を取得
• PUT /submitters/{id} — 提出者を更新
• GET /submitters — すべての提出者を一覧表示

Webhook

• フォーム Webhook
• 提出 Webhook
• テンプレート Webhook

Webhook URL を設定：https://console.docuseal.com/webhooks

セットアップ、シークレット、HMAC 署名の検証、ローカル開発 → references/api/use-webhooks.md

一般的な API パターン

1. 署名用にドキュメントを送信する： テンプレートを作成（または既存のものを使用）→ 提出者のメールアドレスを指定して POST /submissions → 提出者に署名リンクが届きます
2. アプリに署名を埋め込む： send_email: false を指定して提出を作成 → 返された slug を <docuseal-form> で使用します（上記の UI コンポーネントの埋め込みを参照）
3. 事前入力して自動署名する： fields[].default_value と completed: true を指定して POST /submissions
4. 完了状況を追跡する： GET /submissions/{id} をポーリングするか、form.completed の Webhook を設定します
5. 署名済みドキュメントをダウンロードする： GET /submissions/{id}/documents は PDF の URL を返します

クイック判断フロー

1. コンポーネントを埋め込みますか？ → Signing Form または Form Builder → references/embed/ から読み込みます。
2. API を呼び出しますか？ → 使用言語に SDK（JS/TS、Python、Ruby、PHP）があるか確認し、生の HTTP より優先します。該当するエンドポイントを references/api/ から読み込みます。
3. 埋め込み方法についての質問ですか？ コンポーネントのリファレンスにある ## Guides セクションのリンクをたどります。
4. モバイルですか？ references/embed/signing-form-mobile-integration.md を読み込みます。
5. JWT が必要ですか？ Form Builder では常に必要です。references/embed/form-builder-jwt-token.md を読み込みます。Signing Form では data-token を使用する場合（プレビュー／完了モード）のみ必要です。references/embed/signing-form-completed-preview-jwt-token.md を読み込みます。
6. docuseal.com 以外を使用していますか？ コンポーネントに応じて、references/embed/signing-form-hosts.md または references/embed/form-builder-hosts.md を読み込みます。
7. カスタムテーマを使用しますか？ コンポーネントに応じて、references/embed/signing-form-custom-css.md または references/embed/form-builder-custom-css.md を読み込みます。
8. 認証、URL の処理、Webhook の検証、またはセキュリティに関わる埋め込みを行いますか？ コンポーネントに応じて、references/embed/signing-form-security-recommendations.md または references/embed/form-builder-security-recommendations.md を読み込みます。
9. CLI コマンドですか？ 同じリポジトリにある兄弟の docuseal-cli スキルを読み込みます。