Box Signのリクエストの作成

ガイド Box Sign Box Signのリクエストの作成

Box Signのリクエストの作成

Box Signのリクエストを作成エンドポイントを使用するには、少なくとも、署名用ファイルのほか、署名済みドキュメント/署名ログの保存先フォルダを選択し、署名者を指定する必要があります。

cURL
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"
          }
     }'
Java
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);
Python
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('(Sign Request ID: {0})'.format(new_sign_request.id))
Node
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}`);

ファイル

Box Signの各リクエストは、署名が必要なファイルから始まります。そのファイルがまだBoxに存在しない場合は、リクエストを作成する前に、別のAPI呼び出しでファイルをアップロードする必要があります。現時点では、1つのリクエストにつき署名できるファイルは1つだけです。このファイルIDは、source_files本文パラメータで指定されます。

送信者は、Box内のファイルに対してダウンロード権限を持っている必要があります。この要件を満たしているかどうかを確認するには、コラボレーションレベルを確認してください。

サポートされているファイルタイプは以下のとおりです。

すべてのファイルタイプは、署名の処理のために.pdfに変換されます。この変換後のドキュメントは、リクエストの送信が成功した場合は、parent_folderに見つかります。つまり、元のファイルタイプに関係なく、最終的な署名済みドキュメントは.pdfになります。各署名者がリクエストを完了すると、Box Signにより新しいファイルバージョンが自動的に追加されます。

ファイルサイズの上限は、アカウントの種類によって決まります。詳細については、アップロードガイドを参照してください。

親フォルダ

parent_folder本文パラメータで指定されたフォルダIDによって、最終的な署名済みドキュメントと署名ログの保存先が決まります。このフォルダには、フォルダID 0で表される [すべてのファイル] やルートレベルを指定することができません。

署名者

各署名者には、役割として、署名者、承認者、または最終的なコピー受信者を割り当てる必要があります。

送信者に役割が指定されていない場合は、final_copy_readerという役割の署名者が自動的に作成されます。つまり、最終的な署名済みドキュメントと署名ログのコピーを受信するだけです。

署名者は、ドキュメントに署名するために、既存のBoxアカウントを持っている必要も、アカウントを作成する必要もありません。他のAPIエンドポイントとは異なり、署名者はBox user_idではなくメールアドレスを使用して招待されます。

Box Signは、リクエストで指定された署名者のメールアドレスに署名用メールを送信しようとするだけです。Boxユーザーの場合、指定しない限り、メールエイリアスは含まれません。指定された署名者のメールアドレスすべてが有効であることを再確認してください。

複数の署名者と署名の順序

署名の順序は、指定されたorderの数値を小さいものから大きいものへ順序付けすることで決まります。2つの数値が同じ場合、署名者には同時にリクエストが届きます。

最初は、割り当てられたorderの数値が最も小さい署名者だけに、Box Signのリクエストメールが送信されます。その署名者が署名すると、次のユーザーにメールが送信される、というように進んでいきます。Box Signでは、ユーザーが署名するたびに、ドキュメントの新しいバージョンがparent_folderに自動的に追加されます。

いずれかの署名者が拒否した場合、残りの署名者にBox Signのリクエストメールが送信されません。リクエスト全体が拒否されます。

複数の署名者のフロー

ドキュメントの準備

Box Signのリクエストを送信する前にドキュメントを準備することで、開発者は署名者のために日付、テキスト、チェックボックス、署名のプレースホルダを追加できます。これを実行するには、UIを使用するか、ドキュメント内で直接タグを使用します。これを実行しなかった場合、署名者には準備が完了していないドキュメントが送信されるため、署名者の判断で署名やフィールドを配置できます。ただし、開発者は、準備が完了していないドキュメントの機能をオンまたはオフにするためのコントロールをリクエスト内で利用できます。

is_document_preparation_neededtrueに設定すると、レスポンスでprepare_urlが返されます。ブラウザでこのリンクにアクセスすると、ドキュメントの準備を完了し、UIを使用してリクエストを送信できます。

ドキュメントのタグの詳細については、サポート記事を参照してください。

Boxウェブアプリを使用してテンプレートに作成された事前入力タグには、APIからアクセスできません。

準備のオプション

リクエストのステータス

  • converting: リクエストが送信された後、ファイルが署名プロセスのために.pdfに変換されている
  • created: document_preparation_is_neededtrueに設定されているが、prepare_urlがまだアクセスされていない場合
  • sent: リクエストが正常に送信されたが、どの署名者も対応していない
  • viewed: 最初 (または唯一) の署名者が署名用メールの [ドキュメントをレビュー] をクリックするか、署名用URLにアクセスした場合
  • signed: すべての署名者がリクエストの処理を完了した
  • cancelled: リクエストがUIまたはAPIを介してキャンセルされた場合
  • declined: いずれかの署名者がリクエストを拒否した場合
  • error_converting: ファイルを.pdfに変換している間に問題が発生した
  • error_sending: リクエストを送信中に問題が発生した
  • expired: 署名が未完了、不十分のまま、有効期限が過ぎた

エラーステータスになった場合、再試行するには、新しい署名リクエストを作成する必要があります。

ステータスの図