В современном мире электронной коммерции эффективное управление заказами на маркетплейсах является ключевым фактором успеха. Многие продавцы, использующие систему 1С для учета, сталкиваются с необходимостью автоматизировать процесс обновления статусов заказов на Ozon, особенно для схемы FBS (Fulfillment by Seller). В этой статье мы подробно рассмотрим, как осуществить интеграцию 1С с Ozon Seller API для обновления статуса заказа, используя метод /v3/posting/fbs/ship, а также обсудим общие принципы и альтернативные подходы.
Ручное обновление статусов может занимать много времени и приводить к ошибкам, особенно при большом объеме заказов. Автоматизация этого процесса через API позволяет значительно ускорить обработку, снизить нагрузку на персонал и улучшить качество обслуживания клиентов. Мы выясним, как сформировать необходимые запросы, обработать ответы и какие подводные камни могут встретиться на этом пути.
Для схемы FBS процесс обработки заказа включает несколько ключевых этапов, каждому из которых соответствует определенный статус и набор API-методов для работы с ним. Давайте разберем основные шаги и статусы, с которыми мы будем взаимодействовать:
awaiting_packaging (ожидает упаковки). Иногда может встречаться статус awaiting_verification, означающий, что заказ создан, но еще не готов к обработке продавцом, например, ожидает оплаты покупателем. Наша задача — перейти от статуса awaiting_packaging к готовности к отгрузке.awaiting_packaging, продавец должен его упаковать и подтвердить сборку. Передача списка отправлений для упаковки через соответствующий метод переводит их в статус awaiting_deliver (готов к отгрузке). Именно этот этап мы будем автоматизировать с помощью метода /v3/posting/fbs/ship./v1/carriage/create, передав delivery_method_id и departure_date. В эту отгрузку попадут все отправления в статусе "Готов к отгрузке", а сама отгрузка будет создана в статусе "new"./v1/carriage/approve, после чего она перейдет в статус "Сформирована"./v2/posting/fbs/digital/act/get-pdf и штрихкод отгрузки методом /v2/posting/fbs/act/get-barcode./v1/carriage/cancel, если в ответе метода /v1/carriage/get параметр is_cancel_available имеет значение true.delivering (доставляется): Для интегрированных служб доставки статус отслеживается автоматически, для других служб или самостоятельной доставки статус необходимо обновлять через метод /v2/fbs/posting/delivering.delivered (доставлено): Аналогично, для интегрированных служб автоматически, для прочих — через /v2/fbs/posting/delivered.cancelled (отменено): Отменить отправление можно методом /v2/posting/fbs/cancel./v2/posting/fbs/product/cancel./v1/cancel-reason/list позволяет получить список доступных причин отмены, который рекомендуется обновлять раз в неделю для поддержания актуальности./v3/posting/fbs/list (возвращает список отправлений за указанный период) и /v3/posting/fbs/get (возвращает подробную информацию по одному отправлению).Нас интересует, прежде всего, переход заказа из статуса awaiting_packaging в awaiting_deliver.
Для начала работы с Ozon Seller API нам потребуется несколько ключевых элементов:
HTTPСоединение и HTTPЗапрос. Мы будем формировать тело запроса в формате JSON и отправлять его по протоколу HTTP (или HTTPS).ЗаписьJSON, ЗаписатьJSON, ЧтениеJSON и ПрочитатьJSON.Прежде чем отправлять запрос, мы должны создать коллекцию заголовков, которая будет включать Client-Id и Api-Key. Эти данные должны быть получены из вашего личного кабинета Ozon. Для тестирования и отладки таких запросов прямо в базе можно использовать инструмент для тестирования REST API на платформе 1С.
Рассмотрим конкретный пример кода 1С, который демонстрирует, как подтвердить сборку заказа и перевести его в статус awaiting_deliver с использованием метода /v3/posting/fbs/ship. Этот метод делит заказ на отправления и переводит их в указанный статус. Код приведен из реальной дискуссии и адаптирован для лучшего понимания.
Предположим, у нас есть текущий заказ (ЗаказТекущий) со статусом awaiting_packaging, и нам нужно его упаковать и подготовить к отгрузке.
ИначеЕсли ЗаказТекущий.status = "awaiting_packaging" Тогда
Попытка
СтруктураФильтр = Новый Структура;
Пакеты = Новый Массив;
Продукты = Новый Массив;
Для Каждого Товара Из ЗаказТекущий.products Цикл
// Ozon ожидает product_id (идентификатор товара на Ozon),
// но в ЗаказТекущий.products может быть offer_id.
// Убедитесь, что вы передаете корректный ID.
// Если в Товара.offer_id хранится product_id, то оставляем так.
Продукт = Новый Структура("product_id,quantity", Товара.offer_id, Товара.quantity);
Продукты.Вставить(Продукт);
КонецЦикла;
Пакет = Новый Структура("products", Продукты);
Пакеты.Вставить(Пакет); // Добавляем пакет с продуктами в массив Пакетов
СтруктураФильтр.Вставить("packages", Пакеты); // Массив пакетов
СтруктураФильтр.Вставить("posting_number", НомерТекущего); // Номер отправления
// СтруктураФильтр.Вставить("with", Новый Массив); // Эта строка была в примере, но
// в /v3/posting/fbs/ship она не нужна
// и может привести к ошибкам.
// Важно формировать JSON строго по документации API.
ИмяВремФайла = ПолучитьИмяВременногоФайла();
ЗаписьДжейсон = Новый ЗаписьJSON;
ЗаписьДжейсон.УстановитьСтроку(Новый ПараметрыЗаписиJSON(,));
ЗаписатьJSON(ЗаписьДжейсон, СтруктураФильтр, НастройкиДат);
СтрокаЗапроса = ЗаписьДжейсон.Закрыть();
ИмяФайлаОтвет = ПолучитьИмяВременногоФайла("json");
ЧтениеОтвета = Новый ЧтениеJSON;
Сообщить("Сформированный JSON запрос: " + СтрокаЗапроса); // Используем СтрокаЗапроса напрямую
// Заголовки должны быть сформированы заранее и содержать Client-Id и Api-Key
// Например:
// Заголовки = Новый Соответствие;
// Заголовки.Вставить("Client-Id", "ВАШ_CLIENT_ID");
// Заголовки.Вставить("Api-Key", "ВАШ_API_KEY");
// Заголовки.Вставить("Content-Type", "application/json");
HTTPЗапрос = Новый HTTPЗапрос("/v3/posting/fbs/ship", Заголовки);
HTTPЗапрос.УстановитьТелоИзСтроки(СтрокаЗапроса, КодировкаТекста.UTF8, ИспользованиеByteOrderMark.НеИспользовать);
// Соединение должно быть установлено заранее, например:
// Соединение = Новый HTTPСоединение("api-seller.ozon.ru",,,,,,Новый ЗащищенноеСоединениеOpenSSL());
Ответ = Соединение.ОтправитьДляОбработки(HTTPЗапрос, ИмяФайлаОтвет);
ОтветТело = Ответ.ПолучитьТелоКакСтроку();
Сообщить("Ответ от Ozon: " + ОтветТело);
ЧтениеОтвета.ОткрытьФайл(ИмяФайлаОтвет);
// Обработка ответа. Параметры "shipment_date,created_at,in_process_at" могут
// быть неактуальными или требовать уточнения по текущей документации Ozon.
// Обычно Ozon возвращает поле "result" с булевым значением или объект с информацией.
СтруктураОтветПодтверждения = ПрочитатьJSON(ЧтениеОтвета,,,"shipment_date,created_at,in_process_at",ФорматДатыJSON.ISO);
ЧтениеОтвета.Закрыть();
// Здесь можно добавить логику обработки успешного ответа,
// например, обновить статус заказа в 1С.
Если СтруктураОтветПодтверждения.Свойство("result") И СтруктураОтветПодтверждения.result Тогда
Сообщить("Статус заказа успешно обновлен на Ozon.");
// ЗаказТекущий.Статус = "awaiting_deliver";
// ЗаказТекущий.Записать();
Иначе
Сообщить("Ошибка при обновлении статуса: " + ОтветТело);
КонецЕсли;
Исключение
Описание = ОписаниеОшибки();
Сообщить("Неуспех: " + Описание);
ПапкаДляЛогов = "D:\Log\ozon"; // Путь для сохранения логов ошибок
Если ПапкаДляЛогов <> "" Тогда
КопироватьФайл(ИмяФайлаОтвет, ПапкаДляЛогов + "\" + Формат(ТекущаяДата(),"ДФ=""ддММгг_ЧЧ-мм-сс""") + ".json");
КонецЕсли;
УдалитьФайлы(ИмяФайлаОтвет);
КонецПопытки;
КонецЕсли;
Давайте подробно разберем, что делает каждая часть представленного кода:
ИначеЕсли ЗаказТекущий.status = "awaiting_packaging" Тогда
Этот блок кода срабатывает только в том случае, если текущий статус заказа в вашей учетной системе 1С соответствует статусу "ожидает упаковки" на Ozon. Это позволяет избежать повторных запросов или некорректных переходов статусов.
СтруктураФильтр = Новый Структура;
Пакеты = Новый Массив;
Продукты = Новый Массив;
Для Каждого Товара Из ЗаказТекущий.products Цикл
Продукт = Новый Структура("product_id,quantity", Товара.offer_id, Товара.quantity);
Продукты.Вставить(Продукт);
КонецЦикла;
Пакет = Новый Структура("products", Продукты);
Пакеты.Вставить(Пакет);
СтруктураФильтр.Вставить("packages", Пакеты);
СтруктураФильтр.Вставить("posting_number", НомерТекущего);
Здесь мы создаем и заполняем иерархическую структуру 1С, которая затем будет преобразована в JSON. Для метода /v3/posting/fbs/ship Ozon ожидает JSON с полями posting_number и packages. Поле packages должно быть массивом, каждый элемент которого представляет собой отдельный пакет и содержит массив products с полями product_id (идентификатор товара на Ozon) и quantity (количество).
Важное замечание: В примере кода используется Товара.offer_id в качестве product_id. Убедитесь, что Товара.offer_id из вашей структуры ЗаказТекущий.products действительно содержит Ozon Product ID, а не внутренний идентификатор товара или SKU продавца. В противном случае запрос будет некорректным. Документация Ozon API четко указывает, что ожидается product_id.
Строка //СтруктураФильтр.Вставить("with",Новый Массив); была закомментирована, так как поле "with" не является частью тела запроса для метода /v3/posting/fbs/ship и может привести к ошибке. Всегда строго следуйте документации API при формировании JSON-тела.
ЗаписьДжейсон = Новый ЗаписьJSON;
ЗаписьДжейсон.УстановитьСтроку(Новый ПараметрыЗаписиJSON(,));
ЗаписатьJSON(ЗаписьДжейсон, СтруктураФильтр, НастройкиДат);
СтрокаЗапроса = ЗаписьДжейсон.Закрыть();
Сообщить("Сформированный JSON запрос: " + СтрокаЗапроса);
Объекты ЗаписьJSON и ЗаписатьJSON используются для сериализации нашей структуры 1С в строку JSON. Результат сохраняется в переменной СтрокаЗапроса, которая затем будет передана в тело HTTP-запроса. Вывод этой строки в сообщение помогает отлаживать запрос и проверять его структуру.
HTTPЗапрос = Новый HTTPЗапрос("/v3/posting/fbs/ship", Заголовки);
HTTPЗапрос.УстановитьТелоИзСтроки(СтрокаЗапроса, КодировкаТекста.UTF8, ИспользованиеByteOrderMark.НеИспользовать);
Ответ = Соединение.ОтправитьДляОбработки(HTTPЗапрос, ИмяФайлаОтвет);
Здесь мы создаем объект HTTPЗапрос, указывая относительный путь к методу API (/v3/posting/fbs/ship) и коллекцию заголовков. Коллекция Заголовки должна быть сформирована ранее и содержать обязательные заголовки Client-Id, Api-Key и Content-Type: application/json.
Метод УстановитьТелоИзСтроки помещает JSON-строку в тело запроса с указанием кодировки UTF-8. Затем объект HTTPСоединение (который должен быть инициализирован ранее с базовым URL api-seller.ozon.ru и параметрами защищенного соединения) используется для отправки запроса и сохранения ответа во временный файл.
ОтветТело = Ответ.ПолучитьТелоКакСтроку();
Сообщить("Ответ от Ozon: " + ОтветТело);
ЧтениеОтвета.ОткрытьФайл(ИмяФайлаОтвет);
СтруктураОтветПодтверждения = ПрочитатьJSON(ЧтениеОтвета,,,"shipment_date,created_at,in_process_at",ФорматДатыJSON.ISO);
ЧтениеОтвета.Закрыть();
После получения ответа, мы читаем его тело как строку для логирования и анализа. Затем используем ЧтениеJSON и ПрочитатьJSON для парсинга JSON-ответа от Ozon в структуру 1С. Параметры "shipment_date,created_at,in_process_at" для ПрочитатьJSON специфичны для обработки дат и могут потребовать корректировки в зависимости от реальной структуры ответа Ozon API. Рекомендуется сначала изучить структуру успешного ответа, чтобы правильно обрабатывать его.
В случае успешного выполнения, Ozon обычно возвращает поле "result": true или объект с данными об обновленном отправлении.
Исключение
Описание = ОписаниеОшибки();
Сообщить("Неуспех: " + Описание);
// ... логирование и удаление временных файлов ...
КонецПопытки;
Блок Попытка...Исключение используется для перехвата возможных ошибок, возникающих в процессе выполнения кода. При возникновении ошибки выводится ее описание, а также может быть реализовано логирование ответа в файл для дальнейшего анализа. Это помогает быстро определить причину проблемы.
Интеграция с внешними API требует внимательности к деталям. Вот несколько ключевых моментов, которые помогут избежать распространенных ошибок:
"with": {}, является классическим примером неверной структуры. Для метода /v3/posting/fbs/ship такого поля нет.product_id: Убедитесь, что в поле product_id вы передаете именно идентификатор товара на Ozon, а не внутренний ID из вашей 1С или SKU продавца, если они отличаются.Client-Id и Api-Key, а также Content-Type: application/json. Они должны быть переданы в коллекцию Заголовки при создании объекта HTTPЗапрос. Отсутствие или неверное значение этих заголовков приведет к ошибкам аутентификации.Для тех, кто не готов самостоятельно разрабатывать интеграцию с нуля, или кто ищет более быстрое решение, существуют альтернативные подходы:
Преимущества готовых решений: Готовые модули часто учитывают множество нюансов работы API, предоставляют удобный интерфейс, автоматизируют рутинные операции и регулярно обновляются разработчиками в соответствии с изменениями на стороне маркетплейса. Это может существенно сократить время и ресурсы, необходимые для внедрения и поддержки интеграции.
Помимо обновления статусов, важно иметь возможность получать актуальную информацию о состоянии ваших отправлений. Для этого Ozon Seller API предоставляет следующие методы:
/v3/posting/fbs/list: Этот метод позволяет получить список отправлений FBS за определенный период. Вы можете фильтровать список по статусам, датам и другим параметрам, что очень удобно для мониторинга и синхронизации данных./v3/posting/fbs/get: Если вам нужна детальная информация по конкретному отправлению (например, по его номеру posting_number), используйте этот метод. Он вернет полный набор данных об отправлении, включая его статус, список товаров, информацию о доставке и т.д.Используя эти методы, вы можете поддерживать актуальность данных о заказах в вашей учетной системе 1С, автоматизировать отслеживание и реагировать на изменения статусов без необходимости вручную проверять личный кабинет Ozon.
В заключение, успешная интеграция 1С с Ozon Seller API для обновления статусов заказов требует внимательности к деталям документации API, корректного формирования JSON-запросов и тщательной обработки ответов. Независимо от того, разрабатываете ли вы решение с нуля или адаптируете готовые модули, понимание основного принципа взаимодействия с API позволит вам создать надежную и эффективную систему автоматизации управления заказами на Ozon. Регулярно сверяйтесь с документацией Ozon и не стесняйтесь использовать отладчик для изучения работы существующих решений – это ваш лучший помощник в мире интеграций. Для проверки структур и формирования кода работы с JSON можно использовать утилиту для валидации и генерации кода 1С для работы с JSON.