Assinafy

Assinafy MCP クライアントガイド

ポルトガル語 · 英語で読む

Assinafy をアシスタントに接続して、書類の準備と送信、署名状況の確認、リマインダーの送信、署名済みコピーのダウンロードを行えます。

サーバーの URL として https://mcp.assinafy.com.br/mcp を使用します。Assinafy にログインし、ワークスペースを選択して、要求された権限を承認してください。OAuth アプリを作成したり、client ID、client secret、API キー、ワークスペースヘッダーを指定したりする必要はありません。

ログイン前に接続して、カタログを確認することもできます。ツールがワークスペースにアクセスする必要があるときに、認証が要求されます。

Codex

codex mcp add assinafy --url https://mcp.assinafy.com.br/mcp
codex mcp login assinafy

ブラウザーでログインを完了し、ワークスペースを選択して、権限を承認してください。 Codex の MCP ドキュメントをご覧ください。

Claude Code

claude mcp add --transport http assinafy https://mcp.assinafy.com.br/mcp
claude mcp login assinafy

Claude Code で /mcp を開いて Assinafy に認証することもできます。 ブラウザーでログインを完了し、ワークスペースを選択してください。 Claude Code の MCP ドキュメントをご覧ください。

Claude のリモートコネクター

Claude のコネクター設定で、Assinafy という名前のカスタムリモートコネクターを追加し、URL https://mcp.assinafy.com.br/mcp を指定して接続し、同意手続きを完了してください。CIMD が利用できる場合は、任意の OAuth 認証情報を空欄のままにしてください。カスタムコネクターを利用できるかどうかは、プランと組織の設定によって異なります。コマンドラインでの登録は Claude Code 用です。ホスト型コネクターには公開 HTTPS URL が必要です。

Claude コネクターの認証をご覧ください。

ChatGPT

OAuth を使用するリモート MCP 接続を設定し、Assinafy の URL を指定してください。登録オプションがある場合は CIMD を選択し、任意の認証情報は空欄のままにして、Assinafy へのログインとワークスペースの選択を完了してください。 ChatGPT の認証をご覧ください。

ChatGPT Work では、監視対象の書類のステータスが変化したとき、または書類が認証されたときに、サーバーから MCP Events を通じて ChatGPT に通知することもできます。書類の監視を ChatGPT に依頼すると、署名の作成と更新が自動的に行われます。

VS Code / GitHub Copilot Chat

この項目を VS Code の MCP 設定に追加してください。

{
  "servers": {
    "assinafy": {
      "type": "http",
      "url": "https://mcp.assinafy.com.br/mcp"
    }
  }
}

サーバーを起動し、ブラウザーで認証を完了してください。VS Code は CIMD が通知されていればそれを選択し、ツールで必要になったときに追加スコープを要求できます。 VS Code の認証サポートと MCP の設定をご覧ください。

ワークスペースと権限

1つの接続で1つのワークスペースが認可されます。アカウントスコープのツールは、そのアカウントを自動的に特定します。account_id 引数で同じアカウントを指定できますが、別のアカウントを選択することはできません。追加のワークスペースはそれぞれ個別に接続してください。API キー、OAuth トークン、その他の認証情報をプロンプト、ツール引数、または _meta に含めないでください。これらを含むリクエストは拒否されます。

MCP URL はご自身で設定します。メタデータでは、カタログ全体に対して account:read documents:read documents:write templates:read templates:write が通知されます。デフォルトでは、すべてのツールを1回の同意で利用できるよう、ログイン時に完全なスコープセットが要求されます。クライアントまたは同意画面でスコープを絞り、許可されたツールを利用できます。API では、保存済みテンプレートからドキュメントを生成するには templates:write が、フィールド値を検証するには documents:write が必要です。バックグラウンドアクセスでクライアントがリフレッシュトークンを使用する場合は、offline_access を要求してください。

必要な権限がない場合、フローを開始する前に、承認が必要なスコープを示す HTTP 403 insufficient_scope が返されます。すでに許可されているスコープに、要求された権限を追加して認可し、再試行してください。その他のエラーは、処理の開始後に操作を中断させる場合があります。操作を再試行する前に、保持されている document_id を確認してください。

Codex では、ドキュメントとテンプレートの完全なフローを明示的に認可してください。

codex mcp login assinafy --scopes account:read,documents:read,documents:write,templates:read,templates:write,offline_access

ドキュメント接続を意図的に読み取り専用にする場合は、次を選択してください。

codex mcp login assinafy --scopes account:read,documents:read,offline_access

トークンはクライアントが保存し、更新します。許可の有効期限が切れた場合や取り消された場合は、クライアントによる更新を許可するか、Assinafy を通じて再接続してください。offline_access を使用すると、更新のたびに有効期間がさらに30日間の新しいリフレッシュトークンが返されます。更新されない状態が30日間続いた場合にのみ接続の有効期限が切れ、その際は再接続が必要です。トークンを会話やツール引数に貼り付けないでください。

依頼できること

自然な言葉でアシスタントに話しかけてください。アシスタントが適切なツールを選び、名前を検索し、曖昧な場合にだけ確認します。以下の名前、メールアドレス、日付は例です。

ドキュメントの状況を確認する

あなたの発言	起こること
「署名待ちのドキュメントはどれですか？」	pending_signature のドキュメントを新しい順に一覧表示します
「Acme のサービス契約には全員が署名しましたか？」	ドキュメントを検索し、署名済みの人と未署名の人を伝えます
「NDA にまだ署名していない人は誰で、いつ招待されましたか？」	署名待ちの各署名者の段階と招待履歴を確認します
「今週、賃貸契約に何がありましたか？」	ドキュメントのイベントのタイムラインを表示します
「Carlos への WhatsApp の招待は届きましたか？」	依頼の WhatsApp 配信履歴を確認します

署名を依頼する

あなたの発言	起こること
「contrato.pdf を Ana Lima（[email protected]）に送って、署名を依頼してください。」	PDF を送信し、処理を待ってから、メールで招待を送ります
「proposta.pdf をアップロードしてください。まだ送信せず、Proposta v2 という名前にしてください。」	ファイルをアップロードして名前を変更します。通知は送信されません
「Proposta v2 を Ana に送ってから、Bruno に送ってください。」	署名順を指定して、アップロード済みのドキュメントで署名を依頼します
「『金曜日までに署名してください』というメッセージを添えて、6 月 30 日まで有効にしてください。」	招待メッセージと有効期限を設定します
「賃貸契約を Ana に送ってください。[email protected] は署名を依頼せず、CC に入れてください。」	連絡先を保存し、CC の受信者のみを指定して送信します

ファイルを送信するには、ファイルを添付するか、保存場所を指定してください。アシスタントはファイルを読み取り、その内容を送信します。サーバーがあなたのコンピューター上のパスを開くことはありません。

テンプレートを使う

あなたの発言	起こること
「どのようなテンプレートがありますか？」	保存済みテンプレートと役割、フィールドを一覧表示します
「NDA テンプレートを Carla Souza（[email protected]）に使い、会社名は Acme Ltda. にしてください。」	フィールドを対応付け、値を検証して役割に入力し、送信します
「123.456.789-09 は CPF フィールドで有効ですか？」	何も作成せずに値を検証します

連絡先を管理する

あなたの発言	起こること
「Bruno Costa はすでに連絡先に登録されていますか？」	ワークスペースの署名者を検索します
「Bruno Costa（[email protected]）を連絡先に追加してください。」	連絡先を作成します。招待は送信されません
「Carla の WhatsApp 番号を +55 11 91234-5678 に変更してください。」	Assinafy の確認ルールに従って連絡先を更新します

未完了の依頼を確認する

あなたの発言	起こること
「Ana にサービス契約への署名をリマインドしてください。」	まだ未署名であることを確認して、リマインダーを送信します
「賃貸契約の署名期限を 7 月 15 日にしてください。」	有効期限を変更します。リマインダーは送信されません

ダウンロード、検証、削除

あなたの発言	起こること
「Acme の契約書の署名済みコピーをダウンロードしてください。」	証明処理が完了していることを確認し、証明済み PDF をダウンロードします
「契約書の最初のページを表示してください。」	ページのプレビューをダウンロードします
「この署名は有効ですか？ ハッシュ 3f2a…」	公開署名レジストリを確認します。ログインは不要です
「Proposta v1 の下書きを削除してください。」	現在の状態で Assinafy が許可する場合、ドキュメントを削除します

アシスタントが他の人に代わって署名したり、規約に同意したり、確認コードを伝えたりすることはありません。また、テンプレートの作成や編集も行いません。これらの操作は引き続き Assinafy で行ってください。

会話での動作

ユーザーの目的を起点にします。名前を解決し、すでに返されている ID を再利用します。 API の識別子を知っているよう求めないでください。宛先、役割、文書に曖昧さがある場合は、短く質問します。送信、リマインド、削除の明示的な依頼があれば、その操作はすでに承認されています。確認を繰り返さないでください。

依頼	フロー
「この PDF を Ana に送信してください。」	許可された連絡先を解決してから、assinafy_send_pdf_for_signature を実行します
「当社の NDA テンプレートを使ってください。」	テンプレート、役割、フィールドを特定し、値を検証してから、assinafy_create_document_from_template を呼び出します
「Ana はもう署名しましたか？」	assinafy_list_documents、続けて assinafy_get_document を実行し、未完了の項目と現在の状態を伝えます
「Ana にリマインドしてください。」	assignment を確認し、Ana に対して assinafy_resend_notification を呼び出します
「署名済みのコピーをダウンロードしてください。」	証明と成果物を確認し、artifact: "certificated" を指定して assinafy_download_document を実行します

Claude と ChatGPT のカード

あなたの発言	動作
「Acme の契約書の状況を見せてください。」	誰が署名し、誰が未署名か、有効期限を示すステータスカードが表示され、リマインドと更新を実行できます
「Ana と Bruno に NDA を送る前に確認したいです。」	宛先と検証結果を含む確認カードが表示されます。送信をクリックするまで何も送信されません
「賃貸契約書の署名フィールドを自分で配置したいです。」	各ページにフィールドを配置してから送信できる、全画面エディターが表示されます

Claude Code を含むその他のクライアントには、同じ情報がテキストで返されます。ビジュアルカードを参照してください。

モデルがツールを選択します。応答では、不要な ID や base64 を見せずに、結果を平易な言葉で説明します。読み取りや準備によって招待が送信されることはありません。すべてのツールと入力を参照してください。

文書のフロー

このサーバーは、操作ごとに 1 つずつ、27 個のツールを提供します。アシスタントがカタログからツールを選択し、あなたは実行したい操作を説明します。入力と例については、ツールリファレンスを参照してください。

flowchart TD
    A[Conectar e autorizar um workspace] --> B{Origem do documento}
    B --> C[Localizar um documento existente]
    B --> D[Enviar um PDF ou usar um template]
    D --> E[Preparar e solicitar assinaturas]
    C --> F[Ler status, assignment, signatários e atividades]
    E --> F
    F --> G{Estado atual}
    G -->|Pendente| H[Conferir entrega, lembrar ou atualizar expiração]
    H --> F
    G -->|Certificando| F
    G -->|Certificado| I[Baixar e verificar]
    G -->|Falha ou recusa| J[Inspecionar e escolher a recuperação]

1. ドキュメントを探し、状態を確認する

assinafy_list_documents を search、status、page、per_page とともに使用します。sort も指定でき、name または updated_at を受け取ります。先頭に - を付けると、並び順を逆にできます。ページ番号は1から始まり、1ページあたり最大100件が返されます。最初のページにすべてのドキュメントが含まれると決めつけず、返されたページネーションの meta に従ってください。

たとえば、assinafy_list_documents を次のように呼び出します。

{
  "status": "pending_signature",
  "sort": "-updated_at",
  "page": 1,
  "per_page": 25
}

正しいドキュメントを特定したら、assinafy_get_document を呼び出します。

{
  "document_id": "DOCUMENT_ID"
}

以降のすべての呼び出しでは、Assinafy から返された ID を使用してください。ID を作り出したり、ドキュメント ID から assignment の ID を推測したりしないでください。ドキュメントの詳細には、現在の status、is_closed、assignment、署名者の記録、ページ ID、アーティファクト、および Assinafy から報告された拒否理由が示されます。ドキュメント化されているライフサイクルは次のとおりです。

状態	次のステップ
uploading、uploaded、metadata_processing	処理は完了していません。後で確認してください。collect assignment では、ページのメタデータが準備できている必要があります。
metadata_ready	PDF を確認または名前変更し、署名リクエストを準備します。
pending_signature	未完了の署名者、署名順序、配信履歴、有効期限を確認します。
pending_identity_review	すべての署名が完了しています。認証の前に Assinafy で手動の本人確認を完了してください。
certificating	すべての署名がそろっていても、最終アーティファクトの生成中である場合があります。
certificated	利用可能な署名済みアーティファクトをダウンロードします。この状態は、ドキュメント化された API では削除できません。
expired	assignment を確認し、有効期限を更新するかどうか判断します。更新が許可されるかどうかは Assinafy が検証します。
rejected_by_signer、rejected_by_user	拒否の詳細を読み、ユーザーと次のステップを決めます。リマインダーを送っても拒否は取り消されません。
failed	復旧方法を決める前に、ドキュメントのアクティビティとエラーを確認します。

状態の確認は個別の読み取りであり、イベントの購読ではありません。ドキュメントの進捗確認を依頼された場合は、回数を制限して確認し、終端状態に達するか、合意した時間に達したら停止してください。

2. 進捗と配信状況を確認する

assinafy_get_document を使用して、実際に誰が未完了なのかを特定します。assignment には、利用可能な場合、id、signers[].id、completed、step、notified、notification_history、署名 URL が含まれます。省略可能なフィールドが存在しない場合、その情報は API から提供されていません。前のステップを待っている署名者は、必ずしも配信に失敗しているわけではありません。

document_id を指定して assinafy_list_document_activities を呼び出し、各イベントの日付とペイロードを含むタイムラインを取得します。notification_history を確認して、送信または失敗のイベントとエラーの詳細を調べます。WhatsApp での配信については、document_id と assignment_id を指定して assinafy_list_whatsapp_notifications を呼び出します。返されたリンクとアクセスコードは機密情報として扱い、許可された宛先にのみ共有してください。

進捗率が100%でも、認証済み PDF の準備が完了しているとは限りません。 ダウンロードする前に、ライフサイクルの状態とアーティファクトの利用可否を確認してください。

3. リマインダーを再送する

ドキュメントを再度読み込み、署名待ちの署名者と有効なステップを特定し、 ユーザーの指示がそのリマインダーを許可していることを確認してください。OAuth スコープは操作へのアクセスを許可するものであり、ユーザーに代わって 宛先を選ぶものではありません。リマインダーを送信すると通知クレジットを消費します。リマインダーの 明示的な依頼があれば、その操作はすでに許可されています。宛先または操作が 曖昧な場合に限り、質問してください。assinafy_resend_notification を次の内容で呼び出してください。

{
  "document_id": "DOCUMENT_ID",
  "assignment_id": "ASSIGNMENT_ID",
  "signer_id": "SIGNER_ID"
}

is_sent: true は再送の結果を示すもので、相手が 署名したことを意味するわけではありません。その後、配信履歴と進捗を確認してください。進捗に 変化がないからといって、繰り返し再送しないでください。送信が成功した後に 不確かな応答が返ることがあります。再試行する前に、アクティビティを確認してください。レート制限と再試行までの時間を 守ってください。

4. 有効期限を更新する、または宛先データを修正する

現在のドキュメント詳細の ID と、明示的な RFC 3339 タイムスタンプを使って assinafy_set_assignment_expiration を使用してください。

{
  "document_id": "DOCUMENT_ID",
  "assignment_id": "ASSIGNMENT_ID",
  "expires_at": "2027-01-31T23:59:59-03:00"
}

ユーザーが実際に指定した日付とタイムゾーンを選択してください。例は形式を示すためだけの ものです。更新後の assignment を読み込み、設定された日付を確認してください。有効期限を更新しても新しい招待が 送信されるとは限りません。

assinafy_list_signers または assinafy_get_signer で連絡先を 検索してください。assinafy_update_signer は full_name、email、whatsapp_phone_number、 および government_id を受け付けます。証明書または生体認証による検証の許可がある場合に限り、CPF/CNPJ を保存してください。連絡先は ワークスペース内で共有されるため、変更を適用する前に、予定している変更内容を確認してください。Assinafy は、進行中のドキュメントで すでに検証済みのチャネルの変更をブロックします。未検証のチャネルを 変更すると、古いリンクとコードは無効になります。修正に成功したら、許可された再送を使って新しいリンクを届けてください。Assinafy による拒否はそのまま保持し、ユーザーに伝えてください。

5. 新しい PDF を準備して送信する

通常のメール送信フローでは、assinafy_send_pdf_for_signature を呼び出します。

{
  "file_name": "contrato.pdf",
  "file_base64": "BYTES_DO_PDF_EM_BASE64",
  "signers": [
    {
      "full_name": "Pessoa de Exemplo",
      "email": "[email protected]"
    }
  ],
  "message": "Revise e assine o documento",
  "max_wait_secs": 30
}

このアドレスは架空のものです。実際のタスクで許可された宛先のみを指定してください。このツールは PDF を送信し、処理が完了するまで待機して、メール連絡先を作成または再利用し、検証と Email による招待を含む assignment を開始します。結果から document.id、assignment.id、signer_ids を保存してください。 1 回の呼び出しで指定できる署名者は最大 10 名です。合計タイムアウトは max_wait_secs に 2 分を加えた時間です。

送信前に準備するには、次の手順を使います。

1. assinafy_upload_document は file_name と file_base64 を受け取り、ドキュメントを返しますが、招待は送信しません。PDF の上限は 25 MiB、2,000 ページです。ページ数の上限は Assinafy が適用します。MCP サーバーがローカルのファイルパスを開くことはありません。
2. assinafy_get_document で準備状況を確認し、ID とページの寸法を取得します。document_id と name を指定して assinafy_rename_document を使い、名前を変更できる間にドキュメントの名前を変更します。名前を変更できるのは、assignment がまだ存在せず、状態が uploaded または metadata_ready の場合です。
3. assinafy_list_signers / assinafy_create_signer で署名者 ID を取得します。連絡先を作成しただけでは、署名依頼は送信されません。単独での作成は競合エラーになる場合があります。再試行する前に、既存の連絡先を検索してください。
4. assinafy_create_assignment は、既存のドキュメントに署名者 ID を使って署名を開始します。ワークスペースのドキュメント枠を消費し、WhatsApp では通知クレジットも消費するため、ユーザーが許可した宛先と操作を使用してください。追跡用に、返された assignment と ID 情報を保存してください。

assinafy_create_assignment の引数の例：

{
  "document_id": "DOCUMENT_ID",
  "method": "virtual",
  "signers": [
    {
      "id": "SIGNER_ID",
      "verification_method": "Email",
      "notification_methods": [
        "Email"
      ],
      "step": 1
    }
  ],
  "message": "Revise e assine o documento"
}

assignment ツールは、virtual と collect、任意の copy_receivers（署名者 ID）、message、expires_at、および step による署名順序を受け付けます。検証方法は Email、Whatsapp、DigitalCertificate、IdDocumentFaceMatchBasic です。各署名者には、互換性のある通知チャネル Email/WhatsApp を 1 つだけ指定します。WhatsApp を利用するには、適切な連絡先とプランが必要です。電子証明書と生体認証を利用するには、アカウントで該当機能が有効になっており、許可された government_id の更新によって連絡先に CPF/CNPJ が保存されている必要があります。生体認証には有効な CPF が必要です。Assinafy は送信時に、利用資格と現在の機能を検証します。

DigitalCertificate には method: "virtual" が必要です。collect の呼び出しは、見積もりや送信の前に digital_certificate_requires_virtual で拒否されます。

署名ツールでは estimate_only: true を指定して、送信前にコストと残高を確認してください。新しい PDF のプレビューはドキュメントを送信して保持します。署名を依頼するには、その ID を assinafy_create_assignment で再利用してください。それ以外のプレビューでは、レコードは作成されず、メッセージも送信されません。コストのプレビュー とリクエストおよびレスポンスの完全なペイロードを参照してください。依頼された操作には、ユーザーの許可をそのまま使用してください。不足しているドキュメントや宛先の選択についてのみ質問してください。進行が止まっているように見えるという理由だけで、同じ呼び出しを繰り返さないでください。

署名の順序を指定する場合、1 人でも署名者に step を指定したら、全員に指定する必要があります。値は 1 から始まる連続した数値にしてください。同じステップの人は並行して署名します。電子証明書を使う署名者は、単独のステップにしてください。

collect では、metadata_ready になるまで待機してください。フィールド定義の取得には、assinafy_list_fields（任意で include_standard: true を指定）と assinafy_get_field を使います。page_id と fields[] を含む entries[] を渡してください。各配置には、signer_id、field_id、および left、top、width、height、fontSize を含む display_settings を指定します。座標は、150 DPI でのページ画像のピクセルを基準とします。選択したページの範囲外への配置は、assignment を作成する前にサーバーが拒否します。ページのプレビューは assinafy_download_document_page で取得できます。

フィールド値の検証

assinafy_list_fields と assinafy_get_field を使用して定義を確認し、 assinafy_validate_fields で入力候補を検証します。

{
  "values": [
    {
      "field_id": "ID_DO_CAMPO_NOME",
      "value": "Empresa Exemplo"
    },
    {
      "field_id": "ID_DO_CAMPO_TOTAL",
      "value": "1250.00"
    }
  ]
}

MCP は本文の values を API の JSON 配列に変換します。検証によって ドキュメントが作成されたり、招待が送信されたりすることはありません。各結果の success と error_message を確認してください。HTTP リクエストが成功していても、 値が無効と報告される場合があります。先頭にゼロが付く識別子はテキストとして 保持してください。テンプレートの editor_fields[].value は、値が数値や日付を 表す場合でも、常に文字列を指定します。

6. テンプレートからドキュメントを生成する

assinafy_list_templates を使用して、役割、ページ、エディターのフィールドを確認します。 assinafy_get_template は、環境がこの互換ルートに対応している場合に、直接参照できます。個別のルートが利用できない場合は、一覧表示のレスポンスが公式ドキュメントで定義された情報源です。

「サービス契約のテンプレートで customer_name と contract_total を入力して」といった依頼では、作成前に名前を解決します。

1. assinafy_list_templates で依頼されたテンプレートを選択し、ページネーションに従って、処理ステータス、roles、pages[].fields を確認します。
2. 依頼された名前を、配置の label、または assinafy_list_fields / assinafy_get_field が返す定義に対応付けます。定義の id を配置の field_id に関連付け、配置の role_id がテンプレートのエディターの役割と一致することを確認します。そのテンプレートですでに設定済みのフィールドのみ入力してください。
3. editor_fields では、配置の field_id を使用します。配置の id やラベルは使用しないでください。フィールド名は設定可能な名前であり、ツールの引数名ではありません。クライアントはメタデータを使ってこの対応付けを行い、サーバーは ID を受け付けます。
4. 名前が欠落している場合や曖昧な場合は、どのフィールドを指すのかユーザーに確認してください。推測しないでください。同じ field_id を持つ配置が複数ある場合、すべてに同じ値が設定されます。このリクエストでは、配置ごとに異なる値を指定できません。
5. 提案された値を検証し、承認済みの作成を行う前に、テンプレートの各役割に対する署名者を解決します。

テンプレートの作成、およびレイアウトと役割の編集については、内部 API でのみ文書化されており、このサーバーでは公開されていません。テンプレートからドキュメントを作成する公開フローを使用する前に、Assinafy で保存済みのテンプレートを設定してください。

assinafy_create_document_from_template は、すべての役割を入力します。各エントリーには、既存の署名者の id または full_name と email を指定します。サーバーは後者の場合、署名者を作成するか再利用します。同じエントリーで両方を指定することはできません。そのため、1 回の呼び出しでディレクトリ内の署名者と新しい連絡先を組み合わせられます。エントリーでは、文書に記載されたとおりに verification_method、notification_methods、step も指定できます。メールアドレスで解決されたエントリーでは、メールによる検証と通知が使用されます。WhatsApp、証明書、生体認証による通知または検証には署名者の id が必要です。事前に承認済みの連絡先を準備してください。テンプレートの各エントリーで指定できるチャネルは 1 つだけです。Email または Whatsapp を指定します。サーバーは連絡先を作成する前に、すべてのエントリーと順序全体を検証します。エントリーで step を使用する場合は、すべてのエントリーで指定する必要があります。ステップは 1 から始まる連番とし、証明書で署名する人は単独のステップにしてください。Assinafy はその後も役割を検証するため、後続の処理で失敗すると、新しく作成された連絡先が残る場合があります。

フィールドが配置されたテンプレートでは collect を使用し、DigitalCertificate は使用できません。サーバーは証明書対応のテンプレートを確認し、費用の見積もり、連絡先の作成、ドキュメントの生成、招待の送信を行う前に digital_certificate_requires_virtual を返します。

この呼び出しでは、カスタム名、メッセージ、有効期限、tags（テンプレートのデフォルトと統合されるタグの名前）、および {field_id,value} 形式の editor_fields を指定できます。作成時に招待が送信され、ワークスペースのドキュメント割り当て枠が消費される場合があります。ユーザーが承認したドキュメントと宛先を使用してください。返されたドキュメント ID を保存し、以降の割り当てとステータス確認には assinafy_get_document を呼び出してください。

作成時の引数は次のとおりです（テンプレートと署名者ディレクトリで確認した ID に置き換えてください）。

{
  "template_id": "TEMPLATE_ID",
  "name": "Contrato de serviço.pdf",
  "signers": [
    {
      "role_id": "ID_DO_PAPEL_EDITOR",
      "id": "ID_DO_SIGNATARIO_PREPARADOR",
      "step": 1
    },
    {
      "role_id": "ID_DO_PAPEL_CLIENTE",
      "full_name": "Cliente Exemplo",
      "email": "[email protected]",
      "step": 2
    }
  ],
  "editor_fields": [
    {
      "field_id": "ID_DO_CAMPO_NOME",
      "value": "Empresa Exemplo"
    },
    {
      "field_id": "ID_DO_CAMPO_TOTAL",
      "value": "1250.00"
    }
  ]
}

以降のステータス確認、リマインダー、有効期限の変更、ダウンロードでは、アップロード済み PDF の場合と同様に、返されたドキュメント ID を使用します。

7. ページのプレビューを確認する

assinafy_download_document_page は、document_id と返された page_id を受け取ります。画像のバイトデータを base64 で返します。必要なページのみダウンロードしてください。

8. 署名済みアーティファクトをダウンロードして検証する

認証が完了したら、ドキュメント ID と artifact: "certificated" を指定して assinafy_download_document を呼び出します。結果には document_id、アーティファクト名、base64 が含まれます。デコードしたバイト列はクライアントのファイルツールで保存し、大きな base64 を会話に出力しないでください。

このツールでは original、certificated、certificate-page、pades、bundle も指定できます。アーティファクトを取得できるかどうかは、ライフサイクルと署名方式によって異なります。取得できないアーティファクトは、ダウンロードに成功したことを意味しません。バイナリー応答は、base64 にエンコードする前の時点で 64 MiB に制限されます。 base64 は、短いテキストの概要とともに、構造化された結果にのみ返されます。

署名済みドキュメントの署名 SHA-1 ハッシュを指定して assinafy_verify_document を呼び出します。ドキュメント ID や作成した値ではなく、ドキュメントに記載された実際の検証ハッシュを使用してください。これは接続せずに動作する唯一のツールです。公開署名レジストリを照会し、ワークスペースに属するものには一切アクセスしません。返された is_valid を報告してください。

署名の完了、拒否、必要な検証は、ユーザーが Assinafy 内で行います。これらのエンドポイントでは署名者のアクセスコードを使用しますが、これはワークスペースの OAuth2 権限の対象外です。これらのツールは規約に同意したり、検証コードを入力したり、誰かに代わって署名したりすることはありません。

9. 部分的な操作を再開する、または削除する

複数段階の送信は、アップロード後に失敗することがあります。エラーには作成されたドキュメントの ID が保持されます。続行する前に、そのドキュメントとアクティビティを確認してください。

• 既存の assignment があれば、署名リクエストはすでに成功している可能性があります。状況の確認を続けてください。別の assignment を作成したり、確認せずに再送信したりしないでください。
• assignment のない準備済みドキュメントの場合、確認済みの署名者 ID を指定して assinafy_create_assignment で続行します。再アップロードは不要です。フィールドを配置する前に、処理状況を確認してください。
• 削除を求められた場合は、現在のドキュメントの状態で許可されているときに限り、assinafy_delete_document を使用してください。この操作にはユーザーの許可が必要です。

MCP サーバーは、書き込みリクエストを自動的に再試行しません。

エラーと再接続

結果	クライアントの対応
HTTP 401	クライアントで権限を更新するか、Assinafy の同意フローから再接続してください。
insufficient_scope を伴う HTTP 403	要求されたスコープを、すでに許可されているスコープに追加して認可し、同意後に再試行してください。
不足しているスコープを示すツールエラー	Assinafy が呼び出しを拒否しました。示されたスコープを追加して再接続してください。新たな同意なしに再試行しても、再び失敗します。複数段階のツールでは先行する段階が完了している場合があります。エラーに保持された document_id がないか確認し、そこから続行してください。
isError: true を含むツール結果	Assinafy のエラーを読み、書き込みを再試行する前に現在のドキュメントを確認してください。
無効な連絡先、期限切れの assignment、または取得できないアーティファクト	リクエストを修正するか、必要なライフサイクル状態になるまで待ってください。
レート制限、またはネットワーク応答が不確かな場合	再試行までの時間を守ってください。書き込みを再試行する前に、状態と配信履歴を確認してください。
HTTP 429	Assinafy が認可チェックを制限しています。Retry-After に従ってください。
認証時の HTTP 503	サービスが一時的に利用できません。後でもう一度試してください。解消しない場合は Assinafy サポートにお問い合わせください。
カードに「完了できませんでした」と表示される	そのクリックでは何も変更されていません。まず現在の状態を確認するチャットから続行してください。

エラーと復旧および入力リファレンスを参照してください。

接続を確認する

再接続またはクライアントの更新後、クライアントのツール一覧を更新してください。 ログインせずに利用可能なカタログを確認することもできます。

curl -sS -X POST https://mcp.assinafy.com.br/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

ログイン時に invalid_target、invalid_client、またはリソースメタデータの不足が通知された場合は、URL が正確に https://mcp.assinafy.com.br/mcp であることと、クライアントが最新であることを確認してください。問題が解決しない場合は、クライアント名とバージョン、エラーメッセージを添えて Assinafy サポートにお問い合わせください。トークンや認証情報は含めないでください。

コストの事前確認と本人確認

既存の PDF、assignment、template、リマインダーの各ツールで estimate_only: true を使用すると、送信前に残高とコストの内訳を確認できます。PDF の事前確認ではドキュメントが送信され、保持されます。この ID を再利用して署名を依頼してください。その他の事前確認では、レコードは作成されず、メッセージも送信されません。見積もりによってクレジットは確保されません。Assinafy は送信時にリソースを再確認します。ワークフローとペイロードを参照してください。

生体認証では、assignment または template の署名者設定で IdDocumentFaceMatchBasic を使用します。事前に、承認済みの CPF を連絡先の government_id に保存してください。署名者は Assinafy で本人確認書類の写真撮影とライブネスチェックを完了します。手動審査は責任者のアカウントから Assinafy 上で行います。ドキュメントツールには InReview と pending_identity_review が表示されます。ICP-Brasil A1/A3 証明書には DigitalCertificate を使用します。証明書を持つ各署名者は、署名ステップに単独で割り当てられます。

MCP Events とは別に、Assinafy でアカウントの Webhook を設定してください。有料プランでは、最大 3 つのエンドポイントを利用できます。署名を有効にして作成したときに返されるシークレットを保存してください。OAuth アプリケーションでは、後からシークレットを取得したりローテーションしたりできません。カタログのツール数は引き続き正確に 27 個で、コスト、生体認証、Webhook 管理用の個別ツールはありません。本人確認とWebhook の署名を参照してください。