Box Signのリクエストの作成
Box Signのリクエストの作成
At minimum, to create Box Sign request you need the a file you want to be signed, a destination folder for the signed document/signing log, and signers.
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"
}
}'
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);
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(files, signers, parent_folder_id)
print(f'(Sign Request ID: {new_sign_request.id})')
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")
}
ドキュメントの準備
Preparing a document prior to sending a Box Sign request allows developers to add date, text, checkbox, and/or signature placeholders for signers. This can be done with UI or tags directly in the document. If this is not done, signers receive an unprepared document and can place signatures and fields at their own discretion. However, developers can leverage controls in the request that allow them to turn features for the unprepared document on and off.
Setting is_document_preparation_needed
to true
provides a prepare_url
in the response. Visiting this link in your browser allows you to complete document preparation and send the request in the UI.
ドキュメントのタグの詳細については、サポート記事を参照してください。
ファイル
Box Signの各リクエストは、署名が必要なファイルから始まります。そのファイルがまだBoxに存在しない場合は、リクエストを作成する前に、別のAPI呼び出しでファイルをアップロードする必要があります。1つのリクエストで複数のファイルに署名できます。リクエストに含まれる最初のファイルのファイルIDをsource_files
本文パラメータで指定します。
サポートされているファイルタイプは以下のとおりです。
すべてのファイルタイプは、署名の処理のために.pdf
に変換されます。この変換後のドキュメントは、リクエストの送信が成功した場合は、parent_folder
に見つかります。つまり、元のファイルタイプに関係なく、最終的な署名済みドキュメントは.pdf
になります。各署名者がリクエストを完了すると、Box Signにより新しいファイルバージョンが自動的に追加されます。
ファイルサイズの上限は、アカウントの種類によって決まります。詳細については、アップロードガイドを参照してください。
親フォルダ
parent_folder
本文パラメータで指定されたフォルダIDによって、最終的な署名済みドキュメントと署名ログの保存先が決まります。このフォルダには、フォルダID 0
で表される [すべてのファイル] やルートレベルを指定することができません。
署名者
Each signer must be assigned a role: signer
, approver
, or final copy_reader
.
リクエスト送信者に役割が指定されていない場合は、final_copy_reader
という役割の署名者が自動的に作成されます。つまり、最終的な署名済みドキュメントと署名ログのコピーを受信するだけです。
署名者は、ドキュメントに署名するために、既存のBoxアカウントを持っている必要も、アカウントを作成する必要もありません。他のAPIエンドポイントとは異なり、署名者はBox user_id
ではなくメールアドレスを使用して招待されます。
必要に応じて、署名者は、リクエストに署名する前にBoxにログインできます。その場合は、署名者のlogin_required
パラメータをtrue
に設定します。署名者が既存のアカウントを所有していない場合は、無料Boxアカウントを作成するオプションもあります。
Inputs
The inputs
parameter represents placeholders that the user can interact with. The document_tag_id
parameter can be populated with data you want to pass when creating a sign request.
テンプレート
You can create a sign request using a template. To do so, you must provide the template_id
parameter. See this guide to learn more about using templates when creating sign requests.
リダイレクト
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
フェーズが正常に完了しなかった。
エラーステータスになった場合、再試行するには、新しい署名リクエストを作成する必要があります。