Как подключить okdoc к Priority ERP

Что делает интеграция

Она работает в обе стороны. Первое: когда клиент подписывает документ в okdoc, подписанный PDF (вместе с сертификатом аудита) автоматически сохраняется во вложениях соответствующей записи Priority, например заказа клиента. Второе: когда запись в Priority переходит в выбранный вами статус, например заказ одобрен к отправке, okdoc отправляет клиенту документ на подпись по email или в WhatsApp. Никому не нужно вводить одни и те же данные дважды, и ни один подписанный договор не теряется в почте.

Что нужно до начала работы

Со стороны okdoc: тариф с доступом к API, сейчас это AGENCY, поскольку ключи API можно создавать только на нём. Со стороны Priority: версия 17.2 или новее для записи данных через API, 19.1 или новее для Personal Access Token (PAT), 21.0 или новее для прикрепления файлов, а также модуль Webhooks, если вам нужно и второе направление. Между ними: коннектор, который получает сообщение от одной стороны и вызывает другую. Это может быть сценарий в Make или Zapier, workflow в 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 в момент подписания

В том же разделе «Разработчикам» добавьте вебхук с HTTPS-адресом коннектора и отметьте событие document.signed. okdoc отправляет сообщения только на адреса HTTPS, потому что в них передаются имя и email подписанта. У каждого вебхука есть секрет, начинающийся с 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 документа. Коннектор вызывает okdoc с этим ID и получает статус, данные подписанта, журнал событий и ссылку для скачивания подписанного 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. Простой вариант: укажите номер записи в названии документа, например "Заказ SO26000123", и пусть коннектор считывает его из названия. Более точный вариант: когда документ создаётся из Priority (второе направление), коннектор сохраняет ID документа, который вернул okdoc, рядом с номером записи, и когда приходит сообщение о подписании, он точно знает, куда его отнести.

Обратное направление: Priority отправляет документ на подпись

В Priority зарегистрируйте адрес коннектора в форме Webhook Definitions (System Management > System Maintenance > Periodic Maintenance > BPM Maintenance) и сгенерируйте токен аутентификации. Токен скрывается, как только вы уходите со строки, поэтому скопируйте его сразу. Затем добавьте бизнес-правило или правило BPM на нужный статус, выберите действие Webhook и перечислите в теле сообщения поля для отправки: номер записи, имя клиента, email и телефон. Priority передаёт токен в заголовке priority-bpm-token, а коннектор проверяет, что он совпадает. Дальше коннектор вызывает okdoc: если PDF сформирован в Priority, используется маршрут загрузки, который добавляет блок подписи и отправляет клиенту ссылку по email, в 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, есть также журнал ошибок вебхуков. Храните ключи только в коннекторе, никогда в браузере или в публичном коде, и давайте пользователю API в Priority доступ только к тем формам, которые ему действительно нужны.

Частые вопросы