Box Developerドキュメント

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"
          }
     }'
TypeScript Gen
await client.signRequests.createSignRequest({
  signers: [
    {
      email: signer1Email,
      signerGroupId: 'user',
    } satisfies SignRequestCreateSigner,
    {
      email: signer2Email,
      signerGroupId: 'user',
    } satisfies SignRequestCreateSigner,
  ],
  parentFolder: new FolderMini({ id: destinationFolder.id }),
  sourceFiles: [new FileBase({ id: fileToSign.id })],
} satisfies SignRequestCreateRequest);
Python Gen
client.sign_requests.create_sign_request(
    [
        SignRequestCreateSigner(email=signer_1_email, signer_group_id="user"),
        SignRequestCreateSigner(email=signer_2_email, signer_group_id="user"),
    ],
    source_files=[FileBase(id=file_to_sign.id)],
    parent_folder=FolderMini(id=destination_folder.id),
)
.NET Gen
await client.SignRequests.CreateSignRequestAsync(requestBody: new SignRequestCreateRequest(signers: Array.AsReadOnly(new [] {new SignRequestCreateSigner() { Email = signer1Email, SignerGroupId = "user" },new SignRequestCreateSigner() { Email = signer2Email, SignerGroupId = "user" }}), parentFolder: new FolderMini(id: destinationFolder.Id), sourceFiles: Array.AsReadOnly(new [] {new FileBase(id: fileToSign.Id)})));
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_v2(signers, files=files, parent_folder_id=parent_folder_id)
print(f'(Sign Request ID: {new_sign_request.id})')
.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);
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")
}

公開APIを使用したCFR Part 11の署名リクエストの作成はサポートされていません。詳細については、21 CFR Part 11コンプライアンスのサポートを参照してください。

ドキュメントの準備

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

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

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

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

準備のオプション

ファイル

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

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

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

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

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

親フォルダ

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

署名者

各署名者には、役割として、signerapprover、またはfinal copy_readerを割り当てる必要があります。

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

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

必要に応じて、署名者は、リクエストに署名する前にBoxにログインできます。その場合は、署名者のlogin_requiredパラメータをtrueに設定します。署名者が既存のアカウントを所有していない場合は、無料Boxアカウントを作成するオプションもあります。

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

入力

inputsパラメータは、ユーザーが操作できるプレースホルダを表します。document_tag_idパラメータには、署名リクエストの作成時に渡すデータを設定できます。

テンプレート

署名リクエストは、テンプレートを使用して作成できます。そのためには、template_idパラメータを指定する必要があります。署名リクエスト作成時のテンプレートの使用の詳細については、こちらのガイドを参照してください。

リダイレクト

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_neededtrueに設定されているが、prepare_urlがまだアクセスされていない。
  • sent: リクエストが正常に送信されたが、どの署名者も対応していない。
  • error_sending: リクエストを送信中に問題が発生した。
  • viewed: 最初 (または唯一) の署名者が署名用メールの [ドキュメントをレビュー] をクリックするか、署名用URLにアクセスした。
  • downloaded: 署名者が署名用ドキュメントをダウンロードした。
  • signed: すべての署名者がリクエストの処理を完了した。
  • signed and downloaded: 署名者が署名用ドキュメントに署名してダウンロードした。
  • declined: いずれかの署名者がリクエストを拒否した。
  • cancelled: リクエストがUIまたはAPIを介してキャンセルされた。
  • expired: 署名が未完了、不十分のまま、有効期限が過ぎた。
  • finalizing: すべての署名者がリクエストに署名済みでも、署名された最終的なドキュメントと署名ログがまだ生成されていない。
  • error_finalizing: finalizingフェーズが正常に完了しなかった。

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

ステータスの図