MNP

1. Загальна інформація

Сервіс MNP Lookup призначений для визначення поточного оператора обслуговування, країни та статусу перенесення мобільного номера.

Інтеграція доступна двома способами: через HTTP API та ENUM API.

Сервіс підтримує автентифікацію за IP-адресою та портом і надає тестові ендпоінти для перевірки коректності інтеграції.

2. HTTP API

2.1. Автентифікація

Запити до HTTP API потребують автентифікації, щоб ідентифікувати клієнта, повертати коректні результати та гарантувати безпеку.

Автентифікація базується на IP-адресі клієнта, вказаній у його профілі, та порті, який використовується під час запиту.

Перед використанням HTTP API для запитів MNP Lookup (як у тестовому, так і в продакшн-середовищі) клієнт має передати список IP-адрес своєму акаунт-менеджеру для автентифікації.

2.2. Формат запиту

Продакшн:

*HTTP API також дозволяє обрати тариф, передавши його код у запиті (необовʼязково, лише для клієнтів із кількома тарифами).

Тестування:

{NUMBER} — це MSISDN (номер телефону в міжнародному форматі) без знака «+».

{TARIFF_ID} — це код тарифу в системі BSG.

2.3. Отримання результату MNP Lookup для номера

Опис: Повертає інформацію про мобільний номер: країну, MCC/MNC, поточного оператора обслуговування, індикатор перенесення номера та додаткові атрибути (докладніше див. розділ 5).

2.3.1. Приклад запиту (продакшн):

Стандартний запит:

https://mnp.bsg.world:5010/msisdn/380123456789
              

Запит із тарифом (необовʼязково):

https://mnp.bsg.world:5010/msisdn/380123456789/tariff/22
              

2.3.2. Приклад запиту (тестування):

https://mnp-test.bsg.world:5012/msisdn/380123456789
              

2.3.3. Приклад відповіді

Успіх:

{
  "tn": "380123456789",
  "cc": "UA",
  "cn": "lifecell",
  "mcc": "255",
  "mnc": "06",
  "sii": 1,
  "npi": false,
  "nt": "mobile",
  "rc": "000"
}
              

Помилка (діапазони Reason Code 010 - 070):

{
  "rc": "010"
}
              

Примітка: визначення полів відповіді див. у розділах 5–6.

3. ENUM API

3.1. Автентифікація

Запити до ENUM API потребують автентифікації, щоб ідентифікувати клієнта, повертати коректні результати та гарантувати безпеку.

Автентифікація базується на IP-адресі клієнта, вказаній у його профілі, та порті, який використовується під час запиту.

Перед використанням ENUM API для запитів MNP Lookup (як у тестовому, так і в продакшн-середовищі) клієнт має передати список IP-адрес своєму акаунт-менеджеру для автентифікації.

3.2. Формат запиту

Продакшн:

Тестування:

{NUMBER} — це MSISDN (номер телефону в міжнародному форматі) без знака «+».

Примітка: MSISDN у запиті слід записати у зворотному порядку, розділяючи цифри крапками (напр., 380123456789 → 9.8.7.6.5.4.3.2.1.0.8.3.).

3.3. Отримання результату MNP для номера

Опис: Повертає інформацію про мобільний номер: країну, MCC/MNC, поточного оператора обслуговування, індикатор перенесення номера та додаткові атрибути (докладніше див. розділ 5).

3.3.1. Приклад запиту (продакшн):

dig @141.95.255.235 -p 5000 -t naptr 9.8.7.6.5.4.3.2.1.0.8.3.enum
              

3.3.2. Приклад запиту (тестування):

dig @141.95.255.235 -p 5002 -t naptr 9.8.7.6.5.4.3.2.1.0.8.3.enum
              

3.3.3. Приклад відповіді:

Успіх:

; <<>> DiG 9.20.4-3ubuntu1.2-Ubuntu <<>> @141.95.255.235 -p 5000 -t naptr 9.8.7.6.5.4.3.2.1.0.8.3.enum
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 49443
;; flags: qr; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 0

;; QUESTION SECTION:
;9.8.7.6.5.4.3.2.1.0.8.3.enum.   IN      NAPTR

;; ANSWER SECTION:
9.8.7.6.5.4.3.2.1.0.8.3.enum. 300 IN    NAPTR   100 10 "U" "E2U+pstn:tel" "!^.*$!tn:380123456789;cc:UA;cn:lifecell;mcc:255;mnc:06;sii:2;npi:false;nt:mobile;rc:000!" .

;; Query time: 53 msec
;; SERVER: 141.95.255.235#5000(141.95.255.235) (UDP)
;; WHEN: Tue Aug 11 11:11:11 EEST 2025
;; MSG SIZE  rcvd: 167
              

Помилка (діапазони Reason Code 010 - 070):

; <<>> DiG 9.20.4-3ubuntu1.2-Ubuntu <<>> @141.95.255.235 -p 5000 -t naptr 9.8.7.6.5.4.3.2.1.0.8.3.enum
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 30411
;; flags: qr; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 0

;; QUESTION SECTION:
;9.8.7.6.5.4.3.2.1.0.8.3.enum.   IN      NAPTR

;; ANSWER SECTION:
9.8.7.6.5.4.3.2.1.0.8.3.enum. 300 IN    NAPTR   100 10 "U" "E2U+pstn:tel" "!^.*$!rc:013!" .

;; Query time: 48 msec
;; SERVER: 141.95.255.235#5000(141.95.255.235) (UDP)
;; WHEN: Tue Aug 11 11:11:11 EEST 2025
;; MSG SIZE  rcvd: 78
              

Примітка: визначення полів відповіді див. у розділах 5–6.

4. Тестування налаштування інтеграції

Для перевірки інтеграції з HTTP та ENUM API доступні тестові ендпоінти. Вони дозволяють перевірити авторизацію, зʼєднання та коректність формату запитів і відповідей.

Як і в продакшні, доступ до тестового середовища надається лише попередньо переданим IP-адресам клієнта.

Примітка: подробиці про тестові ендпоінти див. у розділах 2.2. і 3.2.

Примітка: тестові відповіді не містять реальних даних абонентів і включають таку інформацію:

• cc — реальний, визначається за префіксом запитуваного номера;

• решта параметрів (cn, mcc, mnc, sii, npi, nt, rc тощо) — не реальні, тестові значення.

5. Поля відповіді MNP Lookup

6. Reason Code

Поле Reason Code rc надає додаткову інформацію про те, як запит було оброблено в системі BSG. Ці коди можуть вказувати на причини помилки (наприклад, некоректну довжину номера) або містити іншу корисну інформацію.

У таблиці нижче наведено поточні значення поля; перелік розширюватиметься з появою нових кодів причин або сервісів.