Формируйте каталог Verified Account программно, напрямую из своей системы.
Catalog API — один из трех способов сформировать каталог Verified Account. Этот вариант подходит отправителям, у которых есть ресурсы разработчиков и система, уже хранящая данные о товарах, — ERP, WMS, PIM или платформа для отправок. Эта система остается источником достоверных данных и записывает товары в Zonos напрямую, а не синхронизирует их через интеграцию с каналом и не загружает CSV-файл. Если вы продаете через поддерживаемый канал или не хотите писать код, эти два варианта позволяют сформировать такой же каталог с меньшими усилиями.
Товары, созданные через API, обрабатываются точно так же, как товары из любого другого источника: после того как товар попал в ваш каталог, для Zonos неважно, как он туда попал. Каждый товар классифицируется для таможни, если вы не указали код ТН ВЭД (HS code), проверяется на требования партнерских государственных агентств США (Partner Government Agency, PGA) и используется для расчета пошлин и налогов по отправлениям, в которых он присутствует.
Одна часть этого процесса остается за пределами API. Когда проверка PGA помечает товар как Needs attention, на вопросы стоящей за этой пометкой анкеты соответствия требованиям нужно ответить и подтвердить их в Dashboard — API для этого нет. Zonos заранее заполняет все, что может, поэтому большая часть работы сводится к проверке и подтверждению. Обычно интеграцию создает не тот человек, который снимает эти пометки, поэтому предусмотрите, чтобы кто-то в вашей организации обработал их в Dashboard после загрузки каталога. Помеченные товары не блокируются для отправки, но именно снятие пометок до отправки позволяет избежать задержки отправления на границе США.
Если вы отправляете товар, SKU или идентификатор продукта которого уже существует, Zonos обновляет этот товар, а не добавляет второй. Повторные попытки и повторные запуски безопасны.
Обратная сторона в том, что два разных товара с одинаковым SKU или идентификатором продукта будут объединены в один. Перед массовой загрузкой проверьте данные на дубликаты.
Ваш уникальный идентификатор товара. *Для каждого товара нужен SKU, идентификатор продукта или оба.
productId
Да*
Идентификатор товара на вашей платформе. *Для каждого товара нужен SKU, идентификатор продукта или оба.
manufacturerProductId
Только для ЕС
Нестандартизированный идентификатор продукта производителя (NS-PID). Обязателен для B2C-отправлений в ЕС стоимостью не более 150 EUR.
gtin
Только для ЕС
Стандартизированный идентификатор продукта производителя (S-PID), только цифры. Обязателен для B2C-отправлений в ЕС стоимостью не более 150 EUR, если у товара есть штрихкод.
name
Да
Название товара.
customsDescription
Рекомендуется
Что представляет собой товар, простыми словами, для таможенной декларации. Пишите «Хлопковая футболка», а не «Футболка Summer Vibes».
countryOfOrigin
Рекомендуется
Двухбуквенный код ISO страны, в которой произведен товар. Необходим для точного расчета пошлины.
measurements
Рекомендуется
Вес и габариты, используемые для расчета тарифов и таможенного оформления.
hsCode
Нет
Универсальный 6-значный код ТН ВЭД (HS). Если его не указать, Zonos классифицирует товар по его названию и описанию.
amount
Нет
Цена товара в виде числа.
currencyCode
Нет
Трехбуквенный код ISO валюты цены. Обязателен, если указан amount.
itemType
Нет
PHYSICAL_GOOD, DIGITAL_GOOD, SERVICE, SUBSCRIPTION, BUNDLE или PARTIAL_ITEM. Не позволяет декларировать нефизические товары как материальные.
provinceOfOrigin
Нет
Штат или провинция происхождения товара. Требуется некоторыми странами назначения.
productComposition
Нет
Список {material, percentage}. Без него текстиль невозможно классифицировать точнее 6 знаков.
catalogItemUrl
Нет
Ссылка на страницу товара на вашем сайте. Повышает точность классификации.
imageUrl
Нет
Общедоступный URL изображения товара. Повышает точность классификации.
Добавление идентификаторов продуктов для ЕС (PID)
Если вы отправляете товары в ЕС со своим Verified Account, с 1 ноября 2026 года ЕС требует указывать идентификаторы продуктов (PID) в отправлениях от бизнеса к потребителю (B2C) стоимостью не более 150 EUR. Храните их в товарах каталога. Для большинства Verified Accounts данные об отправлении передает в Zonos ваша почтовая служба, а Zonos сопоставляет каждую позицию отправления с вашим каталогом и применяет сохраненные вами идентификаторы, поэтому при отправке ничего дополнительно передавать не нужно.
Для новых товаров передавайте идентификаторы в catalogItemCreate. Для товаров, которые уже есть в каталоге, передавайте их в catalogItemUpdate — эта мутация принимает те же поля. Указывайте в sku каждого товара тот же SKU, который вы используете везде, чтобы Zonos мог связать одно с другим.
Передавайте gtin только цифрами, без дефисов и пробелов. Значения UPC, EAN, JAN и 13-значные ISBN указываются в этом одном поле. Если у вас 10-значный ISBN, передайте вместо него 13-значную версию.
Если у товара нет штрихкода, не указывайте gtin вовсе — не передавайте пустую строку, не используйте повторно свой SKU и не заполняйте поле текстом-заглушкой вроде N/A.
Если вы сами вызываете Landed Cost API, вы также можете включить эти идентификаторы в запрос landed cost. Большинство Verified Accounts этого не делают, потому что данные об отправлении передает в Zonos почтовая служба.
Zonos связывает каждую позицию отправления с товаром каталога по вашим идентификаторам в следующем порядке: идентификатор продукта, затем SKU, затем название. Следите за тем, чтобы используемые вами идентификаторы были точными и совпадали в каталоге и в данных, которые вы отправляете перевозчику.
Для почтовых отправлений действует дополнительное ограничение. Zonos получает от почтовых перевозчиков ограниченный набор полей, и на многих направлениях таможенное описание — единственное поле, содержащее какие-либо сведения, специфичные для товара. Описание, одинаковое для всего каталога, само по себе ничего не идентифицирует.
Формат идентификатора в данных об отправлении, которые вы передаете перевозчику, зависит от вашей почтовой службы, потому что каждая почтовая служба сопоставляет отправления с каталогом по-своему. Перейдите на страницу всех почтовых служб и выберите свою. На ее странице описано, как работает сопоставление для этой почтовой службы и что именно нужно передавать.
Указывать в customsDescription товара ту же строку, которую вы отправляете перевозчику, не обязательно, но это позволяет напрямую сравнить обе стороны, когда позиция не сопоставилась и нужно выяснить причину.
Сопоставление чаще всего не срабатывает, когда:
Идентификатор, по которому сопоставляет ваша почтовая служба, отсутствует в данных об отправлении.
Идентификатор не совпадает в точности ни с одним значением в вашем каталоге.
Идентификатор обрезан из-за ограничения перевозчика на количество символов.
Форматирование меняется от отправления к отправлению.
Это поведение еще дорабатывается и может измениться до запуска.
Обновление товаров каталога
catalogItemUpdate принимает тот же тип входных данных, что и создание. Отправляйте только те поля, которые хотите изменить.
Примечание: Неуказанные поля остаются без изменений, поэтому частичные обновления безопасны. Отправка null не очищает значение — она игнорируется. Значение можно заменить другим, но очистить его через API нельзя. Если нужно очистить поле, обратитесь к своему представителю Zonos.
Чтение товаров
Запрос catalogItem принимает id, productId или sku. Используйте его, чтобы проверить, какие данные о товаре хранятся в Zonos.
1queryCatalogItem($sku: String!){
2 catalogItem(sku:$sku) {
3 id
4 itemKey
5 name
6 customsDescription
7 hsCode
8 productId
9 sku
10 countryOfOrigin
11}
12}
Удаление товаров каталога
catalogItemDelete принимает идентификаторы товаров каталога Zonos, а не ваши SKU или идентификаторы продуктов. Сначала получите идентификатор с помощью запроса catalogItem.
Catalog API
Catalog API
Формируйте каталог Verified Account программно, напрямую из своей системы.
Catalog API — один из трех способов сформировать каталог Verified Account. Этот вариант подходит отправителям, у которых есть ресурсы разработчиков и система, уже хранящая данные о товарах, — ERP, WMS, PIM или платформа для отправок. Эта система остается источником достоверных данных и записывает товары в Zonos напрямую, а не синхронизирует их через интеграцию с каналом и не загружает CSV-файл. Если вы продаете через поддерживаемый канал или не хотите писать код, эти два варианта позволяют сформировать такой же каталог с меньшими усилиями.
Товары, созданные через API, обрабатываются точно так же, как товары из любого другого источника: после того как товар попал в ваш каталог, для Zonos неважно, как он туда попал. Каждый товар классифицируется для таможни, если вы не указали код ТН ВЭД (HS code), проверяется на требования партнерских государственных агентств США (Partner Government Agency, PGA) и используется для расчета пошлин и налогов по отправлениям, в которых он присутствует.
Одна часть этого процесса остается за пределами API. Когда проверка PGA помечает товар как Needs attention, на вопросы стоящей за этой пометкой анкеты соответствия требованиям нужно ответить и подтвердить их в Dashboard — API для этого нет. Zonos заранее заполняет все, что может, поэтому большая часть работы сводится к проверке и подтверждению. Обычно интеграцию создает не тот человек, который снимает эти пометки, поэтому предусмотрите, чтобы кто-то в вашей организации обработал их в Dashboard после загрузки каталога. Помеченные товары не блокируются для отправки, но именно снятие пометок до отправки позволяет избежать задержки отправления на границе США.
Как это работает
Создайте товар каталога для каждого отправляемого продукта.
Убедитесь, что у каждого товара есть идентификатор, который ваш почтовый перевозчик передаст дальше.
Когда данные об отправлении поступают в Zonos, каждая позиция сопоставляется с товаром вашего каталога, и данные этого товара применяются к расчету.
Создание товаров каталога
catalogItemCreateпринимает список, поэтому в одном запросе можно отправить множество товаров.mutation CatalogItemCreate($input: [CatalogItemInput!]!) {catalogItemCreate(input: $input) {iditemKeynameproductIdskuhsCodecustomsDescriptioncountryOfOrigin}}Повторная отправка одного и того же товара
Если вы отправляете товар, SKU или идентификатор продукта которого уже существует, Zonos обновляет этот товар, а не добавляет второй. Повторные попытки и повторные запуски безопасны.
Обратная сторона в том, что два разных товара с одинаковым SKU или идентификатором продукта будут объединены в один. Перед массовой загрузкой проверьте данные на дубликаты.
Поля
skuproductIdmanufacturerProductIdgtinnamecustomsDescriptioncountryOfOriginmeasurementshsCodeamountcurrencyCodeamount.itemTypePHYSICAL_GOOD,DIGITAL_GOOD,SERVICE,SUBSCRIPTION,BUNDLEилиPARTIAL_ITEM. Не позволяет декларировать нефизические товары как материальные.provinceOfOriginproductComposition{material, percentage}. Без него текстиль невозможно классифицировать точнее 6 знаков.catalogItemUrlimageUrlДобавление идентификаторов продуктов для ЕС (PID)
Если вы отправляете товары в ЕС со своим Verified Account, с 1 ноября 2026 года ЕС требует указывать идентификаторы продуктов (PID) в отправлениях от бизнеса к потребителю (B2C) стоимостью не более 150 EUR. Храните их в товарах каталога. Для большинства Verified Accounts данные об отправлении передает в Zonos ваша почтовая служба, а Zonos сопоставляет каждую позицию отправления с вашим каталогом и применяет сохраненные вами идентификаторы, поэтому при отправке ничего дополнительно передавать не нужно.
skumanufacturerProductIdgtinДля новых товаров передавайте идентификаторы в
catalogItemCreate. Для товаров, которые уже есть в каталоге, передавайте их вcatalogItemUpdate— эта мутация принимает те же поля. Указывайте вskuкаждого товара тот же SKU, который вы используете везде, чтобы Zonos мог связать одно с другим.mutation CatalogItemCreate($input: [CatalogItemInput!]!) {catalogItemCreate(input: $input) {idskumanufacturerProductIdgtin}}Передавайте
gtinтолько цифрами, без дефисов и пробелов. Значения UPC, EAN, JAN и 13-значные ISBN указываются в этом одном поле. Если у вас 10-значный ISBN, передайте вместо него 13-значную версию.Если у товара нет штрихкода, не указывайте
gtinвовсе — не передавайте пустую строку, не используйте повторно свой SKU и не заполняйте поле текстом-заглушкой вродеN/A.Если вы сами вызываете Landed Cost API, вы также можете включить эти идентификаторы в запрос landed cost. Большинство Verified Accounts этого не делают, потому что данные об отправлении передает в Zonos почтовая служба.
Требования регламента описаны в руководстве по идентификаторам продуктов для ЕС.
Обеспечьте сопоставимость товаров
Zonos связывает каждую позицию отправления с товаром каталога по вашим идентификаторам в следующем порядке: идентификатор продукта, затем SKU, затем название. Следите за тем, чтобы используемые вами идентификаторы были точными и совпадали в каталоге и в данных, которые вы отправляете перевозчику.
Для почтовых отправлений действует дополнительное ограничение. Zonos получает от почтовых перевозчиков ограниченный набор полей, и на многих направлениях таможенное описание — единственное поле, содержащее какие-либо сведения, специфичные для товара. Описание, одинаковое для всего каталога, само по себе ничего не идентифицирует.
Формат идентификатора в данных об отправлении, которые вы передаете перевозчику, зависит от вашей почтовой службы, потому что каждая почтовая служба сопоставляет отправления с каталогом по-своему. Перейдите на страницу всех почтовых служб и выберите свою. На ее странице описано, как работает сопоставление для этой почтовой службы и что именно нужно передавать.
Указывать в
customsDescriptionтовара ту же строку, которую вы отправляете перевозчику, не обязательно, но это позволяет напрямую сравнить обе стороны, когда позиция не сопоставилась и нужно выяснить причину.Сопоставление чаще всего не срабатывает, когда:
Обновление товаров каталога
catalogItemUpdateпринимает тот же тип входных данных, что и создание. Отправляйте только те поля, которые хотите изменить.mutation CatalogItemUpdate($input: [CatalogItemInput!]!) {catalogItemUpdate(input: $input) {iditemKeyhsCodecustomsDescription}}Чтение товаров
Запрос
catalogItemпринимаетid,productIdилиsku. Используйте его, чтобы проверить, какие данные о товаре хранятся в Zonos.query CatalogItem($sku: String!) {catalogItem(sku: $sku) {iditemKeynamecustomsDescriptionhsCodeproductIdskucountryOfOrigin}}Удаление товаров каталога
catalogItemDeleteпринимает идентификаторы товаров каталога Zonos, а не ваши SKU или идентификаторы продуктов. Сначала получите идентификатор с помощью запросаcatalogItem.mutation CatalogItemDelete($input: [ID!]!) {catalogItemDelete(input: $input)}Связанные материалы
CatalogItemInput
catalogItemCreate catalogItemDelete catalogItemUpdate
Была ли эта страница полезной?