Запросы API

Для отправки одиночных и пакетных пуш-сообщений

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

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

https://developers.koshelek.app

Push API

Отправка одиночного сообщения

POST https://api.cardsmobile.ru/push/delivery

Используется партнером для отправки одиночного пуш-сообщения (транзакционного, сервисного, рекламного), адресованного одному конкретному получателю.

Request Body

Name Type Description

Name	Type	Description
pushType*	string	Тип передаваемого сообщения: `TRANSACTION` — транзакционное; `SERVICE` — сервисное; `PROMO` — рекламное.
msisdn*	integer	Номер телефона получателя сообщения без префикса `+`.
payload*	object	Отправляемое сообщение (JSON-объект Payload).
qos	object	Настройки отправки сообщения (JSON-объект QoS).
utm	object	Дополнительные настройки отправки (JSON-объект UTM).

pushType*

string

Тип передаваемого сообщения:

TRANSACTION — транзакционное;

SERVICE — сервисное;

PROMO — рекламное.

msisdn*

integer

Номер телефона получателя сообщения без префикса +.

payload*

object

Отправляемое сообщение

(JSON-объект Payload).

qos

object

Настройки отправки сообщения (JSON-объект QoS).

utm

object

Дополнительные настройки отправки (JSON-объект UTM).

{
  "messageId": "UUID",
  "state": "MSISDN_NOT_REGISTERED|ENQUEUED"
}

{
  "messageId": "aeb739ab-8b3a-4404-94ce-3ec96b3c0afa",
  "state": "ENQUEUED"
}

Описание объектов Payload, QoS и UTM см. в разделе Объекты API.

В случае отказа от отправки сообщения при превышении разрешенной частоты следует повторить попытку отправки позже.

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

{
    "pushType": "TRANSACTION",
    "msisdn": 71234567890,
    "payload": {
        "title": "Списание баллов",
        "message": "С вашей карты списано 10 баллов",
        "image": "http://partnerdomain/logo.jpg",
        "deeplink": {
            "target": "card"
        }
    },
    "qos": {
        "deliveryStatusNotifications": true
    },
    "utm": {
        "utmSource": "cardsmobile",
        "utmMiddle": "cpc",
        "utmCampaign": "campaign_name"
  }
}

Массовая отправка одиночного сообщения

POST https://api.cardsmobile.ru/push/bulk/single

Используется партнером для отправки одиночного пуш-сообщения (транзакционного, сервисного, рекламного), адресованного указанному перечню получателей.

Request Body

Name Type Description

Name	Type	Description
pushType*	string	Тип передаваемого сообщения: `TRANSACTION` — транзакционное; `SERVICE` — сервисное; `PROMO` — рекламное.
msisdn*	array	Массив целых чисел — номеров телефонов получателей сообщения (без префикса `+`).
payload*	object	Отправляемое сообщение (JSON-объект Payload, см. выше).
qos	object	Настройки отправки сообщения (JSON-объект QoS, см. выше).
utm	object	Дополнительные настройки отправки (JSON-объект UTM).

pushType*

string

Тип передаваемого сообщения:

TRANSACTION — транзакционное;

SERVICE — сервисное;

PROMO — рекламное.

msisdn*

array

Массив целых чисел — номеров телефонов получателей сообщения (без префикса +).

payload*

object

Отправляемое сообщение

(JSON-объект Payload, см. выше).

qos

object

Настройки отправки сообщения

(JSON-объект QoS, см. выше).

utm

object

Дополнительные настройки отправки

(JSON-объект UTM).

[
  {
    "msisdn": MSISDN,
    "messageId": "UUID",
    "state": "MSISDN_NOT_REGISTERED|ENQUEUED"
  }, ...
]

[
  {
    "msisdn": 79001234567,
    "messageId": "aeb739ab-8b3a-4404-94ce-3ec96b3c0afa",
    "state": "ENQUEUED"
  },
  {
    "msisdn": 79001234578,
    "messageId": "8df6fed9-73ab-40d0-800c-08bd5343e7f4",
    "state": "ENQUEUED"
  },
  {
    "msisdn": 79001234589,
    "messageId": "1be1561e-c108-4603-9334-567d6db15bf5",
    "state": "ENQUEUED"
  }
]

{
  "status": "ERROR CODE",
  "errors": [
    "Description", ...
  ]
}

{
  "status": "BATCH_SIZE_EXCEEDED",
  "errors": [
    "The allowed batch size has been exceeded"
  ]
}

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

{
  "pushType": "TRANSACTION",
  "msisdn": [
    79001234567,
    79001234578,
    79001234589,
    79001234590
  ],
  "payload": {
    "title": "Списание баллов",
    "message": "С вашей карты списано 10 баллов",
    "image": "http://partnerdomain/logo.jpg",
    "deeplink": {
      "target": "card"
    }
  },
  "qos": {
    "deliveryStatusNotifications": true
  },
  "utm": {
    "utmSource": "cardsmobile",
    "utmMiddle": "cpc",
    "utmCampaign": "campaign_name"
  }
}

Массовая отправка сообщений

POST https://api.cardsmobile.ru/push/bulk/multi

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

Request Body

Name Type Description

Name	Type	Description
*	array	Массив JSON-объектов, описывающих отправляемые сообщения. Каждый объект — тело запроса `/delivery` (см. выше).

array

Массив JSON-объектов, описывающих отправляемые сообщения. Каждый объект — тело запроса /delivery (см. выше).

[
  {
    "msisdn": MSISDN,
    "messageId": "UUID",
    "state": "MSISDN_NOT_REGISTERED|ENQUEUED"
  }, ...
]

[
  {
    "msisdn": 79001234567,
    "messageId": "aeb739ab-8b3a-4404-94ce-3ec96b3c0afa",
    "state": "ENQUEUED"
  },
  {
    "msisdn": 79001234578,
    "messageId": "8df6fed9-73ab-40d0-800c-08bd5343e7f4",
    "state": "ENQUEUED"
  },
  {
    "msisdn": 79001234589,
    "messageId": "1be1561e-c108-4603-9334-567d6db15bf5",
    "state": "ENQUEUED"
  }
]

{
  "status": "ERROR CODE",
  "errors": [
    "Description", ...
  ]
}

{
  "status": "BATCH_SIZE_EXCEEDED",
  "errors": [
    "The allowed batch size has been exceeded"
  ]
}

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

[
  {
    "pushType": "TRANSACTION",
    "msisdn": 71234567890,
    "payload": {
        "title": "Списание баллов",
        "message": "С вашей карты списано 10 баллов",
        "image": "http://partnerdomain/logo.jpg",
        "deeplink": {
            "target": "card"
        }
    },
    "qos": {
        "deliveryStatusNotifications": true
    },
    "utm": {
        "utmSource": "cardsmobile",
        "utmMiddle": "cpc",
        "utmCampaign": "campaign_name"
    }
  }
]

Получение списка акций из Личного кабинета

GET https://api.cardsmobile.ru/promos

Партнер, зарегистрированный в системе «Кошелёк для бизнеса», имеет возможность настройки и публикации в Кошельке промоакций для своих клиентов. Этот метод позволяет получить идентификаторы текущих действующих промоакций, которые можно использовать для настройки перехода из пуш-сообщения к конкретному экрану промоакции в Кошельке.

{
    "promos": [
        {
            "id": <id акции>,
            "name": "Название акции",
            "active": true
        },
        {
            "id": <id акции>,
            "name": "Название акции",
            "active": true
        }
    ]
}

{
    "promos": [
        {
            "id": 1060,
            "name": "Скидка 10% на покупку от 1200 рублей",
            "active": true
        },
        {
            "id": 435,
            "name": "Скидка Пенсионерам",
            "active": true
        }
    ]
}

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

Получение статуса доставки одиночного сообщения

GET https://api.cardsmobile.ru/push/{messageId}/transactional-state

Метод для получения сведений о статусе доставки одиночного сообщения.

Path Parameters

Name	Type	Description
messageId*	string	Идентификатор сообщения.

Name

Type

Description

messageId*

string

Идентификатор сообщения.

{
    "states": [
        {
            "msisdn": <MSISDN>,
            "state": "MSISDN_NOT_REGISTERED|ENQUEUED|DELIVERED|OPENED",
            "time": "yyyy-MM-ddThh:mm:ssZ"
        },
        {
            "msisdn": <MSISDN>,
            "state": "MSISDN_NOT_REGISTERED|ENQUEUED|DELIVERED|OPENED",
            "time": "yyyy-MM-ddThh:mm:ssZ"
        }
    ]
}

{
    "states": [
        {
            "msisdn": 79000000011,
            "state": "DELIVERED",
            "time": "2022-11-11T16:30:08+0300"
        },
        {
            "msisdn": 79000000011,
            "state": "ENQUEUED",
            "time": "2022-11-11T16:30:08+0300"
        },
        {
            "msisdn": 79000000011,
            "state": "OPENED",
            "time": "2022-11-11T16:32:05+0300"
        }
    ]
}

Callback API

Информирование об изменении статуса доставки

POST https://<partner-base-url>/<callback-endpoint>

Если при создании сообщения значение параметра deliveryStatusNotifications равно "true", то при изменении статуса доставки сообщения узел Cardsmobile совершит вызов на URL, предоставленный партнером в рамках проекта интеграции (см. Подключение к API).

Request Body

Name Type Description

Name	Type	Description
msisdn*	integer	Номер телефона получателя сообщения без префикса `+`.
messageId*	string	Идентификатор сообщения.
state*	string	Текущий статус доставки сообщения: `DELIVERED` — сообщение доставлено; `OPENED` — сообщение прочитано.
time*	string	Время ("yyyy-MM-ddThh:mm:ssZ") перехода сообщения в указанный статус.
utm	object	Объектный идентификатор, содержащий дополнительные настройки отправки сообщения, указанные партнером при отправке (см. выше).

msisdn*

integer

Номер телефона получателя сообщения без префикса +.

messageId*

string

Идентификатор сообщения.

state*

string

Текущий статус доставки сообщения:

DELIVERED — сообщение доставлено;

OPENED — сообщение прочитано.

time*

string

Время ("yyyy-MM-ddThh:mm:ssZ") перехода сообщения в указанный статус.

utm

object

Объектный идентификатор, содержащий дополнительные настройки отправки сообщения, указанные партнером при отправке (см. выше).

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

{
    "msisdn": 79051234567,
    "messageId": "c506b550-a309-11e9-a2a3-2a2ae2dbcce4",
    "state": "DELIVERED",
    "time": "2019-11-29T17:11:42Z",
    "utm": {
            "utmSource": "cardsmobile",
            "utmMiddle": "cpc",
            "utmCampaign": "campaign_name"
  }
}

PreviousПередача пуш-сообщений NextОбъекты API

Last updated 11 months ago