Open in app

Sign in

Write

Sign in

Box Sign APIでのテンプレートの使用

Yuko Taniguchi
Box Developer Japan Blog
Published in
13 min readMay 26, 2023
Image by Freepik

Box Sign APIの新しいテンプレート機能でドキュメントの署名プロセスを強化し、APIによるデータの直接統合と事前設定を可能にします。

先日、Boxアプリで作成したテンプレートをAPIで直接使用する機能を追加してBox Sign APIを強化しました。

これまでは、APIでテンプレートを使用できるように、非表示のタグやコードを使って、Box外でテンプレートを作成する必要がありました。

はじめに

ユーザーは、Boxアプリを使用して署名用ドキュメントを準備できます。

これは、実質的に、ユーザーがドキュメントにプレースホルダを配置することで、署名そのものから日付やラジオボタンまで、収集できるさまざまなデータを表すことができることを意味します。

その後、ユーザーは、署名リクエストを受信して開いたときに、これらのフィールドに必要なデータを設定できます。

また、別の方法として、署名リクエストの作成時に、APIを使用してこのデータを事前に設定することもできます。

Signテンプレートの作成方法に詳しい場合は、APIに関するセクションに進んでください。

Signテンプレートの作成

テンプレートを作成します。左側のメニューで [Sign] を選択し、画面右上にある [テンプレート] をクリックします。

[Sign] の [テンプレート] に移動

[新しいテンプレート] ボタン、プラス記号の順にクリックし、ドキュメントを選択またはアップロードします。

新しいテンプレートの [ドキュメントの選択またはアップロード]

この例では、インターネット上で見つけた奨学金の契約書のサンプルを使用します。これは、教師と学生の2名が署名することになっています。

サンプルテンプレート

ユーザーは、情報を取得するためのプレースホルダをドラッグアンドドロップできます。この例では、署名、署名日、名前を使用します。

この各プレースホルダには、変更可能なプロパティがあります。

学生の名前を表すプレースホルダのプロパティ

上の例では、選択した「フルネーム」プレースホルダが学生 (青色) に割り当てられ、必須フィールドに設定されています。詳細プロパティでは、APIを介してこれを事前に設定できるようにstudent_full_nameという外部識別子が追加されています。

学生のフルネームの詳細プロパティでの [外部識別子] の指定

テンプレートのデザインが完成したら、テンプレートを保存できます。これで、このテンプレートを手動で使用できるようになります。

Signテンプレートのリスト

この時点では、署名リクエストを手動で送信できます。[テンプレートを使用] を選択し、教師と学生のメールアドレスを入力して、リクエストを送信するだけです。メールアドレスを確認し、署名プロセスを完了します。

完了した署名済みのリクエストの例を次に示します。

完了した署名済みのリクエスト

APIを使用した署名リクエストの送信

これで、先ほど作成したテンプレートを使用してフルネームのプレースホルダを事前に設定することで、署名リクエストを送信する準備ができました。

まず、使用するテンプレートを示すためのtemplate_idが必要です。

Boxでは、/sign_templatesエンドポイントを使用して、利用可能な全テンプレートのリストを取得できます。

curl --location 'https://api.box.com/2.0/sign_templates' \
--header 'Authorization: Bearer cR...nX'

この例では、次のレスポンスが返されます (簡略化されています)。

...
"entries": [
    {
        "id": "6ae28666-03c4-4ac1-80db-06a90d3b1361",
        "name": "Scholarship-Contract.pdf",
        "parent_folder": {
                "id": "157064745449",
                "etag": "0",
                "type": "folder",
                "sequence_id": "0",
                "name": "My Sign Requests"
            },
        "source_files": [
            {
                "id": "1216382236853",
                "etag": "0",
                "type": "file",
                "sequence_id": "0",
                "sha1": "ca9c75cda0d5e3c3c9b0a1e6d42cb5e29a211ab6",
                "file_version": {
                    "id": "1327286673653",
                    "type": "file_version",
                    "sha1": "ca9c75cda0d5e3c3c9b0a1e6d42cb5e29a211ab6"
                }
            }
        "signers": [...]
        ...
    }
]

テンプレート自体がドキュメントを指していることに注意してください。

さらに詳細を説明します。

署名者

この例では、役割の異なる複数の署名者がドキュメントに設定されています。

"signers": [
    {
        "email": "",
        "label": null,
        "public_id": "4Z8QZZV4",
        "role": "final_copy_reader",
        "is_in_person": false,
        "order": 1,
        "inputs": [...]
    },
    {
        "email": "",
        "label": "Student",
        "public_id": "13VK8794",
        "role": "signer",
        "is_in_person": false,
        "order": 1,
        "inputs": [...]
    },
    {
        "email": "",
        "label": "Teacher",
        "public_id": "13VK77Z4",
        "role": "signer",
        "is_in_person": false,
        "order": 1,
        "inputs": [...]
]

final_copy_readerは、最後に署名済みドキュメントを取得する人を表します。

Studentは、実際にドキュメントに署名する人の1人を表します。teacherについても同様です。

タグの事前入力

署名者ごとに、複数の入力データが関連付けられています。これらの入力データは、ユーザーが操作できる、ドキュメント内のさまざまなプレースホルダを表しています。

また、入力データには、署名リクエストの作成時にデータを事前設定できるようにdocument_tag_idも設定できます。

...
{
    "email": "",
    "label": "Student",
    "public_id": "13VK8794",
    "role": "signer",
    "is_in_person": false,
    "order": 1,
    "inputs": [
        {
            "document_tag_id": "student_full_name",
            "id": "da431975-55c5-4629-86ae-3fb12dda1386",
            "type": "text",
            "text_value": null,
            "is_required": true,
            "content_type": "full_name",
            ...
        },
        {
            "document_tag_id": null,
            "id": "b5a76a22-8d48-456e-a012-22a12fc91eb7",
            "type": "signature",
            ...
        },
        {
            "document_tag_id": null,
            "id": "7e0cc4ee-b878-4739-afde-acbf69b117b2",
            "type": "date",
            "date_value": null,
            ...
        }
    ]
},

上の例には、full_name、signature、dateという3つのプレースホルダ (入力データ) があります。

document_tag_idにfull_nameを設定した場合、署名リクエストの作成時にデータを事前設定できるようになります。

署名リクエスト

最後に、/sign_requestエンドポイントを使用して署名リクエストを作成できます。最初にtemplate_idを設定します。

{
  "template_id": "6ae28666-03c4-4ac1-80db-06a90d3b1361",
  "parent_folder": {
    "id": "157064745449",
    "etag": "0",
    "type": "folder",
    "sequence_id": "0",
    "name": "My Sign Requests"
  },
...
}

parent_folderは、署名ドキュメントと署名ログを保存するフォルダになります。

今回の署名者は次のようになります。

{
  "template_id": "6ae28666-03c4-4ac1-80db-06a90d3b1361",
  "parent_folder": {
    "id": "157064745449",
    "etag": "0",
    "type": "folder",
    "sequence_id": "0",
    "name": "My Sign Requests"
  },
  "signers": [
    {
      "email": "barduinor+teacher@gmail.com",
      "role": "signer"
    },
    {
      "email": "barduinor+student@gmail.com",
      "role": "signer"
    },
  ]
}

また、事前入力タグは次のようになります。

{
  "template_id": "6ae28666-03c4-4ac1-80db-06a90d3b1361",
  "parent_folder": {
    "id": "157064745449",
    "etag": "0",
    "type": "folder",
    "sequence_id": "0",
    "name": "My Sign Requests"
  },
  "signers": [
    {
      "email": "barduinor+student@gmail.com",
      "role": "signer"
    },
    {
      "email": "barduinor+teacher@gmail.com",
      "role": "signer"
    }
  ],
  "prefill_tags": [
    {
      "document_tag_id": "student_full_name",
      "text_value": "Mileva Maric"
    },
    {
      "document_tag_id": "teacher_full_name",
      "text_value": "Albert Einstein"
    }
  ]
}

署名者の順序がテンプレートに表示されている順序と同じであることを確認してください。このテンプレートでは、最初に学生、その後教師が設定されています。POSTリクエストでは、適切な署名者を割り当てるために同じ順序を守る必要があります。

このPOSTリクエストを送信すると、APIはsign_requestオブジェクトを返します (簡略化されています)。

{
    "is_document_preparation_needed": false,
    ...
    "signers": [
        {
            "email": "barduinor@gmail.com",
            "role": "final_copy_reader",
        },
        {
            "email": "barduinor+student@gmail.com",
            "role": "signer",
        },
        {
            "email": "barduinor+teacher@gmail.com",
            "role": "signer",
        }
    ],
    "id": "d02fefd2-15fa-431f-a127-2b4525616ae6",
    "prefill_tags": [
        {
            "document_tag_id": "student_full_name",
            "text_value": "Mileva Maric",
        },
        {
            "document_tag_id": "teacher_full_name",
            "text_value": "Albert Einstein",
        }
    ],
    "source_files": [],
    "parent_folder": {
        "id": "157064745449",
        "type": "folder",
        "name": "My Sign Requests"
    },
    "name": "Scholarship-Contract (5).pdf",
    "type": "sign-request",
    "status": "created",
    "sign_files": {
        "files": [
            {
                "id": "1217421927592",
                "type": "file",
                "name": "Scholarship-Contract (5).pdf",
            }
        ],
        "is_ready_for_download": true
    },
    "template_id": "6ae28666-03c4-4ac1-80db-06a90d3b1361"
}

署名プロセスの完了後は次のように表示されます。

署名リクエストでカスタマイズできる項目は、メールメッセージ、拒否時に表示するURL、確認用電話番号、パスワード、他にも多数あります。

詳細については、署名リクエストに関するドキュメントを参照してください。

Box
Box Api
Rest Api
電子署名
ドキュメント

--

--

Yuko Taniguchi
Box Developer Japan Blog

Written by Yuko Taniguchi

15 Followers
Editor for

Help

Status

About

Careers

Press

Blog

Privacy

Terms

Text to speech

Teams