External API

Что это за раздел

Раздел External API нужен владельцу компании, чтобы выпускать и отключать ключи для внешних сервисов, которые передают данные в Omnis.

Кто может работать с разделом

Раздел доступен только владельцу компании.

Менеджеры и другие сотрудники не должны выпускать ключи External API, потому что ключ дает внешней системе доступ к интеграции от имени компании.

Что видно на странице

На странице есть:

• поле Название ключа
• кнопка Создать ключ
• одноразовый блок с новым Key ID и Secret
• список ранее созданных ключей
• статус ключа: активен или отключен
• дата создания
• дата последнего использования, если по ключу уже были запросы
• fingerprint секрета для сверки без раскрытия самого секрета

Как создать ключ

1. Откройте Система -> Настройки.
2. Откройте карточку External API.
3. Введите понятное название ключа, например название внешней системы.
4. Нажмите Создать ключ.
5. Скопируйте Key ID.
6. Скопируйте Secret.
7. Передайте значения только в защищенное хранилище внешней системы.

Secret показывается только один раз сразу после создания ключа.

Если закрыть блок с секретом или уйти со страницы, посмотреть этот секрет снова нельзя. В таком случае нужно создать новый ключ и отключить старый.

Как использовать ключ во внешней системе

Внешняя система должна подписывать запросы через HMAC.

Минимальный набор заголовков:

X-Omnis-Key-Id: <Key ID>
X-Omnis-Timestamp: <unix timestamp в секундах или миллисекундах>
X-Omnis-Nonce: <случайная одноразовая строка>
X-Omnis-Signature: sha256=<hex HMAC SHA-256>

X-Omnis-Key-Id берется из списка ключей External API. Secret показывается один раз сразу после создания ключа, его нужно сохранить во внешней системе.

Подпись считается по строке:

<timestamp>.<nonce>.<raw request body>

Ключом HMAC является Secret, который был показан при создании ключа.

X-Omnis-Timestamp должен быть свежим. X-Omnis-Nonce должен быть случайной строкой длиной от 8 до 128 символов и не должен повторяться в пределах replay window. Старые или повторно использованные запросы отклоняются защитой от replay.

Пример подписанного запроса на Node.js:

import crypto from "crypto";

const keyId = "ext_live_...";
const secret = "secret_shown_once";
const timestamp = Math.floor(Date.now() / 1000).toString();
const nonce = crypto.randomBytes(16).toString("hex");

const body = JSON.stringify({
  source: "external",
  records: [
    {
      extId: "order-123",
      clientFullName: "Иван",
      clientPhone: "+79990000000",
      note: "Комментарий",
    },
  ],
});

const signature = crypto
  .createHmac("sha256", secret)
  .update(`${timestamp}.${nonce}.`, "utf8")
  .update(body)
  .digest("hex");

await fetch("https://<host>/api/v1/ext/com/call-order", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Omnis-Key-Id": keyId,
    "X-Omnis-Timestamp": timestamp,
    "X-Omnis-Nonce": nonce,
    "X-Omnis-Signature": `sha256=${signature}`,
  },
  body,
});

Важно: подписывать нужно именно ту строку body, которая затем отправляется в запросе. Не пересобирайте JSON после расчета подписи.

Как отключить ключ

1. Откройте Система -> Настройки.
2. Откройте External API.
3. Найдите нужный ключ.
4. Нажмите Отключить.
5. Подтвердите действие.

После отключения ключ больше не принимает внешние запросы.

Важные правила безопасности

• не отправляйте Secret в чатах и письмах без защищенного канала
• не храните Secret в исходном коде внешней системы
• используйте отдельный ключ для каждой внешней системы
• отключайте ключ сразу после подозрения на утечку
• не передавайте ключ подрядчикам без необходимости
• проверяйте дату последнего использования, если внешний сервис неожиданно перестал работать

Что делать при утечке

Если есть подозрение, что Secret стал известен посторонним:

1. Отключите скомпрометированный ключ.
2. Создайте новый ключ.
3. Замените Key ID и Secret во внешней системе.
4. Проверьте последние действия внешней системы.
5. Сообщите ответственному за безопасность или владельцу компании.