Box Signリクエスト

APIバージョン 2024.0 Box Signリクエストオブジェクト。

このリソースにはAPIの使用時に発生する可能性があるいくつかのバリエーションがあります。通常、Standardバリアントに含まれるフィールドは、固有のAPIエンドポイントを介してこのリソースがリクエストされたときに返されます。たとえば、fieldsパラメータが指定されていない場合、IDでファイルを取得すると、これらのフィールドが返されます。

string

例 12345Box SignリクエストID。

type

string

例 sign-request値は常にsign-requestになります。次の値に固定: sign-request

are_reminders_enabled

boolean

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

are_text_signatures_enabled

boolean

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

auto_expire_at

string(date-time)

例 2021-04-26T08:12:13.982Zdays_validを使用すると、未署名の場合に署名リクエストの有効期限となる日時 (GMT) が計算されます。

collaborator_level

string

例 owner署名リクエストに対するユーザーのコラボレータレベル。値には「owner」、「editor」、「viewer」を指定できます。

days_valid

integer

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

declined_redirect_url

string

例 https://declined-redirect.com署名者がドキュメントへの署名を拒否した後にリダイレクトされるURI。

email_message

string

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

email_subject

string

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

external_id

string

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

external_system_name

string

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

is_document_preparation_needed

boolean

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

name

string

例 name署名リクエストの名前。

parent_folder

フォルダ (Mini)object

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

prefill_tags

object[]

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

表示子属性

checkbox_value

boolean

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

date_value

string(date)

例 2021-04-26日付の事前入力値。

document_tag_id

string

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

text_value

string

例 textテキストの事前入力値。

prepare_url

string

例 https://prepareurl.comこのURLは、リクエストでis_document_preparation_neededがtrueに設定されている場合に返されます。このパラメータは、UIを使用して署名リクエストを準備する際に使用されます。署名リクエストは、準備段階が完了するまで送信されません。

redirect_url

string

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

sender_email

string

例 sender@box.com署名リクエストの送信者のメールアドレス。

sender_id

integer

例 12345署名リクエストの送信者のユーザーID。

sign_files

object

署名されるファイル (元のソースファイルのコピー) のリスト。署名者が署名すると、これらのファイルの新しいバージョンが作成され、署名プロセスのどの時点でもダウンロードできます。

表示子属性

files

ファイル (Mini)array

is_ready_for_download

boolean

例 truesign_filesのドキュメントが処理中で、PDFが古くなっている可能性があるかどうかを示します。任意のドキュメントを変更するには、すべてのsign_filesで処理が必要になります。処理が終了するまで (およびこの値がtrueになるまで) 待ってからPDFをダウンロードすることをお勧めします。

signature_color

string

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

signers

object[]

署名リクエストの署名者の配列。

表示子属性

declined_redirect_url

string

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

string

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

embed_url

string

例 https://example.com署名のために署名者に案内するURL。

embed_url_external_user_id

string

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

has_viewed_document

boolean

例 true署名者がドキュメントを表示する場合はtrueに設定します。

iframeable_embed_url

string

例 https://app.box.com/embed/sign/document/gfhr4222-a331-494b-808b-79bc7f3992a3/f14d7098-a331-494b-808b-79bc7f3992a4このURLは、HTMLのiframeタグ内のドキュメントに署名するために設計されています。これがレスポンスで返されるのは、embed_url_external_user_idパラメータがcreate Box Sign requestコールで渡された場合のみです。

inputs

object[]

表示子属性

type

string

例 text入力の種類。次の値のいずれか1つ: signature,date,text,checkbox,radio,dropdown

checkbox_value

boolean

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

content_type

string

例 signature入力のコンテンツタイプ。次の値のいずれか1つ: signature,initial,stamp,date,checkbox,text,full_name,first_name,last_name,company,title,email,attachment,radio,dropdown

date_value

string(date)

例 2021-04-26日付の事前入力値。

document_tag_id

string

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

page_index

integer

例 4入力が配置されるページのインデックス。

read_only

boolean

例 trueこの入力が読み取り専用 (署名者による変更不可) として定義されているかどうか。

text_value

string

例 textテキストの事前入力値。

is_in_person

boolean

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

例 truetrueに設定した場合、署名者はリクエストに署名する前にBoxアカウントにログインする必要があります。署名者に既存のアカウントがない場合は、無料のBoxアカウントを作成できます。

order

integer

例 2署名者の順序。

password

string

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

redirect_url

string

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

role

string

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

signer_decision

object

署名者による最終的な決定。

表示子属性

type

string

例 signed署名者による決定の種類。次の値のいずれか1つ: signed,declined

additional_info

string

例 Requesting changes before signing.署名者の拒否理由など、決定に関する追加情報。

finalized_at

string(date-time)

例 2021-04-26T08:12:13.982Z決定が行われた日時。

signer_group_id

string

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

suppress_notifications

boolean

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

verification_phone_number

string

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

signing_log

ファイル (Mini)object

リクエストに対する署名者のアクティビティがすべて記録されているファイルへの参照。

source_files

ファイル (Base)array

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

status

string

例 converting署名リクエストのステータスを説明します。次の値のいずれか1つ: converting,created,sent,viewed,signed,cancelled,declined,error_converting,error_sending,expired,finalizing,error_finalizing

template_id

string

例 123075213-af2c8822-3ef2-4952-8557-52d69c2fe9cb署名リクエストがテンプレートから作成された場合、このフィールドはそのテンプレートのIDを示します。

{
  "id": "12345",
  "type": "sign-request",
  "are_reminders_enabled": true,
  "are_text_signatures_enabled": true,
  "auto_expire_at": "2021-04-26T08:12:13.982Z",
  "collaborator_level": "owner",
  "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,
  "name": "name",
  "parent_folder": {
    "id": "12345",
    "type": "folder",
    "etag": "1",
    "name": "Contracts",
    "sequence_id": "3"
  },
  "prefill_tags": [
    {
      "checkbox_value": true,
      "date_value": "2021-04-26",
      "document_tag_id": "1234",
      "text_value": "text"
    }
  ],
  "prepare_url": "https://prepareurl.com",
  "redirect_url": "https://www.example.com",
  "sender_email": "sender@box.com",
  "sender_id": 12345,
  "sign_files": {
    "files": [
      {
        "etag": "1",
        "id": "12345",
        "type": "file",
        "file_version": {
          "id": "12345",
          "type": "file_version",
          "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
        },
        "name": "Contract.pdf",
        "sequence_id": "3",
        "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37"
      }
    ],
    "is_ready_for_download": true
  },
  "signature_color": "blue",
  "signers": [
    {
      "declined_redirect_url": "https://declined-example.com",
      "email": "example@gmail.com",
      "embed_url_external_user_id": "1234",
      "is_in_person": true,
      "login_required": true,
      "order": 2,
      "password": "SecretPassword123",
      "redirect_url": "https://example.com",
      "role": "signer",
      "signer_group_id": "cd4ff89-8fc1-42cf-8b29-1890dedd26d7",
      "suppress_notifications": false,
      "verification_phone_number": "6314578901",
      "embed_url": "https://example.com",
      "has_viewed_document": true,
      "iframeable_embed_url": "https://app.box.com/embed/sign/document/gfhr4222-a331-494b-808b-79bc7f3992a3/f14d7098-a331-494b-808b-79bc7f3992a4",
      "inputs": [
        {
          "checkbox_value": true,
          "date_value": "2021-04-26",
          "document_tag_id": "1234",
          "text_value": "text",
          "content_type": "signature",
          "page_index": 4,
          "read_only": true,
          "type": "text"
        }
      ],
      "signer_decision": {
        "additional_info": "Requesting changes before signing.",
        "finalized_at": "2021-04-26T08:12:13.982Z",
        "type": "signed"
      }
    }
  ],
  "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": [
    {
      "etag": "1",
      "id": "12345",
      "type": "file"
    }
  ],
  "status": "converting",
  "template_id": "123075213-af2c8822-3ef2-4952-8557-52d69c2fe9cb"
}