メインコンテンツへスキップ

Documentation Index

Fetch the complete documentation index at: https://developer.box.com/llms.txt

Use this file to discover all available pages before exploring further.

Box Signのコンテキストにおける構造化されたドキュメントとは、Box Sign APIが認識できる特殊なタグを含むドキュメントのことです。これらのタグは、特定の署名者に関連付けられた署名プロパティ (名前、日付、署名など) をドキュメント内に配置するために使用されます。 これにより、アプリでは、署名の準備が整った、動的に生成されたドキュメントを処理できます。これには、いくつかの利点があります。
  • ドキュメントを動的に生成できます。また、署名リクエストを作成する前に署名プロパティをドキュメントに追加できるため、実質的にドキュメントの準備手順を省略できます。
  • ドキュメントの形式はBox Signテンプレートの外部で処理できるため、柔軟性が高まり、外部のドキュメント管理システムとの統合が可能になります。

​
構造化されたドキュメントの詳細

構造化されたドキュメントの例を以下に示します。この例では、Microsoft Wordドキュメントにタグを配置する際に使用される書式を示しています。
Microsoft Wordドキュメントでのタグの使用
上の例では、[[c|1]]は署名者1に割り当てられたチェックボックスを指し、[[s| 1]]は署名者1に割り当てられた署名パッドを指します。署名パッドでフォントサイズ48を使用して、署名用のスペースを縦方向に確保していることに注目してください。 [[t|1|id:tag_full_name|n:enter your complete name]]は、ラベルenter your complete nameとID tag_full_nameを使用して、署名者1に割り当てられた名前タグを指します。 利用可能なすべてのタグの詳細な説明については、こちらのドキュメントを参照してください。 タグを背景と同じcolorに設定すると、タグは見えなくなりますが、そこに存在はしています。 タグ内の番号は、署名の順序ではなく、署名者の番号を指すため、[[c|1]]は署名者1のチェックボックス、[[c|2]]は署名者2のチェックボックスのようになります。 タグ0は送信者用に予約されており、必ず存在します。そのため、送信者がドキュメントにデータを入力する必要がない場合でも、他の署名者には1以降の番号を割り当てる必要があります。

​
構造化されたドキュメントからの署名リクエストの作成

これは、非構造化ドキュメントから署名リクエストを作成する場合と同じです。少なくとも、ドキュメント、受信用フォルダ、およびsignerのメールアドレスを指定する必要があります。 構造化されたドキュメントにはすでに署名プロパティの詳細と場所が含まれているため、ドキュメントの準備は省略できます。 このフローは次のようになり、ドキュメントの生成から始まり、署名リクエストを作成して、最後にドキュメントに署名します。
構造化されたドキュメントへの署名
次のメソッドを考えてみましょう。 
curl --location 'https://api.box.com/2.0/sign_requests' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer nQ...xY' \
    --data-raw '{
      "source_files": [
        {
          "type": "file",
          "id": "1363379762284"
        }
      ],
      "parent_folder": {
        "id": "234102987614",
        "type": "folder"
      },
      "signers": [
        {
          "email": "signer@example.com",
          "role": "signer"
        }
      ]
    }'
結果は次のとおりです (簡略化されています)。 
{
  "is_document_preparation_needed": false,
  "signers": [
    {
      "email": "sender@example.com",
      "role": "final_copy_reader",
    },
    {
      "email": "signer@example.com",
      "role": "signer",
    }
  ],
  "id": "28199d6c-4662-471e-8426-4cbba9affcf1",
  "source_files": [
    {
      "id": "1363379762284",
      "type": "file",
      "name": "Box-Dive-Waiver.docx",
    }
  ],
  "parent_folder": {
    "id": "234102987614",
    "type": "folder",
    "name": "signed docs"
  },
  "name": "Box-Dive-Waiver.pdf",
  "type": "sign-request",
  "status": "converting",
  "sign_files": {
    "files": [
      {
        "id": "1393138856442",
        "type": "file",
        "name": "Box-Dive-Waiver.pdf",
      }
    ],
  },
}
署名者のメールの受信トレイに移動し、Box Signからのメールを開き、[ドキュメントをレビュー] ボタンをクリックすると、署名プロパティが所定の位置に配置されているドキュメントが表示されます。
プロパティが所定の位置に配置されているドキュメント
処理を完了すると、署名済みドキュメントは次のようになります。
署名済みドキュメント

​
署名の属性の事前入力

ドキュメントのタグに外部IDが設定されている場合は、その外部IDを使用して値を事前入力できます。たとえば、tag_full_nameを使用して署名者の名前を事前に入力できます。 次のメソッドを確認してください。 
curl --location 'https://api.box.com/2.0/sign_requests' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer nQ...xY' \
    --data-raw '{
      "prefill_tags": [
        {
          "document_tag_id": "tag_full_name",
          "text_value": "Signer A"
        }
      ],
      "source_files": [
        {
          "type": "file",
          "id": "1363379762284"
        }
      ],
      "parent_folder": {
        "id": "234102987614",
        "type": "folder"
      },
      "signers": [
        {
          "email": "signer@example.com",
          "role": "signer"
        }
      ]
    }'
結果は次のとおりです (簡略化されています)。 
{
  "is_document_preparation_needed": false,
  "redirect_url": null,
  "declined_redirect_url": null,
  "are_text_signatures_enabled": true,
  "signature_color": null,
  "is_phone_verification_required_to_view": false,
  "email_subject": null,
  "email_message": null,
  "are_reminders_enabled": false,
  "signers": [
    {
      "email": "sender@example.com",
      "role": "final_copy_reader",
    },
    {
      "email": "signer@example.com",
      "role": "signer",
    }
  ],
  "id": "11ecebc0-a2b2-4c14-a892-3f56333cc4fa",
  "prefill_tags": [
    {
      "document_tag_id": "tag_full_name",
      "text_value": "Signer A",
    }
  ],
  "source_files": [
    {
      "id": "1363379762284",
      "type": "file",
      "name": "Box-Dive-Waiver.docx",
    }
  ],
  "parent_folder": {
    "id": "234102987614",
    "type": "folder",
    "name": "signed docs"
  },
  "name": "Box-Dive-Waiver (1).pdf",
  "type": "sign-request",
  "status": "converting",
  "sign_files": {
    "files": [
      {
        "id": "1393142670032",
        "type": "file",
        "name": "Box-Dive-Waiver (1).pdf",
      }
    ],
  },
}
これで、ドキュメントには名前が事前入力されるようになりました。
名前が事前入力された、署名の準備が整っているドキュメント

​
署名済みドキュメントからの情報の抽出

たとえば、署名者の名前とその他のプロパティを署名済みドキュメントから抽出したいとします。これは、署名リクエストの情報を再度システムに紐付ける必要がある場合に便利です。 署名済みリクエストから情報を抽出するメソッドを作成しましょう。 
curl --location 'https://api.box.com/2.0/sign_requests/
11ecebc0-a2b2-4c14-a892-3f56333cc4fa' \
    --header 'Authorization: Bearer nQ...xY'
結果は次のとおりです (簡略化されています)。 
{
  "signers": [
    {
      "email": "sender@example.com",
      "role": "final_copy_reader",
    },
    {
      "email": "signer@example.com",
      "role": "signer",
      "signer_decision": {
        "type": "signed",
        "finalized_at": "2023-12-19T14:53:10.547Z",
      },
      "inputs": [
        {
          "document_tag_id": null,
          "checkbox_value": true,
          "type": "checkbox",
          "content_type": "checkbox",
        },
        {
          "document_tag_id": "tag_full_name",
          "text_value": "Signer A",
          "type": "text",
          "content_type": "text",
        },
        {
          "document_tag_id": null,
          "text_value": "Dec 19, 2023",
          "date_value": "2023-12-19",
          "type": "date",
          "content_type": "date",
        },
        {
          "document_tag_id": null,
          "type": "signature",
          "content_type": "signature",
        }
      ],
    }
  ],
  "id": "11ecebc0-a2b2-4c14-a892-3f56333cc4fa",
  "prefill_tags": [
    {
      "document_tag_id": "tag_full_name",
      "text_value": "Signer A",
    }
  ],
  "source_files": [
    {
      "id": "1363379762284",
      "type": "file",
      "name": "Box-Dive-Waiver.docx",
    }
  ],
  "parent_folder": {
    "id": "234102987614",
    "type": "folder",
    "name": "signed docs"
  },
  "name": "Box-Dive-Waiver (1).pdf",
  "type": "sign-request",
  "signing_log": {
    "id": "1393140642252",
    "type": "file",
    "name": "Box-Dive-Waiver (1) Signing Log.pdf",
  },
  "status": "signed",
  "sign_files": {
    "files": [
      {
        "id": "1393142670032",
        "type": "file",
        "name": "Box-Dive-Waiver (1).pdf",
      }
    ],
  },
}

​
まとめ

構造化されたドキュメントの使用は、外部のドキュメント管理システムと統合して、署名可能な動的ドキュメントを作成するのに最適です。 ドキュメントの署名要件に多くの選択肢がある場合は、別のデータソースからこれらを事前に入力して、ユーザーの時間を節約することができます。ただし、これらのプロパティを所有するユーザーはいつでもプロパティを変更できます。 ドキュメントが署名された後に署名リクエストから情報を抽出することができるので、その情報を再度システムに紐付ける必要がある場合に便利です。