署名リクエスト

署名リクエストオブジェクト

このリソースにはAPIの使用時に発生する可能性があるいくつかのバリエーションがあります。

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

string
12345

署名リクエストID

string
sign-request

オブジェクトタイプ

次の値に固定: sign-request

true

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

truetrue

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

string / date-time
2021-04-26T08:12:13.982Z

days_validを使用すると、未署名の場合に署名リクエストの有効期限となる日時 (GMT) が計算されます。

integer
20730

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

https://declined-redirect.com

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

Hello! Please sign the document below

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

Sign Request from Acme

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

123

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

true

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

true

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

string
name

署名リクエストの名前。

The destination folder to place final, signed document and signing log.

When this value was not passed in when the signature request was created, then we will use a default folder which is either the parent folder of the first source file in the payload if we have the permission to upload to that folder or a folder called "My Sign Requests".

object array

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

true

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

2021-04-26

日付の事前入力値

1234

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

text

テキストの事前入力値

https://prepareurl.com

このURLは、リクエストでis_document_preparation_neededtrueに設定されている場合に返されます。これは、UIで署名リクエストを準備する際に使用されます。署名リクエストは、準備が完了するまで送信されません。

https://www.example.com

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

object

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

true

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

blue

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

object array

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

https://declined-example.com

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

example@gmail.com

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

https://example.com

署名のために署名者に案内するURL

1234

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

true

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

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 sign requestコールで渡された場合のみです。

object array
text

入力の種類

次の値のいずれか1つ: signature,date,text,checkbox,radio,dropdown

true

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

signature

入力のコンテンツタイプ

次の値のいずれか1つ: signature,initial,stamp,date,checkbox,text,full_name,first_name,last_name,company,title,email,attachment,radio,dropdown

string / date
2021-04-26

日付の事前入力値

1234

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

4

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

text

テキストの事前入力値

true

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

true

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

20

署名者の順序

SecretPassword123

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

https://example.com

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

signer"signer"

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

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

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

signed

署名者による決定の種類

次の値のいずれか1つ: signed,declined

Requesting changes before signing.

署名者の拒否理由など、決定に関する追加情報

string / date-time
2021-04-26T08:12:13.982Z

決定が行われた日時

cd4ff89-8fc1-42cf-8b29-1890dedd26d7

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

6314578901

設定した場合は、2要素認証による署名者の認証にこの電話番号を使用しないと、署名者はドキュメントに署名できません。

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

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

string
converting

署名リクエストのステータスを説明します

次の値のいずれか1つ: converting,created,sent,viewed,signed,cancelled,declined,error_converting,error_sending,expired,finalizing,error_finalizing

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",
  "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",
  "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",
      "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
        }
      ],
      "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"
}