Обновление данных об операторах
Веб-сервис позволяет получать информацию о телефонных номерах и обслуживающих их операторах мобильной связи, включая данные о номерах, для которых был изменен оператор. Сервис основан на HTTP API.
Клиент может использовать эти данные, чтобы создать и обновлять собственный экземпляр справочника номеров с целью минимизации затрат на SMS-рассылки.
Клиент отправляет POST-запрос, в теле которого содержится пакет provideOperatorRequest в формате XML или JSON с номером версии обновления дан ных MNP. Платформа обрабатывает запрос клиента и отправляет ответный пакет provideOperatorResponse, содержащий структурированную информацию об операторах и телефонных номерах.
URL-адрес подключения сообщается клиенту после заключения договора на использование сервиса
В работе с сервисом следует учитывать ограничение на количество обновлений, которые обрабатываются платформой при формировании ответа на запрос. Поэтому для создания своего экземпляра справочника номеров необходимо последовательно запрашивать обновления – с первого до последнего на текущий момент. В дальнейшем справочник рекомендуется обновлять регулярно – не реже раза в сутки.
Выбор формата передачи данных
Формат передачи данных определяется заголовком HTTP-запроса Content-Type. Допустимые значения: application/xml или application/json.
Если в запросе не указано значение заголовка Content-Type, заголовок имеет значение application/xml или заголовок имеет значение отличное от application/json — сервер будет ожидать запрос в формате XML. Ответ будет также возвращён в формате XML.
Пакет provideOperatorRequest
В секции payload POST-запроса provideOperatorRequest передается обязательный параметр fromVersion – номер версии обновления, начиная с которой требуются данные MNP.
В ответном пакете выводятся данные не более чем 10000 обновлений, начиная с указанной в запросе версии.
Примеры пакета
<!-- XML -->
<provideOperatorRequest>
<header>
<auth>
<login>test</login>
<password>test</password>
</auth>
</header>
<payload>
<fromVersion>123</fromVersion>
</payload>
</provideOperatorRequest>
//JSON
{
"provideOperatorRequest": {
"header": {
"auth": {
"login": "test",
"password": "test"
}
},
"payload": {
"fromVersion": "123"
}
}
}
Пакет provideOperatorResponse
В случае успешной обработки запроса платформа возвращает пакет provideOperatorResponse с результатами в секции payload: статусом выполнения запроса, данными об операторах и телефонных номерах. При некорректном синтаксисе запроса или недоступности сервиса возвращается пакет errorResponse с кодом error-syntax или error-system.
Параметры пакета
| Параметр | Тип | Характер | Описание |
|---|---|---|---|
payload/code | String | Обязательный | Статус выполнения запроса. Возможные значения: - ok – запрос выполнен;- error-auth – ошибка авторизации;- error-forbidden– недостаточно прав для вызова метода;- error-from-version-format– некорректный формат параметра fromVersion. |
payload/countryList | Object | Обязательный | Список стран. |
.../countryList/country | Object | Обязательный | Структура с информацией о стране оператора. |
.../country/code | String | Обязательный | Кодовое обозначение страны в БД. |
.../country/name | String | Необязательный | Название страны. |
.../country/description | String | Необязательный | Описание страны. |
.../country/operatorList | Object | Обязательный | Структура с данными операторов связи. |
.../operatorList/operator | Object | Обязательный | Структура с данными оператора связи. |
.../operator/code | String | Обязательный | Код оператора в БД. |
.../operator/name | String | Необязательный | Название оператора. |
.../operator/description | String | Необязательный | Дополнительная информация об операторе. |
.../operator/standard | String | Необязательный | Стандарт мобильной связи. Пример: gsm. |
.../operator/unitList | Object | Обязательный | Список территориальных подразделений оператора. |
.../unitList/unit | Object | Обязательный | Структура с данными территориального подразделения оператора. |
.../unit/code | String | Обязательный | Кодовое обозначение подразделения в БД. |
.../unit/name | String | Необязательный | Название подразделения (юридического лица). Пример: ОАО "Мобильные ТелеСистемы". |
.../unit/description | String | Необязательный | Дополнительная информация о подразделении. |
.../unit/regionList | Object | Обязательный | Список регионов. |
.../regionList/region | Object | Обязательный | Структура с данными региона, к которому относится номер абонента. |
.../region/code | String | Обязательный | Кодовое обозначение региона в БД. |
.../region/name | String | Необязательный | Название региона. Пример: Саратовская область. |
.../region/description | String | Необязательный | Дополнительная инфо рмация о регионе. |
.../region/timeZone | String | Обязательный | Часовой пояс региона. Пример: Europe/Samara. |
.../region/prefixList | Object | Обязательный | Список телефонных номеров, переведенных в территориальное подразделение оператора. |
.../prefixList/prefix | Object | Обязательный | Данные телефонного номера. |
.../prefix/code | Int | Обязательный | Уникальный код префикса. |
.../prefix/name | String | Обязательный | Название префикса. Обычно совпадает с кодом. |
.../prefix/description | String | Необязательный | Дополнительная информация о префиксе. |
.../prefix/addressPrefix | String | Обязательный | Значение префикса– начальная часть или полный телефонный номер. Все номера, начинающиеся с этого префикса, относятся к одному оператору и региону. Примеры префиксов: 7981860, 79261234567. |
.../prefix/mnp | Boolean | Обязательный | Если true, то в ответе платформы возвращен полный номер, для которого был изменен оператор. Если false, то возвращена начальная часть, с которой начинаются несколько номеров. |
.../prefix/remove | Boolean | Обязательный | Если false, то значение префикса актуально. Если true, то префикс устарел и его не следует учитывать. |
.../prefix/version | Int | Обязательный | Версия обновления. |
Примеры пакета
<!-- XML -->
<provideOperatorResponse>
<header/>
<payload>
<code>ok</code>
<countryList>
<country>
<code>ru</code>
<name>Россия</name>
<description>Россия</description>
<operatorList>
<operator>
<code>ru-megafon</code>
<name>МегаФон</name>
<description>МегаФон</description>
<standard>gsm</standard>
<unitList>
<unit>
<code>ru-megafon-megafon_ural</code>
<name>ОАО "Мегафон" Уральский филиал</name>
<description>ОАО "Мегафон" Уральский филиал</description>
<regionList>
<region>
<code>ru-megafon-megafon_ural-sverdlovskaya_oblast</code>
<name>Свердловская область</name>
<description>Свердловская область</description>
<timeZone>Asia/Yekaterinburg</timeZone>
<prefixList>
<prefix>
<code>79122369285</code>
<name>79122369285</name>
<description>mnp</description>
<addressPrefix>79122369285</addressPrefix>
<mnp>true</mnp>
<remove>false</remove>
<version>80419</version>
</prefix>
<prefix>
<code>79122370644</code>
<name>79122370644</name>
<description>mnp</description>
<addressPrefix>79122370644</addressPrefix>
<mnp>true</mnp>
<remove>false</remove>
<version>80421</version>
</prefix>
</prefixList>
</region>
</regionList>
</unit>
</unitList>
</operator>
</operatorList>
</country>
</countryList>
</payload>
</provideOperatorResponse>
// JSON
{
"provideOperatorResponse": {
"header": {},
"payload": {
"code": "ok",
"countryList": [
{
"code": "ru",
"name": "Россия",
"description": "Россия",
"operatorList": [
{
"code": "ru-mts",
"name": "МТС",
"description": "М ТС",
"standard": "gsm",
"unitList": [
{
"code": "ru-mts-mts",
"name": "ОАО \"Мобильные ТелеСистемы\"",
"description": "ОАО \"Мобильные ТелеСистемы\"",
"regionList": [
{
"code": "ru-mts-mts-omskaya_oblast",
"name": "Омская область",
"description": "Омская область",
"timeZone": "Asia/Novosibirsk",
"prefixList": [
{
"code": "79502193645",
"addressPrefix": "79502193645",
"name": "79502193645",
"description": "mnp",
"mnp": true,
"remove": false,
"version": 86250
},
{
"code": "79095355525",
"addressPrefix": "79095355525",
"name": "79095355525",
"description": "mnp",
"mnp": true,
"remove": false,
"version": 90791
},
"..."
]
}
]
}
]
}
]
}
]
}
}
}
Ответ в случае некорректного формата запроса.
Если провайдер не может обработать запрос, он отправляет в ответ пакет errorResponse с кодом ошибки.
<!-- XML -->
<errorResponse>
<header/>
<payload>
<code>error-syntax</code>
</payload>
</errorResponse>
// JSON
{
"errorResponse": {
"header": {},
"payload": {
"code": "error-system"
}
}
}