Гайд внедрения 1С

Этот документ отвечает на вопрос «что и в каком порядке делать», а точный контракт запросов лежит в справочнике API. Бизнес-часть — в обзоре обмена.

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

---

Как устроено подключение

Мы — сервер, ваша система — клиент. Все запросы исходящие, с вашей стороны; мы к вам не подключаемся.

┌────────────────────┐         исходящие HTTPS-запросы          ┌──────────────────┐
│  ВАША СИСТЕМА (1С) │ ─────────────────────────────────────►   │   LOTUS MARKET   │
│      = клиент      │   ◄─────── только ответы на них ──────   │     = сервер     │
└────────────────────┘                                          └──────────────────┘

Опросом забирается только одно — заказы: это единственное событие, которое происходит на нашей стороне. Обо всём остальном (готовность, недостача, остаток, поставка) ваша система знает сама в момент проведения документа и просто отправляет нам.

Четыре уровня

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

Единственная фактическая связка: остатки и поставки адресуются кодом номенклатуры и кодом склада, поэтому обоим нужна подготовка из следующего раздела. Требований «сначала одно, потом другое» между уровнями нет.

Кто что делает

Требования к среде

---

Подготовка

Это общая часть: она нужна для любого уровня.

1. Ключ доступа

Ключ выпускает владелец аккаунта в кабинете: Профиль → Интеграции → Подключённые системы → Выпустить ключ. Сотруднику компании это действие недоступно при любых правах.

• Для выпуска профиль компании должен быть подтверждён — почта, ИНН и банковские реквизиты. Иначе платформа отвечает 403 PROFILE_INCOMPLETE со списком недостающих полей.
• Значение вида lm_… (67 символов) показывается один раз. Не сохранили — только выпуск нового.
• Ключ бессрочный, действует до отзыва. Обновлять и продлевать нечего.
• Для тестового и боевого контуров ключи разные: ключ одного контура на другом не работает.
• В списке систем остаётся только видимая часть — первые 12 символов; по ней владелец узнаёт, какая система чем ходит. Там же видно «Последнее обращение» — самая быстрая проверка, что обмен пошёл.
• Одновременно у аккаунта может быть до 10 активных ключей. Несколько ключей — штатная ситуация: так делается ротация без простоя (выпустить новый → прописать → отозвать старый) и так разводятся разные экземпляры вашей системы.
• Права выпущенного ключа владелец меняет в любой момент, без перевыпуска: новые права действуют со следующего запроса.
• Отзыв мгновенный и необратимый: следующий же запрос получает 401.

Ключ передаётся заголовком X-Api-Key в каждом запросе; заголовок Authorization машинным обменом не используется. Ответ 401 — ключ отсутствует, неверен или отозван (все три случая отвечают одинаково, различить их по ответу нельзя): обмен нужно остановить и позвать администратора, а не повторять запрос.

2. Права ключа

У ключа есть матрица прав по разделам и отдельные галочки действий — их настраивает владелец в карточке ключа. Уровень раздела и галочка действия проверяются независимо: снятая галочка закроет метод даже при полном доступе к разделу.

Права нового ключа по умолчанию:

Включённые действия: «Выдача заказов», «Отклонение и недостачи», «Внесение товара», «Изменение цен», «Списание остатков».

Что каким правом закрыто:

Кроме прав, все изменяющие методы требуют подтверждённого профиля владельца (почта, ИНН, банк). Чтения — проверка изменений и лента заказов — не требуют.

Рекламации учётной системе недоступны в принципе: методов для них в API нет, и выданное право ничего не откроет.

⚠️ Ответ 403 PERMISSION_DENIED приходит в двух разных случаях: не хватает прав ключа или запрошенный адрес вообще не входит в машинный список (тогда сообщение говорит, что метод недоступен ключу интеграции, и расширение прав не поможет). Ещё два варианта 403: PROFILE_INCOMPLETE — заполнить профиль, ACCOUNT_DEACTIVATED — аккаунт удалён, обмен не возобновится.

3. Адреса и тестовый контур

Тестовый контур изолирован от боевых заказов — экспериментировать в нём можно свободно. Боевой адрес в настройках обработки должен появляться осознанно, а не «по умолчанию».

Ответ 403 SITE_LOCKED у машинного обмена почти всегда означает не замок платформы, а одно из двух: обращение по адресу вне машинного списка либо отсутствующий заголовок X-Api-Key.

4. Транспортная часть обработки

Это самая ценная часть работы: она пишется один раз и обслуживает все уровни.

Отправка — через локальную очередь, а не из проведения документа. Проведение пишет строку в вашу таблицу-очередь (событие, данные, свежий ключ идемпотентности) и завершается. Отдельная быстрая задача (раз в 10–30 секунд) разбирает очередь и отправляет. Иначе наша недоступность подвесит ваш учёт — а этого не должно происходить никогда.

Идемпотентность. Каждый POST несёт заголовок Idempotency-Key — случайный UUID, который генерирует ваша сторона и хранит в строке очереди (длина до 200 символов; без заголовка — 400). Повтор после сбоя отправляется с тем же ключом: если первая попытка дошла, действие не выполнится второй раз, а вернётся сохранённый ответ. Ключи живут у нас 7 суток и привязаны к конкретному ключу доступа.

Три правила, без которых идемпотентность работает против вас:

1. Тот же ключ с изменённым телом — 409. Отсюда: исправленный пакет отправляется с новым Idempotency-Key, а не со старым.
2. 409 «запрос с этим ключом ещё выполняется» — единственный 409, который НУЖНО повторить (тем же ключом, через небольшую паузу). Он означает, что первая попытка ещё в работе. Зависший резерв освобождается через 5 минут.
3. Частично неуспешный ответ тоже сохраняется. Если пакет вернул accepted: 48, rejected: 2, повтор с тем же ключом вернёт тот же ответ и ничего не применит. Исправленные строки шлите новым ключом.

Изменение поставки (PUT) принимается и без заголовка идемпотентности — там защита от дублей стоит на номере вашего документа.

Обработка ответов — одинаковая во всех уровнях:

Частота. Ограничения жёсткие, их три:

• 20 запросов в минуту на проверку изменений (считается по ключу);
• 300 запросов в минуту на весь машинный обмен (по ключу);
• 120 запросов в минуту с одного IP-адреса — считаются любые запросы с заголовком X-Api-Key, включая неудачные попытки аутентификации. Две системы из-под одного адреса делят это ведро.

Превышение — 429 с заголовком Retry-After. Интервал опроса заказов задаём мы: поле nextPollAfterSeconds в ответе и заголовок X-Next-Poll-After (заголовок нужен потому, что у ответа 304 тела нет вовсе). Значение меняется само — от 30 секунд при активности до 900 ночью — и может быть глобально разрежено платформой, поэтому читайте его из каждого ответа, а не зашивайте в код.

Журналы. Ведите свой: время, действие, результат, текст ошибки. В кабинете есть журнал обмена — что принято и что отклонено, с числом принятых и отклонённых строк; хранится 30 суток. ⚠️ Построчных причин отказа в нём нет — они приходят только в теле ответа метода, поэтому сохраняйте ответы у себя. Успешные опросы изменений в журнал не пишутся вовсе (иначе он состоял бы из них одних), и 401 там тоже не появится — отозванный ключ виден только по замершему «Последнему обращению».

5. Сопоставление складов

Коды ваших складов сопоставляются с точками выдачи в кабинете (Подключённые системы → Склады), один к одному. Это нужно всегда, даже при единственном складе: код склада — обязательное поле каждой строки, и автоматической привязки к единственной точке выдачи нет. Пока код не сопоставлен, строки остатка по нему отклоняются с UNKNOWN_WAREHOUSE, а документ поставки отвергается целиком.

Список наших складов через API не отдаётся, и наоборот — справочник складов ваш, мы его не видим. Код вводится руками; какой именно код не сопоставлен, видно в ответе метода.

---

Уровень 1 — Остатки и цены

Что даёт. Витрина показывает тот остаток, который действительно есть, и ту цену, которая стоит у вас. Меньше недостач, меньше отказов покупателю.

Что понадобится. Стабильный код номенклатуры у каждой позиции, сопоставленные склады, сопоставленный уже выложенный товар (см. ниже).

Метод. Один: §9.8 «Передача остатков и цен». До 500 строк в пакете, итог построчный — ошибка одной строки не отменяет остальные.

Порядок работ

1. Сначала сопоставьте то, что уже выложено на платформе. Товар, заведённый вручную или загрузкой прайса, вашего кода не имеет. Платформа защищается от дублей сама (см. ниже), но пока сопоставление не сделано, ваши строки будут отклоняться — а это не то состояние, в котором приятно запускать обмен. В кабинете платформа предлагает совпадения по названию, ростовке и стране; подтвердить их — разовая работа менеджера, не разработчика.
2. Научите обработку собирать изменившиеся строки: код номенклатуры, код склада, остаток, цену, размер связки. При первом появлении кода добавьте название и категорию — из них создастся карточка товара.
3. Отправляйте изменения по событию. Дополнительно полезна полная сверка всего прайса по расписанию — она чинит любые расхождения, накопившиеся из-за сбоев.
4. Разберите построчный ответ: в нём приходят только ошибочные строки, с номером строки в вашем запросе (нумерация с нуля).

Особенности

• Атрибуты применяются только при первом появлении кода. У уже заведённой позиции обмен обновляет остаток и цену — и больше ничего: название, категория, размер связки, страна, ростовка и плантация молча игнорируются. Сменить связку или переименовать товар выгрузкой нельзя, это делается в кабинете.
• Остаток передаётся физический, без вычета броней покупателей платформы: их вычитаем мы. Двойное вычитание отбирает товар из корзин. Вычитаются все корзинные брони и позиции принятых заказов, ещё не выданных покупателю; результат ниже нуля не опускается.
• Кратность связке не требуется и остаток не округляется: передали 247 при связке 25 — на витрине будет 247, а купить покупатель сможет кратно связке.
• Цена — ваша, за одну штуку, в копейках, строго больше нуля. Комиссия платформы накладывается поверх и в ваших цифрах не участвует.
• Верхние границы (иначе построчный отказ): остаток до 100 000 штук, цена до 100 000 ₽ за штуку, связка до 10 000 штук. Пакет больше 500 строк и пустой пакет отвергаются целиком.
• Ноль снимает позицию с витрины, отрицательное значение равнозначно нулю. ⚠️ Но для нового кода нулевая строка всё равно заведёт карточку и позицию — выгрузка «всего прайса с нулями» наполнит каталог пустыми позициями.
• Метод управляет только товаром в наличии. Состав и цены будущей поставки ведёт уровень 3. Если код закреплён только за партией будущей поставки, строка остатка заведёт под ним отдельную позицию в наличии — это разные сущности.
• Позиция, удалённая поставщиком на платформе, повторной строкой не воскресает — приходит отказ EXCLUDED, вернуть её можно в кабинете. Запрет действует на код в пределах всей компании, а не на пару «код + склад».
• Если присланный код похож на уже выложенную несвязанную позицию того же склада, строка не применяется: приходит VALIDATION_ERROR с пояснением, а в кабинете появляется предложение связать их. Это защита от дубля на витрине; ответ «это другой товар» запоминается навсегда, и следующая выгрузка заведёт отдельную позицию.
• Если под одним кодом на складе оказалось несколько позиций, строка отклоняется с AMBIGUOUS_EXTERNAL_CODE: платформа не выбирает за поставщика, это сводится руками в кабинете.
• Инфраструктурный сбой роняет весь запрос (5xx), а не отдельную строку — чтобы вы повторили пакет целиком. Построчными бывают только отказы, которые повтором не лечатся. Строки применяются по одной и сразу, поэтому обрыв в середине оставляет принятые строки применёнными: повторите пакет с новым ключом идемпотентности.
• Принято ≠ видно покупателю. Позиция показывается в тех регионах, которые владелец выбрал в кабинете, и только с ненулевым остатком. Если строка в accepted, а товара на витрине нет — смотрите настройки витрины, а не обмен.

Что изменится в кабинете

Это стоит знать до включения обмена — перечисленное наступает от самого факта живого ключа, независимо от того, какие уровни вы подключили.

• Загрузка прайса из Excel закрывается (409 IMPORT_DISABLED_BY_INTEGRATION): у остатка должен быть один источник. Закрыты загрузка файла и подтверждение импорта; уже начатый черновик доредактировать можно.
• Количество партии с вашим кодом больше не правится руками в кабинете (409 QUANTITY_OWNED_BY_INTEGRATION): его ведёт обмен. Цена и размер связки остаются доступными. Отзыв ключа снова открывает поле.
• Появляется плашка расхождений остатка. Если товар продан и на платформе, и вне её, платформа закрывает витрину по этой позиции и показывает поставщику список затронутых заказов — но ничего не отменяет и не оформляет сама. Кому из покупателей достанется остаток, решает поставщик.
• Работает одна учётная система. Подключить одновременно 1С и МойСклад нельзя: попытка вернёт 409 INTEGRATION_CONFLICT с предложением заменить систему.

Как проверить

• Изменение остатка и цены доезжает до витрины.
• Остаток 0 снимает позицию с витрины.
• Пакет с одной ошибочной строкой: остальные применились, ошибочная пришла в ответе с номером и кодом причины.
• После первой выгрузки в каталоге не появилось пар одинаковых позиций.
• Некратный связке остаток принят и виден на витрине как есть.
• Повтор пакета с тем же ключом идемпотентности не применил его второй раз.

---

Уровень 2 — Заказы

Что даёт. Заказы попадают в вашу систему документами; менеджер перестаёт переносить их руками. Покупатель узнаёт о недостаче заранее, а не приехав на склад.

Что понадобится. Реквизит для нашего идентификатора заказа в шапке документа и реквизит для идентификатора позиции в строке табличной части. Это ключи всех последующих операций.

Методы. Проверка изменений и лента заказов (§9.1–9.2); шесть действий над заказом (§9.3–9.7, §9.13).

Порядок работ

1. Фоновая задача опроса. Сначала лёгкий запрос «есть ли изменения» с моментом последнего успешного обмена; при положительном ответе — постраничный обход ленты; в конце сохраняете serverTime из ответа как момент следующего опроса и спите столько, сколько сказал сервер.
2. Момент берётся только из нашего ответа, не из ваших часов: расхождение часов приводит к молча пропущенным заказам. Двигать его нужно после успешной обработки всех страниц — оборвались на второй, и следующий запуск дочитает. Если пришёл ответ 304 (изменений нет), тела в нём нет вовсе — оставляйте прежний момент.
3. Создание документов. Заказ приходит целиком, со своим текущим состоянием. Повторная обработка того же заказа обязана быть безопасной: лента отдаёт изменения, и один и тот же заказ приходит много раз — при отмене, недостаче, получении, перечислении денег, а иногда и без видимых изменений.
4. Отправка действий — через ту же очередь, что и остальное.

Запрос ленты без момента и без курсора — 400; курсор из ответа непрозрачен, разбирать его не нужно, только передавать обратно. limit — от 1 до 100, по умолчанию 50.

Шесть действий и главная ловушка

Все шесть путей начинаются одинаково, но идентификаторы у них разные:

Подстановка идентификатора заказа вместо идентификатора позиции (и наоборот) даёт 404 без объяснения причины — это ошибка номер один при внедрении. ⚠️ Тот же 404 приходит и на существующий заказ, в котором нет ваших позиций: по коду ответа нельзя понять, есть заказ или нет.

Вторая ловушка: в недостаче передаётся размер нехватки, а не новое количество к выдаче. Заказано 250 штук при связке 25, не хватает трёх связок → передаётся 75, к выдаче остаётся 175. Кратность связке здесь обязательна: половину связки покупателю не выдать.

Особенности

• «Готов» означает «собрали», а не «выдали». Факт выдачи подтверждает покупатель на складе сканированием кода — от этого момента идут сроки рекламаций и расчёты. Метода «отметить выданным» в API нет и не будет.
• Готовность двигает только принятые позиции. Позиции-предзаказы (товар будущей поставки) она не трогает: заказ, целиком состоящий из предзаказов, ответит успехом, но ничего не изменит — сначала должна прийти поставка.
• Когда проводить реализацию — ваш регламент. У одних сборка оформляется реализацией сразу, у других — комплектацией или ордером, а реализация проводится по факту передачи. Платформа момент проводки не диктует. Единственное требование: не откладывать сигнал готовности до приезда покупателя.
• Причина обязательна при недостаче и удалении позиции; при отклонении заказа — если в нём есть уже собранные позиции. При восстановлении причина не обязательна.
• Повторный вызов ведёт себя по-разному. Готовность и откат готовности безопасны при повторе. Отклонение уже отклонённого заказа — 409, а не тихий успех. Откат готовности отвечает 409, если заказ уже выдан или активных позиций не осталось.
• Восстановление после недостачи не гарантировано. Единицы берутся из текущего свободного объёма партии, даже если недостача объявлялась без возврата в остаток: пока вы искали товар, его могли разобрать другие покупатели — тогда придёт 409.
• В заказах приходит полная цена покупателя — ваша цена плюс комиссия платформы, минус скидка покупателя, если она есть. Реализацию и УПД проводите по ценам заказа: покупатель платит именно эту сумму. Сумма заказа включает стоимость доставки, если покупатель её выбрал, поэтому она может быть больше суммы строк.
• Комиссия платформы по заказам, оплаченным через платёжный сервис платформы, удерживается из перечисляемой вам суммы; по остальным приходит отдельным счётом по договору. В обоих случаях расхождение между суммой реализации и суммой поступления — это комиссия, а не ошибка обмена.
• Способ выдачи в ленте не передаётся: склад в заказе всегда ваш, а самовывоз это или доставка — по API не различить.
• Замена позиции приходит как две строки: исходная со статусом «отменена» и новая, со своим идентификатором и своей ценой. Обрабатывать нужно обе. Предложить замену через API нельзя — это делает человек в кабинете.
• Отменённый заказ не всегда «вина» покупателя: отмена вашей же поставки каскадом отменяет связанные предзаказы, и они приходят отменёнными.
• Заказы, ожидающие оплаты, в ленту не попадают — ни в каком виде. Заказ с оплатой через платформу появится у вас после оплаты; неоплаченный не придёт вовсе, даже терминальным.
• Действия доступны и человеку в кабинете: кладовщик может нажать «Готов» руками. Поэтому состояние заказа сверяйте по ленте, а не по своим ожиданиям.
• Ваши собственные заказы к нам не передаются. Направление одностороннее. Продали в офлайне — передайте новый остаток уровнем 1.

Как проверить

• Новый заказ создаёт документ; повторный запуск обработки не создаёт второй.
• Готовность меняет статус на платформе; повтор с тем же ключом идемпотентности ничего не дублирует.
• Недостача: заказ на 10 связок, трёх не хватило → передано 3 связки в штуках, к выдаче осталось 7.
• Некратная связке недостача отклонена понятной ошибкой, очередь не зациклилась.
• Распроведение документа сборки откатывает готовность; повторное проведение возвращает её.
• Отменённый или отклонённый заказ закрывает ваш документ.
• Замена позиции: старая строка пришла отменённой, новая заведена, сумма сошлась.
• Суммы документов совпадают с суммами заказа из ленты, а не с ценами вашего прайса.
• Обрыв связи посреди цикла: после восстановления ничего не потеряно и не задвоено.
• Отзыв ключа останавливает обмен, в вашем журнале понятное сообщение, автоповторов нет.

---

Уровень 3 — Поставки и предзаказы

Что даёт. Будущая поставка выкладывается на витрину из вашего документа, и покупатели оформляют по ней предзаказы — товар продаётся до того, как физически приехал. При приходе предзаказы сами становятся обычными заказами.

Что понадобится. Номер вашего документа поставки (он же защита от дублей), коды номенклатуры и код склада прихода.

Методы. Четыре: создание, изменение, приход, отмена — §9.9–9.12.

Порядок работ

1. Проведён заказ поставщику — отправляете документ целиком: номер, склад, ожидаемую дату и все позиции (до 500, коды не повторяются). Один ваш документ = один вызов.
2. Документ изменился — отправляете его новое состояние тем же номером. Платформа приводит состав к переданному: новые позиции добавляет, отсутствующие убирает, совпадающие обновляет.
3. Проведено поступление — сообщаете о приходе. Предзаказы превращаются в обычные заказы и приходят в ленте, товар встаёт в наличие.
4. Поставка не приедет — сообщаете отмену с причиной: её увидят покупатели, у которых есть предзаказы.

Особенности

• Повторная отправка того же номера документа не создаёт дубль — возвращается уже существующая поставка. Обращение по неизвестному номеру в изменении, приходе и отмене даёт 404.
• ⚠️ Опубликованная поставка закрывается платформой сама, в конце ожидаемого дня прихода: предзаказы становятся заказами, товар встаёт в наличие. Если поставка задерживается, обязательно перенесите дату методом изменения — иначе платформа посчитает её приехавшей.
• Нельзя урезать то, что уже обещано покупателю. Уменьшение количества ниже предзаказанного и удаление позиции с предзаказами отклоняются 409. «Обещано» включает и корзину покупателя, который оформляет заказ прямо сейчас. Если товар не приедет, путь один: недостача по конкретным заказам после прихода.
• ⚠️ Отказ 409 по составу приходит уже после того, как применена шапка документа: новая дата прихода к этому моменту сохранена, а покупатели с предзаказами о переносе уведомлены. Повтор исправленного документа безопасен, но считать, что «ничего не произошло», нельзя.
• Дата публикации. Не указали — поставка создаётся черновиком и ждёт публикации; указали — публикуется в этот момент. Черновик публикуется и следующим изменением с датой публикации — отдельного метода публикации в контракте нет, как нет и снятия с витрины. При изменении отсутствие поля означает «не менять».
• Документ обязан нести хотя бы одну позицию — «обнулить» поставку изменением нельзя, для этого есть отмена. Дата прихода при изменении тоже должна оставаться в будущем: уже наступившую (и, скорее всего, закрытую) поставку изменить нельзя.
• Отказ роняет документ целиком. Построчного ответа, как у остатков, здесь нет: одна испорченная позиция отменяет весь вызов с указанием её номера.
• Позиции без вашего кода обмен не трогает — их завёл человек в кабинете. Позиции, уже уехавшие в наличие поштучным приходом, при изменении молча пропускаются.
• Номер документа живёт вечно и уникален в пределах компании: переиспользовать номер закрытой или отменённой поставки нельзя.
• Платформенный идентификатор поставки хранить не нужно — адресуйтесь своим номером. Если в кабинете ответят «связать с существующей поставкой», ваш номер переедет на неё, и платформенный идентификатор сменится.
• Если ваша поставка пересекается составом и датой (±3 дня) с заведённой не через обмен (вручную или загрузкой прайса), она создаётся черновиком, а в кабинете появляется вопрос — связать или считать разными. На ваш вызов это не влияет, но публикация откладывается до ответа человека.
• После прихода товар живёт как обычный остаток и управляется уровнем 1.

Как проверить

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

---

Уровень 4 — Контрагенты и скидки

Что даёт. Ваши постоянные клиенты и их персональные скидки переезжают на платформу. Когда клиент с этим ИНН регистрируется, платформа узнаёт его и применяет вашу скидку сама — покупателю не приходится просить её, а вам вспоминать, кому что обещано.

Что понадобится. Расширенные права ключа — см. ниже. И список контрагентов с ИНН.

Метод. Один: §9.14 «Контрагенты», до 500 строк за запрос, итог построчный.

Права — метод из коробки отвечает 403

Это не ошибка внедрения. Метод назначает покупателям персональные скидки, то есть распоряжается деньгами компании, поэтому требует уровня «Заказы: полный доступ», а у нового ключа по этому разделу стоит только просмотр. Владелец переключает уровень в карточке ключа: Подключённые системы → ключ → раздел «Заказы» → «Полный». Пока права не расширены, все остальные уровни работают как обычно.

Особенности

• Передаётся только тройка: название, ИНН, скидка. Телефоны, адреса и контактные лица не принимаются — платформа их не хранит.
• Строки обновляются по ИНН, повторная передача дублей не создаёт. Выгрузка не одноразовая: при подключении уходит весь список, дальше — новые клиенты и изменения скидок. Отслеживать изменения поштучно не обязательно, допустимо отправлять весь список раз в сутки регламентным заданием.
• Скидка трёхзначна, и это важно: поле не передано — скидку не меняем; ноль — снимаем; положительное значение — применяем. Трактовать отсутствие поля как ноль нельзя, иначе выгрузка одних названий снесла бы все скидки разом. Диапазон — от 0 до 9999 сотых процента (500 = 5 %).
• Пустой список — штатный успех, а не ошибка: ночное задание с пустым справочником не должно превращаться в инцидент. А вот 501-я строка отвергает весь запрос.
• Удаления через метод нет. Контрагент, отсутствующий в пакете, ничего не теряет.
• Скидку, изменённую человеком в кабинете, выгрузка не перезаписывает — она считается ручной.
• Название длиннее 200 символов обрезается, но контрагент не теряется. ИНН проверяется по контрольным цифрам; неверный отклоняется построчно с кодом INVALID_INN.
• Скидка встаёт сразу, если покупатель с этим ИНН уже на платформе, и позже — когда он укажет ИНН в профиле. Засчитывается только аккаунт покупателя: контрагент, зарегистрировавшийся поставщиком, скидку не получит.
• В ошибочной строке ответа приходит index и inn — внешнего кода у контрагента нет.

Как проверить

• Выгрузка принята: строка с битым ИНН отклонена, остальные применились.
• Новый контрагент появился в кабинете, в разделе покупателей.
• Скидка встала; повторная выгрузка без поля скидки её не изменила; ноль снял.

---

Эксплуатация

Журнал обмена

В кабинете, на вкладке Подключённые системы → Журнал обмена: метод, адрес, код ответа и число принятых и отклонённых строк по пакетным методам. Хранится 30 суток и переживает отзыв ключа.

⚠️ Причин отказа по конкретным строкам в нём нет — они есть только в теле ответа. Поэтому сохраняйте ответы у себя: без этого разобрать «почему не приехали три позиции из пятисот» будет нечем. Успешные опросы изменений в журнал не пишутся, 401 тоже.

Что означают коды отказа

Полная таблица — в §11 справочника. В эксплуатации чаще всего встречается вот это:

Приостановка размещения за неоплаченный счёт

Комиссия платформы приходит поставщику отдельным счётом. Если счёт не оплачен в срок, оператор вправе приостановить размещение нового: товары скрываются с витрины, а выгрузка новых позиций отклоняется с 403 BILLING_RESTRICTED.

Что закрывается: остатки и цены (весь пакет целиком, построчного ответа нет), создание поставки, а также изменение поставки, если документ добавляет позицию, увеличивает количество или впервые показывает поставку покупателям.

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

Повторы здесь не помогают — вопрос решается оплатой счёта.

⚠️ После снятия ограничения выгрузите полную сверку прайса. Строки, отклонённые за время ограничения, не повторяются и в очереди не сохраняются — без полной сверки товары вернутся на витрину с остатками, устаревшими на весь период ограничения.

Смена и отзыв ключа

Отзыв мгновенный: со следующего запроса обмен получает 401. Ротация — выпустить новый ключ, прописать, отозвать старый; простоя при этом нет.

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

Если что-то пошло не так

Порядок разбора, который экономит время:

1. Ваш журнал — код ответа и тело ошибки: в них сказано, что именно не понравилось, включая построчные причины.
2. Журнал обмена в кабинете — дошёл ли запрос вообще и сколько строк принято.
3. Колонка «Последнее обращение» в списке систем — если она замерла, обмен остановился (частая причина — отозванный ключ).
4. Тот же сценарий на тестовом контуре: он изолирован, и ломать в нём ничего не жалко.

На время работ у вас есть прямой контакт нашего разработчика — вопросы по контракту быстрее решать им, чем догадками.