okdocをPriority ERPと連携する方法

連携でできること

連携は双方向で動作します。1つ目：顧客がokdocで文書に署名すると、署名済みPDF（監査証明書付き）が、対応するPriorityのレコード（たとえば受注）の添付ファイルに自動で保存されます。2つ目：Priorityのレコードが指定したステータス（たとえば送付が承認された受注）になると、okdocが顧客にメールまたはWhatsAppで署名用の文書を送信します。同じ情報を二度入力する必要はなく、署名済みの契約書が受信トレイに埋もれることもありません。

始める前に必要なもの

okdoc側：API利用が可能なプラン（現在はAGENCY。APIキーはこのプランでのみ作成できます）。Priority側：APIでデータを書き込むにはバージョン17.2以降、Personal Access Token（PAT）には19.1以降、ファイルの添付には21.0以降が必要です。逆方向の連携も使う場合は、Webhooksモジュールも必要です。その間をつなぐのがコネクターで、一方からメッセージを受け取り、もう一方を呼び出します。MakeやZapierのシナリオ、n8nのワークフロー、または自社サーバー上の短い関数で実装できます。

ステップ1：okdocでAPIキーを作成

okdocアプリで「開発者向け」画面を開き、新しいキーを作成します。キーはok_live_で始まり、一度しか表示されないため、すぐにコネクター内の安全な場所に保存してください。okdoc APIへの呼び出しにはすべて、Authorization: Bearer の後にキーを続けたヘッダーを付けます。

ステップ2：Priorityでアクセストークンを作成

Priorityで、連携に必要なフォームへの権限を持つユーザーに対し、REST Interface Access TokensフォームでPersonal Access Tokenを定義します。Priorityへの呼び出しにはBasic認証を使います。ユーザー名にはトークンを、パスワードには単に「PAT」という文字列を指定します。APIのベースURLはインストールごとに異なり、Priorityの管理者が把握しています。

ステップ3：署名と同時にokdocから通知を受け取る

同じ「開発者向け」画面でWebhookを追加し、コネクターのHTTPSアドレスを指定して、document.signedイベントにチェックを入れます。メッセージには署名者の氏名とメールアドレスが含まれるため、okdocはHTTPSアドレスにのみ送信します。各Webhookにはwhsec_で始まるシークレットがあり、okdocはこれを使ってすべてのメッセージに署名します。X-OKDOC-Signatureヘッダーには、メッセージ本文のHMAC-SHA256が入っています。コネクターは同じ値を計算し、一致しないメッセージはすべて拒否します。メッセージの例と検証方法は次のとおりです。

POST https://your-connector.example.com/okdoc
X-OKDOC-Event: document.signed
X-OKDOC-Signature: <HMAC-SHA256 hex of the raw body, keyed with whsec_...>

{
  "event": "document.signed",
  "created_at": "2026-10-19T09:12:44.120Z",
  "data": {
    "document": { "id": "6f1c...", "title": "Order SO26000123", "status": "signed", "locale": "he" },
    "recipient": { "name": "Dana Levi", "email": "dana@example.com" }
  }
}

// Node.js: reject anything that was not signed with your webhook secret
import { createHmac, timingSafeEqual } from "crypto";
const expected = Buffer.from(createHmac("sha256", process.env.OKDOC_WEBHOOK_SECRET).update(rawBody).digest("hex"));
const received = Buffer.from(req.headers["x-okdoc-signature"] ?? "");
const valid = received.length === expected.length && timingSafeEqual(received, expected);

ステップ4：署名済みコピーをダウンロード

メッセージにはファイルは含まれず、文書のIDだけが入っています。コネクターはそのIDでokdocを呼び出し、ステータス、署名者の情報、イベントログ、署名済みPDFのダウンロードリンクを取得します。リンクの有効期限は1時間なので、リンクを保存するのではなく、すぐにファイルをダウンロードしてください。

GET https://okdocai.com/api/v1/documents/6f1c...
Authorization: Bearer ok_live_...

200 OK
{
  "id": "6f1c...",
  "title": "Order SO26000123",
  "status": "signed",
  "signed_at": "2026-10-19T09:12:41Z",
  "signed_pdf_url": "https://...   (valid for one hour)",
  "recipient": { "name": "Dana Levi", "email": "dana@example.com", "status": "signed" },
  "events": [ { "type": "...", "at": "..." } ]
}

ステップ5：PDFをPriorityのレコードに添付

Priorityでは、レコードの添付ファイル用サブフォーム（EXTFILES_SUBFORM）を通じて、ファイルをbase64のdata URLとして送信して添付します。バージョン22.0以降ではSUFFIXフィールドに.pdfを指定でき、Priorityはファイルの種類を推測する代わりにこの値を使います。例では受注にファイルを添付していますが、添付ファイルを持つフォームであればどれも同じ方法で使えます。

POST {serviceRoot}/ORDERS('SO26000123')/EXTFILES_SUBFORM
Authorization: Basic base64("<your PAT>:PAT")
Content-Type: application/json

{
  "EXTFILEDES": "Signed via okdoc",
  "EXTFILENAME": "data:application/pdf;base64,JVBERi0xLjcK...",
  "SUFFIX": ".pdf"
}

// serviceRoot looks like: https://<server>/odata/Priority/<tabula.ini>/<company>

コネクターが添付先のレコードを判断する方法

okdocの文書からPriorityのレコードを特定する手段が必要です。簡単な方法：文書のタイトルにレコード番号を入れ（例：「注文 SO26000123」）、コネクターにタイトルから読み取らせます。より正確な方法：Priorityから文書を作成する場合（逆方向の連携）、コネクターはokdocが返した文書IDをレコード番号と一緒に保存しておきます。こうすれば、署名完了のメッセージが届いたときに、どのレコードに属するかを正確に判断できます。

逆方向：Priorityから署名用の文書を送信

Priorityで、Webhook Definitionsフォーム（System Management > System Maintenance > Periodic Maintenance > BPM Maintenance）にコネクターのアドレスを登録し、認証トークンを生成します。トークンは行から移動するとすぐに非表示になるため、その場でコピーしてください。次に、対象のステータスにビジネスルールまたはBPMルールを追加してWebhookアクションを選択し、メッセージ本文に送信するフィールド（レコード番号、顧客の氏名、メールアドレス、電話番号）を指定します。Priorityはトークンをpriority-bpm-tokenヘッダーで送信し、コネクターはそれが一致するかを確認します。その後、コネクターがokdocを呼び出します。Priorityで作成したPDFがある場合はアップロード用のルートを使います。このルートは署名欄を追加し、メール、WhatsApp、またはその両方で顧客にリンクを送信します。ファイルがない場合は、POST /api/v1/documentsでテキスト文書を作成できます。

// What Priority sends (header priority-bpm-token carries your webhook token).
// The fields are the ones you put in the business rule message, for example:
{ "ORDERS": { "ORDNAME": "SO26000123", "CDES": "Dana Levi" } }

// Your connector then sends the PDF to okdoc for signature:
POST https://okdocai.com/api/v1/documents/upload
Authorization: Bearer ok_live_...
Content-Type: multipart/form-data

file             = SO26000123.pdf
title            = Order SO26000123
recipient_name   = Dana Levi
recipient_email  = dana@example.com      (optional: emails the signing link)
recipient_phone  = +972501234567         (optional: WhatsApps the signing link)

201 Created
{ "id": "6f1c...", "status": "sent", "signing_url": "https://...", "emailed": true, "whatsapped": true }

おまけ：okdocのレポートに取引金額を反映

okdocは、文書ごとの取引金額と、まだ保留中の金額を表示します。Priorityに金額がすでにある場合は、コネクターがその金額を文書に書き込みます。これは文書の送信後や署名後でも可能です。

PATCH https://okdocai.com/api/v1/documents/6f1c...
Authorization: Bearer ok_live_...
Content-Type: application/json

{ "deal_amount": 12500 }

本番稼働前に確認すること

自分宛てにテスト文書を送り、署名して、正しいレコードの添付ファイルにPDFが表示されることを確認します。問題を見逃さないよう、コネクターが受信したすべてのメッセージと、失敗したすべての呼び出しをログに記録してください。Priorityでは、バージョン26.0以降でWebhookのエラーログも利用できます。キーはコネクター内にのみ保管し、ブラウザや公開コードには絶対に置かないでください。また、PriorityのAPIユーザーには、本当に必要なフォームへのアクセス権だけを付与してください。

よくある質問