PushID API
Отправка PushID
PushID — это отправка идентификатора абоненту через push-канал оператора связи (услуга типа «Пушок»). Услуга работает только для операторов, которые её
поддерживают. Если номер получателя принадлежит оператору без поддержки PushID, запрос по желанию может быть автоматически отправлен как обычное SMS — для этого служит параметр isSmsEnabled.
Про процедуру аутентификации и авторизации, которые связывают вызовы API
с необходимыми приложениями в Вашей учётной записи, см. раздел «Авторизация».
Запрос
Поддерживаются методы POST и GET.
Все параметры передаются в строке запроса (query string). Тело запроса не разбирается — передавать параметры в JSON-теле нельзя.
POST/GET [https://api.unibell.ru/pushid?X-Authorization=AccessKey](https://api.unibell.ru/pushid?X-Authorization=AccessKey) d8ac9959r12b43545XXXXX&destAddr=7XXXXXXXXXX&isSmsEnabled=1&sourceAddr=MySender&shortMessage=Текст сообщенияПример запроса с использованием CURL:
curl --location --request POST '[https://api.unibell.ru/pushid?X-Authorization=AccessKey](https://api.unibell.ru/pushid?X-Authorization=AccessKey) d8ac9959r12b43545XXXXX&destAddr=7XXXXXXXXXX&isSmsEnabled=1&sourceAddr=MySender&shortMessage=Текст сообщения'curl --location --request GET '[https://api.unibell.ru/pushid?X-Authorization=AccessKey](https://api.unibell.ru/pushid?X-Authorization=AccessKey) d8ac9959r12b43545XXXXX&destAddr=7XXXXXXXXXX'Параметры запроса
| Параметр | Тип | Описание |
|---|---|---|
| destAddr | string | Обязательный. Номер телефона получателя в формате e.164, например, для Российской Федерации 7XXXXXXXXXX. Поле не должно содержать кириллицы. Допускаются также форматы 8XXXXXXXXXX и +7XXXXXXXXXX — они автоматически приводятся к 7XXXXXXXXXX. |
| isSmsEnabled | string | Необязательный. Флаг отправки SMS в случае, когда оператор получателя не поддерживает PushID. 1 — при отсутствии поддержки PushID отправить обычное SMS (обязательными становятся sourceAddr и shortMessage); 0 или не указан — если оператор не поддерживает PushID, запрос отклоняется (см. ошибку Destination is not allowed). |
| sourceAddr | string | Имя отправителя SMS (только латиница или номер телефона). Поле не должно содержать кириллицы. Требуется только для SMS-варианта (isSmsEnabled=1 и оператор не поддерживает PushID). Для PushID игнорируется. |
| shortMessage | string | Текст SMS-сообщения. Требуется только для SMS-варианта (isSmsEnabled=1 и оператор не поддерживает PushID). Для PushID игнорируется. |
Как выбирается способ отправки
По номеру получателя определяется оператор/зона:
- если оператор поддерживает PushID — отправляется PushID (в ответе type = PUSHID);
- если оператор PushID не поддерживает:
- при isSmsEnabled=1 — отправляется SMS (в ответе type = SMS);
- иначе — запрос отклоняется с ошибкой Destination is not allowed.
Ответ при успешном выполнении запроса
| Параметр | Тип | Описание |
|---|---|---|
| status | string | Статус запроса: ok — запрос принят к обработке. invalidDataError — ошибка в параметрах запроса (уточнение в поле error). invalidAccessKeyError — ошибка в ключе авторизации. prohibitedForServiceError — ключ не принадлежит услуге PushID. accountFinanciallyBlocked — контрагент заблокирован по балансу / блокировка по IP-адресу. |
| requestId | string | Уникальный идентификатор запроса. |
| type | string | Способ отправки: PUSHID — отправлен PushID; SMS — отправлено обычное SMS (fallback при isSmsEnabled=1). |
| error | string | Описание ошибки (присутствует при status = invalidDataError). Возможные значения: Missing destAddr param — destAddr отсутствует в запросе. Field destAddr must not contain Cyrillic — в destAddr присутствует кириллица. No zone found for the destAddr parameter — не удалось определить оператора/зону по номеру. Missing sourceAddr param — sourceAddr отсутствует (для SMS-варианта). Field sourceAddr must not contain Cyrillic — в sourceAddr присутствует кириллица. Missing shortMessage param — shortMessage отсутствует (для SMS-варианта). |
Примеры ответов при ошибках
Отсутствует destAddr:
{
"status": "invalidDataError",
"error": "Missing destAddr param"
}Оператор не поддерживает PushID, а isSmsEnabled не задан (HTTP 500):
{
"errorCode": 500,
"errorReason": "Destination is not allowed"
}