كيف تربط okdoc مع Priority ERP

ماذا يفعل الربط

يعمل الربط في الاتجاهين. الأول: عندما يوقّع العميل مستندًا في okdoc، يُحفظ ملف PDF الموقّع (مع شهادة التدقيق الخاصة به) تلقائيًا في مرفقات السجل المطابق في Priority، مثل أمر البيع. الثاني: عندما يصل سجل في Priority إلى حالة تختارها، مثل أمر تمت الموافقة على إرساله، يرسل okdoc إلى العميل المستند للتوقيع عبر البريد الإلكتروني أو WhatsApp. لا أحد يُدخل البيانات نفسها مرتين، ولا يضيع أي عقد موقّع في صندوق البريد.

ما تحتاجه قبل أن تبدأ

من جهة okdoc: خطة تتضمن الوصول إلى API، وهي حاليًا AGENCY، لأن مفاتيح API لا يمكن إنشاؤها إلا فيها. من جهة Priority: الإصدار 17.2 أو أحدث لكتابة البيانات عبر API، و19.1 أو أحدث لرمز الوصول الشخصي (Personal Access Token أو PAT)، و21.0 أو أحدث لإرفاق الملفات، بالإضافة إلى وحدة Webhooks إذا أردت الاتجاه الثاني أيضًا. وبين الطرفين: موصِّل يستقبل رسالة من أحدهما ويستدعي الآخر. يمكن أن يكون سيناريو في Make أو Zapier، أو سير عمل في n8n، أو دالة قصيرة على خادمك الخاص.

الخطوة 1: مفتاح API في okdoc

في تطبيق okdoc، افتح شاشة «المطورون» وأنشئ مفتاحًا جديدًا. يبدأ المفتاح بـ ok_live_ ويُعرض مرة واحدة فقط، لذا احفظه فورًا في الموصِّل، في مكان آمن. كل استدعاء لواجهة API الخاصة بـ okdoc يحمل الترويسة Authorization: Bearer متبوعة بالمفتاح.

الخطوة 2: رمز وصول في Priority

في Priority، عرّف رمز وصول شخصي (Personal Access Token) في نموذج REST Interface Access Tokens، لمستخدم لديه صلاحيات على النماذج التي يحتاجها الربط. تستخدم الاستدعاءات إلى Priority مصادقة Basic: اسم المستخدم هو الرمز، وكلمة المرور هي ببساطة الكلمة PAT. عنوان URL الأساسي لواجهة API خاص بكل تثبيت، ويعرفه مسؤول 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: تنزيل النسخة الموقّعة

لا تتضمن الرسالة الملف، بل معرّف المستند فقط. يستدعي الموصِّل okdoc بهذا المعرّف ويحصل على الحالة، وبيانات الموقّع، وسجل الأحداث، ورابط لتنزيل ملف PDF الموقّع. الرابط صالح لمدة ساعة واحدة، لذا نزّل الملف فورًا بدلًا من حفظ الرابط.

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)، ويُرسل الملف بصيغة data URL بترميز base64. بدءًا من الإصدار 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>

كيف يعرف الموصِّل بأي سجل يُرفق الملف

تحتاج إلى طريقة للوصول إلى سجل Priority انطلاقًا من مستند okdoc. الطريقة البسيطة: ضع رقم السجل في عنوان المستند، مثل "Order SO26000123"، ودع الموصِّل يقرؤه من العنوان. والطريقة الأدق: عندما يُنشأ المستند من Priority (الاتجاه الثاني)، يحفظ الموصِّل معرّف المستند الذي أعاده okdoc بجانب رقم السجل، فعندما تصل رسالة التوقيع يعرف بالضبط إلى أين تنتمي.

الاتجاه الآخر: Priority يرسل مستندًا للتوقيع

في Priority، سجّل عنوان الموصِّل في نموذج Webhook Definitions (System Management > System Maintenance > Periodic Maintenance > BPM Maintenance) وأنشئ رمز مصادقة. يُخفى الرمز بمجرد مغادرة السطر، لذا انسخه فورًا. ثم أضف قاعدة عمل أو قاعدة BPM على الحالة التي تريدها، واختر الإجراء Webhook، وحدّد في متن الرسالة الحقول المطلوب إرسالها: رقم السجل، واسم العميل، وبريده الإلكتروني، ورقم هاتفه. يرسل Priority الرمز في الترويسة priority-bpm-token، ويتحقق الموصِّل من تطابقه. ومن هناك يستدعي الموصِّل okdoc: إذا كان هناك ملف PDF أُنتج في Priority، يستخدم مسار الرفع، الذي يضيف خانة توقيع ويرسل إلى العميل رابطًا عبر البريد الإلكتروني أو 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، يوجد أيضًا سجل لأخطاء webhooks. احفظ المفاتيح في الموصِّل فقط، وليس أبدًا في المتصفح أو في كود عام، وامنح مستخدم API في Priority صلاحية الوصول إلى النماذج التي يحتاجها فعلًا فقط.

الأسئلة الشائعة