DOCS
ГлавнаяРешения для исходящих почтовых отправлений Инструменты для отправителей Verified Accounts 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 после загрузки каталога. Помеченные товары не блокируются для отправки, но именно снятие пометок до отправки позволяет избежать задержки отправления на границе США.

Как это работает 

  1. Создайте товар каталога для каждого отправляемого продукта.

  2. Убедитесь, что у каждого товара есть идентификатор, который ваш почтовый перевозчик передаст дальше.

  3. Когда данные об отправлении поступают в Zonos, каждая позиция сопоставляется с товаром вашего каталога, и данные этого товара применяются к расчету.

Создание товаров каталога 

catalogItemCreate принимает список, поэтому в одном запросе можно отправить множество товаров.

1mutation CatalogItemCreate($input: [CatalogItemInput!]!) {
2 catalogItemCreate(input: $input) {
3 id
4 itemKey
5 name
6 productId
7 sku
8 hsCode
9 customsDescription
10 countryOfOrigin
11 }
12}

Повторная отправка одного и того же товара

Если вы отправляете товар, SKU или идентификатор продукта которого уже существует, Zonos обновляет этот товар, а не добавляет второй. Повторные попытки и повторные запуски безопасны.

Обратная сторона в том, что два разных товара с одинаковым SKU или идентификатором продукта будут объединены в один. Перед массовой загрузкой проверьте данные на дубликаты.

Поля

Поле↕Обязательное↕Описание↕
skuДа*Ваш уникальный идентификатор товара. *Для каждого товара нужен SKU, идентификатор продукта или оба.
productIdДа*Идентификатор товара на вашей платформе. *Для каждого товара нужен SKU, идентификатор продукта или оба.
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 изображения товара. Повышает точность классификации.

Обеспечьте сопоставимость товаров 

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

Для почтовых отправлений действует дополнительное ограничение. Zonos получает от почтовых перевозчиков ограниченный набор полей, и на многих направлениях таможенное описание — единственное поле, содержащее какие-либо сведения, специфичные для товара. Описание, одинаковое для всего каталога, само по себе ничего не идентифицирует.

Добавляйте идентификатор продукта или SKU в конец таможенного описания, которое вы отправляете перевозчику.

Men's bifold wallet, cowhide leather - 123456

Добавленный идентификатор должен в точности совпадать с productId или sku соответствующего товара каталога.

Поля описания короткие. Например, в отправлениях Canada Post допускается около 49 символов, поэтому сокращайте описательную часть, если ваши идентификаторы длинные. Идентификатор важнее текста.

Указывать в customsDescription товара ту же строку, которую вы отправляете перевозчику, не обязательно, но это позволяет напрямую сравнить обе стороны, когда позиция не сопоставилась и нужно выяснить причину.

Сопоставление чаще всего не срабатывает, когда:

  • Идентификатор отсутствует в описании.
  • Идентификатор не соответствует ни одному productId или sku в вашем каталоге.
  • Идентификатор обрезан из-за ограничения перевозчика на количество символов.
  • Форматирование меняется от отправления к отправлению.

Это поведение еще дорабатывается и может измениться до запуска.

Обновление товаров каталога 

catalogItemUpdate принимает тот же тип входных данных, что и создание. Отправляйте только те поля, которые хотите изменить.

1mutation CatalogItemUpdate($input: [CatalogItemInput!]!) {
2 catalogItemUpdate(input: $input) {
3 id
4 itemKey
5 hsCode
6 customsDescription
7 }
8}

Примечание: Неуказанные поля остаются без изменений, поэтому частичные обновления безопасны. Отправка null не очищает значение — она игнорируется. Значение можно заменить другим, но очистить его через API нельзя. Если нужно очистить поле, обратитесь к своему представителю Zonos.

Чтение товаров 

Запрос catalogItem принимает id, productId или sku. Используйте его, чтобы проверить, какие данные о товаре хранятся в Zonos.

1query CatalogItem($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.

1mutation CatalogItemDelete($input: [ID!]!) {
2 catalogItemDelete(input: $input)
3}

Связанные материалы 

  • Интеграции с каналами — автоматическая синхронизация каталога из поддерживаемого канала продаж.
  • Импорт CSV — загрузка товаров каталога с помощью таблицы вместо написания кода.
  • Проверки PGA — проверка товаров каталога на соответствие требованиям агентств США (PGA).
  • Как работает Catalog — что Zonos делает с данными о ваших товарах.
GraphQL API ReferenceTypes, inputs, and operations used in this guide
INPUTS

CatalogItemInput

MUTATIONS

catalogItemCreate catalogItemDelete catalogItemUpdate

Была ли эта страница полезной?

Получить поддержку·Юридические документы·© 2026 Zonos
На этой странице:
  • Catalog API