署名セッション
1人の署名者が、1件のドキュメントに、あなたのページの中で署名します。メールの往復も、サイト外へのリダイレクトもありません。
- ドキュメントを読み、自分のフィールドを入力し、手書き・入力・アップロードで署名
- 理由を添えて拒否でき、あなたのページはイベントとして受け取る
- 署名完了時に署名済みPDFをダウンロード
- フレーム内のメニューから言語を切り替え
仕組み
3つのステップ。シークレットキーはサーバーから出ません
埋め込みは、サーバーが発行するセッションから始まります。返されたURLをページがフレームで表示し、フレームは固定されたpostMessageチャネルであなたのコードと通信します。
- 1
サーバーでセッションを発行
シークレットキーで POST /embed_sessions を呼び、対象のドキュメントと、フレームを表示するページのオリジンを指定します。idと、期限付きのURLが返ります。
- 2
ページにマウント
URLを @gingerdocs/embed に渡します。SDKは当社オリジン上で署名体験をフレーム表示し、オリジンとセッションidを両端で固定し、型付きイベントをあなたのコードに渡します。
- 3
ウェブフックで処理
SDKのイベントはUXの合図です — スピナーを消し、確認画面を表示する用途に。実際の処理は署名付きの document.completed ウェブフックで行ってください。すべてのイベントは90日間読み出せます。
const res = await fetch('https://api.gingerdocs.com/api/v1/embed_sessions', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.GINGERDOCS_SECRET_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
kind: 'signing',
document_id: documentId,
host_origin: 'https://app.example.com',
}),
})
const { id, url } = await res.json()import { mount } from '@gingerdocs/embed'
const embed = mount('#signing', { url, sessionId: id })
embed.on('ready', () => hideLoader())
embed.on('completed', () => showConfirmation())
embed.on('session_expired', async () => {
const fresh = await refetchSession()
embed.reload(fresh.url, { sessionId: fresh.id })
})import { GingerDocsEmbed } from '@gingerdocs/react'
<GingerDocsEmbed
url={session.url}
sessionId={session.id}
onEvent={event => event.type === 'completed' && showConfirmation()}
/>URLはそのまま渡してください。フラグメントにはセッションの認証情報が、クエリにはどのページがフレーム表示できるかを当社のエッジが判断するための値が含まれています。
3つの埋め込み方法
1件の署名から、フルエディターまで
すべての埋め込みは、サーバーが発行するセッションです。その種類（kind）とモード（mode）がフレーム内の人ができることを決め、サーバーはUIだけでなくすべてのリクエストでそれを強制します。
ワークスペース · minimal
エディターを見せることなく、あなたのユーザーがテンプレートからドキュメントを作成できます。
- 利用できるテンプレートを選び、変数と自分の入力を記入
- 送信者と署名者を指定 — 事前設定やロックもあなたが行える
- 入力しながらページをプレビューし、作成して送信
- 自分のPDFをアップロードして送信 — 署名フィールドは自動配置
ワークスペース · advanced
GingerDocsアプリと同じエディターが、あなたのドメイン上で動きます。
- PDFをアップロードし、署名・イニシャル・テキスト・日付・チェックボックスのフィールドを配置
- 下書きを保存して、あとから再開
- PDFからテンプレートを作成し、自分が作ったテンプレートを編集
- minimalでできることはすべて含む
4つ目のモード read_only は、完了したドキュメントやテンプレートを操作なしで表示します — 自社UIに置けるビューワーです。
REST API
同じプロダクトを、エンドポイントとして
すべて https://api.gingerdocs.com/api/v1 配下で、Bearer形式のAPIキーで認証します。ユーザーを作成し、ドキュメントをアップロードし、送信し、何が起きたかを読み取る — 4回の呼び出しで、どの言語からでも。
前提にできる規約
- サーバー向けのシークレットキーと、読み取り専用のブラウザ向けパブリッシャブルキー — それぞれ必要な範囲（スコープ）に限定
- 完全に分離されたtestとliveの2環境を、同じエンドポイントで
- すべてのPOSTに Idempotency-Key を付ければ再試行は安全
- エラーには変わらない機械可読の code が付き、message は表示用で変更されうる
- キーごとに毎分120リクエスト、429時には Retry-After
- OpenAPI 3.1の契約で定義され、すべてのレスポンスがそれに対して検証される
curl https://api.gingerdocs.com/api/v1/account \
-H "Authorization: Bearer gd_sk_test_YOUR_KEY"{
"environment": "test",
"scopes": ["documents", "templates", "users", "embed", "webhooks"],
"plan": { "key": "free", "limit": 30, "used": 12, "remaining": 18 },
"defaults": { "email_delivery": "platform" }
}Users
ドキュメントの所有者となる、あなたのプロダクトのユーザー。あなた自身の external_id で管理します。
Documents
PDFをアップロードするかテンプレートから作成し、署名者を指定し、ステータスを追い、署名済みコピーをダウンロード。
Fields
署名・イニシャル・テキスト・日付・チェックボックスのフィールドを、正規化されたページ座標で配置。
Templates
アプリやadvancedワークスペースで作成したテンプレートを一覧・共有し、ドキュメントを生成。
Sending
当社が署名者にメールを送るか、あなたが署名リンクを自分で届けて当社は何も送らないかを選べます。
Webhooks & events
HTTPSエンドポイントを登録し、配信ログを読み、90日間のイベントログからどのイベントも再取得。
v1ではドキュメントごとの署名者は1人だけです — 受信者リストも、署名順序も、引き継ぎもありません。
本番運用のために
自分で作らなければならなかった部分
署名は簡単な半分です。残り — 配信、検証、再試行、ブランディング、多言語 — はプラットフォームに含まれています。
署名付きウェブフック、16種類のイベント
HMAC-SHA256で署名された配信に、再試行と配信ログ。すべてのイベントはイベントAPIから90日間読み出せるため、エンドポイントが停止している間も失われません。
メールを一切送らないテスト環境
テストキーはすべてのプランで使えます。出力には透かしが入り法的効力を持たず、プランの枚数も消費しません。テスト用エンドポイントで署名をシミュレートできるのでCIでCOMPLETEDを検証でき、テストデータは90日後に削除されます。
あなたのブランドカラー、あなたのビューポート
セッション発行時に theme.primary_color を渡すと、フレームのボタン・リンク・フォーカスリングがその色に従います。狭いサイドバーの埋め込みは、拡大ボタンでビューポート全体を使い、元に戻せます。
署名リンクを自分で届ける
アカウント単位または送信単位で、GingerDocsがあなたのブランドで署名者にメールを送るか、あなたのプロダクトが届けるかを選べます。後者なら当社は何も送らず、署名URLをお渡しします。
あなたの名前が記された証明書
リンクを自分で届けた場合や、埋め込みセッションで署名者を受け入れた場合、完了証明書には検証を行った当事者としてあなたの法人名が記載されます — インテグレーター利用条件で引き受ける責任です。
フレームは6言語に対応
署名フレームとワークスペースフレームは英語・日本語・韓国語・ドイツ語・スペイン語・フランス語で提供。セッションまたはマウント時に言語を指定でき、署名者はフレーム内のメニューから切り替えられます。
オープンソース
MITライセンスの小さなSDKが2つ
SDKの役割はひとつ。セッションURLをフレーム表示し、postMessageチャネルの両端でオリジンとセッションidを固定し、型付きイベントをあなたのコードに渡すこと。一度で読み切れる大きさです。
MITライセンスgzip圧縮で1.5 KB未満依存関係ゼロ
開発者向け料金
無料で構築。本番は年額$100。
Developerプランで本番へ
$100/ 年
Proのすべてと同じ月1,000件のドキュメントアップロードに加え、ライブAPIキー、登録ドメインでの埋め込み署名、署名付きウェブフック。
Developerプランを見る