Описание API

Сервис «Мониторинг цен» предоставляет возможность выполнения мониторинга цен при помощи API.
Методы API позволяют регистрироваться в сервисе, добавлять товары для мониторинга, получать актуальные цены товаров с торговых площадок.
Вызовы методов API состоят из отправки HTTP-запроса и получения ответа.
При помощи API методов сервиса сторонние разработчики могут разработать свое решение для Мониторинга цен.

Общие правила

1. Форматом передачи данных является json.
2. Вызов методов API осуществляется вызовами HTTP-запросов на адрес https://api.owwa.ru/fl_0007/hs/api.
3. Для тестирования работы методов рекомендуется завести новую учетную запись в сервисе или использовать тестовую учетную запись с идентификатором клиента 149ec854b8c24a96b60e97bb977d3fb2.

Методы API

• Метод /v1/ping

• Метод /v1/registration/start

• Метод /v1/registration/finish

• Метод /v1/subscriptions/activate

• Метод /v1/items/add

• Метод /v1/items/list

• Метод /v1/archive/add

• Метод /v1/archive/del

Метод /v1/ping

Позволяет определить работоспособность – доступен ли в данный момент сервис для вызовов API.

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

Отсутствуют

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

GET /v1/ping

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

Строка "PONG " + текущая дата.

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

PONG 10.11.2023 12:20:43

Метод /v1/registration/start

Начало регистрации клиента в сервисе. Отправляет код подтверждения на указанную электронную почту.

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

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

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

POST /v1/registration/start

{
   "email": "email@domain"
}

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

Параметр	Описание
ok	Признак успешного выполнения метода. Тип: булево.
error	Описание ошибки, которая возникла в процессе выполнения метода. Тип: строка.

Пример ответа успешного выполнения метода:

{
    "ok": true
}

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

{
    "ok": false,
    "error": "Произошла ошибка при работе с SMTP. Код ошибки: 25 (Отказ в установлении соединения со стороны сервера)."}

Метод /v1/registration/finish

Завершение регистрации клиента в сервисе. Отправляет полученный код подтверждения на проверку.

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

Параметр	Описание
email	Адрес электронной почты, на которую был отправлен код подтверждения для регистрации в сервисе. Обязательный параметр. Тип: строка.
code	Код подтверждения, полученный на указанную почту. Обязательный параметр. Тип: строка.
curr_version	Текущая версия модуля у клиента, используемая при регистрации. Обязательный параметр. Тип: строка.
partner_id	Идентификатор партнера, при помощи которого выполняется регистрация клиента в сервисе. Необязательный параметр. Тип: строка.

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

POST /v1/registration/finish

{
    "email": "email@domain",
    "code": "6743",
    "curr_version": "PG0000008"
}

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

Параметр	Описание
ok	Признак успешного выполнения метода. Тип: булево.
id	Уникальный идентификатор, который присвоен клиенту при регистрации в сервисе. Тип: строка.
error	Описание ошибки, которая возникла в процессе выполнения метода. Тип: строка.

Пример ответа успешного выполнения метода:

{
    "ok": true,
    "id": "eeab2370de9e4911a0e3b33083b9f75a"
}

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

{
    "ok": false,
    "error": "Указанный код подтверждения не совпадает с тем, который был отправлен на электронную почту"
}

Метод /v1/subscriptions/activate

Активация подписки на использование сервиса «Мониторинг цен». Указывается пин-код, полученный при покупке подписки.

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

Параметр	Описание
id	Уникальный идентификатор, который присвоен клиенту при регистрации в сервисе. Обязательный параметр. Тип: строка.
pin	Пин-код подписки, полученный при покупке. Обязательный параметр. Тип: строка.

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

POST /v1/subscriptions/activate

{
    "id": "cf7d2d5111e546d98bf1b93a0836d02e",
    "pin": "a0851b85400a4c5694a131526bc6ad50"
}

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

Параметр	Описание
ok	Признак успешного выполнения метода. Тип: булево.
error	Описание ошибки, которая возникла в процессе выполнения метода. Тип: строка.
Тариф	Информационное поле: название тарифа подписки. Тип: строка.
ДатаНач	Информационное поле: дата начала действия подписки (совпадает с датой активации подписки). Тип: дата.
ДатаКон	Информационное поле: дата окончания действия подписки. Тип: дата.
КоличествоДней	Информационное поле: количество дней действия подписки. Тип: число.
КоличествоТоваров	Информационное поле: максимальное количество товаров, доступное для мониторинга по данной подписке. Тип: число.

Пример ответа успешного выполнения метода:

{
    "ok": true,
    "Тариф": "Оптимальный",
    "ДатаНач": "2023-10-31T00:00:00",
    "ДатаКон": "2023-11-30T00:00:00",
    "КоличествоДней": 31,
    "КоличествоТоваров": 200
}

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

{
    "ok": false,
    "error": "Подписка с указанным пин-кодом уже активирована"
}

Метод /v1/items/add

Добавление товаров для мониторинга.

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

Параметр	Описание
id	Уникальный идентификатор, который присвоен клиенту при регистрации в сервисе. Обязательный параметр. Тип: строка.
items	Массив URL товаров для мониторинга. Обязательный параметр. Тип: массив.
> URL	Адрес страницы товара. Обязательный параметр. Тип: строка.

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

POST /v1/items/add

{
    "id": "149ec854b8c24a96b60e97bb977d3fb2",
    "items": [
        {
            "URL": "https://www.ozon.ru/product/sumka-na-plecho-325735324"
        },
        {
            "URL": "https://www.ozon.ru/product/886273934"
        }
    ]
}

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

Параметр	Описание
ok	Признак успешного выполнения метода. Тип: булево.
error	Описание ошибки, которая возникла в процессе выполнения метода. Тип: строка.
items	Массив результатов добавления товаров для мониторинга. Тип: массив.
> URL	Адрес страницы товара (тот же самый, который был указан в методе). Тип: строка.
> id	Уникальный идентификатор товара, который присвоен сервисом при добавлении товара. Тип: строка.
> ok	Признак успешного добавления товара. Тип: булево.
> Описание	Текстовое описание добавления товара – в случае ошибки, содержит описание ошибки. Тип: строка.

Пример ответа успешного выполнения метода:

{
    "ok": true,
    "items": [
        {
            "URL": "https://www.ozon.ru/product/sumka-na-plecho-325735324",
            "id": "93bd78242c6c11ee8764b4b686880d33",
            "ok": true,
            "Описание": "Выполнено" 
        },
        {
            "URL": "https://www.ozon.ru/product/886273934",
            "id": "962180952c6d11ee8764b4b686880d33",
            "ok": true,
            "Описание": "Выполнено" 
        }
    ]
}

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

{
    "ok": false,
    "error": "Добавить товары невозможно: нет действующей подписки"
}

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

{
    "ok": false,
    "error": "Детальное описание ошибки указано в поле items",
    "items": [
        {
            "URL": "https://unsupported_url.com",
            "id": "93bd78242c6c11ee8764b4b686880d33",
            "ok": false,
            "Описание": "Не удалось определить торговую площадку для указанного URL"
        },
        {
            "URL": "https://www.ozon.ru/product/886273934",
            "id": "962180952c6d11ee8764b4b686880d33",
            "ok": true,
            "Описание": "Выполнено" 
        }
    ]
}

Метод /v1/items/list

Получение актуальных цен товаров, указанных для мониторинга. Максимальное количество товаров, которое возвращает метод – 1000. Если у клиента добавлено большее количество – необходимо повторно вызвать метод с параметром next (см. описание далее).

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

Параметр	Описание
id	Уникальный идентификатор, который присвоен клиенту при регистрации в сервисе. Обязательный параметр. Тип: строка.
next	Уникальный идентификатор, который был указан в предыдущем вызове метода. Используется для «пагинации» результатов. При первом вызове метода параметр указывать не нужно. Необязательный параметр. Тип: строка.

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

POST /v1/items/list

{
    "id": "149ec854b8c24a96b60e97bb977d3fb2",
    "next": "93bd78242c6c11ee8764b4b686880d37"
}

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

Параметр	Описание
ok	Признак успешного выполнения метода. Тип: булево.
error	Описание ошибки, которая возникла в процессе выполнения метода. Тип: строка.
items	Массив цен на товары, которые были добавлены для мониторинга. Тип: массив.
> id	Уникальный идентификатор товара, который присвоен сервисом при добавлении товара. Тип: строка.
> Наименование	Наименование товара, которое указано на странице товара. Тип: строка.
> Цена	Цена товара, указанная на его странице. Тип: число.
> Дата	Дата получения цены со страницы. Тип: дата.
> Статус	Статус получения цены товара. Тип: строка.
> Описание	Текстовое описание статуса, пояснение для клиента (см. пример). Тип: строка.
next	Идентификатор, который нужно указать при повторном вызове метода, чтобы получить следующую порцию цен на товары. Присутствует в ответе, если вызов метода вернул не все товары клиента (если их больше 1000). Тип: строка.

Пример ответа выполнения метода:

{
    "ok": true,
    "items": [
        {
            "id": "93bd78242c6c11ee8764b4b686880d33",
            "Наименование": "GPS трекер для автомобилей, грузов, посылок, RIXET TK-904",
            "Цена": 0,
            "Дата": "2023-10-27T00:00:00",
            "Статус": "Обрабатывается",
            "Описание": ""
        },
        {
            "id": "93bd78242c6c11ee8764b4b686880d34",
            "Наименование": "GPS трекер для автомобилей, грузов, посылок, RIXET TK-905",
            "Цена": 0,
            "Дата": "2023-10-27T00:00:00",
            "Статус": "Нет в наличии",
            "Описание": "Товара нет в наличии на сайте"
        }
        {
            "id": "93bd78242c6c11ee8764b4b686880d35",
            "Наименование": "GPS трекер для автомобилей, грузов, посылок, RIXET TK-906",
            "Цена": 0,
            "Дата": "2023-10-27T00:00:00",
            "Статус": "Ошибка",
            "Описание": "Ошибка. Страница товара не найдена"
        },
        {
            "id": "93bd78242c6c11ee8764b4b686880d36",
            "Наименование": "Прибор ночного видения с записью - NV-3180",
            "Цена": 8032,
            "Дата": "2023-10-27T00:00:00",
            "Статус": "",
            "Описание": ""
        },
        {
            "id": "93bd78242c6c11ee8764b4b686880d37",
            "Наименование": "Интерактивная игрушка Руль Vtech, 80-536626",
            "Цена": 0,
            "Дата": "2023-10-31T00:00:00",
            "Статус": "Ошибка",
            "Описание": "Ошибка. Превышено максимальное количество товаров для мониторинга по вашему тарифу"
        },
    ],
    "next": "93bd78242c6c11ee8764b4b686880d37"
}

Метод /v1/archive/add

Помещение товаров в «архив». Товары, которые добавлены в архив, не участвуют в ежедневном мониторинге цен.

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

Параметр	Описание
id	Уникальный идентификатор, который присвоен клиенту при регистрации в сервисе. Обязательный параметр. Тип: строка.
items	Массив товаров, которые помещаются в архив. Обязательный параметр. Тип: массив.
> id	Уникальный идентификатор товара, который присвоен сервисом при добавлении товара. Тип: строка.

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

POST /v1/archive/add

{
    "id": "149ec854b8c24a96b60e97bb977d3fb2",
    "items": [
        {
            "id": "9427288c2e5511ee8764b4b686880d33"
        }
    ]
}

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

Параметр	Описание
ok	Признак успешного выполнения метода. Тип: булево.
error	Описание ошибки, которая возникла в процессе выполнения метода. Тип: строка.

Пример ответа успешного выполнения метода:

{
    "ok": true
}

Метод /v1/archive/del

Извлечение товаров из «архива». Метод обратный для /v1/archive/add.

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

Параметр	Описание
id	Уникальный идентификатор, который присвоен клиенту при регистрации в сервисе. Обязательный параметр. Тип: строка.
items	Массив товаров, которые извлекаются из архива. Обязательный параметр. Тип: массив.
> id	Уникальный идентификатор товара, который присвоен сервисом при добавлении товара. Тип: строка.

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

POST /v1/archive/del

{
    "id": "149ec854b8c24a96b60e97bb977d3fb2",
    "items": [
        {
            "id": "9427288c2e5511ee8764b4b686880d33"
        }
    ]
}

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

Параметр	Описание
ok	Признак успешного выполнения метода. Тип: булево.
error	Описание ошибки, которая возникла в процессе выполнения метода. Тип: строка.

Пример ответа успешного выполнения метода:

{
    "ok": true
}