Box Signのリクエストの作成
Box Signのリクエストの作成
Box Signのリクエストを作成するには、少なくとも、署名が必要なファイル、署名済みドキュメント/署名ログの保存先フォルダ、署名者が必要です。
curl -i -X POST "https://api.box.com/2.0/sign_requests" \
-H "authorization: Bearer <ACCESS_TOKEN>" \
-d '{
"signers": [
{
"role": "signer",
"email": "example_email@box.com"
}
],
"source_files": [
{
"type": "file",
"id": "123456789"
}
],
"parent_folder":
{
"type": "folder",
"id": "0987654321"
}
}'
await client.signRequests.createSignRequest({
signers: [
{
email: signerEmail,
suppressNotifications: true,
declinedRedirectUrl: 'https://www.box.com',
embedUrlExternalUserId: '123',
isInPerson: false,
loginRequired: false,
password: 'password',
role: 'signer' as SignRequestCreateSignerRoleField,
} satisfies SignRequestCreateSigner,
],
areRemindersEnabled: true,
areTextSignaturesEnabled: true,
daysValid: 30,
declinedRedirectUrl: 'https://www.box.com',
emailMessage: 'Please sign this document',
emailSubject: 'Sign this document',
externalId: '123',
externalSystemName: 'BoxSignIntegration',
isDocumentPreparationNeeded: false,
name: 'Sign Request',
parentFolder: new FolderMini({ id: destinationFolder.id }),
redirectUrl: 'https://www.box.com',
prefillTags: [
{
dateValue: dateFromString('2035-01-01'),
documentTagId: '0',
} satisfies SignRequestPrefillTag,
],
sourceFiles: [new FileBase({ id: fileToSign.id })],
} satisfies SignRequestCreateRequest);
client.sign_requests.create_sign_request(
[
SignRequestCreateSigner(
email=signer_email,
suppress_notifications=True,
declined_redirect_url="https://www.box.com",
embed_url_external_user_id="123",
is_in_person=False,
login_required=False,
password="password",
role=SignRequestCreateSignerRoleField.SIGNER,
)
],
source_files=[FileBase(id=file_to_sign.id)],
parent_folder=FolderMini(id=destination_folder.id),
is_document_preparation_needed=False,
redirect_url="https://www.box.com",
declined_redirect_url="https://www.box.com",
are_text_signatures_enabled=True,
email_subject="Sign this document",
email_message="Please sign this document",
are_reminders_enabled=True,
name="Sign Request",
prefill_tags=[
SignRequestPrefillTag(
date_value=date_from_string("2035-01-01"), document_tag_id="0"
)
],
days_valid=30,
external_id="123",
external_system_name="BoxSignIntegration",
)
await client.SignRequests.CreateSignRequestAsync(requestBody: new SignRequestCreateRequest(signers: Array.AsReadOnly(new [] {new SignRequestCreateSigner() { Email = signerEmail, SuppressNotifications = true, DeclinedRedirectUrl = "https://www.box.com", EmbedUrlExternalUserId = "123", IsInPerson = false, LoginRequired = false, Password = "password", Role = SignRequestCreateSignerRoleField.Signer }}), areRemindersEnabled: true, areTextSignaturesEnabled: true, daysValid: 30, declinedRedirectUrl: "https://www.box.com", emailMessage: "Please sign this document", emailSubject: "Sign this document", externalId: "123", externalSystemName: "BoxSignIntegration", isDocumentPreparationNeeded: false, name: "Sign Request", parentFolder: new FolderMini(id: destinationFolder.Id), redirectUrl: "https://www.box.com", prefillTags: Array.AsReadOnly(new [] {new SignRequestPrefillTag() { DateValue = Utils.DateFromString(date: "2035-01-01"), DocumentTagId = "0" }}), sourceFiles: Array.AsReadOnly(new [] {new FileBase(id: fileToSign.Id)})));
List<BoxSignRequestFile> files = new ArrayList<BoxSignRequestFile>();
BoxSignRequestFile file = new BoxSignRequestFile("12345");
files.add(file);
// you can also use specific version of the file
BoxFile file = new BoxFile(api, "12345");
List<BoxFileVersion> versions = file.getVersions();
BoxFileVersion firstVersion = versions.get(0);
BoxSignRequestFile file = new BoxSignRequestFile(firstVersion.getFileID(), firstVersion.getVersionID());
List<BoxSignRequestSigner> signers = new ArrayList<BoxSignRequestSigner>();
BoxSignRequestSigner newSigner = new BoxSignRequestSigner("signer@mail.com");
signers.add(newSigner);
String destinationParentFolderId = "55555";
BoxSignRequest.Info signRequestInfo = BoxSignRequest.createSignRequest(api, files,
signers, destinationParentFolderId);
source_file = {
'id': '12345',
'type': 'file'
}
files = [source_file]
signer = {
'name': 'John Doe',
'email': 'signer@mail.com'
}
signers = [signer]
parent_folder_id = '123456789'
new_sign_request = client.create_sign_request_v2(signers, files=files, parent_folder_id=parent_folder_id)
print(f'(Sign Request ID: {new_sign_request.id})')
var sourceFiles = new List<BoxSignRequestCreateSourceFile>
{
new BoxSignRequestCreateSourceFile()
{
Id = "12345"
}
};
var signers = new List<BoxSignRequestSignerCreate>
{
new BoxSignRequestSignerCreate()
{
Email = "example@gmail.com"
}
};
var parentFolder = new BoxRequestEntity()
{
Id = "12345",
Type = BoxType.folder
};
var request = new BoxSignRequestCreateRequest
{
SourceFiles = sourceFiles,
Signers = signers,
ParentFolder = parentFolder
};
BoxSignRequest signRequest = await client.SignRequestsManager.CreateSignRequestAsync(request);
const signRequest = await client.signRequests.create({
signers: [
{
role: 'signer',
email: 'user@example.com',
},
],
source_files: [
{
type: 'file',
id: '12345',
},
],
parent_folder: {
type: 'folder',
id: '1234567',
},
});
console.log(`Created a new sign request id ${signRequest.id}`);
let signers = [SignRequestCreateSigner(email: "signer@mail.com", role: .approver)]
let sourceFiles = [SignRequestCreateSourceFile(id: "12345"), SignRequestCreateSourceFile(id: "34567")]
let parentFolder = SignRequestCreateParentFolder(id: "234")
client.signRequests.create(signers: signers, sourceFiles: sourceFiles, parentFolder: parentFolder) { (result: Result<SignRequest, BoxSDKError>) in
guard case let .success(signRequest) = result else {
print("Error creating sign request")
return
}
print("Sign request \(signRequest.id) was created")
}
ドキュメントの準備
Box Signのリクエストを送信する前にドキュメントを準備することで、開発者は署名者のために日付、テキスト、チェックボックス、署名のプレースホルダを追加できます。これを行うには、UIを使用するか、ドキュメント内で直接タグを使用します。準備を行わなかった場合、署名者には準備が完了していないドキュメントが送信されるため、署名者の判断で署名やフィールドを配置できます。ただし、開発者は、準備が完了していないドキュメントの機能をオンまたはオフにするためのコントロールをリクエスト内で利用できます。
is_document_preparation_needed
をtrue
に設定すると、レスポンスでprepare_url
が返されます。ブラウザでこのリンクにアクセスすると、ドキュメントの準備を完了し、UI上でリクエストを送信できます。
ドキュメントのタグの詳細については、サポート記事を参照してください。
ファイル
Box Signの各リクエストは、署名が必要なファイルから始まります。そのファイルがまだBoxに存在しない場合は、リクエストを作成する前に、別のAPIコールでファイルをアップロードする必要があります。1つのリクエストで複数のファイルに署名できます。リクエストに含まれる最初のファイルのファイルIDをsource_files
本文パラメータで指定します。
サポートされているファイルタイプは以下のとおりです。
すべてのファイルタイプは、署名の処理のために.pdf
に変換されます。この変換後のドキュメントは、リクエストの送信が成功した場合にparent_folder
で見つかります。つまり、元のファイルタイプに関係な く、最終的な署名済みドキュメントは.pdf
になります。各署名者がリクエストを完了すると、Box Signにより新しいファイルバージョンが自動的に追加されます。
ファイルサイズの上限は、アカウントの種類によって決まります。詳細については、アップロードガイドを参照してください。
親フォルダ
parent_folder
本文パラメータで指定されたフォルダIDによって、最終的な署名済みドキュメントと署名ログの保存先が決まります。このフォルダには、フォルダID 0
で表される [すべてのファイル] やルートレベルを指定することができません。
署名者
各署名者には、役割として、signer
、approver
、またはfinal copy_reader
を割り当てる必要があります。
リクエスト送信者に役割が指定されていない場合は、final_copy_reader
という役割の署名者が自動的に作成されます。つまり、最終的な署名済みドキュメントと署名ログのコピーを受信するだけです。
署名者は、ドキュメントに署名するために、既存のBoxアカウントを持っている必要も、アカウントを作成する必要もありません。他のAPIエンドポイントとは異なり、署名者はBox user_id
ではなくメールアドレスを使用して招待されます。
必要に応じて、署名者は、リクエストに署名する前にBoxにログインできます。その場合は、署名者のlogin_required
パラメータをtrue
に設定します。署名者が既存のアカウントを所有していない場合は、無料Boxアカウントを作成するオプションもあります。
入力
inputs
パラメータは、ユーザーが操作できるプレースホルダを表します。document_tag_id
パラメータには、署名リクエストの作成時に渡すデータを設定できます。
テンプレート
署名リクエストは、テンプレートを使用して作成できます。そのためには、template_id
パラメータを指定する必要があります。署名リクエスト作成時のテンプレートの使用の詳細については、こちらのガイドを参照してください。
リダイレクト
redirect_url
およびdeclined_redirect_url
で指定したURLにより、署名するか署名リクエストを拒否した署名者をカスタムランディングページにリダイレクトすることができます。たとえば、アプリケーションをBox Signと統合した場合は、署名者をアプリケーションにリダイレクトすることもカスタムランディングページにリダイレクトすることもできます。リダイレクトURLは、すべての署名者を対象にグローバルに設定することも、特定の署名者のみを対象に設定することもできます。つまり、Box Signでは、選択した署名者に特定のURLを使用し、残りの署名者にグローバルな設定を使用します。リダイレクトURLを設定しなかった場合、Box Signでは署名者がデフォルトのページにリダイレクトされます。
複数の署名者と署名の順序
署名の順序は、指定されたorder
の数値を小さいものから大きいものへ順序付けすることで決まります。2つの数値が同じ場合、署名者には同時にリクエストが届きます。
最初は、割り当てられたorder
の数値が最も小さい署名者だけに、Box Signのリクエストメールが送信されます。その署名者が署名すると、次のユーザーにメールが送信される、というように進んでいきます。Box Signでは、ユーザーが署名するたびに、ドキュメントの新しいバージョンがparent_folder
に自動的に追加されます。
いずれかの署名者が拒否した場合、残りの署名者にBox Signのリクエストメールが送信されません。リクエスト全体が拒否されます。
リクエストのステータス
converting
: 署名リクエストが送信された後、ファイルが署名プロセスのために.pdf
に変換されている。error_converting
: ファイルを.pdf
に変換している間に問題が発生した。created
:document_preparation_is_needed
がtrue
に設定されているが、prepare_url
がまだアクセスされていない。sent
: リクエストが正常に送信されたが、どの署名者も対応していない。error_sending
: リクエストを送信中に問題が発生した。viewed
: 最初 (または唯一) の署名者が署名用メールの [ドキュメントをレビュー] をクリックするか、署名用URLにアクセスした。downloaded
: 署名者が署名用ドキュメントをダウンロードした。signed
: すべての署名者がリクエストの処理を完了した。signed and downloaded
: 署名者が署名用ドキュメントに署名してダウンロードした。declined
: いずれかの署名者がリクエストを拒否した。cancelled
: リクエストがUIまたはAPIを介してキャンセルされた。expired
: 署名が未完了、不十分のまま、有効期限が過ぎた。finalizing
: すべての署名者がリクエストに署名済みでも、署名された最終的なドキュメントと署名ログがまだ生成されていない。error_finalizing
:finalizing
フェーズが正常に完了しなかった。
エラーステータスになった場合、再試行するには、新しい署名リクエストを作成する必要があります。