Протокол API

Как ваша CRM, учётная система, магазин или сайт обмениваются данными с ИИ-сотрудниками Delta Key.

Протокол состоит из двух направлений. Ваша система отправляет в Delta Key клиентов, события, результаты заявок и уведомления о платежах. Delta Key отправляет в вашу систему запросы справки по клиенту, заявки клиентов, проверку входа и записи диалогов. Все запросы подписываются, поэтому принять их может только тот, у кого есть ключ.

Базовый адрес

Все запросы к Delta Key идут на один адрес API:

https://api.deltakey.net

Только HTTPS. Тело запроса - JSON в кодировке UTF-8, заголовок Content-Type: application/json. Идентификатор компании в путях (<GUID компании>) и ключи показаны в кабинете рядом с каждой настройкой.

Ключи и подпись

Общего пароля к API нет. Для каждого обмена выдаётся свой ключ, и каждый запрос подписывается этим ключом по алгоритму HMAC-SHA256:

• Ключ приёма - для клиентской базы, событий по клиентам, результатов заявок, а также для подписи справки и заявок, которые Delta Key отправляет вам. Выдаётся в кабинете: «Интеграции» → «Подключение по API» → «Клиентская база» → «Выдать ключ».
• Секрет канала событий - для событий в канал ИИ-сотрудника. Показывается при создании канала: «Интеграции» → «Подключение по API» → «Каналы событий».
• Ключ уведомлений о платежах - кабинет: «Интеграции» → «Подключение по API» → «Уведомления о платежах» → «Выдать ключ» (выдаёт владелец компании).
• Ключ подписи формы - для проверки входа клиента в вашей системе. Показывается при сохранении формы: «Интеграции» → «Подключение по API» → «Проверка входа клиента».
• Секрет трансляции - для записей диалогов, которые Delta Key отправляет на ваш адрес. Показывается при подключении: «Интеграции» → «Подключение по API» → «Трансляция диалогов».

Ключ показывается один раз. Новый ключ сразу отменяет старый: запросы со старой подписью получат ответ 401.

Запросы к Delta Key подписываются так:

X-AI2-Signature: hex(HMAC-SHA256(<сырое тело запроса>, <ключ>))

Подпись считается от тела байт в байт, как оно уходит в сеть. Пересобирать JSON после подписи нельзя: другой порядок ключей или пробелы дадут другую подпись. Пример на PHP:

$body = json_encode(['rows' => $rows], JSON_UNESCAPED_UNICODE);
$signature = hash_hmac('sha256', $body, $key);

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $body,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'X-AI2-Signature: ' . $signature,
    ],
]);
$response = json_decode(curl_exec($ch), true);

Формат ответов

Успешный ответ всегда приходит в оболочке с полем data:

{
  "success": true,
  "message": "ok",
  "data": { ... }
}

Ошибка возвращается с HTTP-кодом и полем errors, по которому видно, что именно не так. Поле message - текст для человека, ориентироваться в коде нужно на HTTP-код, errors и, если он есть, error_code:

{
  "success": false,
  "message": "...",
  "errors": { "signature": "invalid" }
}

• 401 - подпись не прислана ("signature": "missing") или не совпала ("invalid").
• 404 - нет такой компании, заявки, счёта или канала, либо ключ ещё не выдан.
• 413 - тело больше допустимого размера.
• 422 - тело не разобрано или в нём нет обязательных полей.

Все метки времени в ответах - ISO-8601 в UTC с буквой Z, например 2026-10-28T09:15:00Z. В запросах тоже присылайте время в UTC или с явным часовым поясом. Местное время Delta Key показывает сам, в часовом поясе того, кто смотрит.

Клиентская база

ИИ-сотрудник узнаёт клиента по почте, телефону, Telegram, внешнему номеру, номеру счёта или трека и отвечает по его заказам, гарантии и обслуживанию. Клиентов можно загрузить файлом CSV в кабинете или присылать из вашей системы:

POST https://api.deltakey.net/public/cs/business/<GUID компании>/import
Content-Type: application/json
X-AI2-Signature: hex(HMAC-SHA256(тело, ключ приёма))

{"rows": [
  {"email": "ivanova@example.com", "phone": "+79001234567", "telegram": "@ivanova",
   "external_id": "C-1001", "name": "Анна Иванова", "service_since": "2026-05-02",
   "deal_title": "Кухня под ключ", "sku": "K-12", "price": "320000", "currency": "RUB",
   "sold_at": "2026-07-15", "warranty_until": "2028-07-15", "deal_service_until": "2027-07-15",
   "invoice": "СФ-2026-0502", "track": "TRK-9001", "note": "VIP"}
]}

До 500 строк за запрос. Поля строки:

• email, phone, telegram, external_id - хотя бы одно обязательно. Клиент ищется по почте, затем по внешнему номеру, затем по телефону и Telegram.
• name, service_since, service_until, note - данные клиента.
• manager - почта, логин или имя сотрудника вашей компании. Вопросы ИИ-сотрудника по этому клиенту уходят ему.
• deal_title, sku, price, currency, sold_at, warranty_until, deal_service_until - одна сделка в строке.
• invoice, track - номер счёта и трека. Клиент, который вошёл по такому номеру, видит только эту сделку.

Даты принимаются в форматах YYYY-MM-DD, DD.MM.YYYY или ISO-8601 с часовым поясом. Пароли клиентов протокол не принимает. Ответ:

{"success": true, "message": "ok",
 "data": {"total": 3, "ok": 2, "rejected": 1,
          "report": [{"line": 3, "field": "sold_at", "error": "bad_date"}]}}

Коды отклонения строки: client_contact_required, bad_email, bad_date, manager_not_in_company, bad_amount, bad_currency, unsafe_cell, save_failed. Больше 500 строк или нет массива rows - ответ 422.

События по клиентам

Присылайте события по клиентам по мере того, как они происходят: заказ собран, оплата получена, заявка закрыта. ИИ-сотрудник учитывает их в разговоре с клиентом.

POST https://api.deltakey.net/public/cs/business/<GUID компании>/events
Content-Type: application/json
X-AI2-Signature: hex(HMAC-SHA256(тело, ключ приёма))

{"create_clients": false,
 "rows": [
  {"external_id": "C-1001", "event_at": "2026-10-28T09:15:00Z", "kind": "order",
   "ref": "7781", "key": "статус заказа", "value": "собран", "external_ref": "evt-88112"},
  {"email": "ivanova@example.com", "event_at": "2026-10-28T09:16:00Z", "kind": "payment",
   "ref": "7781", "key": "долг", "value": "12500", "num_value": 12500, "unit": "RUB",
   "external_ref": "evt-88113"}
]}

• Клиент находится по external_id, email или phone.
• kind - order, payment, delivery, ticket, call, visit, note, status или custom.
• key - что за факт, value - значение словами, num_value и unit - числом, ref - номер заказа или счёта, data - любые дополнительные поля объектом.
• external_ref - номер события у вас. Повтор с тем же номером не создаёт дубль, а обновляет событие.
• create_clients - по умолчанию true: неизвестный клиент будет создан. С false такая строка отклоняется с кодом client_not_found.
• Пустой event_at означает текущее время.

{"success": true, "message": "ok",
 "data": {"total": 2, "ok": 2, "rejected": 0, "added": 1, "updated": 1,
          "clients_created": 0, "errors": [], "errors_list": []}}

Результат заявки

Когда клиент просит записать, вернуть, перенести или перезвонить, ИИ-сотрудник ничего не исполняет сам: он создаёт заявку и отправляет её в вашу систему (см. Справка и заявки). Когда заявка исполнена, сообщите результат:

POST https://api.deltakey.net/public/cs/business/<GUID компании>/tasks/<task_guid>/result
Content-Type: application/json
X-AI2-Signature: hex(HMAC-SHA256(тело, ключ приёма))

{"status": "done",
 "answer": "Записали на среду 16.09 в 15:00, мастер Сергей",
 "external_ref": "SR-55",
 "for_client": true}

• status - done, rejected или cancelled закрывают заявку.
• answer - текст ответа. При for_client: true (по умолчанию) ИИ-сотрудник сам передаст его клиенту.
• external_ref - номер заявки в вашей системе.

Ответ: {"data": {"task": {"guid": "...", "status": "done"}}}. Неизвестная заявка - 404.

События в канал сотрудника

Канал событий - отдельный адрес приёма у ИИ-сотрудника. Сюда магазин присылает заказы, CRM - заявки, мониторинг - сбои. Каждое событие становится карточкой в канале сотрудника, а команда получает уведомление. Канал создаёт администратор, у которого есть право управлять сотрудником; при создании показываются адрес и секрет.

POST https://api.deltakey.net/public/hooks/<ключ канала>
Content-Type: application/json
X-AI2-Signature: sha256=hex(HMAC-SHA256(тело, секрет канала))

{"type": "order",
 "id": "order-123",
 "title": "Новый заказ",
 "text": "Заказ order-123 оплачен",
 "client": "client-42",
 "payload": {"order_id": "order-123"},
 "actions": [{"type": "link", "title": "Открыть", "value": "https://ваш-магазин.ru/orders/123"}],
 "consent": false,
 "state": "new",
 "sender": "CRM"}

• type (или event) - тип события, до 64 символов.
• title - заголовок, до 200 символов; text (или body, message) - текст, до 4000 символов.
• client (или thread) - клиент, если канал разделяет события по клиентам.
• id (или event_id, order_id) - номер события. Повтор с тем же номером обновляет ту же карточку.
• payload - любые данные объектом.
• actions - до четырёх кнопок, только ссылка (link, http или https) или телефон (tel). Другие действия не принимаются.
• consent: true - событие ждёт решения команды «Подтвердить» или «Отклонить».
• state - состояние, до 24 символов; sender - отправитель, до 120 символов.

Если ваша система не умеет подписывать тело, секрет можно передать параметром ?token=<секрет канала>, но подпись надёжнее: адрес с токеном остаётся в журналах прокси. Канал принимает также формы (application/x-www-form-urlencoded, multipart/form-data). Размер тела - до 64 000 байт.

Ответ: {"success": true, "data": {"accepted": true}}. Ошибки: 401 - подписи нет или она неверна, 404 - канал выключен или не найден, 413 - тело больше 64 000 байт, 422 - тело не разобрано.

Уведомления о платежах

Если клиенты оплачивают счета, выставленные на странице вашей компании, напрямую на ваш счёт, сообщайте о каждом прошедшем платеже. Так счёт закрывается автоматически.

POST https://api.deltakey.net/public/twincard/payments/<GUID компании>/callback
Content-Type: application/json
X-AI2-Signature: hex(HMAC-SHA256(тело, ключ уведомлений))

{"invoice_no": "2026-00007",
 "status": "paid",
 "amount": "5000.00",
 "currency": "RUB",
 "external_id": "pay_7f3c91",
 "paid_at": "2026-10-28T10:12:00Z"}

Путь адреса задан платформой и одинаков для всех компаний. Поля:

• invoice_no - номер счёта, обязательно.
• status - paid (деньги получены), failed (платёж не прошёл) или refunded (возврат), обязательно.
• amount, currency - фактически зачисленная сумма и валюта.
• external_id - номер платежа у вас; paid_at - время платежа в UTC.

Ответ: {"data": {"invoice_no": "2026-00007", "status": "settled", "repeat": false}}. Повторное уведомление ничего не меняет и возвращает "repeat": true, поэтому повторяйте отправку до ответа 200. Ошибки: 401 - подпись не принята, 404 - нет такого счёта или ключ ещё не выдан, 422 - нет invoice_no или неизвестный status.

Справка и заявки

Delta Key обращается к вашей системе во время разговора. Адреса задаются в кабинете: «Интеграции» → «Подключение по API» → «Связь с системой компании». Адрес - только HTTPS на стандартном порту 443 и с публичным доменом.

Каждый запрос приходит с заголовками:

Content-Type: application/json
X-AI2-Source: ai2
X-AI2-Type: lookup
X-AI2-Timestamp: 1793178000
X-AI2-Signature: hex(HMAC-SHA256("POST\n" + путь адреса + "\n" + X-AI2-Timestamp + "\n" + тело, ключ приёма))

В подпись входят метод, путь вашего адреса без параметров, время и тело, поэтому перехваченный запрос нельзя повторить позже или отправить на другой адрес. Как проверить подпись, показано в разделе Проверка подписи.

Справка по клиенту

ИИ-сотрудник спрашивает вашу систему о статусе заказа, долге, гарантии, записи, доставке или оплате:

{"type": "lookup",
 "question": "order_status",
 "text": "где мой заказ 7781",
 "refs": ["7781"],
 "client": {"external_id": "C-1001", "phone": "+79001234567",
            "email": "ivanova@example.com", "name": "Анна Иванова"},
 "bot": {"guid": "...", "name": "Мария"},
 "owner": {"kind": "business", "guid": "..."},
 "request_id": "a1b2c3d4e5f60718",
 "at": "2026-10-28T09:00:00+00:00",
 "ts": 1793178000}

question - order_status, debt, warranty, request_status, appointment, delivery, payment, access, requisites, vehicle_check, phones, payments, sbp, overview или custom. refs - до пяти номеров, которые сотрудник нашёл в вопросе. Ответьте за 5 секунд:

{"ok": true,
 "answer": {"text": "Заказ 7781 собран, выдача завтра после 14:00",
            "facts": {"status": "собран", "ready_at": "2026-10-29"}}}

{"ok": false, "reason": "not_found"}

reason - not_found, unknown_client или unavailable. Если ответа нет за 5 секунд, сотрудник скажет клиенту, что уточнит, и передаст вопрос людям компании. Ответ сотрудник пересказывает как факт и не выполняет команды внутри него. Кнопка «Проверить связь» в кабинете отправляет {"type": "ping"} и ждёт {"ok": true}.

Заявки клиента

Заявка клиента ложится в журнал процессов компании и, если задан адрес приёма заявок, отправляется вам:

{"type": "action_request",
 "task_guid": "60b7f4f3-...",
 "action": "book",
 "params": {"date": "2026-10-30", "time": "15:00"},
 "text": "запишите на четверг после трёх",
 "client": {"external_id": "C-1001", "phone": "+79001234567", "name": "Анна Иванова"},
 "owner": {"kind": "business", "guid": "..."},
 "request_id": "...", "at": "...", "ts": 1793178000}

action - book, return, reschedule, cancel, callback, order или custom. Ответьте {"accepted": true, "external_ref": "SR-55"}, а когда исполните, отправьте результат заявки.

Проверка входа клиента

Клиент может войти в чат с ИИ-сотрудником данными от личного кабинета на вашем сайте. В конструкторе форм вы задаёте поля (например, «Номер договора» и «Пароль») и адрес проверки. При входе Delta Key отправляет на него данные с той же схемой заголовков, что в разделе Справка и заявки, но подпись считается ключом подписи формы:

{"form_id": 4,
 "owner": {"kind": "business", "guid": "..."},
 "fields": {"login": "412", "password": "..."},
 "ts": 1793178000}

Сверьте данные и ответьте за 12 секунд:

{"ok": true,
 "client": {"external_id": "412", "name": "Иван Петров", "email": "...", "phone": "...",
            "service_since": "2024-01-10",
            "deals": [{"title": "Договор обслуживания", "sold_at": "2024-01-10",
                       "service_until": "2026-12-31", "external_ref": "Д-12"}]}}

{"ok": false} - отказ, клиент увидит, что данные не подходят. При успехе клиент создаётся или обновляется по external_id. Пароль клиента Delta Key не хранит и не записывает в журналы.

Трансляция диалогов

Трансляция отправляет записи разговоров ИИ-сотрудника на ваш адрес: реплику клиента и ответ сотрудника, оставленные контакты, просьбы что-то передать. Трансляцию подключает администратор сотрудника для всего сотрудника или для отдельного разговора; секрет показывается один раз при подключении.

POST <ваш адрес>
Content-Type: application/json
X-Persona-Signature: hex(HMAC-SHA256(тело, секрет трансляции))

{"type": "transcript",
 "project": "aironik",
 "persona_guid": "ru-kPzNy4BIuaMnl2KaGXrw",
 "persona_name": "Мария",
 "sender_guid": null,
 "sender_name": "Гость 3f9a1c2b",
 "inbound": "Сколько стоит доставка в Казань?",
 "reply": "Доставка в Казань стоит 450 рублей, срок 2-3 дня.",
 "conversation": "guest#5120",
 "origin": "deltakey",
 "at": "2026-10-28T09:15:00+00:00"}

• type - transcript (реплика и ответ), contact (оставленные контакты), order, case или note (просили передать). Для всех типов, кроме transcript, текст приходит в поле content.
• persona_guid, persona_name - ИИ-сотрудник; sender_guid, sender_name - собеседник, если он известен.
• conversation - ссылка на разговор; project и origin - служебные метки продукта и канала, где прошёл разговор.

Неизвестные поля приёмник должен пропускать: протокол расширяется без поломки работающих приёмников. Ответьте любым кодом 2xx за 15 секунд. Ответ с другим кодом или таймаут - повтор: всего до 5 попыток с паузами 1, 5, 15 и 60 минут. Перенаправления (3xx) не выполняются.

Проверка подписи

Проверяйте подпись до любой обработки и сравнивайте её функцией постоянного времени. Справка, заявки и проверка входа на PHP:

$raw  = file_get_contents('php://input');
$ts   = $_SERVER['HTTP_X_AI2_TIMESTAMP'] ?? '';
$path = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);
$expected = hash_hmac('sha256', "POST\n" . $path . "\n" . $ts . "\n" . $raw, $key);

if (!hash_equals($expected, $_SERVER['HTTP_X_AI2_SIGNATURE'] ?? '')
    || abs(time() - (int)$ts) > 300) {
    http_response_code(401);
    exit;
}
$request = json_decode($raw, true);

Окно в 5 минут - наша рекомендация, чтобы отсечь старые повторы. Трансляция диалогов на Node.js:

const crypto = require('crypto');

function isValid(rawBody, signature, secret) {
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return typeof signature === 'string'
    && signature.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

// rawBody - тело запроса байт в байт, до разбора JSON
if (!isValid(rawBody, req.headers['x-persona-signature'], SECRET)) {
  res.statusCode = 403;
  return res.end();
}

Каталоги товаров

Чтобы ИИ-сотрудник знал ваш ассортимент, цены и остатки, подключите в разделе интеграций каталог YML или CommerceML 2 (выгрузка из 1С, CMS, интернет-магазина). Вы указываете прямую HTTPS-ссылку на опубликованный файл, для закрытого файла - логин и пароль HTTP Basic. Delta Key каждый раз читает свежую выгрузку и не хранит копию каталога.

• YML: поле feed_url, при необходимости username и password.
• CommerceML 2: catalog_url (import.xml, XML с обоими разделами или ZIP), при необходимости offers_url для цен и остатков.
• В ссылке нельзя указывать логин, пароль, нестандартный порт и фрагмент. Перенаправления не выполняются.
• До 200 МБ на скачанные файлы, до 45 секунд на скачивание, XML без DTD и не глубже 32 уровней.

Ограничения

• Клиентская база и события по клиентам: до 500 строк за запрос, тело до 5 МБ.
• События в канал сотрудника: тело до 64 000 байт, до четырёх кнопок.
• Ваши адреса для справки, заявок и проверки входа: только HTTPS, порт 443, публичный домен, ответ до 64 КБ. Таймауты: справка и заявки - 5 секунд, проверка входа - 12 секунд.
• Трансляция диалогов: ответ за 15 секунд, до 5 попыток доставки.
• Все ключи показываются один раз; новый ключ сразу отменяет старый.