Обработка ошибок
Как приложение обрабатывает ошибки при синхронизации
Интеграция не «ломается молча». Если Битрикс24 или МойСклад отвечают с ошибкой, приложение старается само исправить ситуацию, не отправить заведомо плохие данные или написать понятное объяснение прямо в заказ (или счёт), чтобы вы увидели проблему без разбора логов.
Ниже — не про код, а про то, что вы увидите и что это значит.
Общие правила (коротко)
1. Сначала пробуем починить запрос сами
Перед отправкой в Битрикс24 приложение часто «подчищает» данные: убирает пустые поля, исправляет формат телефона и e-mail, подставляет значения по умолчанию для обязательных свойств товара и т.п. Если после этого запрос всё равно не проходит — пробуем повторить (например, при истёкшем токене, перегрузке API или дубле номера счёта).
2. Не всегда выгружаем «как получится»
Для заказов есть важное правило: товарные строки в сделку либо уходят все корректно, либо не уходят целиком. Частичная выгрузка строк специально запрещена — иначе при обратной синхронизации позиции могли бы исчезнуть из заказа в МойСклад.
3. Заметка в заказе — это не паника, а подсказка
Если проблема касается конкретного заказа, в карточке заказа МойСклад может появиться заметка с объяснением. Обычно там есть ссылка на сделку в Битрикс24 и, при необходимости, номер события в журнале синхронизации.
4. Одна и та же ошибка не спамит каждую минуту
Технические записи в журнале ошибок для одного и того же случая — не чаще одного раза в сутки на портал (или на заказ, где это уместно). Заметка в заказе про лимит каталога — один раз на заказ, даже если заказ правят снова.
5. Есть ошибки, после которых синхронизация портала останавливается
Это редкие и серьёзные случаи: блокировка портала лицензией, закончилось место на диске Битрикс24. Обычные проблемы с товарами, телефонами или одним заказом портал целиком не отключают.
Заметки в заказе МойСклад — когда и зачем
Это главный способ «достучаться» до пользователя по проблеме с выгрузкой заказа.
1. В каталоге Битрикс24 закончился лимит товаров
Когда: на портале слишком много товаров в каталоге CRM (типичный лимит — несколько тысяч), и для части позиций заказа нет привязки к товару в Б24.
Что делает приложение: заказ в сделку выгружается без товарных строк. Новые товары и услуги в этот день не создаются в каталоге.
Заметка в заказе: пометка [moysklad24-sync] лимит каталога CRM, объяснение, что строки пропущены, ссылка на сделку. Повторно не дублируется на тот же заказ.
Что делать: разобраться с каталогом в Б24 (лишние товары, тариф, привязка позиций МС к существующим товарам). После исправления — дождаться следующей синхронизации или обновить заказ.
2. Товар из заказа не найден в каталоге Битрикс24
Когда: у позиции заказа нет PRODUCT_ID в Б24 — товар/услуга в CRM не привязан.
Что делает приложение: не отправляет товарные строки в сделку (все строки, не часть). Заказ при этом может выгрузиться «шапкой» без состава.
Заметка в заказе: что заказ ушёл без товарных строк, список проблемных позиций, ссылка на сделку, код события в журнале.
Что делать: проверить синхронизацию каталога и привязку товаров/услуг МойСклад к карточкам в Б24.
3. У позиции не указано количество
Когда: в данных для выгрузки у строки пустое количество (QUANTITY).
Что делает приложение: такие строки не передаёт в сделку. Остальные строки с нормальным количеством — передаёт.
Заметка в заказе: какие позиции пропущены и почему, ссылка на сделку.
Что делать: проверить количество в заказе МойСклад и пересохранить/синхронизировать.
4. В Битрикс24 включён складской учёт CRM
Когда: при сохранении товарных строк Б24 отвечает, что недостаточно товара на складе (складской учёт в CRM).
Заметка в заказе: что товары не выгрузились из‑за складского учёта, рекомендация отключить складской учёт в настройках Битрикс24 (он несовместим с логикой приложения), текст ответа Б24, ссылка на сделку и документацию.
Что делать: отключить складской учёт в CRM или согласовать процесс с поддержкой интеграции. После отключения заказ подтянется при следующей синхронизации.
5. Не удалось обновить сделку (стадия, склад, услуги и т.п.)
Когда: при обновлении сделки Битрикс24 возвращает ошибку — часто про невозможность закрыть сделку, склад, услуги.
Заметка в заказе:
- блок «Ответ Битрикс24» — дословный текст ошибки;
- блок «Совет разработчиков интеграции» — что проверить (остатки, состав сделки, складской учёт), ссылка на сделку.
Что делать: открыть сделку по ссылке, прочитать ответ Б24, проверить настройки склада и состав сделки.
Заметка в счёте МойСклад (не в заказе)
Дублируется номер счёта в Битрикс24
Когда: при выгрузке счёта номер уже занят в Б24.
Что делает приложение: автоматически меняет номер на вариант с префиксом MS_ и повторяет выгрузку.
Заметка в счёте МойСклад: что исходный номер был занят и счёт выгружен с новым номером.
Телефон и e-mail (компании, контакты, лиды)
Это не заметки в заказе, но частая причина «странного» поведения при выгрузке контрагентов.
Что делает приложение перед отправкой в Б24:
- Пустой телефон или e-mail — просто не отправляет это поле (ошибки из‑за пустоты не будет).
- Кривой телефон или e-mail (не распознался как нормальный) — поле убирается из запроса, контакт/компания/лид всё равно создаётся или обновляется без этого телефона или почты.
- Нормальный номер — приводится к виду, который принимает Битрикс24 (цифры, код страны где возможно).
- Нормальный e-mail — приводится к нижнему регистру и проверяется на корректность.
Что видит пользователь: контрагент в Б24 появился, но телефона или почты нет — хотя в МойСклад они были записаны с опечаткой или в нестандартном формате. Исправьте данные в МойСклад — при следующей синхронизации подтянутся.
Пустые поля в сделках и счетах: если в CRM уходит, например, пустой комментарий или «не назначен» ответственный — такие поля вообще не отправляются, чтобы Б24 не ругался на null.
Другие типичные ситуации (без заметки в заказе)
Кратко, чтобы пользователь не пугался журнала синхронизации:
| Ситуация | Что происходит |
|---|---|
Картинка товара в формате .jfif |
Картинка не грузится, товар синхронизируется без неё |
|
Сложные свойства товара (списки, привязки) |
Такие поля из настроек синхронизации пропускаются, чтобы не ломать выгрузку каталога |
|
Значение из МойСклад «справочник» в простое текстовое поле |
Преобразуется в текст (например, «3 месяца» вместо технического объекта) |
|
Временная ошибка API («повторите позже», лимит запросов) |
Приложение само повторяет запрос |
|
Лимит товаров в каталоге (глобально) |
Очищается очередь выгрузки товаров; портал не отключается |
Что делать, если увидели заметку в заказе
- Прочитайте текст заметки — там обычно уже сказано что не выгрузилось и почему.
- Откройте сделку по ссылке из заметки.
- Исправьте причину в МойСклад или Битрикс24 (каталог, количество, складской учёт, привязка товаров).
- Сохраните заказ или дождитесь следующего цикла синхронизации.
Если после исправления заметка остаётся, а заказ не обновляется — передайте в поддержку номер заказа МойСклад, ссылку на сделку и код события из заметки (если есть).
