Comex HTTP API

Справочное руководство

Введение

Сервис Comex предназначен для отправки сообщений по различным каналам связи. Поддерживаются следующие каналы:

Термины и определения

Условные обозначения

Во всех примерах запросов используются обозначения в треугольных скобках - например, <имя отправителя>. Вместо такого обозначения при выполнении запросто нужно использовать значение соответствующего параметра.

Обозначения в круглых скобках указывают на возможные варианты содержимого, если их количество ограничено - например, (true|false). В запросе следует указывать только один из вариантов, разделенных вертикальной чертой.

Взаимодействие с API

Взаимодействие с сервисом осуществляется через REST API с помощью стандартных HTTP-запросов.

Структура запроса:

Авторизация

В API используется аутентификация на основе базовой схемы. При регистрации каждый пользователь получает ID ноды и пароль. Для авторизации нужно перекодировать эти параметры, разделённые двоеточием, в формат base64. Пример для ОС семейства Linux (39999 - ID ноды, 123654 - пароль):

echo -n '39999:123654' | base64

Вывод приведённой команды выглядит так:

Mzk5OTk6MTIzNjU0

Эту строку нужно передавать во всех запросах в заголовке Authorization. Пример запроса к Comex HTTP API с помощью утилиты cURL:

curl -X POST -H "Content-Type: application/json" -H "Authorization: Basic Mzk5OTk6MTIzNjU0" -d '<содержимое запроса>' https://external-api.i-dgtl.ru/<вызываeмое действие>

Принципы формирования содержимого запроса описаны ниже.

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

Параметр Тип Значение
@type string Тип объекта (в запросах на отправку сообщений - оutbound)
addresses object Объект, содержащий адреса отправителя и получателя
source string Имя или адрес отправителя
destination string Адрес или номер телефона получателя
body object Объект, в котором передаётся содержимое сообщения
bodyType string Тип сообщения (SMS, e-mail, VK Notify, Viber, Push, WhatsApp, FlashCall)
content string Содержимое сообщения (подробнее см. в примерах запросов на отправку сообщений)
nodeId integer ID ноды
requestDelivery boolean Указывает, cледует ли предоставлять отчёт о доставке после отправки сообщения
expirationDate timestamp Время, до которого будет ожидаться получение статуса от оператора (Unix Timestamp в миллисекундах или в формате ISO 8601). По умолчанию составляет 24 часа с момента отправки сообщения. Если статус к этому времени не будет получен, возвращается ошибка 127 (см. описание ниже)

ВАЖНО: все временные метки в протоколе Comex передаются в формате Unixtime с учетом миллисекунд. Это отличается от наиболее распространенной реализации, где в основном используются секунды. В запросах на отправку сообщений допускается передача временных меток в формате ISO 8601.

Номер телефона указывается в международном формате MSISDN, состоящем из кода страны, DEF-кода оператора и номера абонента. Например, российский номер выглядит так: 79001234567, где 7 - код страны (Россия). Если клиент по той или иной причине использует другой формат номеров (со скобками, с дополнительными символами и т.п.), можно настроить автоматическую конвертацию номеров в MSISDN. Правила конвертации оговариваются с каждым клиентом индивидуально.

Будьте внимательны при использовании в SMS следующих символов:

£,¥,è,é,ù,ì,ò,Ç,Ø,ø,Å,å,Δ,Φ,Γ,Λ,Ω,Π,Ψ,Σ,Θ,Ξ,Æ,æ,ß,É,¤,¡,Ä,Ö,Ñ,Ü,§ ¿,ä,ö,ñ,ü,à,
NUL,SOH,STX,ETX,EOT,ENQ,ACK,BEL,BS,TAB,VT,SO,SI,DLE,DC1,DC2,DC3,DC4,
NAK,SYN,ETB,CAN,EM,SUB,FS,GS,RS,US,`,DEL.

Операторы (в зависимости от особенностей их платформы и спецификации) могут не поддерживать эти символы или конвертировать сообщения в Unicode, тем самым увеличивая количество тарифицируемых частей сообщения.

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

URI: https://external-api.i-dgtl.ru/message

SMS

 {
    "@type": "outbound",
    "addresses": {
        "source": "<имя отправителя>",
        "destination": "<номер телефона получателя>"
    },
    "body": {
        "bodyType": "text",
        "content": "<текст сообщения>"
    },
    "nodeId": <ID ноды>,
    "requestDelivery": (true|false)
}

Viber

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

 {
    "@type": "outbound",
    "addresses": {
        "source": "<имя отправителя>",
        "destination": "<номер телефона получателя>"
    },
    "body": {
        "bodyType": "viber",
        "content": "<текст сообщения>"
    },
    "nodeId": <ID ноды>,
    "requestDelivery": (true|false)
}

ВАЖНО:

Отправка сообщения с графическим вложением

При отправке графических вложений через Viber в поле content включается JSON-объект в виде строки, в котором содержатся следующие дополнительные параметры:

 {
    "@type": "outbound",
    "addresses": {
        "source": "<имя отправителя>",
        "destination": "<номер телефона получателя>"
    },
    "body": {
        "bodyType": "viber",
        "content": "{\"content_type\":\"image\",\"imageUrl\":\"<ссылка на изображение>\"}"
    },
    "nodeId": <ID ноды>,
    "requestDelivery": (true|false)
}

ВАЖНО:

Отправка сообщения с интерактивными элементами (изображением и кнопкой)

 {
   "@type": "outbound",
   "addresses": {
       "source": "<имя отправителя>",
       "destination": "<номер телефона получателя>"
   },
   "body": {
       "bodyType": "viber",
       "content": "{\"content_type\":\"button\",\"text\":\"<текст сообщения>\",\"caption\":\"<текст кнопки>\",\"action\":\"<ссылка на сайт>\",\"imageUrl\":\"<ссылка на изображение>\"}"
   },
   "nodeId": <ID ноды>,
   "requestDelivery": (true|false)
}

Параметры Viber-сообщения c интерактивными элементами:

ВАЖНО:

E-mail

 {
   "@type": "outbound",
   "addresses": {
       "source": "<email-адрес отправителя>",
       "destination": "<email-адрес получателя>"
   },
   "body": {
       "bodyType": "email",
       "html": (true|false),
       "content": "<содержимое письма>",
       "senderName": "<отображаемое имя отправителя>",
       "subject": "<тема письма>"
   },
   "nodeId": <ID ноды>,
   "requestDelivery": (true|false)
}

Параметры e-mail-сообщения:

VK Notify

{
    "@type": "outbound",
    "addresses": {
        "source": "<имя отправителя>",
        "destination": "<номер телефона получателя>"
    },
    "body": {
        "bodyType": "vk",
        "content": "<текст сообщения>"
    },
    "nodeId": <ID ноды>,
    "requestDelivery": (true|false)
}

ВАЖНО:

Push

Пример 1

{
    "@type": "outbound",
    "addresses": {
        "source": "<имя отправителя>",
        "destination": "<номер телефона получателя>"
    },
    "body": {
        "bodyType": "push",
        "content": "<текст сообщения>"
    },
    "nodeId": <ID ноды>,
    "requestDelivery": (true|false)
}

Пример 2

{
    "@type": "outbound",
    "addresses": {
        "source": "<имя отправителя>",
        "destination": "<номер телефона получателя>"
    },
    "body": {
        "bodyType": "push",
        "content": "<текст сообщения>"
    },
    "properties": {
        "pushParameters": {
            "shortMessage": "Test",
            "fullMessage": "Текст тестового сообщения"
        }
    },
    "nodeId": <ID ноды>,
    "requestDelivery": (true|false)
}

Во втором примере в запросе содержитcя объект properties -> pushParameters с дополнительными параметрами

WhatsApp

{
    "@type": "outbound",
    "addresses": {
        "source": "<имя отправителя>",
        "destination": "<номер телефона получателя>"
    },
    "body": {
        "bodyType": "whatsapp",
        "content": "<текст сообщения>"
    },
    "nodeId": <ID ноды>,
    "requestDelivery": (true|false)
}

Отправка сообщения с графическим вложением

{
    "@type": "outbound",
    "addresses": {
        "source": "<имя отправителя>",
        "destination": "<номер телефона получателя>"
    },
    "body": {
        "bodyType": "whatsapp",
        "content": "{\"content_type\":\"image\",\"imageUrl\":\"http://example.com/my-image.png\"}"
    },
    "nodeId": <ID ноды>,
    "requestDelivery": (true|false)
}

Параметры WhatsApp-сообщения с графическим вложением

ВАЖНО:

Отправка сообщения с вложенным документом

{
    "@type": "outbound",
    "addresses": {
        "source": "<имя отправителя>",
        "destination": "<номер телефона получателя>"
    },
    "body": {
        "bodyType": "whatsapp",
        "content":  "{\"content_type\":\"document\",\"documentUrl\":\"http://bank.ru/docs/tarif123.pdf\",\"documentName\":\"Новые тарифы на 2019 год\"}"
    },
    "nodeId": <ID ноды>,
    "requestDelivery": (true|false)
}

Параметры WhatsApp-сообщения с вложенным документом

ВАЖНО:

Отправка сообщения с вложенным аудиофайлом

{
    "@type": "outbound",
    "addresses": {
        "source": "<имя отправителя>",
        "destination": "<номер телефона получателя>"
    },
    "body": {
        "bodyType": "whatsapp",
        "content":  "{\"content_type\":\"audio\",\"audioUrl\":\"http://example.com/audios/hello.mp3\"}"
    },
    "nodeId": <ID ноды>,
    "requestDelivery": (true|false)
}

Параметры WhatsApp-сообщения с вложенным аудиофайлом

ВАЖНО:

Отправка сообщения с вложенным видеофайлом

{
    "@type": "outbound",
    "addresses": {
        "source": "<имя отправителя>",
        "destination": "<номер телефона получателя>"
    },
    "body": {
        "bodyType": "whatsapp",
        "content": "{\"content_type\":\"video\",\"videoUrl\":\"http://example.com/videos/hello.mp4\",\"videoName\":\"Добро пожаловать\"}"
    },
    "nodeId": <ID ноды>,
    "requestDelivery": (true|false)
}

Параметры WhatsApp-сообщения с вложенным видеофайлом

ВАЖНО:

Вызовы FlashCall

FlashCall - звонок с номера, последние четыре цифры которого являются кодом авторизации/подтверждения.

{
    "@type": "outbound",
    "addresses": {
        "source": "<имя отправителя>",
        "destination": "<номер телефона получателя>"
    },
    "body": {
        "bodyType": "flashcall",
        "content": "<текст сообщения>"
    },
    "nodeId": <ID ноды>,
    "requestDelivery": (true|false)
}

В запросе на отправку вызова FlashCall в качестве значения параметра content можно указать как последовательность от 4 до 6 цифр, так и произвольный текст. В последнем случае из текста будет извлечена крайняя правая последовательность из 4-х цифр при помощи регулярного выражения:

(?ius)^.*(?<CODE>\d{4,}).*$

Будьте внимательны при составлении произвольных текстов. Например, если вы передадите сообщение вида “Код для подтверждения заказа №457861: 4578. Приятного аппетита!”, то будет выбрана последовательность 4578, звонок поступит с номера вида XXXXXXX4578, и пользователь получит верный код авторизации.

Если же вы передадите в запросе сообщение вида “Ваш код авторизации: 4579. Для получения дополнительной информации: 70000000019”, то будет выбрана последовательность 0019, и звонок пользователю поступит с номера вида XXXXXXX0019. Верный код авторизации в этом случае он не получит.

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

В ответ на все приведённые выше примеры запросов API возвращает ответ вида:

{
    "id": "<MSID сообщения>",
    "timestamp": <время отправки сообщения>,
    "code": <код ответа сервиса>
}

Ответ содержит следующие параметры:

Параметр Тип Значение
id string ID сообщения
timestamp timestamp Дата и время отправки сообщения (Unix Timestamp в миллисекундах)
code integer Код ответа (в случае успешного выполнения запроса - 200 OK)

ВАЖНО: все временные метки в протоколе Comex передаются в формате Unixtime с учетом миллисекунд. Это отличается от наиболее распространенной реализации, где в основном используются секунды

Коды ошибок

Код ошибки Описание
200 Успешно
400 Неверный синтаксис запроса
401 Ошибка авторизации
403 Доступ запрещён
405 Метод запроса отключён и не может быть использован
415 Некорректное значение заголовка Content-Type
451 В запросе содержатся запрещённые к использованию слова

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

С помощью API можно отправлять не только одиночные сообщения, но и группы (пакеты) сообщений.

URI: https://external-api.i-dgtl.ru/pack

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

[
    {
        "@type": "outbound",
        "addresses": {
            "source": "<имя отправителя>",
            "destination": "<номер телефона получателя #1>"
        },
        "body": {
            "bodyType": "text",
            "content": "<текст сообщения>"
        },
        "nodeId": <ID ноды>,
        "requestDelivery": (true|false)
    },
    {
        "@type": "outbound",
        "addresses": {
            "source": "<имя отправителя>",
            "destination": "<номер телефона получателя #2>"
        },
        "body": {
            "bodyType": "text",
            "content": "<текст сообщения>"
        },
        "nodeId": <ID ноды>,
        "requestDelivery": (true|false)
    }
]

Как видно из приведённого примера, тело запроса представляет собой массив из одиночных сообщений.

Максимальное количество сообщений в пакете составляет 100.

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

В ответ на запрос API возвращает ID, время отправки и код ответа для каждого сообщения из пакета:

{
   "timestamp": "<дата и время отправки пакета сообщений>",
   "code": 200,
   "responses": [
      {
         "timestamp": "<дата и время отправки сообщения>",
         "code": 200,
         "id": "<MSID сообщения>"
      },
      {
         "timestamp": "<дата и время отправки сообщения>",
         "code": 200,
         "id": "<MSID сообщения>"
      }
   ]
}

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

Параметр Тип Значение
id string ID сообщения
timestamp timestamp Дата и время отправки сообщения (Unix Timestamp в миллисекундах)
code integer Код ответа (в случае успешного выполнения запроса - 200 OK)

Коды ошибок

Код ошибки Описание
401 Ошибка авторизации
413 Превышено количество сообщений в пакете
451 Сработала блокировка по стоп-словам

Каскадная отправка

Каскадной отправкой называется технология переотправки сообщения по различным каналам. Последовательность каналов настраивается по согласованию с клиентом. При поступлении сообщение будет направлено в канал с наивысшим приоритетом; в случае недоставки оно будет переотправлено в следующий канал. Переотправка продолжится до тех пор, пока не будет получен статус “Доставлено” или пока не будут использованы все возможные каналы. Например, если Push-уведомление по той или иной причине не поступает на мобильное устройство пользователя, его содержание может быть переотправлено в виде SMS.

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

Отправка сообщений с одинаковым содержимым

Если при каскадной отправке не требуется отображение разного содержимого через разные каналы доставки, поле bodyType может содержать значение text и иметь такое же содержимое, как при отправке SMS.

Отправка сообщений с разным содержимым

{
    "@type": "outbound",
    "addresses": {
        "source": "<имя отправителя>",
        "destination": "<номер телефона получателя>"
    },
    "body": {
        "bodyType": "generic",
        "content": [
            {
                "bodyType": "viber",
                "content": "<текст сообщения>"
            },
            {
                "bodyType": "text",
                "content": "<текст сообщения>"
            }
        ]
    },
    "nodeId": <ID ноды>,
    "requestDelivery": (true|false)
}

В запросах на каскадную отправку сообщений с разным содержимым параметр bodyType имеет значение generic. Такой синтаксис используется для отправки массива объекта body разного типа. Таким образом при каскадной отправке вы можете комбинировать любой из доступных способов отправки, описанных выше, указывая необходимое содержимое для каждого типа канала.

Получение статусов доставки

Получение статусов доставки возможно только в случае, если при отправке сообщения указано значение параметра requestDelivery: true. Время получения статуса зависит от доступности абонента и качества сигнала мобильной сети.

URI: https://external-api.i-dgtl.ru/receive.

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

curl -H 'Content-Type: application/json'\
     -H 'Accept: application/json' \
     -H "Authorization: Basic  Mzk5OTk6MTIzNjU0" \
     -d '10' \
     'https://external-api.i-dgtl.ru/receive'
     -X POST

В теле запроса передаётся количество сообщений, статусы которых нужно включить в ответ. В приведённом примере в теле запроса передаётся число 10, и это значит, что в ответ будет включена информация о полученных статусах для 10 сообщений. Максимальное количество запрашиваемых статусов не должно превышать 1000.

ВАЖНО:

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

{
   "timestamp": <дата и время генерации ответа>,
   "code": 200,
   "states": [
      {
         "@type": "state",
         "msid": "<MSID сообщения>",
         "status": "<статус сообщения>",
         "creationDate": <дата и время генерации статуса>,
         "errorCode": <код ошибки>,
         "final": (true|false)
      },
      {
         "@type": "state",
         "msid": "<MSID сообщения>",
         "status": "<статус сообщения>",
         "creationDate": <дата и время генерации статуса>,
         "errorCode": <код ошибки>,
         "final": (true|false)
      },
      ...
   ]
}

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

Параметр Тип Значение
timestamp timestamp Дата и время отправки сообщения (Unix Timestamp в миллисекундах)
code integer Код ответа
states array Массив со статусами сообщений. Последовательность сообщений в массиве соответствует их последовательности в запросе

Параметры сообщения в массиве

Параметр Тип Значение
@type string Тип объекта (в запросах на получение статусов - state)
msid string UUID сообщения
status string Статус сообщения (cм. ниже)
creationDate timestamp Дата формирования статуса
errorCode integer Код ошибки (см. ниже)
final boolean Указывает, является ли статус сообщения финальным. Финальным называется последний в жизненном цикле сообщения статус. Финальными являются все статусы, кроме DELIVERED (после него через некоторое время может быть возвращен ещё и статус READ)

Cтатусы сообщений

Статус Описание
DELIVERED Сообщение доставлено абоненту
UNDELIVERED Сообщение не доставлено
EXPIRED Время ожидания статуса истекло (временем ожидания статуса считается промежуток времени от отправки до даты, указанной в параметре expirationDate)
READ Сообщение прочитано
EXPIRED_READ Сообщения было доставлено, но статус READ не был получен. По умолчанию не передаётся; если вам нужно получать этот статус, обратитесь в службу технической поддержки или к вашему менеджеру

Возможные ошибки

Код ошибки Описание
401 Ошибка авторизации
413 Превышено количество запрашиваемых статусов

Коды ошибок

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

Общие коды ошибок

Код ошибки Текст сообщения об ошибке Описание ошибки
6969 Error without additional information Неизвестная ошибка
127 Timeout of getting status from SMSC, Viber or Push platform Истекло время ожидания статуса сообщения от SMSC оператора, Viber или Push-платформы.

SMS

Код ошибки Текст сообщения об ошибке Описание ошибки
501 Unknown subscriber Номер телефона не существует или не обслуживается.
508 The subscriber is absent or out of coverage Устройство абонента выключено или находится вне зоны доступа сети.
504 Teleservice not provisioned Сервис коротких сообщений не предоставляется.
523 Subscriber is busy Устройство абонента занято операцией, препятствующей получению короткого сообщения.
518 SS7 routing error Внутренняя ошибка маршрутизации на стороне конечного оператора.
502 SMSC failure Ошибка центра передачи сообщений (SMSC) на стороне конечного оператора.
509 Roaming restrictions Абонент находится в роуминге.
511 Message queue full Очередь сообщений со стороны оператора переполнена абонента
557 Internal system failure Внутренняя ошибка системы на стороне конечного оператора.
525 IMSI error Ошибка на стороне оператора при запросе IMSI.
647 Illegal subscriber Абонент не зарегистрирован или заблокирован оператором
515 Equipment protocol error Аппаратная ошибка телефона абонента.
505 Call bar service activated У абонента включен запрет на прием сообщений или абонента заблокировал оператор (возможно, в связи с отрицательным балансом).

Viber

Код ошибки Текст сообщения об ошибке Описание ошибки
601 not-viber-user У абонента нет Viber или он выключен.
605 user-bloked Абонент заблокировал прием сообщений на устройстве.
607 no-suitable-device Устройство абонента не поддерживает сервис Viber.

VK Notify

Код ошибки Текст сообщения об ошибке Описание ошибки
250 NOT ENOUGH DATA Не хватает обязательных параметров
251 INCORRECT_SIGNATURE Некорректная подпись сообщения
252 ERROR Ошибка общего характера
253 UNSUPPORTED_NUMBER Номер не поддерживается (неподдерживаемая страна или оператор)
254 INCORRECT_NUMBER Некорректный формат номера
255 NUMBER_IN_BLACK_LIST Номер абонента занесен в черный список
256 NUMBER_TYPE_NOT_ALLOWED Номер абонента виртуальный или определен как «спамерский»
357 RATELIMIT Превышен лимит отправки сообщений для данного номера
258 DAILY_RATELIMIT_FOR_RECEIVER Превышен дневной лимит отправки сообщений от группы ВКонтакте для данного номера.
259 UNSUPPORT Сообщение не может быть доставлено по одной из причин: - данного абонента (пользователя) не существует в системе; - абонент проявлял активность в системе более 7 дней назад.
260 UNSUPPORTED TEMPLATE Параметр text не соответствует ни одному шаблону.
261 UNKNOWN Неизвестный тип ошибки (возможен при получении неизвестного статуса от ВКонтакте)
262 BLOCKED_BY_USER Абонент запретил прием сообщений от данного отправителя (группы)

Push

Код ошибки Текст сообщения об ошибке Описание ошибки
700 recipient-is-locked Абонент заблокирован на платформе вручную
701 recipient-not-found Абонент не найден
705 subscription-disabled Абонент отписался от Push-уведомлений
709 certificate_expired Истек cрок действия сертификата iOS-устройства
706 device-locked Отправка Push-уведомлений на устройство абонента заблокирована
707 application-not-configured Приложение не настроено на платформе или в настройках приложения не указаны обязательные параметры
704 client_application_removed Приложение удалено с устройства абонента
703 device_not_found Устройство абонента не найдено
702 recipient-has-no-active-device Устройство абонента неактивно
708 device-unregistered Устройство не зарегистрировано на платформе

Приём сообщений от абонентов

Процесс получения входящих сообщений аналогичен получению статусов доставки. Максимальное количество единовременно запрашиваемых сообщений - 100.

URI: https://external-api.i-dgtl.ru/receiveinbound

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

curl  -H 'Content-Type: application/json'\
      -H 'Accept: application/json' \
      -H'Authorization: Basic Mzk5OTk6MTIzNjU0' \
      -d '10'\
      https://external-api.i-dgtl.ru/receiveinbound\
      -X POST

В теле запроса передаётся количество сообщений, который будут включены в ответ. Приведённом примере в ответ на запрос API вернёт 10 сообщений (-d ‘10’). Число запрашиваемых сообщений не должно превышать 100.

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

  {
  "timestamp": <дата и время формирования пакета>,
  "code": <код ответа>,
  "messages": [
    {
      "@type": "inbound",
      "properties": {},
      "creationDate": <дата и время получения сообщения>,
      "requestDelivery":<не используется>
      "addresses": {
        "source": "<имя или адрес отправителя>",
        "destination": "<адрес или номер телефона получателя>"
      },
      "body": {
        "bodyType": "<тип сообщения>",
        "content": "<текст сообщения>"
      },
      "expirationDate":<не используется>,
      "msid": "<MSID сообщения>"
    }
  ]

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

Параметр Тип Значение
timestamp timestamp Дата и время отправки сообщения (Unix Timestamp в миллисекундах)
code integer Код ответа (в случае успешного выполнения запроса - 200 OK)
messages object Объект, cодержащий принятые сообщения

Параметры сообщения в массиве

Параметр Тип Значение
@type string Тип объекта (в запросах на получение сообщений - inbound)
properties string Служебный параметр
сreationDate timestamp Дата и время создания сообщения (Unix Timestamp в миллисекундах)
addresses object Объект, содержащий адреса отправителя и получателя
source string Имя или адрес отправителя
destination string Адрес или номер телефона получателя
body object Объект, который содержит параметры bodyType и content
bodyType string Тип сообщения (SMS, e-mail, VK Notify, Viber, Push, WhatsApp)
content string Содержимое сообщения (подробнее см. в описании запросов на отправку)
msid string UUID сообщения

Коды ошибок

Код ошибки Описание
401 Ошибка авторизации
413 Превышено количество сообщений в пакете