Аналитика Ozon для FBS и FBO

Client ID и API-ключ хранятся раздельно

Ozon требует идентификатор клиента и секретный API-ключ. Client ID относится к настройкам подключения, ключ уходит в зашифрованное хранилище. Validate выполняет безопасный запрос к Seller API и классифицирует ошибку без сохранения provider body. Discover формирует магазины и capabilities, после чего Core запускает доступные backfill jobs.

Каждый ресурс имеет собственный health: offers, orders, returns, stocks, finance, supplies и reviews. Состояние fresh показывает попадание в целевое окно. delayed и stale отделяют задержку от критического устаревания. Error сохраняет только безопасный код последней job. Cursor наружу не раскрывается, интерфейс показывает лишь факт его наличия.

Событие ускоряет синхронизацию, Seller API подтверждает факт

После подтверждённой ротации Oborot один раз показывает URL с секретным token. Его нужно вставить в настройки Push API кабинета Ozon. Внешний callback не требует входа сотрудника: tenant определяется по домену, module marketplace проверяется до обработки, token сравнивается безопасно. Ошибочный URL или secret получает закрытый ответ без раскрытия подключения.

TYPE_PING и все принятые события получают обязательный ответ Ozon с version, name и UTC time. Заказы, карточки и остатки ставят incremental pull. Повтор события поглощается по ID или отпечатку тела. Chat, category и неизвестные типы подтверждаются без job, пока для них нет канонического ресурса. Плановый polling остаётся страховкой от задержек и пропусков.

Cursor v4 защищает большие выгрузки заказов

FBS-заказы читаются через `/v4/posting/fbs/list`. Контракт v4 использует opaque cursor и возвращает postings в корне ответа. Oborot хранит cursor с версией, поэтому числовое состояние старого v3 не передаётся в новый метод. Первый запуск сбрасывает legacy offset и идемпотентно сверяет фиксированное окно, не создавая повторные заказы.

Цена позиции приходит объектом amount и currency, затем нормализуется в денежную строку общего заказа. Исходный статус, substatus, схема исполнения и безопасные metadata остаются рядом. Если Ozon сообщает следующую страницу без cursor, job завершается ошибкой. Такой fail-closed подход сохраняет предыдущий подтверждённый снимок и явно показывает неполную синхронизацию.

Сборка использует актуальный состав отправления

Перед сборкой адаптер запрашивает точное отправление. Уже собранный awaiting_deliver считается успешным повтором. Для awaiting_packaging позиции и количества берутся из свежего ответа Ozon и отправляются одним пакетом. Postflight повторно читает отправление, а `ship_failed` переводится в retryable error с сохранением job и безопасного кода.

Причины отмены запрашиваются для конкретного отправления. Пользователь выбирает providerReasonId из актуального справочника. Перед cancel адаптер снова читает отправление и причины, поэтому устаревший ID блокируется. Для причины 402 обязателен комментарий. PDF-этикетка появляется после awaiting_deliver и может готовиться 45-60 секунд, поэтому worker поддерживает управляемый повтор.

Поставка привязана к складу, акт к точному supply_id

Oborot получает список supply order через `/v3/supply-order/list`, затем загружает детали через `/v3/supply-order/get`. Одна страница содержит до 100 заказов, а детали запрашиваются пачками до 50 ID. Перед сохранением Core сверяет точный набор ответов. Пропущенный, повторный или чужой ID останавливает загрузку и сохраняет прежний подтверждённый снимок.

Внутри одного supply order Ozon может вернуть несколько поставок на разные склады. Oborot создаёт отдельную запись для каждого supply_id. Для статуса COMPLETED система получает существующий act_file_uuid через FBP archive, требует готовность EXIST и скачивает PDF только с HTTPS-домена Ozon. Ссылка проходит allowlist, ответ ограничен 20 МБ и не кешируется. Генерация акта, транспортной накладной, создание и перенос поставки остаются отдельными будущими контрактами.

Начисления сохраняют день и точный внешний ID

Актуальный Finance API проходит выбранное окно по одному дню. Cursor содержит дату и last_id. Provider last_id живёт ограниченное время, поэтому Core обновляет его внутри задачи и сбрасывает после длительного простоя, повторяя только текущий день. Accrual ID поглощает дубликаты, пустая страница завершает день, повторяющийся cursor на непустом ответе считается ошибкой.

Возвраты используют отдельное 30-дневное окно с versioned cursor. В доменной записи остаются статус, причина, схема, сумма и связь с заказом и артикулом. Сверка выплат не смешивает валюты. Юнит-экономика добавляет известную себестоимость и рекламный расход, а неподвязанные начисления и товары без маппинга остаются отдельными сигналами качества данных.