Методы для работы с API

Лимит запросов к API

На каждое приложение накладываются персональное ограничение. Время рассчитывается с момента первого запроса в серии.

Количество выполненных запросов в текущей серии передается в каждом ответе API в HTTP заголовке API-Usage-Limit (пример: API-Usage-Limit: 1/500).

При превышении лимита доступ к API становится недоступным до окончания текущих 5 минут. В таком случае код ответа сервера - 429 и при этом в HTTP заголовке Retry-After передается время до начала предоставления доступа в секундах.

Универсальные параметры запросов

Параметр Обязательный Значение по умолчанию Описание
apikey да

Параметр, необходимый для авторизации и совершения запросов API. Предоставляется системой.

supplier_key да, если используется apikey лаборатории

Параметр, позволяющий лаборатории делать запросы от имени заказчика. Предоставляется заказчиком лаборатории.

format нет "json"

Формат вывода ответа. Возможные значения: "json", "xml"

Параметр supplier_key обязательный только в методах feed и feed-status. В остальных методах параметр необязательный.

Но если результат запроса зависит от запрашивающего аккаунта (к примеру методы attributes и locations), и нужны данные, доступные именно заказчику, в этом случае параметр supplier_key становится необходимым. То есть, если передан supplier_key, запрашивающем аккаунтом считается заказчик.

HTTP ETag (Контроль версий)

Заголовок "Entity Tag" (или коротко ETag) используется для передачи хэша содержания страницы. Если страница была изменена, то хэш страницы тоже изменится. Сравнивая хэш на стороне клиента с хэшем, генерируемым на стороне сервера, кэш может определить, была ли станица изменена и требуется ли её передавать заново. Используется для таких методов: product, categories, brands.

При запросе, сервер возвращает ресурс вместе с соответствующим значением ETag, который находится в HTTP заголовке в поле ETag:
ETag: "686897696a7c876b7e"
Затем можно кэшировать ресурс вместе с его ETag. Позже, при получении страницы с того же адреса, можно послать ранее сохраненное значение ETag вместе с запросом в поле If-None-Match.
If-None-Match: "686897696a7c876b7e"

На этот запрос сервер сравнит ETag клиента с ETag для текущей версии ресурса. Если значения ETag совпадают, это означает, что ресурс не изменился, сервер отправит обратно очень короткий ответ с HTTP статусом 304 Not Modified. Статус 304 сообщает, что кэш версия по-прежнему актуальна и обновление данных не требуется.
Однако, если ETag-значения не совпадают, значит ресурс изменился и сервер вернет полный ответ. В этом случае можно обновить кэш ресурса и его ETag.

При использовании Etag и получении ответа со статусом 304 Not Modified лимит использования API не действует.

Для метода product длина хеша ETag зависит от количества товаров в ответе. Максимальная длина - 4Kb.

Пример заголовка с ETag:


Content-type: application/json; charset=utf-8
API-Usage-Limit: 1/500
Etag: "38fho43p543re634c993ec28581d867"
Status Code: 200
                        

Пример ответа со статусом 304:


Content-type: application/json; charset=utf-8
Status Code: 304
                        

Запрос на поиск отсутствующего товара

При использовании метода product с указанием gtin, параметров supplier_id, party_id (опционально product_name, cat_id) если товар отсутствует в базе данных (ответ метода product 404), будет произведен поиск товара у поставщика и его оцифровка согласно регламента.

https://апи.национальный-каталог.рф/v3/product?apikey=XXX&gtin=6114300162475&supplier_id&party_id=7&product_name=Пирожное с яблочным вареньем&cat_id=3423

Коды ответов

  • 200 — OK
  • 304 — Страница не изменилась
  • 400 — Ошибка в параметрах запроса
  • 401 — Не авторизован, в запросе отсутствует apikey
  • 403 — Нет доступа к запрашиваемой информации
  • 404 — Запрашиваемая информация не найдена
  • 413 — Размер запроса превышает лимит
  • 429 — Превышен лимит запросов к API, в HTTP заголовке Retry-After передается время до начала предоставления доступа в секундах
  • 500 — Внутренняя ошибка сервера
  • 501 — Метод не существует
  • 503 — Сервис недоступен, техническое обслуживание, повторите запрос позже

Метод attributes

Возвращает список атрибутов как публичных так и приватных для запрашивающего аккаунта.

Пример запроса

https://апи.национальный-каталог.рф/v3/attributes?apikey=XXX&cat_id=2&attr_type=m

Параметры запроса

  • cat_id — (необязательный, обязателен если указан attr_type) идентификатор категории, к которой относятся атрибуты. Если не указан, возвращается полный список атрибутов доступных для запрашивающего аккаунта.
  • attr_type — (необязательный) возможные значения параметра
    • a — (используется по-умолчанию) вернуть все атрибуты
    • m — вернуть только обязательные атрибуты
    • r — вернуть только рекомендуемые атрибуты
    • o — вернуть только опциональные атрибуты

Параметры ответа

  • attr_id - идентификатор атрибута
  • attr_name - наименование атрибута
  • attr_group_name - наименование группы, к которой относится атрибут
  • attr_group_id - идентификатор группы, к которой относится атрибут
  • attr_value_type - массив возможных значений типа атрибута
  • attr_field_type - тип значения атрибута (number или text)
  • attr_preset - массив возможных значений атрибута
  • attr_type - тип атрибута, будет указано, только при наличии cat_id в запросе

JSON

Content-type: application/json; charset=utf-8
API-Usage-Limit: 1/500
Status Code: 200
{
  "apiversion": 3,
  "result": [
    {
      "attr_id": 1,
      "attr_name": "Питательные характеристики",
      "attr_group_name": "Жиры",
      "attr_group_id": 6,
      "attr_field_type": "text",
      "attr_value_type": [ "г/100г", "мг/100г", "мг/100мл" ],
    },
    {
      "attr_id": 42,
      "attr_name": "Вкус",
      "attr_group_name": "Основные качества",
      "attr_group_id": 11,
      "attr_preset": [ "Абрикос", "Малина", "Яблоко" ],
      "attr_field_type": "text",
      "attr_type": "m"
    }
    ...
  ]
}

XML


Content-type: application/xml; charset=utf-8
API-Usage-Limit: 1/500
Status Code: 200
<?xml version="1.0" encoding="UTF-8"?>
<root>
    <apiversion>3</apiversion>
    <result>
        <item>
            <attr_id>1</attr_id>
            <attr_name>Содержание смолы</attr_name>
            <attr_group_name>Прочее</attr_group_name>
            <attr_group_id>26</attr_group_id>
            <attr_field_type>text</attr_field_type>
            <attr_value_type>
                <item>г/100г</item>
                <item>мг/100г</item>
                <item>мг/100мл</item>
            </attr_value_type>
            <attr_preset/>
        </item>
        <item>
            <attr_id>42</attr_id>
            <attr_name>Вкус</attr_name>
            <attr_group_name>Основные качества</attr_group_name>
            <attr_group_id>11</attr_group_id>
            <attr_preset>
                <item>Абрикос</item>
                <item>Малина</item>
                <item>Яблоко</item>
            </attr_preset>
            <attr_type>m</attr_type>
            <attr_field_type>text</attr_field_type>
        </item>
    </result>
</root>

Метод brands

Используется для получения списка торговых марок

Пример запроса

https://апи.национальный-каталог.рф/v3/brands?apikey=XXX

Параметры запроса

  • party_id — идентификатор торговой сети (необязательный)

Параметры ответа

  • party_brand_id — идентификатор бренда для торговой сети (только для владельца сети, если указан party_id в запросе)
  • brand_id - идентификатор бренда
  • brand_name - наименование бренда

JSON

Content-type: application/json; charset=utf-8
API-Usage-Limit: 1/500
Etag: "38fho43p543re634c993ec28581d867"
Status Code: 200
{
  "apiversion": 3,
  "result": [
    {
      "brand_id": 8117,
      "brand_name": "1 Сентября"
    },
    {
      "brand_id": 6262,
      "brand_name": "Nike"
    },
    {
      "party_brand_id": "12345",
      "brand_id": 7105,
      "brand_name": "Roshen"
    },
    {
      "brand_id": 6035,
      "brand_name": "1000 секретов"
    }...
  ]
}

XML

Content-type: application/xml; charset=utf-8
API-Usage-Limit: 1/500
Etag: "38fho43p543re634c993ec28581d867"
Status Code: 200
<?xml version="1.0" encoding="UTF-8"?>
<root>
    <apiversion>3</apiversion>
    <result>
        <item>
            <brand_id>8117</brand_id>
            <brand_name>1 Сентября</brand_name>
        </item>
        <item>
            <brand_id>6262</brand_id>
            <brand_name>Nike</brand_name>
        </item>
        <item>
            <party_brand_id>12345</party_brand_id>
            <brand_id>7105</brand_id>
            <brand_name>Roshen</brand_name>
        </item>
        <item>
            <brand_id>6035</brand_id>
            <brand_name>1000 секретов</brand_name>
        </item>
        ...
    </result>
</root>

Метод categories

Используется для получения дерева категорий, корень дерева не возвращается.

Пример запроса

https://апи.национальный-каталог.рф/v3/categories?apikey=XXX

Параметры запроса

Отсутствуют.

Параметры ответа

  • cat_id - идентификатор категории
  • cat_name - наименование категории
  • cat_parent_id - идентификатор родительской категории
  • cat_level - уровень в дереве категорий (1 верхний уровень, 2 подлежащий и так далее)

JSON

Content-type: application/json; charset=utf-8
API-Usage-Limit: 1/500
Etag: "38fho43p543re634c993ec28581d867"
Status Code: 200
{
  "apiversion": 3,
  "result": [
    {
      "cat_id": 14001,
      "cat_name": "Продукты питания",
      "cat_parent_id": 14000,
      "cat_level": "1"
    },
    {
      "cat_id": 14002,
      "cat_name": "Напитки",
      "cat_parent_id": 14001,
      "cat_level": 2
    }
    ...
  ]
}

XML

Content-type: application/xml; charset=utf-8
API-Usage-Limit: 1/500
Etag: "38fho43p543re634c993ec28581d867"
Status Code: 200
<?xml version="1.0" encoding="UTF-8"?>
<root>
    <apiversion>3</apiversion>
    <result>
        <item>
            <cat_id>14002</cat_id>
            <cat_name>Напитки</cat_name>
            <cat_parent_id>14000</cat_parent_id>
            <cat_level>2</cat_level>
        </item>
        <item>
            <cat_id>14001</cat_id>
            <cat_name>Питание</cat_name>
            <cat_parent_id>14000</cat_parent_id>
            <cat_level>2</cat_level>
        </item>
    </result>
</root>

Метод product

Метод возвращает краткую или полную информацию о продукте (товаре). Требует обязательного указания одного из следующих параметров: идентификатор товара, GTIN (штрих-код), LTIN или SKU с указанием идентификатора торговой сети, который относится к запрашиваемому аккаунту.

Если указаны более одного из обязательных параметров, то возвращается результат выборки, соответствующий данному алгоритму:

  • good_id - при указании, возвращается товар с соответствующим идентификатором или ошибка 404. При этом GTIN, LTIN и SKU игнорируются.
  • gtin - при указании, возвращается товар с соответствующим GTIN или ошибка 404. При этом LTIN и SKU игнорируются.
  • ltin - при указании, возвращается товар с соответствующим LTIN или ошибка 404. При этом SKU игнорируется.
  • sku - при указании, возвращается товар с соответствующим SKU или ошибка 404.
  • product_name — название продукта (необязательный; используется при запросе на поиск отсутствующего товара)
  • cat_id — идентификатор категории (необязательный; используется при запросе на поиск отсутствующего товара)

Пример запроса

https://апи.национальный-каталог.рф/v3/product?apikey=XXX&gtin=6411300162475

Параметры запроса

  • good_id — идентификатор товара в каталоге (обязательный, если отсутствуют gtin, ltin, sku)
  • gtin — глобальный штрих-код GTIN (обязательный, если отсутствуют good_id, ltin, sku)
  • ltin — локальный штрих-код LTIN (например весовые шк) (обязательный, если отсутствуют good_id, gtin, sku)
  • sku — локальный идентификатор товарной позиции (артикул) (обязательный, если отсутствуют good_id, gtin, ltin)
  • party_id — идентификатор торговой сети (обязательный, если при запросе указан ltin и sku)
  • supplier_id — идентификатор поставщика (необязательный; используется при запросе на поиск отсутствующего товара: идентификационный номер или регистрационый номер или налоговый номер)
  • product_name — название продукта (необязательный; используется при запросе на поиск отсутствующего товара)
  • cat_id — идентификатор категории (необязательный; используется при запросе на поиск отсутствующего товара)

Параметры ответа

  • identified_by — массив содержащий информацию о штрих-кодах (ltin/sku отдаются только те, которые принадлежат party для аккаунта apikey)
    • value — штрих-код или локальный идентификатор
    • type — тип штрих-кода
      • gtin — глобальный штрих-код GTIN
      • ltin — локальный штрих-код LTIN (например весовые шк)
      • sku — локальный идентификатор товарной позиции (артикул)
      • barcode — штрих-код Barcode (штрихкод с неправильной контрольной цифрой)
    • party_id — идентификатор торговой сети, возвращается только при условии, что параметр type имеет значение ltin, sku или barcode.
    • multiplier — количество товаров в упаковке, по-умолчанию 1
    • level — уровень упаковки
      • trade-unit — штука
      • box — коробка
      • layer — слой на палете
      • pallet — палета
      • metro-unit — метро-юнит
      • show-pack — шоу-пак
      • inner-pack — спайка
  • good_id — идентификатор товара
  • good_name — наименование товара
  • good_img — изображение товара
  • categories — массив категорий
    • cat_id — идентификатор категории, в которой расположен товар, исключая парентов этой категории.
    • cat_name — наименование категории, в которой расположен товар
    • и/или
    • party_cat_id — идентификатор категории торговой сети, в которой расположен товар (только для владельца сети, если указан party_id в запросе)
    • party_cat_name — наименование категории торговой сети, в которой расположен товар (только для владельца сети, если указан party_id в запросе)
  • party_brand_id — идентификатор бренда для торговой сети (только для владельца сети, если указан party_id в запросе)
  • brand_id — идентификатор бренда товара
  • brand_name — наименование бренда
  • good_rating — рейтинг товара
  • good_images — массив с изображениями
    • photo_type — тип фотографии
      • default — фотография по умолчанию (вид спереди)
      • facing — crop-фотография для планограмм (обрезанная по контуру товара)
      • left — фотография товара слева
      • right — фотография товара справа
      • back — фотография товара сзади
      • 3ds — 3D серия
      • marketing — коммерческая фотография товара
      • ecommerce — e-commerce фото
      • undef — single shot, фотография товара с не предопределенного ракурса
      • cubi — (опционально) фотография измерения ВГХ
    • photo_date — дата создания фотографии в UTC
    • photo_url — ссылка на med (medium) размер фотографии
    • barcode — (опционально) штрихкод или артикул товара, для которого сделана фотография
  • good_attrs — массив с атрибутами (приватные атрибуты отдаются только те, которые принадлежат аккаунту apikey)
    • attr_id — идентификатор атрибута
    • attr_name — наименование атрибута
    • attr_value_id — идентификатор значения атрибута (только для атрибутов 2502, 2503)
    • attr_value — значение атрибута
    • value_id — идентификатор значения атрибута
    • attr_value_type — тип значения атрибута
    • attr_group_id — идентификатор группы атрибутов
    • attr_group_name — наименование группы атрибутов
    • measure_date — дата измерения атрибута (UTC), (опционально)
    • published_date — дата публикации атрибута (UTC), (опционально)
    • effective_date — дата с которой действительно значение атрибута (UTC), (опционально)
    • expired_date — дата с которой недействительно значение атрибута (UTC), (опционально)
    • location_id — идентификатор локации, в которой было проведено измерение (опционально)
    • party_location_id — внутренний идентификатор локации для компании, в которой было проведено измерение (опционально, отображается только компании, которой принадлежит локация)
    • level — уровень упаковки (опционально)
    • gtin — штрих-код (опционально)
    • multiplier — мультипликатор (опционально)
    • certificate_number* - номер сертификата
    • certificate_issued_date* - дата начала срока действия
    • certificate_valid_until_date* - дата окончания срока действия
    • certificate_applicant* - заявитель
    • certificate_manufacturer* - изготовитель
    • certificate_product_description* - продукция
  • good_reviews — массив с отзывами
    • review_id — идентификатор отзыва
    • review_author — автор (имя, фамилия, псевдоним)
    • review_rating — рейтинг отзыва
    • review_text — текст отзыва
    • review_date — дата создания отзыва в UTC
    • review_author_img — ссылка на фотографию автора
    • review_replies — массив отзывов. Возвращается, если отзыв имеет ответы (т.е. отзывы со значением review_parent_id равным идентификатору данного/родительского отзыва)
      • review_id — идентификатор отзыва-ответа
      • review_author — автор (имя, фамилия, псевдоним)
      • review_rating — рейтинг отзыва-ответа
      • review_text — текст отзыва-ответа
      • review_date — дата создания отзыва в UTC
      • review_author_img — ссылка на фотографию автора
  • good_reviews_count — количество отзывов
  • good_url — ссылка на страницу товара
  • good_prices — массив цен на товар по торговым сетям данного аккаунта:
    • party_id — идентификатор торговой сети
    • address— местонахождение
      • country — название страны (ISO 3166-2)
      • city — название города
      • street — название улицы, дом
      • location — координаты
        • lat — географическая широта
        • lon — географическая долгота

* параметры с префиксом "certificate" есть только у атрибутов из групы "Сертификаты"

JSON

Content-type: application/json; charset=utf-8
API-Usage-Limit: 1/500
Etag: "38fho43p543re634c993ec28581d867"
Status Code: 200
{
  "apiversion": 3,
  "result": [
    {
      "good_id": 672136,
      "identified_by": [
        {
          "value": "11033",
          "type": "sku",
          "multiplier": 1,
          "level": "trade-unit"
        },
        {
          "value": "24823002000164",
          "type": "ltin",
          "multiplier": 12,
          "level": "box"
        }
      ],
      "good_name": "Gala стиральный порошoк авт. 1,5кг. Горная лаванда",
      "good_url": "https://национальный-каталог.рф/product/gala-pralniy-poroshok-avt-15kg-svizhist-girskoi-lavandi",
      "good_img": "https://национальный-каталог.рф/i/med/63d3beae-b0be-db33-f86b-65a0e37da584.jpg",
      "categories": [
        {
          "cat_id": 14786,
          "cat_name": "Порошки"
        },
        {
          "party_cat_id": 241000,
          "party_cat_name": "Порошки"
        }
      ],
      "brand_id": null,
      "brand_name": null,
      "good_rating": 4.33333,
      "good_images": [
        {
          "photo_type": "default",
          "photo_date": "2016-07-20T16:26:30+00:00",
          "photo_url": "https://национальный-каталог.рф/i/med/63d3beae-b0be-db33-f86b-65a0e37da584.jpg",
          "barcode": "6437005056338"
        },
        {
          "photo_type": "3ds",
          "photo_date": "2016-07-20T16:26:30+00:00",
          "photo_url": [
            "https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.0.jpg",
            "https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.1.jpg",
            "https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.2.jpg",
            "https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.3.jpg",
            "https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.4.jpg",
            "https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.5.jpg",
            "https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.6.jpg",
            "https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.7.jpg",
            "https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.8.jpg",
            "https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.9.jpg",
            "https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.10.jpg",
            "https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.11.jpg",
            "https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.12.jpg",
            "https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.13.jpg",
            "https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.14.jpg",
            "https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.15.jpg",
            "https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.16.jpg",
            "https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.17.jpg",
            "https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.18.jpg",
            "https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.19.jpg",
            "https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.20.jpg",
            "https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.21.jpg",
            "https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.22.jpg",
            "https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.23.jpg"
          ],
          "barcode": "6437005056338"
        },
        {
          "photo_type": "left",
          "photo_date": "2016-07-20T16:26:30+00:00",
          "photo_url": "https://национальный-каталог.рф/i/med/63d3beae-b0be-db33-f86b-65a0e37da584.6.jpg",
          "barcode": "6437005056338"
        },
        {
          "photo_type": "right",
          "photo_date": "2016-07-20T16:26:30+00:00",
          "photo_url": "https://национальный-каталог.рф/i/med/63d3beae-b0be-db33-f86b-65a0e37da584.18.jpg",
          "barcode": "6437005056338"
        },
        {
          "photo_type": "back",
          "photo_date": "2016-07-20T16:26:30+00:00",
          "photo_url": "https://национальный-каталог.рф/i/med/63d3beae-b0be-db33-f86b-65a0e37da584.12.jpg",
          "barcode": "6437005056338"
        }
      ],
      "good_attrs": [
        {
          "attr_id": 18,
          "attr_name": "Вес брутто",
          "attr_value": "1.506",
          "value_id": 7824938,
          "attr_value_type": "кг",
          "attr_group_id": 19,
          "attr_group_name": "Cubiscan-атрибуты",
          "measure_date": "2018-02-01T16:39:04+00:00",
          "published_date": "2018-02-03T13:22:11+00:00",
          "effective_date": "2018-02-05T16:39:04+00:00",
          "expired_date": "2018-08-05T16:39:04+00:00",
          "location_id": "532",
          "party_location_id": "Store #53",
          "level": "trade-unit",
          "gtin": "4011200255905",
          "multiplier": 1.00
        },
        {
          "attr_id": 19,
          "attr_name": "Высота",
          "attr_value": "29.2",
          "value_id": 8214928,
          "attr_value_type": "см",
          "attr_group_id": 19,
          "attr_group_name": "Cubiscan-атрибуты",
          "measure_date": "2018-02-01T16:39:04+00:00",
          "published_date": "2018-02-03T13:22:11+00:00",
          "effective_date": "2018-02-05T16:39:04+00:00",
          "expired_date": "2018-08-05T16:39:04+00:00",
          "location_id": "532",
          "party_location_id": "Store #53",
          "level": "trade-unit",
          "gtin": "4011200255905",
          "multiplier": 1.00
        },
        {
          "attr_id": 20,
          "attr_name": "Глубина",
          "attr_value": "",
          "value_id": 5325635,
          "attr_value_type": "см",
          "attr_group_id": 19,
          "attr_group_name": "Cubiscan-атрибуты",
          "measure_date": "2018-02-01T16:39:04+00:00",
          "published_date": "2018-02-03T13:22:11+00:00",
          "effective_date": "2018-02-05T16:39:04+00:00",
          "expired_date": "2018-08-05T16:39:04+00:00",
          "location_id": "532",
          "party_location_id": "Store #53",
          "level": "trade-unit",
          "gtin": "4011200255905",
          "multiplier": 1.00
        },
        {
          "attr_id": 21,
          "attr_name": "Ширина",
          "attr_value": "20.7",
          "value_id": 1224735,
          "attr_value_type": "см",
          "attr_group_id": 19,
          "attr_group_name": "Cubiscan-атрибуты",
          "measure_date": "2018-02-01T16:39:04+00:00",
          "published_date": "2018-02-03T13:22:11+00:00",
          "effective_date": "2018-02-05T16:39:04+00:00",
          "expired_date": "2018-08-05T16:39:04+00:00",
          "location_id": "532",
          "party_location_id": "Store #53",
          "level": "trade-unit",
          "gtin": "4011200255905",
          "multiplier": 1.00
        },
        {
          "attr_id": 2503,
          "attr_name": "Производитель",
          "attr_value_id": 3408,
          "value_id": 7812631,
          "attr_value": "ООО «ООО»",
          "attr_value_type": "",
          "attr_group_id": 25,
          "attr_group_name": "Стороны",
          "published_date": "2017-12-10 15:35:08",
          "location_id": "532",
          "party_location_id": "Store #53"
        },
        {
          "attr_id": 2813,
          "attr_name": "Единый реестр сертификатов соответствия",
          "attr_value": "https://национальный-каталог.рф/certificates/86F13A2714824C4B93545560F7D1CCC1",
          "value_id": 1624735,
          "attr_group_id": 41,
          "attr_group_name": "Сертификаты",
          "published_date": "2017-12-15 17:14:01",
          "location_id": "532",
          "party_location_id": "Store #53",
          "certificate_number": "С-RU.АЮ64.В.01026",
          "certificate_issued_date": "24.07.2017",
          "certificate_valid_until_date": "23.07.2022",
          "certificate_applicant": "Общество с ограниченной ответственностью «Производственная компания «Севкабель»",
          "certificate_manufacturer": "Общество с ограниченной ответственностью «Производственная компания «Севкабель»",
          "certificate_product_description": "Кабель судовой безгалогенный ..."
        }
      ],
      "good_reviews": [
        {
          "review_id": 286,
          "review_author": "Evgeniy",
          "review_rating": 4,
          "review_text": "Отлично!",
          "review_date": "2016-11-28T09:31:54+00:00",
          "review_author_img": "https://lh5.googleusercontent.com/-F0rhYj_uC6o/AAAAAAAAAAI/AAAAAAAAFUs/_nuL7XLXK88/photo.jpg?sz=50",
          "review_replies": [
            {
              "review_id": 288,
              "review_author": "Maxim",
              "review_rating": 4,
              "review_text": "Perfect!!!",
              "review_date": "2016-11-28T09:49:39+00:00",
              "review_author_img": "https://lh5.googleusercontent.com/-F0rhYj_uC6o/AAAAAAAAAAI/AAAAAAAAFUs/_nuL7XLXK88/photo.jpg?sz=50"
            }
          ]
        },
        {
          "review_id": 282,
          "review_author": "Maria Moryakina",
          "review_rating": 5,
          "review_text": "Вкусно пахнет",
          "review_date": "2016-11-17T11:19:48+00:00",
          "review_author_img": "https://scontent.xx.fbcdn.net/v/t1.0-1/c0.17.100.100/p100x100/14102384_286143021757109_2710809744588865430_n.jpg?oh=2eb1e9f751c01e58c7b9fdc76dc7153b&oe=58F8B7F4"
        }
      ],
      "good_reviews_count": 3,
      "good_prices": []
    }
  ]
}

XML

Content-type: application/xml; charset=utf-8
API-Usage-Limit: 1/500
Etag: "38fho43p543re634c993ec28581d867"
Status Code: 200
<?xml version="1.0" encoding="UTF-8"?>
<root>
    <apiversion>3</apiversion>
    <result>
        <item>
            <good_id>672136</good_id>
            <identified_by>
                <item>
                    <value>11033</value>
                    <type>sku</type>
                    <multiplier>1</multiplier>
                    <good_id>672136</good_id>
                    <level>trade-unit</level>
                </item>
                <item>
                    <value>24823002000164</value>
                    <type>ltin</type>
                    <multiplier>12</multiplier>
                    <good_id>672136</good_id>
                    <level>box</level>
                </item>
            </identified_by>
            <good_name>Gala стиральный порошoк авт. 1,5кг. Горная лаванда</good_name>
            <good_url>https://национальный-каталог.рф/product/gala-pralniy-poroshok-avt-15kg-svizhist-girskoi-lavandi</good_url>
            <good_img>https://национальный-каталог.рф/i/med/63d3beae-b0be-db33-f86b-65a0e37da584.jpg</good_img>
            <categories>
                <item>
                    <cat_id>14786</cat_id>
                    <cat_name>Порошки</cat_name>
                </item>
                <item>
                    <party_cat_id>241000</party_cat_id>
                    <party_cat_name>Порошки</party_cat_name>
                </item>
            </categories>
            <brand_id></brand_id>
            <brand_name></brand_name>
            <good_rating>4,33333</good_rating>
            <good_images>
                <item>
                    <photo_type>default</photo_type>
                    <photo_date>2016-07-20T16:26:30+00:00</photo_date>
                    <photo_url>https://национальный-каталог.рф/i/med/63d3beae-b0be-db33-f86b-65a0e37da584.jpg</photo_url>
                    <barcode>6437005056338</barcode>
                </item>
                <item>
                    <photo_type>3ds</photo_type>
                    <photo_date>2016-07-20T16:26:30+00:00</photo_date>
                    <photo_url>
                        <item>https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.0.jpg</item>
                        <item>https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.1.jpg</item>
                        <item>https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.2.jpg</item>
                        <item>https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.3.jpg</item>
                        <item>https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.4.jpg</item>
                        <item>https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.5.jpg</item>
                        <item>https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.6.jpg</item>
                        <item>https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.7.jpg</item>
                        <item>https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.8.jpg</item>
                        <item>https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.9.jpg</item>
                        <item>https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.10.jpg</item>
                        <item>https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.11.jpg</item>
                        <item>https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.12.jpg</item>
                        <item>https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.13.jpg</item>
                        <item>https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.14.jpg</item>
                        <item>https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.15.jpg</item>
                        <item>https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.16.jpg</item>
                        <item>https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.17.jpg</item>
                        <item>https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.18.jpg</item>
                        <item>https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.19.jpg</item>
                        <item>https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.20.jpg</item>
                        <item>https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.21.jpg</item>
                        <item>https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.22.jpg</item>
                        <item>https://национальный-каталог.рф/i/med/3d/63d3beae-b0be-db33-f86b-65a0e37da584.3d.23.jpg</item>
                    </photo_url>
                    <barcode>6437005056338</barcode>
                </item>
                <item>
                    <photo_type>left</photo_type>
                    <photo_date>2016-07-20T16:26:30+00:00</photo_date>
                    <photo_url>https://национальный-каталог.рф/i/med/63d3beae-b0be-db33-f86b-65a0e37da584.6.jpg</photo_url>
                    <barcode>6437005056338</barcode>
                </item>
                <item>
                    <photo_type>right</photo_type>
                    <photo_date>2016-07-20T16:26:30+00:00</photo_date>
                    <photo_url>https://национальный-каталог.рф/i/med/63d3beae-b0be-db33-f86b-65a0e37da584.18.jpg</photo_url>
                    <barcode>6437005056338</barcode>
                </item>
                <item>
                    <photo_type>back</photo_type>
                    <photo_date>2016-07-20T16:26:30+00:00</photo_date>
                    <photo_url>https://национальный-каталог.рф/i/med/63d3beae-b0be-db33-f86b-65a0e37da584.12.jpg</photo_url>
                    <barcode>6437005056338</barcode>
                </item>
            </good_images>
            <good_attrs>
                <item>
                    <attr_id>18</attr_id>
                    <attr_name>Вес брутто</attr_name>
                    <attr_value>1.506</attr_value>
                    <value_id>7824938</value_id>
                    <attr_value_type>кг</attr_value_type>
                    <attr_group_id>19</attr_group_id>
                    <attr_group_name>Cubiscan-атрибуты</attr_group_name>
                    <measure_date>2018-02-01T16:39:04+00:00</measure_date>
                    <published_date>2018-02-03T13:22:11+00:00</published_date>
                    <effective_date>2018-02-05T16:39:04+00:00</effective_date>
                    <expired_date>2018-08-05T16:39:04+00:00</expired_date>
                    <location_id>532</location_id>
                    <party_location_id>Store #53</party_location_id>
                    <level>trade-unit</level>
                    <gtin>4011200255905</gtin>
                    <multiplier>1.00</multiplier>
                </item>
                <item>
                    <attr_id>19</attr_id>
                    <attr_name>Высота</attr_name>
                    <attr_value>29.2</attr_value>
                    <value_id>8214928</value_id>
                    <attr_value_type>см</attr_value_type>
                    <attr_group_id>19</attr_group_id>
                    <attr_group_name>Cubiscan-атрибуты</attr_group_name>
                    <measure_date>2018-02-01T16:39:04+00:00</measure_date>
                    <published_date>2018-02-03T13:22:11+00:00</published_date>
                    <effective_date>2018-02-05T16:39:04+00:00</effective_date>
                    <expired_date>2018-08-05T16:39:04+00:00</expired_date>
                    <location_id>532</location_id>
                    <party_location_id>Store #53</party_location_id>
                    <level>trade-unit</level>
                    <gtin>4011200255905</gtin>
                    <multiplier>1.00</multiplier>
                </item>
                <item>
                    <attr_id>20</attr_id>
                    <attr_name>Глубина</attr_name>
                    <attr_value></attr_value>
                    <value_id>5325635</value_id>
                    <attr_value_type>см</attr_value_type>
                    <attr_group_id>19</attr_group_id>
                    <attr_group_name>Cubiscan-атрибуты</attr_group_name>
                    <measure_date>2018-02-01T16:39:04+00:00</measure_date>
                    <published_date>2018-02-03T13:22:11+00:00</published_date>
                    <effective_date>2018-02-05T16:39:04+00:00</effective_date>
                    <expired_date>2018-08-05T16:39:04+00:00</expired_date>
                    <location_id>532</location_id>
                    <party_location_id>Store #53</party_location_id>
                    <level>trade-unit</level>
                    <gtin>4011200255905</gtin>
                    <multiplier>1.00</multiplier>
                </item>
                <item>
                    <attr_id>21</attr_id>
                    <attr_name>Ширина</attr_name>
                    <attr_value>20.7</attr_value>
                    <value_id>1224735</value_id>
                    <attr_value_type>см</attr_value_type>
                    <attr_group_id>19</attr_group_id>
                    <attr_group_name>Cubiscan-атрибуты</attr_group_name>
                    <measure_date>2018-02-01T16:39:04+00:00</measure_date>
                    <published_date>2018-02-03T13:22:11+00:00</published_date>
                    <effective_date>2018-02-05T16:39:04+00:00</effective_date>
                    <expired_date>2018-08-05T16:39:04+00:00</expired_date>
                    <location_id>532</location_id>
                    <party_location_id>Store #53</party_location_id>
                    <level>trade-unit</level>
                    <gtin>4011200255905</gtin>
                    <multiplier>1.00</multiplier>
                </item>
                <item>
                    <attr_id>2503</attr_id>
                    <attr_name>Производитель</attr_name>
                    <attr_value_id>3408</attr_value>
                    <value_id>7812631</value_id>
                    <attr_value>ООО ООО</attr_value>
                    <attr_value_type></attr_value_type>
                    <attr_group_id>25</attr_group_id>
                    <attr_group_name>Стороны</attr_group_name>
                    <published_date>2017-12-10 15:35:08</published_date>
                    <location_id>532</location_id>
                    <party_location_id>Store #53</party_location_id>
                </item>
                <item>
                    <attr_id>2813</attr_id>
                    <attr_name>Единый реестр сертификатов соответствия</attr_name>
                    <attr_value>https://национальный-каталог.рф/certificates/86F13A2714824C4B93545560F7D1CCC1</attr_value>
                    <value_id>1624735</value_id>
                    <attr_group_id>41</attr_group_id>
                    <attr_group_name>Сертификаты</attr_group_name>
                    <published_date>2017-12-15 17:14:01</published_date>
                    <location_id>532</location_id>
                    <party_location_id>Store #53</party_location_id>
                    <certificate_number>С-RU.АЮ64.В.01026</certificate_number>
                    <certificate_issued_date>24.07.2017</certificate_issued_date>
                    <certificate_valid_until_date>23.07.2022</certificate_valid_until_date>
                    <certificate_applicant>Общество с ограниченной ответственностью «Производственная компания «Севкабель»</certificate_applicant>
                    <certificate_manufacturer>Общество с ограниченной ответственностью «Производственная компания «Севкабель»</certificate_manufacturer>
                    <certificate_product_description>Кабель судовой безгалогенный, не распространяющий горение...</certificate_product_description>
                </item>
            </good_attrs>
            <good_reviews>
                <item>
                    <review_id>286</review_id>
                    <review_author>Evgeniy</review_author>
                    <review_rating>4</review_rating>
                    <review_text>Отлично!</review_text>
                    <review_date>2016-11-28T09:31:54+00:00</review_date>
                    <review_author_img>https://lh5.googleusercontent.com/-F0rhYj_uC6o/AAAAAAAAAAI/AAAAAAAAFUs/_nuL7XLXK88/photo.jpg?sz=50</review_author_img>
                    <review_replies>
                        <item>
                            <review_id>288</review_id>
                            <review_author>Maxim</review_author>
                            <review_rating>4</review_rating>
                            <review_text>Perfect!!!</review_text>
                            <review_date>2016-11-28T09:49:39+00:00</review_date>
                            <review_author_img>https://lh5.googleusercontent.com/-F0rhYj_uC6o/AAAAAAAAAAI/AAAAAAAAFUs/_nuL7XLXK88/photo.jpg?sz=50</review_author_img>
                        </item>
                    </review_replies>
                </item>
                <item>
                    <review_id>282</review_id>
                    <review_author>Maria Moryakina</review_author>
                    <review_rating>5</review_rating>
                    <review_text>Вкусно пахнет</review_text>
                    <review_date>2016-11-17T11:19:48+00:00</review_date>
                    <review_author_img>https://scontent.xx.fbcdn.net/v/t1.0-1/c0.17.100.100/p100x100/14102384_286143021757109_2710809744588865430_n.jpg?oh=2eb1e9f751c01e58c7b9fdc76dc7153b&amp;oe=58F8B7F4</review_author_img>
                </item>
            </good_reviews>
            <good_reviews_count>3</good_reviews_count>
            <good_prices/>
        </item>
    </result>
</root>

Метод etagslist

Метод возвращает список всех товаров конкретного продавца (торговой сети) вместе с хэшем содержания страницы. Предназначен для того, чтобы можно было быстро получить список хешей, сравнить с локальным хранилищем и обновить информацию по товарам (метод product) для которых хеш изменился - т.е есть новые данные.

Пример запроса

https://апи.национальный-каталог.рф/v3/etagslist?apikey=XXX&party_id=YYY

Параметры запроса

  • party_id — идентификатор торговой сети (обязательный)

Параметры ответа

  • good_id — идентификатор товара
  • etag — хеш (детальнее в секции контроль версии)
  • sku — артикулы
    • item — значение артикула

JSON

Content-type: application/json; charset=utf-8
API-Usage-Limit: 1/500
Status Code: 200
{
    "apiversion":3,
    "result": [
        {
            "good_id":59363,
            "etag":"e90d02cd2ee1344c",
            "sku": [
                "112629"
            ]
        },
        {
            "good_id":18407,
            "etag":"96f5d483b11a7b21",
            "sku": [
                "112606"
            ]
        },
        {
            "good_id":10869,
            "etag":"0195473cf6b9a2be",
            "sku": [
                "112612"
            ]
        }
    ]
}

XML

Content-type: application/xml; charset=utf-8
API-Usage-Limit: 1/500
Status Code: 200
<?xml version="1.0" encoding="UTF-8"?>
<root>
    <apiversion>3</apiversion>
    <result>
        <item>
            <good_id>59363</good_id>
            <etag>e90d02cd2ee1344c</etag>
            <sku>
                <item>112629</item>
            </sku>
        </item>
        <item>
            <good_id>18407</good_id>
            <etag>96f5d483b11a7b21</etag>
            <sku>
                <item>112606</item>
            </sku>
        </item>
        <item>
            <good_id>10869</good_id>
            <etag>0195473cf6b9a2be</etag>
            <sku>
                <item>112612</item>
            </sku>
        </item>
    </result>
</root>

Метод suggestions

Возвращает список товаров по найденному соответствию в имени.

Пример запроса

https://апи.национальный-каталог.рф/v3/suggestions?apikey=XXX&q=Мыл

Параметры запроса

  • q — (обязательный) строка для поиска по наименованию товара, не меньше 3-х символов

Параметры ответа

  • brand_name — наименование бренда
  • good_id — идентификатор товара
  • good_name — наименование товара
  • good_img — фотография товара по умолчанию (размер 300x200px)

JSON

Content-type: application/json; charset=utf-8
API-Usage-Limit: 1/500
Status Code: 200
{
  "apiversion": 3,
  "result": [
    {
      "brand_name": "Шик",
      "good_id": "319932",
      "good_name": "Мыло туалетное Ягоды калиновые Родное мыло",
      "good_img": "https://национальный-каталог.рф/i/e6104f.jpg"
    },
    {
      "brand_name": "Шик",
      "good_id": "319933",
      "good_name": "Мыло туалетное Душисты Родное мыло Шик 80г",
      "good_img": "https://национальный-каталог.рф/i/aabac1c6.jpg"
    }
    ...
  ]
}

XML

Content-type: application/xml; charset=utf-8
API-Usage-Limit: 1/500
Status Code: 200
<?xml version="1.0" encoding="UTF-8"?>
<root>
  <apiversion>3</apiversion>
  <result>
    <item>
      <brand_name>Шик</brand_name>
      <good_id>319932</good_id>
      <good_name>Мыло туалетное Ягоды калиновые Родное мыло Шик 80г</good_name>
      <good_img>https://национальный-каталог.рф/i/e6104f.jpg</good_img>
    </item>
    <item>
      <brand_name>Шик</brand_name>
      <good_id>319933</good_id>
      <good_name>Мыло туалетное Душистые бархатцы Родное мыло Шик 80г</good_name>
      <good_img>https://национальный-каталог.рф/i/aabac1c6.jpg</good_img>
    </item>
    ...
  </result>
</root>

Метод addreview

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

Пример запроса

https://апи.национальный-каталог.рф/v3/addreview?apikey=XXX&review_parent_id=174
или
https://апи.национальный-каталог.рф/v3/addreview?apikey=XXX&good_id=62433

POST-параметр Значение параметра
review_text "Отличное средство!"
social_type "gp"
social_id "120076146314"
review_author "Petrenko Petro"
review_rating 4

Параметры запроса

GET-параметры:

  • review_parent_id — идентификатор родительского отзыва (при указании родительского идентификатора, указывать идентификатор сущности не требуется, т.к. он игнорируется)
  • brand_id — идентификатор бренда (необходимо указать, если не задан review_parent, party_id, good_id)
  • party_id — идентификатор торговой сети (необходимо указать, если не задан review_parent, brand_id, good_id)
  • good_id — идентификатор товара (необходимо указать, если не задан review_parent, party_id, brand_id)

POST-параметры:

  • review_text — (обязательный) текст отзыва
  • social_type — (обязательный) тип используемого сервиса для авторизации, возможные значения:
    • gp — Google plus
    • fb — Facebook
    • tw — Twitter
    • vk — VK
  • social_id — (обязательный) идентификатор пользователя для сервиса авторизации, указанного в social_type.
  • review_author — (обязательный) автор (имя, фамилия, псевдоним)
  • review_rating — (обязательный) рейтинг, выставленный автором отзыва (число от 0 до 5)

Параметры ответа

  • review_id — идентификатор отзыва.
  • review_parent_id — идентификатор родительского отзыва, если это ответ.
  • brand_id — идентификатор бренда, если отзыв относится к этой сущности.
  • good_id — идентификатор товара, если отзыв относится к этой сущности.
  • party_id — идентификатор торговой сети, если отзыв относится к этой сущности.
  • review_rating — рейтинг, выставленный автором (число от 0 до 5)
  • review_text — текст отзыва
  • review_date — дата создания отзыва в UTC
  • review_author — автор (имя, фамилия, псевдоним)
  • review_author_img — ссылка на фотографию автора

JSON

Content-type: application/json; charset=utf-8
API-Usage-Limit: 1/500
Status Code: 200
{
  "apiversion": 3,
  "result": {
    "review_id": 181,
    "good_id": 62084,
    "review_author": "Petrenko Petr",
    "review_rating": 4,
    "review_text": "Отличное средство!",
    "review_date": "2016-10-21 10:17:13",
    "review_author_img": "https://plus.google.com/petro.jpg"
  }
}

XML

Content-type: application/xml; charset=utf-8
API-Usage-Limit: 1/500
Status Code: 200
<?xml version="1.0" encoding="UTF-8"?>
<root>
  <apiversion>3</apiversion>
  <result>
    <review_id>181</review_id>
    <good_id>62084</good_id>
    <review_author>Petrenko Petr</review_author>
    <review_rating>4</review_rating>
    <review_text>Отличное средство!</review_text>
    <review_date>2016-10-21 10:17:13</review_date>
    <review_author_img>https://plus.googl.jpg</review_author_img>
  </result>
</root>

Метод image

Дает возможность пропорционально изменить размер изображения с заполнением не достающих полей белым цветом. Метод принимает и фозвращает формат JPEG.

Пример запроса

https://апи.национальный-каталог.рф/v3/image?apikey=XXX&name=https://национальный-каталог.рф/i/300x200/5a7eb614-13d3-69ed-caf7-420624d1bdd3.jpg&width=300&height=400

Параметры запроса

GET-параметры:

  • name — полный URI изображения, те что приходят в ответе API
  • width — ширина рисунка на выходе, должна быть в границах [100, 1000] (результирующая высота в пикселях)
  • height — высота рисунка на выходе, должна быть в границах [100, 1000] (результирующая ширина в пикселях)
  • no-background — по-умолчанию к результирующему рисунку будет добавлен белый фон, чтобы строго соблюсти желаемые размеры width и height, но если этот параметр выставить в "1" - фон добавлен не будет

Ответ

Ответом метода является фото уже измененного размера.

Метод parties

Используется для получения списка компаний

Пример запроса

https://национальный-каталог.рф/v3/parties?apikey=XXX
или
https://национальный-каталог.рф/v3/parties?apikey=XXX&role=m

Параметры запроса

  • role — вид деялельности (необязательный), возможные значения:
    • m — Продавец
    • r — Торговая сеть
    • e — Интернет-магазин
    • p — Производитель
    • i — Импортер
    • d — Дистрибютор
    • s — Поставщик

Параметры ответа

  • parties_id — идентификатор компании.
  • party_name — наименование компании.

JSON

Content-type: application/json; charset=utf-8
API-Usage-Limit: 1/500
Status Code: 200
{
  "apiversion": 3,
  "result": [
    {
      "party_id": 1,
      "party_name": "Щёкинобумпром, ООО"
      }
    },
    {
      "party_id": 3,
      "party_name": "Биокон"
    },
    {
      "party_id": 6,
      "party_name": "Европродукт"
    }
  ]
}

XML

Content-type: application/xml; charset=utf-8
API-Usage-Limit: 1/500
Status Code: 200
<root>
<apiversion>3</apiversion>
<result>
    <item>
        <party_id>1</party_id>
        <party_name>Щёкинобумпром, ООО </party_name>
    </item>
    <item>
        <party_id>3</party_id>
        <party_name>Биокон</party_name>
    </item>
    <item>
        <party_id>6</party_id>
        <party_name>Европродукт</party_name>
    </item>
</result>
</root>

Метод locations

Возвращает список локаций для запрашивающего аккаунта (если не указан party_id) или конкретной торговой сети (если указан ее party_id).

Пример запроса

https://апи.национальный-каталог.рф/v3/locations?apikey=XXX
или
https://апи.национальный-каталог.рф/v3/locations?apikey=XXX&party_id=123

Параметры запроса

  • party_id — идентификатор торговой сети (необязательный)

Параметры ответа

  • location_id — идентификатор локации.
  • party_id — идентификатор торговой сети.
  • party_location_id — идентификатор локации в торговой сети
  • location_name — наименование локации.
  • status — состояние локации, возможные значения:
    • O — открыто
    • C — закрыто
    • U — строится
    • R — ремонт
  • services — доступные сервисы
  • schedule — рабочее время
  • address— местонахождение
    • country — название страны (ISO 3166-1 alpha-2)
    • region — название региона
    • city — название города
    • street — название улицы, дом
    • location — координаты
      • lat — географическая широта
      • lon — географическая долгота

JSON

Content-type: application/json; charset=utf-8
API-Usage-Limit: 1/500
Status Code: 200
{
  "apiversion": 3,
  "result": [
    {
      "location_id": 12,
      "party_id": 1,
      "party_location_id": "",
      "location_name": "Мегамаркет на Горького",
      "status": "O",
      "services": "",
      "schedule": "08:00 - 23:00",
      "address": {
        "country": "RU",
        "region": "Московская область",
        "city": "Москва",
        "street": "улица Антоновича, 50",
        "location": {
          "lat": "50.43142399",
          "lon": "30.51443219"
        }
      }
    },
    {
      "location_id": 14,
      "party_id": 1,
      "party_location_id": null,
      "location_name": "Мегамаркет на Петровке",
      "status": "O",
      "services": "",
      "schedule": "08:00 - 23:00",
      "address": {
        "country": "RU",
        "region": "Московская область",
        "city": "Москва",
        "street": "Московский проспект, 6",
        "location": {
          "lat": "50.48752964",
          "lon": "30.49469632"
        }
      }
    },
    {
      "location_id": 15,
      "party_id": 1,
      "party_location_id": null,
      "location_name": "Мегамаркет на Соломенке",
      "status": "O",
      "services": "",
      "schedule": "08:30 - 23:00",
      "address": {
        "country": "RU",
        "region": "Московская область",
        "city": "Москва",
        "street": "улица Василия Сурикова, 3",
        "location": {
          "lat": "50.43384300",
          "lon": "30.47654100"
        }
      }
    },
    {
      "location_id": 17,
      "party_id": 1,
      "party_location_id": null,
      "location_name": "Мегамаркет в ТРЦ \"Большевик\"",
      "status": "O",
      "services": "",
      "schedule": "08:30 - 23:00",
      "address": {
        "country": "RU",
        "region": "Московская область",
        "city": "Москва",
        "street": "улица Вадима Гетьмана, 6",
        "location": {
          "lat": "50.45105400",
          "lon": "30.44150100"
        }
      }
    },
    {
      "location_id": 16,
      "party_id": 4133,
      "party_location_id": null,
      "location_name": "Мегамаркет в ТРЦ \"Терминал\"",
      "status": "C",
      "services": "",
      "schedule": "09:00 - 23:00",
      "address": {
        "country": "RU",
        "region": "Московская область",
        "city": "Тула",
        "street": "Москваская улица, 316",
        "location": {
          "lat": "50.52641100",
          "lon": "30.79639900"
        }
      }
    },
    {
      "location_id": 18,
      "party_id": 4134,
      "party_location_id": null,
      "location_name": "МегаМаркет Ходосовка",
      "status": "O",
      "services": "",
      "schedule": "09:00 - 23:00",
      "address": {
        "country": "RU",
        "region": "Московская область",
        "city": "Ходосовка",
        "street": "Новообуховское шоссе 1, д.16",
        "location": {
          "lat": "50.27026310",
          "lon": "30.53536270"
        }
      }
    }
  ]
}

XML

Content-type: application/xml; charset=utf-8
API-Usage-Limit: 1/500
Status Code: 200
<root>
<apiversion>3</apiversion>
<result>
    <item>
        <location_id>12</location_id>
        <party_id>1</party_id>
        <party_location_id/>
        <location_name>Мегамаркет на Горького</location_name>
        <status>O</status>
        <services/>
        <schedule>08:00 - 23:00</schedule>
        <address>
            <country>RU</country>
            <region>Московская область</region>
            <city>Москва</city>
            <street>улица Антоновича, 50</street>
            <location>
                <lat>50.43142399</lat>
                <lon>30.51443219</lon>
            </location>
        </address>
    </item>
    <item>
        <location_id>14</location_id>
        <party_id>1</party_id>
        <party_location_id/>
        <location_name>Мегамаркет на Петровке</location_name>
        <status>O</status>
        <services/>
        <schedule>08:00 - 23:00</schedule>
        <address>
            <country>RU</country>
            <region>Московская область</region>
            <city>Москва</city>
            <street>Московский проспект, 6</street>
            <location>
                <lat>50.48752964</lat>
                <lon>30.49469632</lon>
            </location>
        </address>
    </item>
    <item>
        <location_id>15</location_id>
        <party_id>1</party_id>
        <party_location_id/>
        <location_name>Мегамаркет на Соломенке</location_name>
        <status>O</status>
        <services/>
        <schedule>08:30 - 23:00</schedule>
        <address>
            <country>RU</country>
            <region>Московская область</region>
            <city>Москва</city>
            <street>улица Василия Сурикова, 3</street>
            <location>
                <lat>50.43384300</lat>
                <lon>30.47654100</lon>
            </location>
        </address>
    </item>
    <item>
        <location_id>17</location_id>
        <party_id>1</party_id>
        <party_location_id/>
        <location_name>Мегамаркет в ТРЦ "Большевик"</location_name>
        <status>O</status>
        <services/>
        <schedule>08:30 - 23:00</schedule>
        <address>
            <country>RU</country>
            <region>Московская область</region>
            <city>Москва</city>
            <street>улица Вадима Гетьмана, 6</street>
            <location>
                <lat>50.45105400</lat>
                <lon>30.44150100</lon>
            </location>
        </address>
    </item>
    <item>
        <location_id>16</location_id>
        <party_id>4133</party_id>
        <party_location_id/>
        <location_name>Мегамаркет в ТРЦ "Терминал"</location_name>
        <status>C</status>
        <services/>
        <schedule>09:00 - 23:00</schedule>
        <address>
            <country>RU</country>
            <region>Московская область</region>
            <city>Тула</city>
            <street>Московская улица, 316</street>
            <location>
                <lat>50.52641100</lat>
                <lon>30.79639900</lon>
            </location>
        </address>
    </item>
    <item>
        <location_id>18</location_id>
        <party_id>4134</party_id>
        <party_location_id/>
        <location_name>МегаМаркет Ходосовка</location_name>
        <status>O</status>
        <services/>
        <schedule>09:00 - 23:00</schedule>
        <address>
            <country>RU</country>
            <region>Московская область</region>
            <city>Ходосовка</city>
            <street>Новообуховское шоссе 1, д.16</street>
            <location>
                <lat>50.27026310</lat>
                <lon>30.53536270</lon>
            </location>
        </address>
    </item>
</result>
</root>

Метод generate-gtins

Генерирует черновики GTIN и возвращает их.

Пример запроса

https://апи.национальный-каталог.рф/v3/generate-gtins?apikey=XXX&quantity=3
или
https://апи.национальный-каталог.рф/v3/generate-gtins?apikey=XXX&quantity=3&supplier_key=YYY

Параметры запроса

  • quantity — количество новых черновиков GTIN, которые нужно сгенерировать (обязательный)
  • supplier_key — ключ поставщика или производителя товаров

Параметры ответа

  • monthly-limit — ежемесячное ограничение.
    • limit — общее количество черновиков GTIN, доступных для генерации, в течении одного месяца
    • usage — количество черновиков GTIN, которые уже были сгенерированы, в течении этого месяца
  • drafts — список черновиков
    • gtin — GTIN, которые были сгенерированы

JSON

Content-type: application/json; charset=utf-8
API-Usage-Limit: 1/500
Status Code: 200
{
    "apiversion": 3,
    "result": {
        "monthly-limit": {
            "limit": 100,
            "usage": 6
        },
        "drafts": [
            {
                "gtin": "4600002575689"
            },
            {
                "gtin": "4600002575696"
            },
            {
                "gtin": "4600002575702"
            }
        ]
    }
}

XML

Content-type: application/xml; charset=utf-8
API-Usage-Limit: 1/500
Status Code: 200
<root>
<apiversion>3</apiversion>
<result>
    <monthly-limit>
        <limit>100</limit>
        <usage>6</usage>
    </monthly-limit>
    <drafts>
        <gtin>4600002575689</gtin>
        <gtin>4600002575696</gtin>
        <gtin>4600002575702</gtin>
    </drafts>
</result>
</root>

Метод feed

Дает возможность лабораториям создавать и обновлять товары. Метод возвращает feed_id или ошибку.

Ограничения

  • Размер фида - 25 МБ
  • Количество товаров в фиде - 5000

При привышении лимита на размер фида или на количество товаров в фиде будет вызвана ошибка с кодом 413.

При ошибке в схеме данных будет получена ошибка с кодом 400.

Пример запроса

https://апи.национальный-каталог.рф/v3/feed?apikey=XXX&supplier_key=YYY&party_id=ZZZ

Параметры запроса

URL обязательно должен содержать apikey, supplier_key и party_id.

  • party_id — идентификатор компании поставщика (обязательный)
  • supplier_key — ключ поставщика или производителя товаров (обязательный)

Фид передается в тело запроса. Поддерживается 2 формата для отправки фида: json и xml.

В Header нужно передать

  • "Content-Type: application/xml", если фид в формате xml;
  • "Content-Type: application/json", если фид в формате json.

Фид представляет собой массив объектов, называемых entry.

Описание entry.

Для изменения существующего товара должно быть передано значение его идентификатора good_id. Если параметра good_id нет, товар определяется как новый.

Для нового товара обязательным является параметр good_name и gtin.

Параметры:

  • @id - идентификатор энтри, который лаборатория может задать для более конкретной идентификации ответа (необязательный)
  • good_id - идентификатор товара (обязательный для обновляемых товаров)
  • gtin — идентификатор в Национальном каталоге товаров GTIN (обязательный для нового товара)
  • good_name - наименование товара (обязательный для нового товара)
  • identified_by массив идентификаторов (необязательный)

    Структура идентификатора

    • type - тип идентификатора (обязательный). Возможные значения:
      • gtin
      • sku
      • ltin
      • barcode
    • value - значение (обязательный)
    • level - тип упаковки (обязательный) Возможные значения:
      • trade-unit — штука
      • box — коробка
      • layer — слой на палете
      • pallet — палета
      • metro-unit — метро-юнит
      • show-pack — шоу-пак
      • inner-pack — спайка
    • multiplier - количество в упаковке (обязательный)
    • party_id - идентификатор торговой сети (необязательный) при типе gtin, (обязательный) при других типах
    • unit - тип измерений (необязательный) Возможные значения:
      • кг — килограмм
      • шт — штука
  • categories массив категорий

    Структура категории:

    • cat_id - идентификатор категории (обязательный)
    • delete - со значением 1 - удаление товара из категории (необязательный). Доступно только при редактировании существующего товара.
  • good_attrs массив атрибутов (необязательный)

    Структура атрибута:

    • attr_value_id - идентификатор значение атрибута (обязательный для обновления существующих атрибутов товара)
    • attr_id - идентификатора атрибута (обязательный при создании товара).
    • attr_value - значение атрибута (обязательный при создании товара; необязательный при редактировании и удалении)
    • attr_value_type - тип значение атрибута (необязательный)
    • gtin - значение gtin (необязательный)
    • delete - со значением 1 - удаление атрибута товара (необязательный). Доступно только при редактировании существующего товара. При передаче данного параметра, обязательно указать attr_value_id .
  • good_images массив изображений (необязательный)

    Структура изображения:

    • photo_type - тип изображения (обязательный). Возможные значения:
      • default — фотография по умолчанию (вид спереди)
      • facing — crop-фотография для планограмм (обрезанная по контуру товара)
      • 7 — фотография товара слева
      • 19 — фотография товара справа
      • 13 — фотография товара сзади
      • si1 — фотография товара сверху
      • si2 — фотография товара снизу
      • si3 — фотография товара в упаковке
      • si4 — фотография товара без упаковки
      • si5 — фотография товара внутри упаковки
      • 3ds — 3D серия
      • marketing — коммерческая фотография товара
      • text — фотография текста на товаре
      • ecommerce — e-commerce фото
      • undef — single shot, фотография товара с не предопределенного ракурса
      • cubi — (опционально) фотография измерения ВГХ
    • photo_url - url, либо массив url при типе 3ds (обязательный). Ссылки на фотографии с редиректом не поддерживаются
    • location_id - Id места проведения съемки (необязательный).
    • identifier - значение gtin/sku/ltin/barcode (необязательный). Используется для связи фотографий с идентификаторами товара
    • identifier_type - тип идентификатора (обязательный, если передан identifier). Возможные значения:
      • gtin
      • sku
      • ltin
      • barcode
    • identifier_party_id - идентификатор торговой сети (необязательный при типе gtin; обязательный при других типах).

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

JSON

Content-type: application/json; charset=utf-8
Content-length: 434
[
  {
    "@id": "12",
    "gtin": "4600000000015",
    "good_name": "Шоколад с Цельным Миндалём 55% 90г 14шт шоу-бокс",
    "identified_by": [
      {
        "value": "4607065373085",
        "type": "gtin",
        "multiplier": 1,
        "level": "trade-unit",
        "unit":"кг"
      },
      {

        "value": "4600000000015",
        "type": "sku",
        "multiplier": 1,
        "level": "trade-unit",
        "party_id": 1
      }
    ],
    "categories": [
      {
        "cat_id": 203069
      }
    ],
    "good_images": [
      {
        "photo_type": "default",
        "photo_url": "https://your-site-name.com/photo.jpg",
        "location_id": 12,
        "identifier": "4600000000015",
        "identifier_type": "sku",
        "identifier_party_id": 2
      },
      {
        "photo_type": "3ds",
        "photo_url": [
          "https://your-site-name.com/photo-1.jpg",
          "https://your-site-name.com/photo-2.jpg"
        ]
      }
    ],
    "good_attrs": [
      {
        "attr_id": 2630,
        "attr_value": "RU",
        "gtin":"4607065373089"
      },
      {
        "attr_id": 2501,
        "attr_value": "ДА",
        "attr_value_type": "кг"
      }
    ]
  }
]

XML

Content-type: application/xml; charset=utf-8
Content-length: 511
<?xml version="1.0" encoding="UTF-8"?>
<entries>
  <entry id="12">
    <gtin>4600000000015</gtin>
    <good_name>Йогурт легкий. Злаки + чернослив</good_name>
    <identified_by>
      <item>
        <value>4607065373085</value>
        <type>gtin</type>
        <multiplier>1</multiplier>
        <level>trade-unit</level>
        <unit>кг</unit>
      </item>
      <item>
        <value>4600000000015</value>
        <type>sku</type>
        <multiplier>1</multiplier>
        <level>trade-unit</level>
        <party_id>1</party_id>
      </item>
    </identified_by>
    <categories>
        <item>
          <cat_id>203069</cat_id>
        </item>
    </categories>
    <good_images>
        <item>
          <photo_type>default</photo_type>
          <photo_url>https://your-site-name.com/photo.jpg</photo_url>
          <location_id>12</location_id>
          <identifier>4600000000015</identifier>
          <identifier_type>sku</identifier_type>
          <identifier_party_id>2</identifier_party_id>
        </item>
        <item>
          <photo_type>3ds</photo_type>
          <photo_url>
            <item>https://your-site-name.com/photo.jpg</item>
            <item>https://your-site-name.com/photo.jpg</item>
          </photo_url>
        </item>
    </good_images>
    <good_attrs>
        <item>
          <attr_id>2630</attr_id>
          <attr_value>RU</attr_value>
          <gtin>490122000021</gtin>
        </item>
        <item>
          <attr_id>2501</attr_id>
          <attr_value>RU</attr_value>
          <attr_value_type>кг</attr_value_type>
        </item>
    </good_attrs>
  </entry>
</entries>

Обновление существующего товара

JSON

Content-type: application/json; charset=utf-8
Content-length: 434
[
  {
    "@id": "13",
    "good_id": 1939447,
    "gtin": "4600000000015",
    "categories": [
      {
        "cat_id": 203069,
        "delete": 1
      },
      {
        "cat_id": 185002
      }
    ],
    "identified_by": [
      {
        "value": "4607065373092",
        "type": "gtin",
        "multiplier": 1,
        "level": "trade-unit"
      }
    ],
    "good_attrs": [
      {
       "attr_id": 5,
       "attr_value": "46%"
      },
      {
       "attr_id": 4540,
       "attr_value": "ДА",
       "attr_value_id": 12742580
      },
      {
       "attr_id": 4424,
       "attr_value_id": 12183715,
       "delete": 1
      }
    ]
  }
]

XML

Content-type: application/xml; charset=utf-8
Content-length: 511
<?xml version="1.0" encoding="UTF-8"?>
<entries>
  <entry id="13">
    <good_id>1939447</good_id>
    <gtin>4600000000015</gtin>
    <categories>
        <item>
          <cat_id>203069</cat_id>
          <delete>1</delete>
        </item>
        <item>
          <cat_id>203069</cat_id>
        </item>
    </categories>
    <identified_by>
      <item>
        <value>4607065373092</value>
        <type>gtin</type>
        <multiplier>1</multiplier>
        <level>trade-unit</level>
      </item>
    </identified_by>
    <good_images>
        <item>
          <photo_type>default</photo_type>
          <photo_url>https://your-site-name.com/photo.jpg</photo_url>
        </item>
    </good_images>
    <good_attrs>
        <item>
          <attr_id>5</attr_id>
          <attr_value>46%</attr_value>
        </item>
        <item>
          <attr_id>4540</attr_id>
          <attr_value>ДА</attr_value>
          <attr_value_id>12742580</attr_value_id>
        </item>
        <item>
          <attr_id>4424</attr_id>
          <attr_value_id>12183715</attr_value_id>
          <delete>1</delete>
        </item>
    </good_attrs>
  </entry>
</entries>

Ответ

  • feed_id — идентификатор фида

JSON

Content-type: application/json; charset=utf-8
API-Feed-Limit: 2/10
API-Usage-Limit: 1/500
Status Code: 200
{
    "apiversion":3,
    "result": {
        "feed_id": 2131
    }
}

XML

Content-type: application/xml; charset=utf-8
API-Feed-Limit: 2/10
API-Usage-Limit: 1/500
Status Code: 200
<?xml version="1.0" encoding="UTF-8"?>
<root>
    <apiversion>3</apiversion>
    <result>
        <feed_id>2131</feed_id>
    </result>
</root>

Метод feed-status

Дает возможность проверить стасус ранее отправленого фида. Результат возможно получить если только лаборатория создала этот фид и если только от имени того же заказчика.

Пример запроса

https://апи.национальный-каталог.рф/v3/feed-status?apikey=XXX&supplier_key=YYY&feed_id=7126

Параметры запроса

  • supplier_key — apikey заказчика (обязательное)
  • feed_id — идентификатор фида (обязательное)

Ответ

  • feed_id — идентификатор фида;
  • status — статус фида, возможные варианты:
    • Rejected — запрос не принят;
    • Received — запрос получен, данные на модерации;
    • Moderated — товары прошли модерацию;
    • Signed — одобренные модератором товары подписаны;
  • received_at — время создания фида;
  • status_updated_at — время перехода фида в текущий статус;
  • result — ошибки обнаруженные при валидации контента. Ключами являются порядковые номера товаров в переданной информации;
  • totalErrors — общее количество ошибок;
  • commonError — общая ошибка при разборе информации, если она произошла.

Пример успешно разобранной информации

JSON

Content-type: application/json; charset=utf-8
API-Usage-Limit: 1/500
Status Code: 200
{
    "apiversion":3,
    "result": {
        "feed_id": 7126,
        "status": "Received",
        "received_at":"2018-08-13T17:03:40Z",
        "status_updated_at":"2018-08-14T12:03:40Z"
    }
}

XML

Content-type: application/xml; charset=utf-8
API-Usage-Limit: 1/500
Status Code: 200
<?xml version="1.0" encoding="UTF-8"?>
<root>
    <apiversion>3</apiversion>
    <result>
        <feed_id>7126</feed_id>
        <status>Received</status>
        <received_at>2018-08-13T17:03:40Z</received_at>
        <status_updated_at>2018-08-14T12:03:40Z</status_updated_at>
    </result>
</root>

Пример отклоненной информации

JSON

Content-type: application/json; charset=utf-8
API-Usage-Limit: 1/500
Status Code: 200
{
    "apiversion":3,
    "result": {
        "feed_id": 7126,
        "status": "Rejected",
        "received_at": "2018-12-06T13:03:20Z",
        "status_updated_at": "2018-12-06T13:03:30Z",
        "result": {
          "0": [
            "GTIN 4600002576143 используется другим товаром"
          ],
          "totalErrors": "1",
          "commonError": ""
        }
    }
}

XML

Content-type: application/xml; charset=utf-8
API-Usage-Limit: 1/500
Status Code: 200
<?xml version="1.0" encoding="UTF-8"?>
<root>
    <apiversion>3</apiversion>
    <result>
        <feed_id>7126</feed_id>
        <status>Rejected</status>
        <received_at>2018-08-13T17:03:40Z</received_at>
        <status_updated_at>2018-08-14T12:03:40Z</status_updated_at>
        <result>
            <item>GTIN 4600002576075 используется другим товаром</item>
            <item>Атрибут #44 недоступен для редактирования</item>
        </result>
        <totalErrors>2</totalErrors>
        <commonError/>
    </result>
</root>