Number Verifier

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

Сервіс Number Verifier призначений для перевірки мобільних номерів: він визначає їхній поточний статус у мережі, чинного оператора, країну та ознаку перенесення номера.

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

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

2. HTTP API

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

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

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

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

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

Робоче середовище:

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

Тестове середовище:

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

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

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

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

2.3.1. Приклад запиту (робоче середовище):

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

https://hlr.bsg.world:5011/msisdn/380123456789
              

Необовʼязковий запит (із кодом тарифу):

https://hlr.bsg.world:5011/msisdn/380123456789/tariff/22
              

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

https://hlr-test.bsg.world:5013/msisdn/380123456789
              

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

Успіх:

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

Помилка (лише для діапазону Reason Code 100 - 199):

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

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

{
  "rc": "010"
}
              

Примітка: опис полів відповіді наведено в розділах 5–7.

3. ENUM API

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

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

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

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

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

Робоче середовище:

Тестове середовище:

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

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

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

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

3.3.1. Приклад запиту (робоче середовище):

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

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

dig @141.95.255.235 -p 5003 -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 5001 -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: 38477
;; 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:1;npi:false;nt:mobile;ls:000;rc:000!" .

;; Query time: 32 msec
;; SERVER: 141.95.255.235#5001(141.95.255.235) (UDP)
;; WHEN: Tue Aug 11 11:11:11 EEST 2025
;; MSG SIZE  rcvd: 174
              

Помилка (лише для діапазону Reason Code 100 - 199):

; <<>> DiG 9.20.4-3ubuntu1.2-Ubuntu <<>> @141.95.255.235 -p 5001 -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: 44972
;; 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:1;npi:false;nt:mobile;ls:201;rc:120!" .

;; Query time: 38 msec
;; SERVER: 141.95.255.235#5001(141.95.255.235) (UDP)
;; WHEN: Tue Aug 11 11:11:11 EEST 2025
;; MSG SIZE  rcvd: 174
              

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

; <<>> DiG 9.20.4-3ubuntu1.2-Ubuntu <<>> @141.95.255.235 -p 5001 -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: 80127
;; 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: 51 msec
;; SERVER: 141.95.255.235#5001(141.95.255.235) (UDP)
;; WHEN: Tue Aug 11 11:11:11 EEST 2025
;; MSG SIZE  rcvd: 78
              

Примітка: опис полів відповіді наведено в розділах 5–7.

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

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

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

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

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

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

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

5. Поля відповіді Number Verifier

6. Статус активності (Live Status)

Поле Статус активності (ls) показує, чи активний мобільний номер у мережі на цей момент. Сервіс динамічно опитує HLR (Home Location Register) цільового оператора через мережу SS7, щоб перевірити статус мобільного номера й отримати інформацію про відповідного абонента.

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

7. Код причини (Reason Code)

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

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