Box Developerドキュメント
ログイン

Box Signのリクエストの作成

ガイド Box Sign 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
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"
          }
     }'
.NET
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);
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(f'(Sign Request ID: {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}`);
iOS
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.

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

Prefill tags created in a template with the Box web app cannot be accessed from the API.

準備のオプション

ファイル

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

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

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

すべてのファイルタイプは、署名の処理のために.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アカウントを作成するオプションもあります。

Box Signは、リクエストで指定された署名者のメールアドレスに署名用メールを送信しようとするだけです。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では署名者がデフォルトのページにリダイレクトされます。

デフォルトのページには「すべての関係者がドキュメントでの作業を完了すると、期限が設定された最終版へのリンクがメールで届きます。また、Boxアカウントをお持ちの場合は、アカウントにコピーが保存されます。」と表示されます。署名者を別のページにリダイレクトする場合、この情報は署名者に表示されなくなります。

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

署名の順序は、指定された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フェーズが正常に完了しなかった。

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

ステータスの図