Интеграция с учётной системой

Адреса

Пути в справочнике указаны относительно базового адреса. Только HTTPS, TLS 1.2 и выше.

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

Аутентификация — заголовок X-Api-Key

Ключ бессрочный, действует до отзыва и показывается один раз при выпуске. Для тестового и боевого контуров ключи разные. Активных ключей у компании до 10 — этим и делается ротация без простоя.

Права ключа — уровень по разделу плюс отдельные галочки действий; уровень и галочка проверяются независимо. По умолчанию: «Заказы» — просмотр, «Товары и партии» и «Поставки» — полный; включены действия «Выдача заказов», «Отклонение и недостачи», «Внесение товара», «Изменение цен», «Списание остатков». Владелец меняет права без перевыпуска — новые действуют со следующего запроса.

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

⚠️ 403 PERMISSION_DENIED «метод недоступен ключу интеграции» — не про матрицу прав, а про адрес: такого пути в машинной ветке нет, и расширение прав не поможет. На закрытом контуре (сегодня это тестовый) тот же неверный адрес отвечает 403 SITE_LOCKED ещё до проверки ключа.

Ключ не является пользователем — в частности, публикация новой редакции юридических документов обмен не останавливает.

Формат запросов и ответов

GET несёт только заголовки. POST — плюс Content-Type и Idempotency-Key, тело JSON в UTF-8.

Тело, не разобравшееся как JSON (обрезанное; валидный JSON, который объектом не является — массив, число, строка; а также пустое там, где тело обязательно), даёт 400 BAD_REQUEST у методов, которые тело используют. null телом-не-объектом не считается: он читается как «значения нет», ровно как пустой объект.

Непустое тело принимается только с Content-Type, оканчивающимся на json. Любой другой тип — 400 BAD_REQUEST, и проверка идёт до разбора, то есть до любых сообщений о полях. Гард стоит на методах, которые тело используют; «Готов к выдаче» и «Откат готовности» принимают что угодно. Пустой POST без Content-Type законен везде, где тело необязательно.

Читает метод тело или нет, в слепок идемпотентности оно входит всегда: повтор отправляйте байт в байт тем же телом — впервые добавленные фигурные скобки вместо пустого тела дадут 409.

Успешный ответ приходит в обёртке data (плюс meta у списков), ошибка — объектом error с полями code и message.

HTTP-коды

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

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

Идемпотентность — заголовок Idempotency-Key

Заголовок обязателен в каждом POST; без него — 400. Длина до 200 символов. Изменение поставки (PUT) принимается и без него: там от дублей защищает номер вашего документа.

На каждую новую операцию — новый ключ (случайный UUID), генерирует ваша сторона. Повтор после сбоя отправляйте с тем же ключом: если первая попытка дошла, действие не выполнится второй раз, вернётся сохранённый ответ с исходным кодом, включая 201.

Повтор с тем же ключом, но другим телом даёт 409. Слепок считается по методу, пути и телу — у всех методов, включая те, что тело не читают.

409 с кодом IDEMPOTENCY_IN_PROGRESS («запрос с этим Idempotency-Key ещё выполняется») означает, что первая попытка не завершилась. Это единственный 409, который НУЖНО повторить — тем же ключом, через паузу. Опознавайте случай по машинному коду, а не по русскому тексту сообщения.

Незавершённый резерв старше 5 минут отвечает обычным 409 CONFLICT с текстом «Исход первой попытки неизвестен». Так бывает, когда процесс не дожил до записи исхода: действие могло примениться, а могло и нет. Гарантия «действие не выполнится второй раз» держится на записанном исходе, поэтому здесь платформа не угадывает — сверьтесь с лентой заказов и, если действия не было, отправьте его с НОВЫМ ключом. Повторять тем же ключом бесполезно: ответ будет тот же. Автоматического освобождения зависшего резерва нет.

Частично неуспешный ответ тоже сохраняется. Пакет, вернувший accepted: 48, rejected: 2, при повторе с тем же ключом вернёт тот же ответ и ничего не применит: исправленные строки отправляйте с НОВЫМ ключом. Такой пакет — выполненный запрос с ответом 200, а не отказ.

Ключи хранятся на платформе 7 суток и привязаны к конкретному ключу доступа: после его ротации прежние ключи идемпотентности начинают новые операции.

Частота запросов

Ограничения применяются одновременно, поэтому фактический потолок — минимум из применимых. Типовое внедрение (вся 1С ходит с одного внешнего адреса) упирается в 120 запросов в минуту, а не в 300; 300 достижимы, только если обмен идёт с нескольких адресов.

Превышение — 429 с заголовком Retry-After: выдержать паузу и повторить.

⚠️ Пауза повтора спорит с правилом страниц в выгрузке остатков, и спор решается в пользу страниц. Пауза дольше 5 минут между пакетами одного прайса читается платформой как конец выгрузки и начало следующей, а в режиме «весь остаток» это снимает с витрины позиции недосланных страниц. Поэтому страницу, повтор которой пришлось отложить надолго, не дошлите в хвост: считайте выгрузку прерванной и отправьте прайс заново с первой страницы. То же и с повторами 5xx.

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

Это нижняя граница, а не расписание. Реже указанного ходить можно всегда: ничего не теряется, заказ просто появится у вас позже. Чаще — нельзя, и следит за этим только потолок в 20 запросов в минуту.

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

Пагинация

Списки отдаются страницами; в meta приходит курсор. Значение непрозрачно: передавайте его как есть, не разбирайте.

Цикл обхода: запросить страницу с since, обработать data, при meta.hasMore = false закончить, иначе повторить запрос с cursor вместо since.

Ограничение размещения за неоплаченный счёт

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

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

У черновика размещением считается любой переданный publishAt, даже совпадающий с сохранённым; у запланированной к показу — только перенос момента, повтор того же момента отказа не вызывает.

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

Ограничение снимается оплатой счёта — со стороны обмена оно не лечится.

Режим завершения дел

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

В этом режиме отвечают 403 ACCOUNT_WIND_DOWN: остатки и цены (весь пакет целиком, построчного results в этом случае нет), создание поставки, контрагенты и их скидки; изменение поставки — только если документ размещает новое (добавляет позицию, увеличивает количество существующей либо выводит на витрину поставку, которую покупатели ещё не видели).

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

Со стороны обмена режим не лечится: его снимает владелец, приняв условия в личном кабинете. Автоповторы бессмысленны — сообщите поставщику. Если срок истёк и аккаунт закрылся, ключ начинает отвечать ACCOUNT_DEACTIVATED.

Идентификаторы

UUID в текстовом виде: 018f3b2a-7c1e-7b2a-9f00-1a2b3c4d5e6f. Регистр не значим.

Дата и время

RFC 3339 со смещением. Сервер принимает любое смещение, но настоятельно рекомендуется UTC с суффиксом Z — так журналы обеих сторон сопоставимы без пересчёта. Правильно: 2026-08-04T09:14:02Z. Неправильно: 04.08.2026 12:14:02 или 2026-08-04T12:14:02 без зоны.

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

Дата без времени (ожидаемый приход поставки) — 2026-08-15. Такая дата понимается как конец указанного дня по московскому времени: документ, выписанный на сегодня, принимается, а опубликованная поставка закрывается в конце этого дня.

Деньги

Целое число копеек, всегда за одну штуку (стебель): 45 ₽ — это 4500, 45 ₽ 50 коп — 4550, 1 200 ₽ — 120000.

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

Количества

Целое число штук (не банчей, не коробок).

Кратность банчу обязательна в недостаче и восстановлении: выдать покупателю часть связки платформа не может. При банче 25 допустимы 25, 50, … 250; недопустимы 10, 240, 251. Там же количество строго больше нуля: 0 отвергается кодом 400.

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

externalCode — ваш код номенклатуры

Строка до 120 символов, ваш внутренний код или артикул.

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

Уникальность в пределах компании: один код — одна карточка товара. Позиция при этом своя на каждом складе: идентичность позиции — пара «код + склад». Разводить склады суффиксами в коде (RSA-70-MSK01) не нужно и вредно — так одна номенклатура превратится в две карточки.

Регистр значим. Сравнение точное, срезаются только крайние пробелы: rsa-70 и RSA-70 — разные позиции, msk-01 при сопоставленном MSK-01 даст UNKNOWN_WAREHOUSE. Держите регистр кодов стабильным.

То же справедливо для кодов складов и для номера документа поставки.

Цены: передаёте свою — в заказах приходит цена покупателя

Вы → платформа (остатки, поставки): ваша цена продажи за штуку, например 10000 (100 ₽). Платформа → вы (заказы): полная цена покупателя — ваша цена за вычетом скидки покупателя, плюс комиссия платформы, например 10300 (103 ₽).

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

Комиссия приходит числом: commissionAmount на заказе и на каждой позиции. Ваше нетто берётся вычитанием: amount − commissionAmount по строке, totalAmount − commissionAmount по заказу. Вычислять её самому по ставке НЕ НУЖНО и нельзя: наценка округляется поштучно, обратное деление даёт расхождение, которое копится против вас, ставка со временем меняется, а каждый заказ хранит ту, что действовала в его момент.

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

Атрибуты карточки: длина стебля может быть взята из названия

Длина стебля — фильтр каталога: без неё товар не попадает ни в фильтр «Длина», ни в разделы, у которых длина задана условием. Поэтому у карточки СРЕЗКИ, заводимой без stemLengthCm, платформа пробует вывести длину из названия: берётся первое отдельно стоящее число из закрытого ряда 30, 35, 40, 45, 50, 55, 60, 65, 70, 80, 90, 100 («Роза Фридом 60» → 60). Число, слипшееся с единицей измерения («60см»), год и любое другое значение выводом не считаются; у остальных категорий вывод не делается вовсе.

Выведенная длина помечена, и поставщик видит в кабинете пометку «из названия» — это подсказка платформы, а не ваши данные.

Переданное значение всегда главнее выведенного ПРИ ЗАВЕДЕНИИ карточки: пришёл stemLengthCm — он и записывается, пометка не ставится. Осознанный ноль остаётся нулём: «поле не передали» и «передали 0» платформа различает.

Атрибуты карточки применяются ТОЛЬКО при её первичном заведении. Позиция с уже известным кодом на карточку не влияет: длина, страна и название, присланные позже, ничего в ней не меняют — карточку ведёт поставщик в личном кабинете. Поэтому длину имеет смысл передавать с первой же выгрузки позиции; исправить её потом можно в кабинете, а обменом — нельзя.

Страна происхождения приводится к принятому на платформе написанию, если совпадает с ним без учёта регистра («эквадор» → «Эквадор»). Незнакомое платформе название сохраняется как прислали — оно уедет в фильтр каталога отдельным значением.

Остаток — физический

Передаётся фактический остаток на складе, без вычета броней покупателей платформы — их вычитает платформа. Двойное вычитание занижает витрину.

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

Схема выгрузки: сначала режим чтения, потом расписание

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

⚠️ Дельта в режиме «весь остаток» не работает, и отдельная полная сверка по расписанию её не спасает: окно платформа считает по вашему же ритму (примерно два соседних цикла, но не меньше 15 минут), а частые дельта-пакеты сами делают это окно коротким — редкая сверка в него не попадает, и позиции уходят с витрины между сверками.

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

Присылаете только изменения — сначала переключите режим на «только изменения», и лишь тогда стройте расписание так: отправляйте строку, когда у неё изменился остаток или цена, — сразу или накопленной пачкой раз в несколько минут; и не реже раза в час, круглосуточно, отправляйте весь прайс целиком для сверки. Распроданное в этом режиме снимайте строкой с нулевым quantity: выводов из отсутствия строки платформа здесь не делает, и сверка выправляет только разошедшиеся числа.

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

⚠️ Прайс длиннее 5 000 строк уходит несколькими пакетами, и одной выгрузкой они считаются, только пока идут подряд: пауза между страницами дольше 5 минут читается как конец одной выгрузки и начало следующей. В режиме «весь остаток» отсюда прямое следствие для витрины — позиции, которые приедут следующими страницами, к этому моменту выглядят пропавшими и после второй такой выгрузки снимаются. Значит, страницы идут вплотную — паузу платформа меряет от окончания обработки одной страницы до окончания обработки следующей, а страница с новыми позициями обрабатывается дольше обычной, — строки одного склада идут подряд, на соседних страницах (склейка страниц идёт по складу, поэтому выгрузку сортируйте по складу), а прерванная выгрузка (пауза по Retry-After, серия 5xx, перезапуск задания) отправляется заново с первой страницы, а не дописывается хвостом.

Первая выгрузка после включения режима «весь остаток» снимает накопившийся хвост позиций, которых на складе давно нет, — у живого поставщика это бывает больше половины ассортимента склада. Отправляйте её полной: если в ней не окажется больше 90 % позиций склада, платформа сочтёт выгрузку сломанной и не снимет ничего. Потолок первого прогона действует и для склада, который выгружается своим пакетом или подключён позже других, если его первый прогон пришёлся на первые двое суток после первого прогона поставщика, а сам склад выгружается не реже раза в 10 часов; иначе по складу работает обычный предохранитель.

Если у регламентного задания фиксированный интервал, сдвиньте его с круглой минуты (10:03, а не 10:00): пакеты разных систем не встанут в одну очередь.

Запись числа

Числовые поля (quantity, pricePerUnit, stemsPerBundle, stemLengthCm, discountBps) принимают целое число цифрами, без кавычек.

Колонка «Итог» в таблице ниже — про запись, а не про годность значения: -3 и 0 записаны верно, но цена и размер банча требуют больше нуля, скидка — диапазона 0–9999, количество недостачи и восстановления — не меньше единицы.

⚠️ Дробная часть не округляется, а отвергается: платформа не берётся угадывать, рубли ей передали или копейки. Так же и с форматированием — «5 000» и «5000,00» не разбираются, потому что «5,000» читается и как пять тысяч, и как пять целых.

Отказ называет поле и присланное значение, а для типовых промахов — прямую причину («передайте число без кавычек», «похоже, передана цена в рублях»).

Отказ по записи числа — построчный в остатках и контрагентах (остальные строки пакета применяются) и 400 на весь вызов в остальных методах; в поставках сообщение называет ещё и номер позиции.

Два идентификатора: заказ и позиция

Заказ и каждая его строка имеют собственные UUID: id — идентификатор заказа (orderId), itemId — идентификатор позиции.

В адресе orderId принимают «Готов к выдаче», «Откат готовности» и «Отклонение заказа». В адресе itemId — недостача, восстановление выдачи и удаление позиции.

Путь начинается с /supplier/orders/… в обеих группах — ориентируйтесь на имя параметра в описании метода, а не на слово orders в пути.

Статусы заказа

Жизненный цикл: pre_order (предзаказ) → confirmed (ждёт сборки) → ready (ждёт покупателя) → received (покупатель забрал) → completed (завершён). Терминальные ветки: cancelled — отменён покупателем или платформой, rejected — отклонён вами.

Статус есть у заказа и у каждой позиции отдельно; статус заказа — агрегат по позициям.

pre_order — предзаказ на товар будущей поставки; после прихода поставки сам станет confirmed. received означает, что покупатель получил товар: при самовывозе — скан кода на складе, при доставке — подтверждение покупателем. cancelled ставится и когда заказ аннулирован вместе с отменённой поставкой — в том числе вашей же, отменённой машинно.

⚠️ «Готов к выдаче» означает «собрали», а не «выдали». Метода «отметить выданным» в API нет: received ставит только покупатель — сканом кода на складе при самовывозе либо подтверждением при доставке (и то лишь после кабинетного «Передал в доставку»).

⏱ Самовывозный заказ стоит в ready, пока покупатель не приедет: ждать он может сколь угодно долго. У ДОСТАВКИ с 09.2026 есть таймер: через 12 часов после кабинетного «Передал в доставку» заказ отмечается received автоматически, если покупатель не подтвердил получение сам. Таймер останавливается, если покупатель заявил, что заказ не получен, — тогда заказ снова ждёт человека (поставщик довозит и передаёт заново либо отменяет передачу). Отмена передачи в кабинете тоже гасит таймер, а повторная передача взводит его заново.

⚠️ Если в кабинете выключены рекламации, received может не наблюдаться вовсе: такой заказ переходит сразу в completed в момент выдачи. Опрашивайте статусы по списку, а не ждите received как отдельного шага.

Ваши собственные заказы на платформу не передаются. Продали в офлайне — передайте новый остаток.

Цикл опроса

Проверка изменений запрашивается с since из прошлого ответа. hasChanges = false — до следующего опроса делать нечего; true — лента заказов запрашивается с ТЕМ ЖЕ since, что в первом шаге, и её страницы проходятся по курсору.

⚠️ В запрос ленты передаётся since первого шага, а не только что полученный serverTime, и передаётся обязательно: запрос ленты без since и без cursor отвечает 400.

Новый serverTime становится since следующего опроса и действителен только после того, как все страницы разобраны: на 304 и на любой ошибке момент остаётся прежним.

since — только из serverTime

Успешный ответ проверки изменений содержит serverTime; именно он передаётся как since следующего опроса. Собственные часы не используются: их расхождение с сервером приводит к пропуску изменений.

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

Два случая, когда двигать since нельзя: ответ 304 (тела нет, брать значение неоткуда) и любая ошибка. В обоих случаях сохраняется прежний момент — повторная выдача уже известных заказов безопасна, а пропуск нового заказа необратим.

Ограничения на глубину окна нет: since может отстоять сколь угодно далеко, лента просто отдаст больше страниц. «Текущее время минус сутки» на первом запуске — рекомендация, а не требование сервера.