API для мониторинга цен на маркетплейсах и интернет-магазинах

Существует возможность взаимодействия с сервисом через HTTP API, это открывает множество возможностей по автоматизации работы, агрегации результатов отчётов. Если у вас возникнут вопросы по документации, напишите нам в чат или по email.

Содержание

Базовая информация

Авторизация

По ключу.

Для передачи ключа в запросе нужно использовать HTTP заголовок Api-Key.

Важно: не сообщайте ключ API третьим лицам, если не хотите дать им доступ к вашему аккаунту.

Формат

JSON. В запросе должен присутствовать заголовок Content-Type со значением application/json.

HTTP методы

В данный момент — GET и POST. GET — для получения информации, POST — для создания сущностей.

Обработка ошибок

В случае, если запрос не был обработан корректно, возвращается ответ вида

{
  "code": "ERROR_CODE",
  "message": "Error message"
}

Например:

{
  "code": 404,
  "message": "Price #1 not found."
}

Код ошибки повторяется в HTTP коде ответа.

Формат ответа

Все успешные ответы имеют следующую структуру:

{
  "response": [
    //...
  ]
}

Примеры:

{
  "response": [
    {
      "id": 222
    }
  ]
}


{
  "response": [
    {
      "success": true
    }
  ]
}

Структура урлов

https://cp2.marketparser.ru/api/v2/ENDPOINT/SLUG.json?param=value

Endpoints

Кампании

Список кампаний

метод: GET

URL: https://cp2.marketparser.ru/api/v2/campaigns.json

Пример ответа:

{
  "response": {
    "total": 3,
    "campaigns": [
      {
        "id": 557,
        "name": "Ноутбуки",
        "createdAt": "2015-10-28T16:38:00+03:00",
        "readyToCreateReports": true
      },
      {
        "id": 556,
        "name": "Мобильные телефоны",
        "createdAt": "2015-10-28T16:38:00+03:00",
        "readyToCreateReports": false
      },
      {
        "id": 555,
        "name": "Весь магазин",
        "createdAt": "2015-10-28T16:38:00+03:00",
        "readyToCreateReports": true
      }
    ]
  }
}

Выводится до 25 кампаний в ответе, которые не были удалены пользователем (так же возвращает кампании с вкладки «Архив кампаний»).
Возможен постраничный вывод при указании query parameter page, url принимает вид https://cp2.marketparser.ru/api/v2/campaigns.json?page=2

Поле total показывает полное число кампаний.

Поле readyToCreateReports показывает, можно ли по данной кампании создать отчёт. Для того, чтобы можно было создать отчёт по кампании, она должна быть настроена, а также её прайс должен быть успешно обработан.

Создание и настройка кампаний

Для большинства сценариев использования API нет необходимости в создании или изменении настроек кампании. Всегда есть возможность настроить кампанию через веб-интерфейс. Сделать это нужно всего один раз.

Поэтому в данный момент в API нет способа создать кампанию или изменить её настройки.

Единственная настройка кампании, которую иногда необходимо менять в автоматическом режиме — это регион(ы) мониторинга.

И у нас есть возможность указать регион мониторинга при обновлении прайс-листа. Более того, этот вариант настройки более гибкий, чем обычное указание региона мониторинга в кампании. Он позволяет в одном отчёте получать данные по разным товарам из разных регионов (100 товаров по Москве, 200 других товаров по СПб и так далее).

В случае использования обычных настроек — пришлось бы использовать несколько кампаний, или несколько раз менять настройки кампании и обновлять прайс-лист.

Если вам интересна эта функция — обратитесь в тех. поддержку для её активации и получения деталей.

Прайс кампании

Обновление прайса кампании

метод: POST

URL: https://cp2.marketparser.ru/api/v2/campaigns/CAMPAIGN_ID/price.json

Пример тела запроса:

{
  "products": [
    {
      "name": "product-1",
      "cost": 500,
      "id": "our-shop-identifier-1",
      "yandex_model_id": 111111,
      "custom": {
        "custom-field-1": "custom-value-1",
        "custom-field-2": "custom-value-2"
      }
    },
    {
      "name": "product-2",
      "cost": 800,
      "id": "our-shop-identifier-2",
      "yandex_model_id": 22222,
      "custom": {
        "custom-field-1": "custom-value-1",
        "custom-field-2": "custom-value-2"
      }
    }
  ]
}

Поле products — обязательное. Массив products не должен быть пустым. Все элементы массива products должны иметь одинаковую структуру.

Замечание: при использовании Триального прайс-листа существует ограничение на размер прайс-листа — 200 позиций. При попытке загрузки прайс-листа большего размера прайс получит статус PARSED_BUT_TRIAL_PRICE_SIZE_LIMIT_EXCEEDED и не будет успешно обработан. На других тарифных планах такого ограничения нет.

Элементы массива products должны иметь поле name.

Значения, которых нет в базовом наборе полей, но которые необходимо получить в результате парсинга (привязанные к тем же продуктам) могут быть перечислены в поле custom. Иногда бывает полезно передать некую дополнительную информацию о позиции (например, цена со скидкой, название категории, ссылка на товар в вашем магазине, и т.д.), чтобы в дальнейшем вся нужная информация была доступна в отчёте.

Данные прайса должны быть переданы в теле POST запроса.

Ответом на успешный запрос создания прайса будет следующее:

{
  "response": {
    "success": true
  }
}

В случае ошибок, будет передан текст и код ошибки, например:

{
  "code": 400,
  "message": "Price field \"products\" of type array required"
}

Пример кода для обновления прайса кампании на языке PHP:

<?php
$apiKey = 'PUT-YOUR-API-KEY-HERE';
$campaignId = 555; //replace with your actual campaign ID
$url = sprintf('https://cp.marketparser.ru/api/v2/campaigns/%s/price.json', $campaignId);
$products = [    
    [
        "name" => "apple iphone 6s plus 16 gb", //REQUIRED field        
        "cost" => 60000, //optional field        
        "id" => "our-shop-identifier-1", //optional field     
        "yandex_model_id" => 12858631, //optional field
        "custom" => [ //optional field            
            "custom-field-1" => "custom-value-1",            
            "custom-field-2" => "custom-value-2",  
         ],  
     ],    
    [        
        "name" => "Siemens WS 10G160", //REQUIRED field        
        "cost" => 25000, //optional field        
        "id" => "our-shop-identifier-2", //optional field
        "yandex_model_id" => 8444167, //optional field        
        "custom" => [ //optional field            
            "custom-field-1" => "custom-value-1",            
            "custom-field-2" => "custom-value-2",        
        ],    
    ],
];
$priceData = [    
    'products' => $products,
];
$curlHandle = curl_init($url);
curl_setopt_array($curlHandle, [    
    CURLOPT_RETURNTRANSFER => true,    
    CURLOPT_POST => true,    
    CURLOPT_HTTPHEADER => [        
        'Api-Key: ' . $apiKey,        
        'Content-Type: application/json',    
    ],    
    CURLOPT_POSTFIELDS => json_encode($priceData),    
    CURLOPT_SSL_VERIFYPEER => true,    
    CURLOPT_SSL_VERIFYHOST => 2,    
//you can download cacert.pem here: https://curl.haxx.se/ca/cacert.pem    CURLOPT_CAINFO => '/path/to/cacert.pem',]);
$response = curl_exec($curlHandle);
$curlError = curl_error($curlHandle);
curl_close($curlHandle);
if ($response === false) {   
 //curl error occured, check $curlError for details} 
    else {    
        $parsedResponse = json_decode($response, true);    
        if (isset($parsedResponse['response']['success']) && $parsedResponse['response']['success'] === true) {       
         //price was updated successfully    } else {        //an error occured, check $parsedResponse['message']    }}

Получение информации о прайсе кампании

После создания прайс не будет сразу же готов к использованию. Он должен быть обработан сервисом. Получение информации о прайсе:

метод: GET

URL: https://cp2.marketparser.ru/api/v2/campaigns/CAMPAIGN_ID/price.json

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

{
    "response": {
        "id": 333,
        "createdAt": "2015-10-28T16:38:00+03:00",
        "status": "PROCESSED",
        "countNotEmptyRows": 2,
        "countFoundDuplicatedRows": 0,
        "isSuccessfullyProcessed": true
    }
}

Исходя из значения поля isSuccessfullyProcessed можно определить, можно ли создавать отчёты по кампании.

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

ERROR
PARSED
READY_TO_BE_PARSED
SEARCH_IN_PROGRESS
PROCESSED
NOT_ENOUGH_BALANCE_TO_PROCESS
PARSED_BUT_TRIAL_PRICE_SIZE_LIMIT_EXCEEDED

Отчёты кампании

Создание отчёта по кампании

method: POST

url: https://cp2.marketparser.ru/api/v2/campaigns/CAMPAIGN_ID/reports.json

В ответе будет отдан ID созданного отчёта, например:

{
  "response": {
    "id": 123
  }
}

Прайс кампании, указанной в ссылке создания отчёта, должен быть обработан (поле isSuccessfullyProcessed в информации о прайсе должно быть установлено в true). Если это не так — будет возвращена ошибка:

{
  "code": 400,
  "message": "Campaign price is not processed yet.."
}

Получение информации об отчёте

method: GET

url: https://cp2.marketparser.ru/api/v2/campaigns/CAMPAIGN_ID/reports/REPORT_ID.json

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

{
    "response": {
        "id": 500,
        "status": "WAITING",
        "createdAt": "2015-10-30T11:12:52+03:00",
        "isSuccessfullyFinished": false
    }
}

{
  "response": {
    "id": 32,
    "status": "OK",
    "createdAt": "2015-10-28T16:38:00+03:00",
    "isSuccessfullyFinished": true,
    "startedAt": "2015-10-28T16:38:00+03:00",
    "finishedAt": "2015-10-28T16:38:00+03:00",
    "countErrorProducts": 0,
    "countOkProducts": 3
  }
}

Когда поле isSuccessfullyFinished принимает значение true, результаты обработки отчёта можно забирать.

Дополнительная информация о прогрессе обработки отчёта доступна в поле status. Поле status может принимать значения:

WAITING
WAITING_FOR_REDOWNLOAD_ERRORS
IN_PROGRESS
OK
ERROR

Получение результатов парсинга отчёта

method: GET

URL: https://cp2.marketparser.ru/api/v2/campaigns/CAMPAIGN_ID/reports/REPORT_ID/results.json

По-умолчанию выводится до 25 результатов (товаров отчёта) в ответе. Это число можно изменить используюя query parameter per_page, максимальное его значение — 100. При его использовании url принимает вид https://cp2.marketparser.ru/api/v2/campaigns/CAMPAIGN_ID/reports/REPORT_ID/results.json?per_page=100

Возможен постраничный вывод при указании query parameter page, url принимает вид https://cp2.marketparser.ru/api/v2/campaigns/CAMPAIGN_ID/reports/REPORT_ID/results.json?page=2

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

{
  "response": {
    "total": 2,
    "products": [
      {
        "name": "product1",
        "yandexModelId": 5555555,
        "yandexRegionId": 213,
        "yandexRegionName": "Москва",
        "linkToOffers": "https://market.yandex.ru/product/5555555/offers?lr=35&deliveryincluded=0&cpa=&how=aprice",
        "ourId": "1",
        "ourCost": 6611,
        "medianPrice": 1880,
        "maxPrice": 2100,
        "minPrice": 1660,
        "averagePrice": 1880,
        "countOffers": 2,
        "ourShopPosition": 1,
        "offers": [
          {
            "shopName": "Ситилинк",
            "price": 2100,
            "deliveryPrice": 290,
            "inStock": true,
            "pickup": true,
            "producerWarranty": false,
            "linkToOffer": "https://market.yandex.ru/search.xml?lr=213&fesh=111111&cvredirect=0&text=product1"
          },
          {
            "shopName": "Cenam.NET",
            "price": 1660,
            "deliveryPrice": null,
            "inStock": false,
            "pickup": false,
            "producerWarranty": false,
            "linkToOffer": "https://market.yandex.ru/search.xml?lr=213&fesh=222222&cvredirect=0&text=product1"
          }
        ],
        "custom": {
          "employer_id": 111,
          "yandex_region_id": 1
        },
         "searchResult": "NO_MODELS"
      },
      {
        "name": "product2",
        "yandexModelId": null,
        "yandexRegionId": 213,
        "yandexRegionName": "Москва",
        "linkToOffers": "https://market.yandex.ru/search.xml?lr=35&deliveryincluded=0&cpa=&how=aprice&cvredirect=0&onstock=0&text=product2",
        "ourId": "2",
        "ourCost": 6622,
        "medianPrice": 1880,
        "maxPrice": 2100,
        "minPrice": 1660,
        "averagePrice": 1880,
        "countOffers": 2,
        "ourShopPosition": 1,
        "offers": [
          {
            "shopName": "Ситилинк",
            "price": 2100,
            "deliveryPrice": 290,
            "inStock": true,
            "pickup": true,
            "producerWarranty": false,
            "linkToOffer": "https://market.yandex.ru/search.xml?lr=213&fesh=11111&cvredirect=0&text=product2"
          },
          {
            "shopName": "Cenam.NET",
            "price": 1660,
            "deliveryPrice": null,
            "inStock": false,
            "pickup": false,
            "producerWarranty": true,
            "linkToOffer": "https://market.yandex.ru/search.xml?lr=213&fesh=22222&cvredirect=0&text=product2"
          }
        ],
        "custom": {
          "employer_id": 222,
          "yandex_region_id": 2
        },
        "searchResult": "NO_MODELS"
      }
    ]
  }
}

{
  "response": {
    "total": 26,
    "products": [
      {
        "name": "product26",
        "yandexModelId": null,
        "yandexRegionId": 213,
        "yandexRegionName": "Москва",
        "linkToOffers": "https://market.yandex.ru/search.xml?lr=213&deliveryincluded=0&cpa=&how=aprice&cvredirect=0&onstock=0&text=product26",
        "ourId": "26",
        "ourCost": null,
        "medianPrice": 1880,
        "maxPrice": 2100,
        "minPrice": 1660,
        "averagePrice": 1880,
        "countOffers": 2,
        "ourShopPosition": null,
        "offers": [
          {
            "shopName": "Ситилинк",
            "price": 2100,
            "deliveryPrice": 290,
            "inStock": true,
            "pickup": true,
            "producerWarranty": false,
            "linkToOffer": "https://market.yandex.ru/search.xml?lr=213&fesh=111111&cvredirect=0&text=product26"
          },
          {
            "shopName": "Cenam.NET",
            "price": 1660,
            "deliveryPrice": null,
            "inStock": false,
            "pickup": false,
            "producerWarranty": true,
            "linkToOffer": "https://market.yandex.ru/search.xml?lr=213&fesh=222222&cvredirect=0&text=product26"
          }
        ],
        "custom": {},
        "searchResult": "NO_MODELS"
      }
    ]
  }
}

Поле total показывает полное число товаров в отчёте.

Элементы offers массива products содержат поле custom, в которое подставляются те кастомные поля, которые были переданы при создании прайса.

В поле yandexModelId указывается ID модели на яндекс маркете, данные по которой были получены. Если соответствующей карточки нет, поле будет иметь значение null.

В полях yandexRegionId и yandexRegionName указываются соответственно ID и название региона на яндекс маркете (отчёт может быть создан по нескольким регионам, эти поля необходимы для того, чтобы понять, к какому региону относятся данные).

Поле searchResult (результат поиска товар) может иметь 3 возможных значения:

NO_MODELS — моделей при поиске товара по названию не найдено
MANY_MODELS — найдено несколько моделей при поиске товара по названию
ONE_MODEL — найдена одна модель при поиске товара по названию

Получение списка отчётов кампании

method: GET

URL: https://cp2.marketparser.ru/api/v2/campaigns/CAMPAIGN_ID/reports.json

Выводится до 25 результатов в ответе. Возможен постраничный вывод при указании query parameter page, url принимает вид https://cp2.marketparser.ru/api/v2/campaigns/CAMPAIGN_ID/reports.json?page=2

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

{
  "response": {
    "total": 27,
    "reports": [
      {
        "id": 26,
        "status": "OK",
        "createdAt": "2015-10-28T16:38:00+03:00",
        "isSuccessfullyFinished": true,
        "startedAt": "2015-10-28T16:38:00+03:00",
        "finishedAt": "2015-10-28T16:40:00+03:00",
        "countErrorProducts": 0,
        "countOkProducts": 1
      },
      {
        "id": 27,
        "status": "OK",
        "createdAt": "2015-10-29T16:38:00+03:00",
        "isSuccessfullyFinished": true,
        "startedAt": "2015-10-29T16:38:00+03:00",
        "finishedAt": "2015-10-29T16:40:00+03:00",
        "countErrorProducts": 0,
        "countOkProducts": 5
      }
    ]
  }
}

Поле total показывает полное число отчётов.

Структура элементов массива reports такая же, как при получении информации об отчёте по его ID.

Информация о пользователе

Баланс

method: GET

URL: https://cp2.marketparser.ru/api/v2/me/balance.json

Устаревший endpoint, используйте Информация о подписке на план вместо него.

Получение текущего баланса пользователя.

Пример ответа:

{
  "response": {
    "balance": 200000
  }
}

Информация о подписке на план

method: GET

URL: https://cp2.marketparser.ru/api/v2/me/plan.json

Получение плана на который активирована подписка, остаток единиц и даты окончания подписки.

Пример ответа:

{
  "response": {
    "planName": "ПРО 200 000",
    "remainingUnits": 13520,
    "planExpiresAt": "2017-05-20"
  }
}

В случае если активной подписки нет — будет возвращён следующий ответ:

{
  "response": {
    "planName": null,
    "remainingUnits": 0,
    "planExpiresAt": null
  }
}

API для работы с сервисом мониторинга цен

Содержание

Базовая информация

Авторизация

Формат

HTTP методы

Обработка ошибок

Формат ответа

Структура урлов

Endpoints

Кампании

Список кампаний

Создание и настройка кампаний

Прайс кампании

Обновление прайса кампании

Получение информации о прайсе кампании

Отчёты кампании

Создание отчёта по кампании

Получение информации об отчёте

Получение результатов парсинга отчёта

Получение списка отчётов кампании

Информация о пользователе

Баланс

Информация о подписке на план