Как получать от ИИ корректный JSON для CRM и ERP

Короткий ответ: для интеграции с CRM или ERP нужны две отдельные вещи. Во-первых, структурированный вывод по схеме, чтобы модель возвращала данные в известной форме с нужными полями и типами. Во-вторых, собственная проверка бизнес-значений в коде интеграции до любой записи. Корректный JSON не означает, что сумма верна, товар существует, клиент найден или модель имела право менять сделку.

Главное условие: модель предлагает данные, а решение о записи принимает ваш код по правилам процесса. Прочитав статью, вы сможете описать контракт данных для своего сценария, перечень проверок перед CRM, правила обработки неполных ответов и отказов, а также набор приёмочных примеров, без которого интеграцию не стоит запускать.

Три уровня корректности

Когда разработчик говорит «модель возвращает неправильный JSON», он может иметь в виду три разные проблемы. Их следует разделять, потому что каждая решается по-своему.

Уровень 1. Синтаксис. Ответ вообще является допустимым JSON: скобки закрыты, строки заключены в кавычки, до или после объекта нет пояснительного текста. Режим JSON во многих API решает именно эту задачу, но не больше.

Уровень 2. Соответствие схеме. Объект содержит все обязательные поля нужных типов, значения перечислений (enum) берутся только из разрешённого списка, лишних полей нет. Структурированный вывод по схеме, который поддерживают некоторые модели и API, предназначен именно для этого уровня. Разница с режимом JSON существенна: допустимым JSON может быть любой объект, а соответствие схеме означает, что модель не пропустит обязательный ключ и не придумает значение вне списка.

Уровень 3. Корректность содержания. Значения соответствуют действительности и правилам процесса. Идентификатор клиента существует в CRM. Сумма совпадает с написанной клиентом. Дата не в прошлом. Статус допустим для текущего этапа сделки. Пользователь, от имени которого работает интеграция, имеет право на это действие.

Документация поставщиков прямо признаёт возможность ошибок третьего уровня даже при идеальной структуре: модель может заполнить поле неправильным значением, отказаться отвечать или вернуть незавершённый ответ. Поэтому схема отвечает за форму, а за содержание отвечает ваша проверка.

Контракт данных

Контракт данных описывает, что именно интеграция ожидает от модели и что будет делать с каждым полем. Его следует составить до промпта вместе с владельцем процесса в CRM.

Для каждого поля полезно определить:

• Обязательность. Невозможна ли запись без поля или оно может быть пустым.
• Тип и формат. Число или строка, целое или дробное, формат даты (например, ISO 8601 с часовым поясом), число знаков после запятой.
• Допустимые значения. Для статусов, валют и типов обращений используйте перечисления. Модель не должна придумывать статус «почти закрыто», если его нет в CRM.
• Правило для отсутствующих данных. Если в тексте нет суммы, поле должно иметь значение null, а не 0 или среднее значение. Надёжнее, когда поле всегда присутствует в объекте, а отсутствие данных явно обозначено как null: так код интеграции не спутает «модель забыла поле» с «данных действительно нет». Проверьте, как именно ваш API позволяет описать необязательные значения.
• Источник значения. Откуда оно берётся: из текста клиента, справочника или расчёта. Сумму, «рассчитанную» моделью, стоит помечать отдельно от суммы, которую клиент указал явно.
• Валюта и единицы. Сумма без валюты — неполное значение. Количество без единицы измерения — тоже неполное.

Отдельное поле status в самом объекте помогает модели сообщать о неуверенности. Например, значение needs_review означает: «Я заполнила поля, но кое-что нужно проверить человеку». Это полезный контракт, но он не доказывает корректность: модель может указать ok, даже если ошиблась. Статус модели — подсказка для маршрутизации, а не замена проверок.

Ещё один практический совет: давайте полям понятные названия и короткие описания. Поле amount_uah_from_text менее двусмысленно, чем sum. Описание в схеме также служит инструкцией: «сумма, которую клиент явно указал в письме; null, если суммы нет» оставляет модели меньше пространства для догадок, чем просто «сумма».

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

Неполные ответы и отказы

Структурированный вывод не гарантирует, что каждый ответ будет полным. Документация описывает как минимум два отдельных случая, которые интеграция должна явно обрабатывать.

Отказ. Модель может отказаться выполнять запрос, например по соображениям безопасности. В таких API отказ приходит отдельным полем или признаком, а не объектом по схеме. Если интеграция этого не проверяет, она попытается разобрать отсутствующий объект и завершится ошибкой или, что хуже, запишет пустые значения.

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

Правила обработки:

• Проверяйте причину завершения до разбора. Дальше проходит только нормально завершённый ответ.
• Обрабатывайте отказ как отдельный результат. Запишите его в журнал и передайте обращение человеку. Автоматически повторять тот же запрос имеет смысл только тогда, когда причина понятна и повтор может дать другой результат.
• Не записывайте потоковый вывод до завершения. Если ответ приходит частями, CRM получает данные лишь после их полного получения и всех проверок.
• Не угадывайте отсутствующее. Если обязательного поля нет или оно равно null, правильное действие — отметить запись как неполную и запросить данные, а не подставлять значение по умолчанию.

Проверки перед CRM

После разбора JSON и проверки схемы данные проходят бизнес-валидацию. Этот слой реализуется в коде и не зависит от модели.

Полный путь от ответа модели до записи удобно описать как последовательность шагов, каждый из которых может остановить обработку:

1. Проверить причину завершения и наличие отказа.
2. Разобрать JSON и проверить соответствие схеме собственным валидатором, даже если API обещает правильную структуру. Это защищает от изменений модели или настроек.
3. Выполнить бизнес-проверки из списка ниже.
4. Проверить ключ идемпотентности.
5. Определить, требует ли действие подтверждения человека.
6. Записать в CRM и сохранить в журнале входное событие, ответ модели, результаты проверок и ID созданной записи.

Журнал на последнем шаге нужен не для отчётности. Когда менеджер увидит странную сделку, именно он поможет понять, где возникла ошибка: в модели, проверке или самой CRM.

Типичные проверки:

• Существование сущностей. Клиент, товар, менеджер или филиал с такими идентификаторами существует в CRM или ERP. Иначе запись не создаётся.
• Допустимые значения. Валюта есть в разрешённом списке, статус разрешён на текущем этапе, количество попадает в разумный диапазон для товара.
• Арифметика. Сумма позиций равна общей сумме, цена за единицу, умноженная на количество, даёт сумму строки. Расчёты выполняет код, а не модель.
• Соответствие источнику. Значение, которое модель якобы извлекла из текста, действительно есть в тексте. Для критичных полей (сумма, дата, номер договора) полезно сохранять фрагмент исходного текста, из которого они получены.
• Права. Интеграция действует от имени конкретного пользователя или сервисной учётной записи с минимально необходимыми правами. Разрешение проверяется в CRM или отдельном сервисе, а не доверяется модели. Если модель предложила изменить статус сделки, а у этого пользователя нет такого права, действие отклоняется.
• Версия записи. При обновлении существующей записи интеграция проверяет, не изменилась ли запись с момента чтения. Иначе можно перезаписать изменения, которые менеджер только что внёс вручную.

Отдельно разделяйте действия по риску. Создание черновой заметки к клиенту и изменение суммы сделки или отправка счёта имеют разную цену ошибки. Действия с высокой ценой ошибки лучше проводить с подтверждением человека, даже если все технические проверки пройдены.

Повторы и идемпотентность

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

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

• Стабильный идентификатор события. ID письма, сообщения, webhook или строки формы. Некоторые платформы автоматизации используют его, чтобы не запускать сценарий дважды для одной записи. Но это защищает только запуск, а не последующую запись в CRM.
• Ключ операции. Для каждого действия формируется ключ, например «ID события + тип действия». Перед записью интеграция проверяет, не выполнялась ли уже операция с таким ключом.
• Поиск существующей записи. Перед созданием контакта или сделки проверяется, нет ли уже записи с тем же внешним идентификатором.
• Осторожность после тайм-аута. Тайм-аут не означает, что запись не состоялась. CRM могла создать сделку, а ответ не дошёл. Перед повтором нужно проверить, существует ли запись.

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

Набор приёмочных примеров

Не включайте интеграцию на реальных данных, пока она не пройдёт фиксированный набор примеров, включая неудачные. Ниже приведён учебный пример. Данные вымышлены и не взяты из реальной CRM.

Модель вернула объект:

{"customer_id":"C-17","amount":1200,"currency":"UAH","status":"needs_review"}

Ниже приведён пример компактной схемы для этого объекта. Значения UAH и needs_review здесь учебные: замените их фактическими перечнями вашей CRM. Все четыре поля обязательны, но неизвестная сумма может быть null. Поддерживаемое подмножество JSON Schema зависит от поставщика и режима API; перед использованием проверьте его для своей модели. Схема не проверяет существование клиента, подтверждение суммы или право на запись — это делает код интеграции.

{
  "type": "object",
  "properties": {
    "customer_id": {
      "type": "string"
    },
    "amount": {
      "type": [
        "number",
        "null"
      ]
    },
    "currency": {
      "type": "string",
      "enum": [
        "UAH"
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "needs_review"
      ]
    }
  },
  "required": [
    "customer_id",
    "amount",
    "currency",
    "status"
  ],
  "additionalProperties": false
}

Схема принимает объект: все поля на месте, типы правильные, валюта и статус входят в список. Затем выполняются бизнес-проверки.

Учебная таблица проверок

Теперь рассмотрим тот же объект, но с "customer_id":"C-99", которого нет в CRM. JSON допустим, схема соблюдена, а запись всё равно недопустима. Это и показывает, почему формат не заменяет проверки.

Минимальный набор приёмочных примеров для такой интеграции:

1. Корректный запрос. Все данные есть в тексте, запись создаётся.
2. Неизвестный товар или клиент. Модель возвращает несуществующий идентификатор. Запись не создаётся.
3. Пустая сумма. В тексте суммы нет. Поле равно null, запись отмечается как неполная.
4. Запрещённое действие. Текст просит изменить то, на что у интеграции нет права. Действие отклоняется.
5. Повтор. Одно событие приходит дважды. Создаётся одна запись.
6. Отказ или обрезанный ответ. Ничего не записывается, обращение передаётся человеку.

Вывод

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

Что можно сделать в своём процессе:

1. Опишите контракт данных для одного сценария: поля, типы, перечисления, правила для отсутствующих значений, источник каждого значения.
2. Включите структурированный вывод по схеме, если модель его поддерживает, и до разбора проверяйте причину завершения и отказ.
3. Реализуйте бизнес-проверки: существование сущностей, допустимые значения, арифметика, соответствие тексту, права, версия записи.
4. Определите ключ идемпотентности по входному событию и после каждого тайм-аута проверяйте существующую запись.
5. Соберите шесть приёмочных примеров выше и запускайте их до каждого включения и после изменений промпта или схемы.
6. Разделите действия по уровню риска и определите, какие требуют подтверждения человека.

Если вы планируете передавать данные от ИИ в CRM или ERP, команда BotLabs может разобрать ваш сценарий на 15-минутной консультации. Обсудим, какие поля нужны процессу, какие проверки обязательны и какие действия следует оставить на подтверждение человека. Следующим шагом определим, с какого набора приёмочных примеров начать проверку.

Часто задаваемые вопросы