Box Developerドキュメント

Box Signリクエストを作成

post
https://api.box.com/2.0
/sign_requests

署名リクエストを作成します。これには、署名用ドキュメントの準備と署名者への署名リクエストの送信が含まれます。

リクエスト

bearer [ACCESS_TOKEN]
application/json

リクエスト本文

boolean本文内省略可能
true

3、8、13、18日目にドキュメントに署名するよう署名者に促します。リマインダは未署名の署名者にのみ送信されます。

boolean本文内省略可能
true
true

(テキストの) 入力で生成された署名の使用を無効にします。

integer本文内省略可能
2
0
730

作成した署名リクエストが完了しなかった場合に自動的に期限切れになるまでの日数を設定します。デフォルトでは、署名リクエストに有効期限を適用しないため、署名リクエストは期限切れになりません。

string本文内省略可能
"https://declined-redirect.com"

署名者がドキュメントへの署名を拒否した後にリダイレクトされるURI。

string本文内省略可能
"Hello! Please sign the document below"

署名リクエストメールに含めるメッセージ。このフィールドは、特定の文字のサニタイズによって消去されます。ただし、一部のHTMLタグは使用できます。また、このメッセージに含まれているリンクはメールではハイパーリンクに変換されます。このメッセージには、HTMLタグaabbracronymbblockquotecodeemiulliolstrongを含めることができます。HTMLに対するテキストの比率が大きすぎると、メールがスパムフィルタに入る可能性があることに注意してください。これらのタグにカスタムスタイルを適用することはできません。このフィールドを渡さない場合は、デフォルトのメッセージが使用されます。

string本文内省略可能
"Sign Request from Acme"

署名リクエストメールの件名。これは、署名リクエストによって消去されます。このフィールドを渡さない場合は、デフォルトの件名が使用されます。

string本文内省略可能
"123"

これは、署名リクエストが関連する外部システムのIDを参照する際に使用できます。

string本文内省略可能
"Box"

署名ログで、embed_url_external_idが割り当てられている署名者の横に表示するシステム名 (省略可) として使用されます。

boolean本文内省略可能
true

UIを使用してドキュメントの準備を完了するために送信者がレスポンスでprepare_urlを受け取る必要があるかどうかを示します。

boolean本文内省略可能
true

ドキュメントを表示する前にテキストメッセージを確認するよう署名者に強制します。この設定を署名者に適用するには、署名者の電話番号を指定する必要があります。

string本文内省略可能
"name"

署名リクエストの名前。

最終的な署名済みドキュメントと署名ログの保存先フォルダ。IDフィールドとtypeフィールドのみが必須です。ルートフォルダ (フォルダID 0) は使用できず、nullにすることもできません。

署名リクエストの作成時にこの値が渡されない場合は、デフォルトのフォルダを使用することになります。デフォルトのフォルダは、ペイロードの最初のソースファイルの親フォルダ (そのフォルダへのアップロード権限がある場合) または「My Sign Requests」という名前のフォルダになります。

object array本文内省略可能

署名に関連するタグがドキュメントのコンテンツに含まれている場合、このprefill_tagsを使用してタグを事前入力できます。その際、タグの「id」を事前入力タグのexternal_idフィールドとして参照します。

boolean本文内省略可能
true

チェックボックスの事前入力値

string (date)本文内省略可能
"2021-04-26"

日付の事前入力値

string本文内省略可能
"1234"

これは、署名リクエストのファイルに含まれている特定のタグのIDを参照します。

string本文内省略可能
"text"

テキストの事前入力値

string本文内省略可能
"https://www.example.com"

指定した場合、ドキュメントに署名された時点で、署名リクエストがこのURLにリダイレクトされます。

string本文内省略可能
"blue"

署名に特定の色 (青、黒、または赤) を強制します。

次の値のいずれか1つ: blue,black,red

object array本文内必須

署名リクエストの署名者の配列。許可されている署名者の最大数は35です。

: 一部の署名者が競合するセグメント (ユーザーグループ) に属している可能性もあります。これは、セキュリティポリシーにより、倫理的な競合につながる可能性のあるやり取りやコミュニケーションを防ぐためにユーザーがセグメントに割り当てられていることを意味します。このような場合、署名リクエストを送信しようとすると、エラーが発生します。

セグメントと情報バリアの詳細については、こちらを参照してください。

string本文内省略可能
"https://declined-example.com"

署名者がドキュメントへの署名を拒否した後にリダイレクトされるURL。このURLを定義すると、特定の署名者で、デフォルトまたはグローバルのリダイレクトURL設定より優先されます。

string本文内省略可能
"example@gmail.com"

署名者のメールアドレス。メールアドレスが含まれるように構成されているテンプレートを使用する場合を除き、署名リクエストを作成する際は署名者のメールアドレスが必須です。

string本文内省略可能
"1234"

埋め込みURLへのアクセス時に認証を担当する、外部アプリケーションの署名者のユーザーID。

boolean本文内省略可能
true

送信者の埋め込みURLと組み合わせて使用されます。送信者が署名すると、その次のin_person署名者にリダイレクトされます。

boolean本文内省略可能
true

trueに設定した場合、署名者はリクエストに署名する前にBoxアカウントにログインする必要があります。署名者に既存のアカウントがない場合、署名者は無料のBoxアカウントを作成できます。verification_phone_numberと組み合わせて選択することはできません。

integer本文内省略可能
2
0

署名者の順序

string本文内省略可能
"SecretPassword123"

設定した場合、署名者は、このパスワードを入力しないと、ドキュメントに署名できません。このフィールドは書き込み専用です。

string本文内省略可能
"https://example.com"

署名者がドキュメントに署名した後にリダイレクトされるURL。このURLを定義すると、特定の署名者で、デフォルトまたはグローバルのリダイレクトURL設定より優先されます。拒否した場合のリダイレクトURLが指定されていない場合は、このURLが拒否の操作にも使用されます。

string本文内省略可能
"signer"
"signer"

署名リクエストに含まれる署名者のロールを定義します。signerはドキュメントに署名し、approverはドキュメントを承認する必要があります。最終的な署名済みドキュメントと署名ログを受け取るのは、final_copy_readerのみです。

次の値のいずれか1つ: signer,approver,final_copy_reader

string本文内省略可能
"cd4ff89-8fc1-42cf-8b29-1890dedd26d7"

設定した場合、同じ値が設定されている署名者は、同じ入力および同じ署名者グループに割り当てられます。署名者グループはBoxグループではありません。これは、署名リクエストに属しているエンティティであり、この署名リクエスト内でのみ使用/アクセスできます。署名者グループには複数の署名者が含まれることが想定されています。指定された値が1人の署名者に対してのみ使用されている場合、この値は無視され、リクエストは、個別の署名者を対象としたものとして処理されます。指定できる値は任意の文字列で、同じグループに属している署名者を判別するためだけに使用できます。成功したレスポンスでは、同じ署名者グループ内の署名者ではなく、生成されたUUID値が示されます。

boolean本文内省略可能
false

trueの場合、署名リクエストに関するメールは送信されません

string本文内省略可能
"6314578901"

設定した場合、2要素認証での署名者の認証にこの電話番号が使用されます。認証されると、署名者はドキュメントに署名できるようになります。login_requiredと組み合わせて選択することはできません。

ファイル (Base) array本文内省略可能

署名するドキュメントの作成元ファイルのリスト。現在は、10ファイルに制限されています。ファイルごとにIDフィールドとtypeフィールドのみが必要です。

string本文内省略可能
"123075213-af2c8822-3ef2-4952-8557-52d69c2fe9cb"

署名リクエストがテンプレートから作成された場合、このフィールドはそのテンプレートのIDを示します。

レスポンス

Box Signリクエストオブジェクトを返します。

予期しないクライアントエラー。

post
Box Signリクエストを作成
このドキュメント内で一部のAPIを試せるようになりました。
ログイン

リクエストの例

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")
}

レスポンスの例

{
  "id": "12345",
  "type": "sign-request",
  "are_reminders_enabled": true,
  "are_text_signatures_enabled": true,
  "auto_expire_at": "2021-04-26T08:12:13.982Z",
  "days_valid": 2,
  "declined_redirect_url": "https://declined-redirect.com",
  "email_message": "Hello! Please sign the document below",
  "email_subject": "Sign Request from Acme",
  "external_id": "123",
  "external_system_name": "Box",
  "is_document_preparation_needed": true,
  "is_phone_verification_required_to_view": true,
  "name": "name",
  "parent_folder": {
    "id": "12345",
    "type": "folder",
    "etag": "1",
    "name": "Contracts",
    "sequence_id": "3"
  },
  "prefill_tags": [
    {
      "document_tag_id": "1234",
      "text_value": "text",
      "checkbox_value": true,
      "date_value": "2021-04-26"
    }
  ],
  "prepare_url": "https://prepareurl.com",
  "redirect_url": "https://www.example.com",
  "sign_files": {
    "files": [
      {
        "id": "12345",
        "etag": "1",
        "type": "file",
        "sequence_id": "3",
        "name": "Contract.pdf",
        "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
        "file_version": {
          "id": "12345",
          "type": "file_version",
          "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
        }
      }
    ],
    "is_ready_for_download": true
  },
  "signature_color": "blue",
  "signers": [
    {
      "email": "example@gmail.com",
      "role": "signer",
      "is_in_person": true,
      "order": 2,
      "embed_url_external_user_id": "1234",
      "redirect_url": "https://example.com",
      "declined_redirect_url": "https://declined-example.com",
      "login_required": true,
      "verification_phone_number": "6314578901",
      "password": "SecretPassword123",
      "signer_group_id": "cd4ff89-8fc1-42cf-8b29-1890dedd26d7",
      "suppress_notifications": false,
      "has_viewed_document": true,
      "signer_decision": {
        "type": "signed",
        "finalized_at": "2021-04-26T08:12:13.982Z",
        "additional_info": "Requesting changes before signing."
      },
      "inputs": [
        {
          "document_tag_id": "1234",
          "text_value": "text",
          "checkbox_value": true,
          "date_value": "2021-04-26",
          "type": "text",
          "content_type": "signature",
          "page_index": 4,
          "read_only": true
        }
      ],
      "embed_url": "https://example.com",
      "iframeable_embed_url": "https://app.box.com/embed/sign/document/gfhr4222-a331-494b-808b-79bc7f3992a3/f14d7098-a331-494b-808b-79bc7f3992a4"
    }
  ],
  "signing_log": {
    "id": "12345",
    "type": "file",
    "etag": "1",
    "file_version": {
      "id": "12345",
      "type": "file_version",
      "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
    },
    "name": "Contract.pdf",
    "sequence_id": "3",
    "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37"
  },
  "source_files": [
    {
      "id": "12345",
      "etag": "1",
      "type": "file"
    }
  ],
  "status": "converting",
  "template_id": "123075213-af2c8822-3ef2-4952-8557-52d69c2fe9cb"
}