Як отримувати від ШІ коректний 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 і зберегти в журналі вхідну подію, відповідь моделі, результати перевірок і ідентифікатор створеного запису.

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

Типові перевірки:

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

Окремо варто розділити дії за ризиком. Створити чернетку нотатки до клієнта і змінити суму угоди або надіслати рахунок мають різну ціну помилки. Дії з високою ціною помилки краще проводити через підтвердження людиною, навіть якщо всі технічні перевірки пройдено.

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

Інтеграції повторюють запити: через таймаути, повторну доставку вебхука, перезапуск сценарію. Якщо кожен повтор створює новий запис, в CRM з'являються дублікати угод, задач і контактів.

Ідемпотентність означає: повторна обробка тієї самої вхідної події не змінює результат після першої успішної обробки. Що для цього потрібно:

• Стабільний ідентифікатор події. ID листа, повідомлення, вебхука або рядка у формі. Деякі платформи автоматизації використовують такий ідентифікатор, щоб не запускати сценарій двічі для одного запису. Але це захищає лише запуск, а не подальший запис у 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-хвилинній консультації. Обговоримо, які поля потрібні процесу, які перевірки обов'язкові і які дії варто залишити на підтвердження людині. Наступним кроком визначимо, з якого набору приймальних прикладів почати перевірку.

Часті запитання