АПИ АТС
Версия: v.0.9.15 (2024-11-14). В метод checkCall добавлен параметр ssid
Версия: v.0.9.14 (2024-09-17). Доработка данного документа в части описания заголовков. Изменений в АПИ не производилось.
Версия: v.0.9.13 (2024-03-18). Удален заголовок X-id-call (в связи с реструктуризацией системы и баз данных). ВОЗМОЖНО некий аналог будет возращен позднее и в другом виде, при востребованности
Версия: v.0.9.12 (2024-03-10). Обновлены приложения со значениями бит ошибок X-Error-Bits
Версия: v.0.9.11 (2024-03-05). Добавлено приложение со значениями бит ошибок X-Error-Bits
Версия: v.0.9.10 (2024-02-14). Добавлены дополнительные разъяснения для опциональных параметров id_src/id_dst. Добавлено описание HTTP-кодов 5хх и 307 (см. п.7 Введения)
Версия: v.0.9.9 (2024-02-07). Добавлен метод Ping
Версия: v.0.9.8 (2024-02-04). Добавление методов "help" и "numberInfo"
Версия: v.0.9.7 (2024-01-25). Обновлена секция возвращаемых значений метода "call" и секции ошибок ряда методов. Изменено описание параметра dbg и ион добавлен во все методы.
Версия: v.0.9.6 (2024-01-24). В CheckCall параметр "o" переименован в "c" (как в остальных методах и документации ГРЧЦ). В RegisterCall и CheckCall Добавлены параметры "bh" и "ch"
Версия: v.0.9.5 (2023-11-29). Обновлено описание параметра call_id метода RegisterCall (но оно актуально и для других методов)
Версия: v.0.9.4 (2023-10-25). Обновлено наименование и описание метода "3" CheckCallUpdate переименован в callUpdate
Введение.
-
Вызовы методов АПИ осуществляются HTTP POST запросами на соответствующие URL, указанные в описании каждого метода.
-
Обратите особое внимание на тот факт, что различные методы могут быть расположены на различных серверах и различных портах.
-
Во всех методах АПИ подробная информация об ошибках и предупреждениях передается в HTTP заголовках X-Error-Bits и X-Error-Messages и X-Warning-Bits и X-Warning-Messages соответственно
-
X-Error-Bits и X-Warning-Bits являются битовыми полями представленным в виде шестнадцатеричных чисел.
Пример: X-Error-Bits: 0x00000003
Каждый бит соответствует отдельной ошибке. Одновременно может быть несколько ошибок и, соответственно, выставленных бит. Тексты ошибок и их соответствие битам ошибок можно увидеть в X-Error-Messages и X-Warning-Messages соответственно при включенном режиме отладки (параметр dbg установлен и имеет "непустое" значение (предпочтительно - 1))
Пример: X-Error-Messages: [0x00000001] Required POST parameter "a" not found or empty; [0x00000002] Required POST parameter "b" not found or empty Значения бит ошибок приведены в "Приложении 1" в конце документа. -
Все заголовки с ошибками и предупреждениями выдаются только при наличии ошибок и предупреждений соответственно. Если ошибок нет - заголовок X-Error-Bits НЕ выдается. Если предупреждений нет - заголовок X-Warning-Bits НЕ выдается. Флаг dbg включает/отключает выдачу заголовков текстовых расшифровок бит сообщений/предупреждений (X-Error-Messages и X-Warning-Messages соответственно) - но, эти заголовки также выдаются только при наличии ошибок/предупреждений.
-
Важно! На старых серверах могут встречаться заголовки X-Error-Code, X-Error-Message и их сочетания. Использовать их не надо. Такое поведение оставлено в целях совместимости и по мере перевода на новые сервера такие заголовки будут удаляться.
-
Помимо указанных в описании HTTP-кодов сервер может возвращать следующие HTTP коды:
- 5хх - Все коды из данного диапазона коды являются признаком аварии сервера в целом и требуют перехода на работу с резервным сервером. Возвращение на основной сервер рекомендуется только по согласованию с техподдержкой.
- 307 - Temporary Redirect - сервер временно недоступен (техработы или другая причина). Требуется временный переход на работу с резервным сервером. Возвращение на основной сервер возможно сразу после снятия кода 307 (проверяется методом /ping)
1. RegisterCall - Регистрация звонка
Регистрация звонка осуществляется HTTP POST запросом на адрес [http://x.x.x.x:8085/RegisterCall]()
Параметры запроса:
Запрос должен иметь следующие параметры:
- "a" - [число][обязательный] - номер с которого осуществляется вызов
- "b" - [число][обязательный] - номер на который осуществляется вызов
- "bh" - [строка][опциональный] - номер на который осуществляется вызов (в виде хеша) (при наличии - параметр "b" игнорируется)
- "id_dst" - [строка][опциональный] - Идентификатор оператора связи, в сеть которого (в чей транк) осуществляется пропуск трафика для соединения, согласно справочнику
- "call_id" - [строка][опциональный] - Идентификатор звонка. Минимальная длина - 1, однако, это плохой вариант, т.к. должна обеспечиваться уникальность хотя-бы в течение суток. Максимальная длина 100 символов. Ограничено ГРЧЦ ( 1137847334745.63.11.1.2023 10 .1.001.ПВ.01). Набор символов в базе колхоза utf8mb4. Но! Скажем, если вы используете Content-Type: application/x-www-form-urlencoded то нужно учитывать его ограничения, равно как и прочие ограничения метода POST протокола HTTP. Если нужны служебные или двоичные символы - используйте multipart/form-data. Учитывайте также, что ГРЧЦ НЕ указал в своей документации допустимые кодировки и наборы символов. И для "экзотики" могут возникнуть проблемы с инцидентами и историческими данными, куда это поле выгружается.
- "dbg" - [0,1][опциональный] - Если параметр присутствует и равен 1 - то в заголовке X-Error-Messages будет возвращена подробная отладочная информация. Если параметр в запросе отсутствует или равен 0 - отладочная информация не выдается
[TBD] - будут наложены regex ограничения на оба параметра
Дополнительные условия:
- Оператор-владелец номера "а" должен быть членом "колхоза"
- IP-адрес, с которого осуществляется вызов данной функции, должен быть закреплен за оператором, которому по базе ГРЧЦ принадлежит номер "а".
- Важно! Параметр id_dst является опциональными. Регистрация и последующая верификация звонка успешно пройдут и без него. Однако! Его корректное заполнение необходимо для прохождения комплекта тестов ГРЧЦ связанных со статистикой/инцидентами.
Возвращаемые значения:
- В случае успешной регистрации система вернет HTTP Status code: 201 Created
- В случае ошибки запрос вернет HTTP Status code: 400 Bad Request. Подробная информация об ошибке в этом случае передается в HTTP заголовках X-Error-Bits
2. CheckCall - Проверка звонка
Проверка звонка осуществляется HTTP POST запросом на адрес [http://x.x.x.x:8085/CheckCall]()
Параметры запроса:
Запрос может иметь следующие параметры:
- "a" - [строка][обязательный] - номер в формате E.164 с которого осуществляется вызов. Пример: "74957846459" (без кавычек)
- "b" - [строка][обязательный] - номер в формате E.164 на который осуществляется вызов. Пример: "74957846459" (без кавычек)
- "bh" - [строка][опциональный] - номер на который осуществляется вызов (в виде хеша) (при наличии - параметр "b" игнорируется)
- "c" - [строка][опциональный] - originate - первоначальное значение номера вызываемого абонента до переадресации (при ее наличии) в формате E.164 Пример: "74857846459" (без кавычек)
- "ch" - [строка][опциональный] - номер на который осуществляется вызов (в виде хеша) (при наличии - параметр "c" игнорируется)
- "d" - [число][опциональный] - Дополнительный номер абонента, в формате E.164
- "id_src" - [строка][опциональный] - Идентификатор оператора связи, из сети (с транка) которого осуществляется пропуск трафика для соединения, согласно справочнику
- "id_dst" - [строка][опциональный] - Идентификатор оператора связи, в сеть которого (в чей транк) осуществляется пропуск трафика для соединения, согласно справочнику
- "call_id" - [строка][опциональный] - Идентификатор звонка. Внимание! Параметр опционален только если указан id_src, в противном случае он является обязательным, так как требуется для последующего вызова CheckCallUpdate. Значение генерируется оператором и должно быть уникальным для оператора как минимум в течении 12 часов с момента вызова
- "dbg" - [0,1][опциональный] - Если параметр присутствует и равен 1 - то в заголовке X-Error-Messages будет возвращена подробная отладочная информация. Если параметр в запросе отсутствует или равен 0 - отладочная информация не выдается
- "ssid" - [0,1][опциональный] - Если параметр присутствует и равен 1 И запрос завершился с вердиктом "вызов не найден" (HTTP Status code: 404 Not found) - то в заголовке X-ssid будет возвращен sessionId запроса к УВр (необходим для обращения к владельцу УВр для выяснения причин, по которым звонок не был подтвержден)
Внимание! Выдача отладочной информации не является гарантированной функцией и может быть отключена в любое время без предупреждения.
[TBD] - будут наложены regex ограничения на все параметры
Возвращаемые значения:
- В случае успешной проверки вызова система вернет HTTP Status code: 200 OK
- В случае если вызов отвечающий заданным критериям не найден - запрос вернет HTTP Status code: 404 Not found.
- В случае ошибки при обработке запрос вернет HTTP Status code: 400 Bad Request Подробная информация об ошибке в этом случае передается в HTTP заголовках X-Error-Bits и X-Error-Messages
Дополнительные условия:
- IP-адрес, с которого осуществляется вызов данной функции, должен быть закреплен за оператором, которому по базе ГРЧЦ принадлежит номер "b".
- Важно! Параметры id_src/id_dst являются опциональными. Верификация пройдет и без них. Но! Их корректное заполнение потребуется для прохождения комплекта тестов ГРЧЦ связанных со статистикой/инцидентами. Для прохождения тестов верификации необходимым является id_src
3. callUpdate - В ДАННЫЙ МОМЕНТ НЕ ИСПОЛЬЗУЕТСЯ, НО ПЛАНИРУЕТСЯ К ИСПОЛЬЗОВАНИЮ ПОЗДНЕЕ Дополнение/обновление данных проверки звонка ранее созданного с помощью CheckCall или Call
Дополнение либо обновление данных уже проверенного с помощью CheckCall или Call звонка осуществляется HTTP POST запросом на адрес [http://x.x.x.x:8085/callUpdate]()
Вызов данного метода обязателен для случаев, когда при вызове CheckCall или Call не были переданы параметры id_src, id_dst либо для указания длительности звонка DUR (если вызов был пропущен) либо указания TA для транзитных вызовов
Параметры запроса:
Запрос должен иметь следующие параметры:
- "CALL_ID" - [строка][обязательный] - Идентификатор звонка указанный при проверке звонка (CheckCall)
- "ID_SRC" - [число][опциональный] - Идентификатор оператора связи, из сети (с транка) которого осуществляется пропуск трафика для соединения, согласно справочнику
- "ID_DST" - [число][опциональный] - Идентификатор оператора связи, в сеть которого (в чей транк) осуществляется пропуск трафика для соединения, согласно справочнику
- "DUR" - [число][опциональный] - DURATION - Длительность вызова в секундах
- "RС" - [число][опциональный] - RELEASE_CODE - Код отбоя
- "TA" - [число][опциональный] - T_ACTION_CODE - Статус прохождения вызова. Обязательно для транзитного оператора. Возможные значения см. "Протокол-взаимодействия-ЦУ-УВр"
- "dbg" - [0,1][опциональный] - Если параметр присутствует и равен 1 - то в заголовке X-Error-Messages будет возвращена подробная отладочная информация. Если параметр в запросе отсутствует или равен 0 - отладочная информация не выдается
Возвращаемые значения:
- В случае успешного обновления данных проверки вызова система вернет HTTP Status code: 200 OK
- В случае если вызов отвечающий заданным критериям не найден - запрос вернет HTTP Status code: 404 Not found.
- В случае ошибки при обработке запрос вернет HTTP Status code: 400 Bad Request Подробная информация об ошибке в этом случае передается в HTTP заголовках X-Error-Bits и X-Error-Messages
Важно! Несмотря на то, что эти данные не требуются непосредственно для проверки звонка, они необходимы для корректного формирования инцидентов, статистики и ответов на запросы о соединении.
Важно! Настоятельно рекомендуется вызывать метод не более чем через 5 минут после вызова CheckCall или Call. В противном случае данные не попадут в формируемую статистику и инциденты!
Важно! В силу технологических особенностей работы оборудования оператора id_src, id_dst и DUR могут появляться в различное время. В случае если интервал появления более одной минуты (например, длительность звонка может стать доступна только по окончании вызова) настоятельно рекомендуется делать несколько вызовов, по мере появления данных, указывая те параметры, которые становятся известны. Наиболее важным является параметр id_src. Его следует заполнять как можно раньше. Т.к. он является обязательным для формирования статистики и инцидентов.
Важно! Метод допускается применять только для вызовов, совершенных не более чем 12 часов назад от текущего момента. Более ранние вызовы обновлены быть не могут.
4. Сall - Универсальный вызов (Предварительная версия! Будет изменяться!)
Осуществляется HTTP POST запросом на адрес [http://x.x.x.x:8085/сall]()
[TBD (To Be Determined)] Адрес будет изменяться
Параметры запроса:
Запрос должен иметь следующие параметры:
- "a" - [число][обязательный] - номер с которого осуществляется вызов
- "b" - [число][обязательный] - номер на который осуществляется вызов
- "bh" - [строка][опциональный] - номер на который осуществляется вызов (в виде хеша)
- "c" - [число][опциональный] - originate - первоначальное значение номера вызываемого абонента до переадресации (при ее наличии) в формате E.164 Пример: "74857846459" (без кавычек)
- "ch" - [строка][опциональный] - originate - первоначальное значение номера вызываемого абонента до переадресации (при ее наличии) в формате E.164 (в виде хеша)
- "d" - [число][опциональный] - Дополнительный номер абонента, в формате E.164
- "id_src" - [число][опциональный] - Идентификатор оператора связи, из сети (с транка) которого осуществляется пропуск трафика для соединения, согласно справочнику
- "id_dst" - [число][опциональный] - Идентификатор оператора связи, в сеть которого (в чей транк) осуществляется пропуск трафика для соединения, согласно справочнику
- "call_id" - [строка][опциональный] - Идентификатор звонка
- "dbg" - [0,1][опциональный] - Если параметр присутствует и равен 1 - то в заголовке X-Error-Messages будет возвращена подробная отладочная информация. Если параметр в запросе отсутствует или равен 0 - отладочная информация не выдается
- "ssid" - [0,1][опциональный] - Актуально ТОЛЬКО для входящих вызовов. Если параметр присутствует и равен 1 И запрос завершился с вердиктом "вызов не найден" (HTTP Status code: 404 Not found) - то в заголовке X-ssid будет возвращен sessionId запроса к УВр (необходим для обращения к владельцу УВр для выяснения причин, по которым звонок не был подтвержден)
- Вызов считается исходящим и регистрируется в системе, если идентификатор оператора номера "а" в таблице numbers совпадает с идентификатором оператора определенным по его IP адресу. Во всех остальных случаях вызов считается исходящим и проверяется в общем порядке.
- В отличие от остальных функций, некоторые операции НЕ прерываются сразу при обнаружении ошибок. Поэтому функция возвращает не единичный код ошибки, а битовое поле, в котором может быть заполнено сразу несколько бит ошибок.
- Важно! Параметры id_src/id_dst являются опциональными. Регистрация/верификация пройдут и без них. Но! Их корректное заполнение потребуется для прохождения комплекта тестов ГРЧЦ связанных со статистикой/инцидентами. Для прохождения тестов при регистрации звонка требуется корректно заполненный id_dst. Для верификации - id_src
Возвращаемые значения:
- В случае успешной проверки возвращается HTTP Status code: 200 OK
- В случае успешной регистрации система вернет HTTP Status code: 201 Created
- В случае если вызов отвечающий заданным критериям не найден - запрос вернет HTTP Status code: 404 Not found.
- В случае ошибок возвращается HTTP Status code: 400 Bad Request Подробная информация об ошибках в виде двоичных флагов возвращается в HTTP заголовке X-Error-Bits (значения бит будут описаны позднее) Текстовые сообщения об ошибках можно получить если параметр dbg установлен в "1"
5. Help - получение актуальной версии описания АПИ (этого файла)
Осуществляется HTTP POST (допускается GET) запросом на адрес [http://x.x.x.x:8085/help]()
Параметры запроса:
Запрос не имеет параметров
Возвращаемые значения:
Описание АТС АПИ в виде файла формата markdown (*.md) Важно! Содержимое файла возвращается БЕЗ заголовка Content-Disposition. Таким образом, режим отображения (inline или attachment) определяется клиентом
6. numberInfo - получение информации о номере из актуальных на данный момент справочников ГРЧЦ (NUM и OPR объединенных по полю id_src)
Осуществляется HTTP POST запросом на адрес [http://x.x.x.x:8085/numberInfo]()
Параметры запроса:
- "n" - [число][обязательный] - номер, информацию о котором требуется получить
Возвращаемые значения:
-
200 Ok - успешное выполнение Возвращаемым значением является JSON следующей структуры:
{ "data": { "created": "2024-01-19 07:50:13", "number": 79316043317, "id_uvr_p": 7, "id_uvr_s": null, "id_src": 11469, "INN": "7812014560", "IP_UVR_P_P": "1.1.1.1", "IP_UVR_P_S": "1.1.1.1", "IP_UVR_S_P": null, "IP_UVR_S_S": null } } -
404 Not Found. Номер не найден в numbers В теле ответа возвращается json вида
{ "data": null }
6. Ping - проверка доступности сервера АПИ по HTTP
Осуществляется HTTP POST (допускается GET) запросом на адрес [http://x.x.x.x:8085/ping]()
Позволяет убедиться в доступности самого сервера АПИ и доступности БД требующихся для его работы.
Параметры запроса:
Запрос не имеет параметров
Возвращаемые значения:
- В случае успешной проверки возвращается HTTP Status code: 200 OK
- В случае ошибок возвращается HTTP Status code: 400 Bad Request
Приложение 1. Биты ошибок (X-Error-Bits) для методов registerCall/checkCall/callUpdate
Внимание! Приводятся только для справки. До версии 1.0.0 могут изменяться без предупреждения!
const PARAM_A_NOT_FOUND = 1 << 0;
const PARAM_B_NOT_FOUND = 1 << 1;
const PARAM_A_NOT_INT = 1 << 2;
const PARAM_B_NOT_INT = 1 << 3;
const PARAM_B_HASH_BAD_REGEX = 1 << 4;
const PARAM_C_NOT_INT = 1 << 5;
const PARAM_C_HASH_BAD_REGEX = 1 << 6;
const PARAM_D_NOT_INT = 1 << 7;
const CLIENT_ID_SRC_EMPTY = 1 << 8;
const A_ID_SRC_IS_EMPTY = 1 << 9;
const A_NOT_FOUND_IN_DB = 1 << 10;
const A_UVR_IS_EMPTY_OR_SERVICE = 1 << 11;
const USER_UVR_NOT_FOUND = 1 << 12;
const USER_HUB_P_NOT_FOUND = 1 << 13;
const GRFC_CHECK_UVR_FAILED = 1 << 14;
const FREE_15 = 1 << 15;
const FREE_16 = 1 << 16;
const FREE_17 = 1 << 17;
const FREE_18 = 1 << 18;
const FREE_19 = 1 << 19;
const FREE_20 = 1 << 20;
const FREE_21 = 1 << 21;
const FREE_22 = 1 << 22;
const NOT_A_OWNER = 1 << 23;
const PARAM_A_NOT_RUS = 1 << 24;
const GRFC_DB_ERROR = 1 << 25;
const UVR_RESPONSE_TIMEOUT = 1 << 26;
const FREE_27 = 1 << 27;
const FREE_28 = 1 << 28;
const FREE_29 = 1 << 29;
const FREE_30 = 1 << 30;
const EXCEPTION = 1 << 31;
const MESSAGES = [
self::PARAM_A_NOT_FOUND => 'Required POST parameter "a" not found or empty',
self::PARAM_A_NOT_INT => 'POST parameter "a" can not be converted to int',
self::PARAM_B_NOT_FOUND => 'Required POST parameter "b" not found or empty',
self::PARAM_B_NOT_INT => 'POST parameter "b" can not be converted to int',
self::PARAM_B_HASH_BAD_REGEX => 'The POST parameter "bh" does not match the template: ' . UVrPage::PARAM_HASH_REGEX,
self::PARAM_C_NOT_INT => 'POST parameter "c" can not be converted to int',
self::PARAM_C_HASH_BAD_REGEX => 'The POST parameter "ch" does not match the template: ' . UVrPage::PARAM_HASH_REGEX,
self::PARAM_D_NOT_INT => 'POST parameter "d" can not be converted to int',
self::CLIENT_ID_SRC_EMPTY => 'Can\'t determine client\'s ID_SRC (by his IP)',
self::A_ID_SRC_IS_EMPTY => 'ID_SRC field of the "a" number is empty',
self::A_NOT_FOUND_IN_DB => 'The "a" number not found in database',
self::A_UVR_IS_EMPTY_OR_SERVICE => 'The primary UVr of "a" number is empty or service (<1 OR >16000)',
self::USER_UVR_NOT_FOUND => 'Can not find user UVr settings in "uvr" table. Probably, you requesting wrong server',
self::USER_HUB_P_NOT_FOUND => 'The users primary hub of primary UVr not found in "hub" table',
self::GRFC_CHECK_UVR_FAILED => 'The request to GRFC\'s "8081/CheckUvr" API failed',
self::NOT_A_OWNER => 'You are not owner of the "a" number',
self::PARAM_A_NOT_RUS => 'The "a" number does not match the template: ' . UVrPage::RUS_NUM_REGEX,
self::UVR_RESPONSE_TIMEOUT => 'The UVr response timeout exceeded',
self::EXCEPTION => 'An exception occurred during code execution'
];Приложение 2. Биты ошибок (X-Error-Bits) для VerifyCallState (могут быть проброшены клиентам через УВз, а могут и не быть... В любом случае, биты отличаются от основных методов АПИ)
case UVR_REQUEST_IS_EMPTY = 1 << 1;
case UVR_REQUEST_FIELD_NOT_FOUND = 1 << 2;
case UVR_REQUEST_SUBFIELD_NOT_FOUND = 1 << 3;
case UVR_REQUEST_UNSUPPORTED_SERVICE_KEY = 1 << 4;
case UVR_REQUEST_INVALID_UVR_O = 1 << 5;//'Invalid value of the "uvrO" parameter'
case UVR_REQUEST_INVALID_UVR_T = 1 << 6;//'Invalid value of the "uvrT" parameter'
case UVR_REQUEST_INVALID_SESSION_ID = 1 << 7;//'Invalid value of the "sessionId" parameter'
case UVR_REQUEST_INVALID_OPCODE = 1 << 8;//'Invalid value of the "opcode" parameter'
case UVR_REQUEST_INVALID_DATA = 1 << 9;//'Invalid value of the "data" parameter'
case A_NOT_FOUND_IN_DB = 1 << 10;
case UVR_REQUEST_SESSION_KEY_NOT_FOUND = 1 << 11;
case UVR_REQUEST_DATA_CALLING_PARTY_NUMBER_NOT_FOUND = 1 << 12;
case UVR_REQUEST_DATA_CALLED_PARTY_NUMBER_NOT_FOUND = 1 << 13;
case A_NOT_SERVED_BY_UVR = 1 << 14;
case PARAM_A_NOT_RUS = 1 << 15;
VerifyErrorEnum::UVR_REQUEST_IS_EMPTY->value => 'The HTTP request body is empty',
VerifyErrorEnum::UVR_REQUEST_FIELD_NOT_FOUND->value => 'The required json parameter "request" was not found',
VerifyErrorEnum::UVR_REQUEST_SESSION_KEY_NOT_FOUND->value => 'The required parameter ["request"]["data"]["sessionKey"] was not found',
VerifyErrorEnum::UVR_REQUEST_DATA_CALLING_PARTY_NUMBER_NOT_FOUND->value => 'The required parameter ["request"]["data"]["callingPartyNumber"] was not found',
VerifyErrorEnum::UVR_REQUEST_DATA_CALLED_PARTY_NUMBER_NOT_FOUND->value => 'The required parameter ["request"]["data"]["calledPartyNumber"] was not found',
VerifyErrorEnum::A_NOT_FOUND_IN_DB->value => 'The "a" number not found in "numbers"'