Запросы API

Для управления промоакциями

Документация перемещена

Информация на этой странице не обновляется и может быть устаревшей. Наиболее полная и актуальная версия документации для разработчиков доступна по новому адресу:

https://developers.koshelek.app

Получение списка существующих акций

GET https://api.cardsmobile.ru/promo/v1/all

Получение информации о созданных промоакциях партнера.

Request Body

Name	Type	Description
limit	number	Количество выводимых элементов. Максимальное значение: 100. По умолчанию возвращается 15 последних промоакций.
offset	number	Количество пропускаемых элементов списка. По умолчанию: 0.
activeOnly	boolean	true — получить список только активных акций. false — получить полный список акций, включая завершенные и запланированные. По умолчанию обрабатывается как false.

200: OK Запрос обработан. В теле ответа — JSON-объект, содержащий список промоакций партнера:

HTTP: 200

{
  "metadata": {
    "limit": 15,
    "offset": 0,
    "totalCount": 2,
    "activeOnly": false
  },
  "items": [
    {
      "promoId": 1010,
      "name": "Скидки ПО-ЧЁРНОМУ!",
      "startDate": "2020-09-01T00:00:00+03",
      "endDate": "2020-09-10T00:00:00+03",
      "status": "active"
    },
    {
      "promoId": 977,
      "name": "Встречайте товар недели!",
      "startDate": "2020-08-20T15:00:00+03",
      "endDate": "2020-08-27T21:00:00+03",
      "status": "completed"
    }
  ]
}

400: Bad Request Неверный формат запроса. Ответ содержит описание ошибки:

HTTP: 400

{
  "code": "REQUEST_PARAMS_ERROR",
  "details": "Invalid request parameters format"
}

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

Параметр	Тип	Обязательно	Значение
metadata	Object	Да	Объект метаданных, содержащий указанные в запросе значения фильтров и ограничений, а также значение общего количества записей.
metadata.limit	Number	Да	Количество выводимых элементов списка.
metadata.offset	Number	Да	Количество пропускаемых элементов списка.
metadata.totalCount	Number	Да	Общее количество записей.
metadata.activeOnly	Boolean	Да	true — вывести только активные акции. false — вывести все акции.
items	Array	Да	Массив объектов Item, содержащих сведения об акциях. Описание объекта Item см. в разделе Объекты API.

Получение информации об акции по идентификатору

GET https://api.cardsmobile.ru/promo/v1/details?promoId={id}

Получение полной информации по выбранной акции.

Query Parameters

Name	Type	Description
promoId*	number	Уникальный идентификатор акции, присвоенный узлом Cardsmobile при создании акции.

200: OK Запрос обработан. В теле ответа — JSON-объект, содержащий подробную информацию о запрашиваемой промоакции:

{
  "promoId": 1010,
  "name": "Скидки ПО-ЧЁРНОМУ!",
  "startDate": "2020-09-01T00:00:00+03",
  "endDate": "2020-09-10T00:00:00+03",
  "status": "active",
  "images": {
    "imageWide": "https://promo.partner.ru/wide.jpg",
    "imageSquare": "https://promo.partner.ru/square.jpg"
  },
  "description": "<p>Чёрная пятница уже здесь и громит цены!</p>\n<p>Самое время найти свою скидку и устроить шоппинг ПО-ЧЁРНОМУ!</p>\n<p><a href=\"https://www.partner.ru/promo/black-friday/?utm_source=crm&utm_medium=wallet&utm_content=promo&utm_campaign=261119_bf_wallet_w48\">Подробнее об акции</a></p>",
  "discount": "10",
  "source": "api"
}

400: Bad Request Неверный формат запроса. Ответ содержит описание ошибки:

{
  "code": "NO_EXPECTED_PARAMETERS",
  "details": "No expected parameters in the request"
}

422: Unprocessable Entity Ошибка обработки бизнес-логики. Тело ответа содержит описание ошибки:

{
  "code": "PROMOID_NOT_FOUND",
  "details": "promoId not found"
}

Тело запроса пустое.

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

Параметр	Тип	Обязательно	Значение
promoId	Number	Да	Уникальный идентификатор акции.
name	String	Да	Наименование акции.
startDate	String	Да	Дата начала акции в формате YYYY-MM-DDTHH:MM:SS+00.
endDate	String	Нет	Дата окончания акции в формате YYYY-MM-DDTHH:MM:SS+00. null — бессрочная акция (актуально для source = rmc).
status	String	Да	Статус акции, рассчитанный исходя из срока ее действия: active — активная акция; completed — завершенная акция; planned — запланированная акция.
images	Object	Да	Графические изображения акции для отображения на экране предъявления карты в Кошельке.
images.imageWide	String	Да	Гиперссылка на файл с большим изображением предложения акции (1080×420 пикселей).
images.imageSquare	String	Да	Гиперссылка на файл с малым изображением предложения акции (600×600 пикселей).
description	String	Да	Текстовое описание предложения в разметке HTML для отображения в каталоге Кошелька.
discount	Number	Да	Размер скидки по акции. Отображается в качестве ярлыка на изображении предложения. 0 — нет скидки по акции.
source	String	Да	Источник загрузки данных акции в Кошелёк: api — источником является Promo API. rmc — источником является Личный кабинет ритейлера.

​Создание новой акции

POST https://api.cardsmobile.ru/promo/v1/create

Создание новой промоакции.

Request Body

Name	Type	Description
name*	string	Наименование акции (до 255 символов).
startDate*	string	Дата начала акции в формате YYYY-MM-DDTHH:MM:SS+00.
endDate	string	Дата окончания акции в формате YYYY-MM-DDTHH:MM:SS+00. Если акция бессрочная, параметр не передается или передается значение null.
images*	object	Графические изображения акции для отображения на экране предъявления карты в Кошельке.
images.imageWide*	string	Гиперссылка (до 1024 символов) на файл с большим изображением предложения (1080×420 пикселей).
images.imageSquare*	string	Гиперссылка (до 1024 символов) на файл с малым изображением предложения (600×600 пикселей).
description*	string	Текстовое описание предложения для отображения в каталоге Кошелька (до 10 000 символов в разметке HTML). Поддерживаемые HTML-теги: <a> <b> <br> <i> <ol>, <li> <ul>, <li> <p> <s> <u>
discount	number	Размер скидки по акции (целое число от 1 до 100). Отображается в качестве ярлыка на изображении предложения. Если скидки нет, параметр не передается или передается значение 0.

200: OK Запрос обработан. В теле ответа — JSON-объект, содержащий идентификатор и текущий статус созданной промоакции:

HTTP: 200

{
  "promoId": 1020,
  "status": "planned"
}

400: Bad Request Неверный формат запроса. Ответ содержит описание ошибки:

HTTP: 400

{
  "code": "JSON_VALIDATION_ERROR",
  "details": "Invalid JSON request format"
}

HTTP: 400

{
  "code": "IMAGE_VALIDATION_ERROR",
  "details": "Image validation error"
}

HTTP: 400

{
  "code": "DATA_VALIDATION_ERROR",
  "details": "Data validation error"
}

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

Параметр	Тип	Обязательно	Значение
promoId	Number	Да	Уникальный идентификатор акции.
status	String	Да	Текущий статус акции, рассчитанный исходя из срока ее действия: active — активная акция; completed — завершенная акция; planned — запланированная акция.

Обновление данных существующей акции

POST https://api.cardsmobile.ru/promo/v1/update

Обновление данных созданной промоакции.

Request Body

Name	Type	Description
promoId*	number	Уникальный идентификатор акции (выдается узлом Cardsmobile при создании акции и не может быть обновлен).
name*	string	Наименование акции (до 255 символов).
startDate*	string	Дата начала акции в формате YYYY-MM-DDTHH:MM:SS+00.
endDate	string	Дата окончания акции в формате YYYY-MM-DDTHH:MM:SS+00. Если акция бессрочная, параметр не передается или передается значение null.
images*	object	Графические изображения акции для отображения на экране предъявления карты в Кошельке.
images.imageWide*	string	Гиперссылка (до 1024 символов) на файл с большим прямоугольным изображением предложения (1080×420 пикселей).
images.imageSquare*	string	Гиперссылка (до 1024 символов) на файл с малым квадратным изображением предложения (600×600 пикселей).
description*	string	Текстовое описание предложения для отображения в каталоге Кошелька (до 10 000 символов в разметке HTML). Поддерживаемые HTML-теги: <a> <b> <br> <i> <ol>, <li> <ul> , <li> <p> <s> <u>
discount	number	Размер скидки по акции (целое число от 1 до 100). Отображается в качестве ярлыка на изображении предложения. Если скидки нет, параметр не передается или передается значение 0.

200: OK Запрос обработан. В теле ответа — JSON-объект, содержащий идентификатор и текущий статус обновленной промоакции:

HTTP: 200

{
  "promoId": 1020,
  "status": "planned"
}

400: Bad Request Неверный формат запроса. Ответ содержит описание ошибки:

HTTP: 400

{
  "code": "JSON_VALIDATION_ERROR",
  "details": "Invalid JSON request format"
}

HTTP: 400

{
  "code": "IMAGE_VALIDATION_ERROR",
  "details": "Image validation error"
}

HTTP: 400

{
  "code": "DATA_VALIDATION_ERROR",
  "details": "Data validation error"
}

422: Unprocessable Entity Ошибка обработки бизнес-сценария. Ответ содержит описание ошибки:

HTTP: 422

{
  "code": "PROMOID_NOT_FOUND",
  "details": "promoId not found"
}

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

Параметр	Тип	Обязательно	Значение
promoId	Number	Да	Уникальный идентификатор акции.
status	String	Да	Статус акции, рассчитанный исходя из срока ее действия: active — активная акция; completed — завершенная акция; planned — запланированная акция.