Описание методов API

 

Для получения дополнительной информации пишите:partners@runexis.ru

Введение

Всё взаимодействие с сервером АПИ осуществляется по протоколу JSON-RPC. Данные отправляются на сервер через POST запросы. 

Примеры

Пример 1 Вызовы методов из PHP-кода

/**
*	Функция получения содержимого страницы.
*
*	@return Содержимое страницы.
*/
function			send_post_request( $Host , $URL , $PostParameters )
{
	$Params = array();
	foreach( $PostParameters as $Key => $Value )
	{
		$Params [] = $Key.'='.$Value;
	}

	$Curl = curl_init();
	curl_setopt( $Curl , CURLOPT_FOLLOWLOCATION , 1 );
	curl_setopt( $Curl , CURLOPT_MAXREDIRS , 5 );
	curl_setopt( $Curl , CURLOPT_POST , 1 );
	curl_setopt( $Curl , CURLOPT_POSTFIELDS , $PostParameters );
	curl_setopt( $Curl , CURLOPT_RETURNTRANSFER , 1 );
	curl_setopt( $Curl , CURLOPT_SSL_VERIFYPEER , 0 );
	curl_setopt( $Curl , CURLOPT_URL , "$Host/$URL" );
	curl_setopt( $Curl , CURLOPT_REFERER , "$Host/" );
	$Result = curl_exec( $Curl );

	if( $Result === false )
	{
		$Error = curl_error( $Curl );
		curl_close( $Curl );
		throw( new Exception( $Error ) );
	}
	else
	{
		curl_close( $Curl );
	}

	return( $Result );
}

/**
*	Враппер для отправки запросов.
*/
function			rpc_did_api_send_request( $Parameters )
{
	global			$DIDAPIHost;

	$PostParameters = array( 'jsonrpc' => $Parameters );

	$Result = send_post_request( $DIDAPIHost , '' , $PostParameters );

	$Result = json_decode( $Result );

	return( $Result->result );
}

/**
*	Коннект к DID-API.
*/
function			rpc_did_api_connect( $Login , $Password )
{
	return( 
		rpc_did_api_send_request( 
			'{ "jsonrpc" : "2.0" , "method" : "connect" , "params" : [ "'.$Login.
			'" , "'.$Password.'" ] , "id" : 1 }'
		)
	);
}

Полный список PHP-врапперов для API можно посмотреть в файле php-did-api-functions.php

Пример 2. Заголовки и тело корректного запроса

Host: did-api.tellan.ru\r\n
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:30.0) Gecko/20100101 Firefox/30.0\r\n
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8\r\n
Accept-Language: ru-RU,ru;q=0.8,en-US;q=0.5,en;q=0.3\r\n
Accept-Encoding: gzip, deflate\r\n
Cookie: PHPSESSID=b0402fadd0b922015af72f1e5e448fe7\r\n
Cache-Control: max-age=0\r\n
Content-Type: application/x-www-form-urlencoded\r\n
Content-Length: 153\r\n
Connection: close\r\n\r\n
jsonrpc=%7B+%22jsonrpc%22+%3A+%222.0%22+%2C+%22method%22+%3A+%22connect%22+%2C+%22params%22+%3A+%5B+%22admin%22+%2C+%22root%22+%5D+%2C+%22id%22+%3A+1+%7D

Пример 3. Отправка заголовков через сокеты

function			post_request( $URL , $Data , $Referer = '' )
{
	$Data = http_build_query( $Data );

	$URL = parse_url( $URL );

	$Host = $URL[ 'host' ];
	$Path = $URL[ 'path' ];

	$fp = fsockopen( $Host , 80 , $errno , $errstr , 10 );
	 
	if( $fp )
	{
		fputs( $fp , "POST {$URL['path']} HTTP/1.1\r\n" );
		fputs( $fp , "Host: {$URL['host']}\r\n" );
	
		if( $Referer != '' )
		{
			fputs( $fp , "Referer: $Referer\r\n" );
		}

		fputs( $fp , "User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:30.0) Gecko/20100101 Firefox/30.0\r\n" );
		fputs( $fp , "Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8\r\n" );
		fputs( $fp , "Accept-Language: ru-RU,ru;q=0.8,en-US;q=0.5,en;q=0.3\r\n" );
		fputs( $fp , "Accept-Encoding: gzip, deflate\r\n" );
		fputs( $fp , "Cookie: PHPSESSID=b0402fadd0b922015af72f1e5e448fe7\r\n" );
		fputs( $fp , "Cache-Control: max-age=0\r\n" );
		fputs( $fp , "Content-type: application/x-www-form-urlencoded\r\n" );
		fputs( $fp , "Content-length: ".strlen( $Data )."\r\n" );
		fputs( $fp , "Connection: close\r\n\r\n" );
		fputs( $fp , $Data );

		$Result = ''; 
		while( !feof( $fp ) )
		{
			$Result .= fgets( $fp , 128 );
		}
	}
	else
	{ 
		return(
			array(
				'status' => 'err' , 
				'error' => "$errstr ($errno)"
			)
		);
	}

	fclose( $fp );

	$Result = explode( "\r\n\r\n" , $Result , 2 );

	$Header = isset( $Result[ 0 ] ) ? $Result[ 0 ] : '';
	$Content = isset( $Result[ 1 ] ) ? $Result[ 1 ] : '';

	return(
		array(
			'status' => 'ok',
			'header' => $Header,
			'content' => $Content
		)
	);
}
var_dump( post_request( 
	'http://did-api.tellan.ru/' , array( 'jsonrpc' => '{ "jsonrpc" : "2.0" , "method" : "connect" , "params" : [ "gdever" , "root" ] , "id" : 1 }' ) 
) );

Вопрос-ответ

Вопрос: «Получаю ошибку при авторизации {"id":null,"jsonrpc":"2.0","error":{"code":-32600,"message":"Invalid Request"}}»

Ответ: Это не ошибка авторизации, а ошибка отправки запроса. Запрос надо отправлять в поле формы jsonrpc. Как это сделать, описано в Примере 1.

Модель данных

Meta-поля

К таким полям относятся поля, в которых хранится существенная для бизнеса информация, но которая не влияет на отображение и выборки номеров из DID-API.

ready

В данном поле хранится информация о том через сколько месяцев мы сможем подключить данный номер. Если в поле хранится значение "0", значит номер будет подключён сразу после оплаты. Если, например, "3", такой номер может быть подключён в течение трёх месяцев.

Номера с ready=N могут быть доступны для продажи. Однако, в этом случае клиентам необходимо открытым текстом сообщать о том, что данный номер будет доступен только через N месяцев.

Порядок действий с номерами

Для продажи свободного номера его необходимо зарезервировать, тогда его в течение 1 часа никто не сможет "перехватить". Резерв автоматически снимается через 1 час. Если клиент дал своё согласие на покупку этого номера, то этот номер бронируется. Бронь автоматически снимается через 31 день. После поступления денег, номер необходимо переместить в статус "продан". Проданные номера необходимо отрулить на оборудовании.

Методы API

Базовые функции

Подключение к АПИ серверу

{ "jsonrpc" : "2.0" , "method" : "connect " , "params" : [ "<login>" , "<password>" ] , "id" : 1 }

Метод возвращает идентификатор сессии, которую необходимо использовать в других вызовах АПИ-методов.

Если подключение не произошло, то возвращается объект

{"result": "error%","id":1,"jsonrpc":"2.0"}

Здесь и далее поле "id" - это идентификатор запроса. Используется при асинхронном выполнении запросов к серверу. Если же API-методы вызываются в синхронном режиме (например из PHP скриптов), то в этом поле можно указывать любое целочисленное значение.

Аутентификация по токену доступа

{ "jsonrpc" : "2.0" , "method" : "connect_by_acces_token" , "params" : [ "<session-id>" , "<access-token>" ] , "id" : 27 }

Изменение статусов номеров

Резервирование номеров

{ "jsonrpc" : "2.0" , "method" : "reserv_numbers" , "params" : [ "<session-id>" , "<client-login>" , 
[ <numbers> ] , "<timeout>" ] , "id" : 3 }

Метод возвращает список номеров, которые удалось зарезервировать для указанного клиента. Резервированию поддаются только те номера, которые ещё никто не зарезервировал для себя. Резервирование осуществляется на timeout минут. Но не менее чем на 15 минут и не более чем на 7200 минут (5 дней). В случае если это параметр не указан, то номер резервируется на 15 минут.

Пример вызова:

{ "jsonrpc" : "2.0" , "method" : "reserv_numbers" , "params" : [ "ttkafq919po8f7ad8hc0lqrm01" , 
"example-user-login" , ["4951234567","4952345678"] ] , "id" : 3 }

Метод возвращает следующий объект:

{ "result" : { "reserved_numbers" : [ <список-зарезервированных-номеров> ] , "numbers_not_found" : 
[ <ненайденные-номера> ] , "error_numbers" : 
[ <прочие-незагруженые-номера> ] } , "id" : 3 , "jsonrpc" : "2.0" }

Бронирование номеров

{ "jsonrpc" : "2.0" , "method" : "book_numbers" , "params" : [ "<session-id>" , [ <numbers> ] ] , "id" : 4 }

Метод возвращает список номеров, которые удалось забронировать. Забронировать можно только те номера, которые зарезервированы. Номера бронируются на 31 день.

Если номер уже забронирован, то для него бронь будет продлена.

Приобретение номеров 

{ "jsonrpc" : "2.0" , "method" : "sell_numbers" , "params" : [ "<session-id>" , [ <numbers> ] ] , "id" : 5 }

Метод возвращает список номеров, которые удалось продать. Продать можно свободные, зарезервированные или забронированные номера.

Дополнительные ограничения на работу метода:

sell-numbers - доступ на выполнение этого метода.

Отруливание номеров (Назначение оборудования номерам)

{ "jsonrpc" : "2.0" , "method" : "install_numbers" , "params" : [ "<session-id>" , [ <numbers> ] , 
"<operator-id>" , "<equipment-group-id>" ] , "id" : 20 }

operator-id - идентификатор оператора; equipment-group-id - идентификатор группы оборудования.

Метод отруливает только те номера номера, у которых код города и номер дают в сумме 10 символов. Остальные номера игнорируются.

Дополнительные ограничения на работу метода:

install-numbers - доступ на выполнение этого метода.

install-numbers-limit - суточный лимит на количество отруливаемых номеров. По умолчанию - 1000 номеров в сутки.

В случае ошибки возвращается объект с полем error_message, которое содержит описание ошибки.

Возврат номеров

{ "jsonrpc" : "2.0" , "method" : "return_numbers" , "params" : [ "<session-id>" , [ <numbers> ] ] , "id" : 21 }

Смена статуса номера из зарезервирован/забронирован/продан на статус «свободен, доступен для резервирования».

Пример вызова:

{ "jsonrpc" : "2.0" , "method" : "return_numbers" , "params" : [ "ttkafq919po8f7ad8hc0lqrm01" , 
["4951234567","4952345678"] ] , "id" : 21 }

Метод возвращает следующий объект:

{ "result" : { "returned_numbers" : [ <список-обработанных-номеров> ] , "numbers_not_found" : 
[ <ненайденные-номера> ] , "error_numbers" : [ <прочие-необработанные-номера> ] } , "id" : 21 , 
"jsonrpc" : "2.0" }

Перемещение номера в буффер-отстойник

{ "jsonrpc" : "2.0" , "method" : "buffer_numbers" , "params" : [ "<session-id>" , [ <numbers> ] ] , "id" : 36 }

Перемещение отруленного номера в буффер-отстойник.

Пример вызова:

{ "jsonrpc" : "2.0" , "method" : "buffer_numbers" , "params" : [ "ttkafq919po8f7ad8hc0lqrm01" , 
["4951234567","4952345678"] ] , "id" : 36 }

Метод возвращает список перемещённых в буффер номеров.

Для работы метода необходимо доступ buffer-numbers.

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

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

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

Открепление номера

{ "jsonrpc" : "2.0" , "method" : "detach_numbers" , "params" : [ "<session-id>" , [ <numbers> ] , "<operator-id>" , "<equipment-id>" , "<owner-id>" ] , "id" : 64}

Метод возвращает список откреплённых номеров.

Для работы метода необходимо доступ detach-numbers.

Выборки записей

Поиск номеров

{ "jsonrpc" : "2.0" , "method" : "search_numbers" , "params" : [ "<session-id>" , 
{ "<search-field>" : "<search-pattern>" } , "<from>" , "<limit>" ] , "id" : 9 }

Здесь search-field - это поле, по которому осуществляется поиск, а search-pattern – это искомое значение. Поиск может осуществляться сразу по нескольким полям.

Поля from и limit используются для ограничения размеров выборок. Будет выбраны номера в количестве limit, начиная с номера from в выборке.

В случае успеха метод возвращает

{"result": "<список номеров>","id":9,"jsonrpc":"2.0"}

Поиск можно осуществлять по следующим полям:

owners – массив идентификаторов владельцев номеров;

regions – массив идентификаторов регионов;

usage_statuses – массив статусов номера. Допустимые значения – free, reserved, booked, unbooked, installed, sold, undefined. Соответственно, свободен для резервирования, зарезервирован, забронирован, бронь снята, отрулен, продан, неопределён, технический;

city_code_near/phone_number_near – код города и номер телефона, для которого надо вывести ближайшие номера. Поиск работает только если заданы оба этих поля;

city_code – код города;

phone_number – номер телефона;

При осуществлении поиска по номеру телефона в запросе можно указывать спецсимволы "?" и "*" (в обоих случаях, разумеется, без кавычек). Где "?" это любой один символ, а "*" это последовательность любых символов.

booked_from – начало периода, за который осуществляется поиск забронированных номеров;

booked_to – конец периода, за который осуществляется поиск забронированных номеров;

reserved_from – начало периода, за который осуществляется поиск зарезервированных номеров;

reserved_to – конец периода, за который осуществляется поиск зарезервированных номеров;

action_from – начало периода, за который осуществляется поиск номеров, дата последнего действия с которыми больше этой даты;

action_to – конец периода, за который осуществляется поиск номеров, дата последнего действия с которыми меньше этой даты;

numbers – список номеров телефонов для выборки (номера телефонов указываются вместе с кодами регионов);

managers – идентификаторы ответственных менеджеров;

operators – идентификаторы операторов.

number_type – тип номера. 0 – простой, 1 – серебро, 2 – золото, 3 – платина, 4 – эксклюзивный, 5 - бронзовый;

number_types – массив типов номеров. 0 – простой, 1 – серебро, 2 – золото, 3 – платина, 4 – эксклюзивный, 5 - бронзовый;

notes – примечания. При осуществлении поиска по примечаниям в запросе можно указывать спецсимволы "?" и "*" (в обоих случаях, разумеется, без кавычек). Где "?" это любой один символ, а "*" это последовательность любых символов;

ready – готовность номера (online/not-ready/дата);

operator_fas - оператор по ФАС.

phone_number_mask - маска по которой будет осуществляться поиск номеров. Например, XYYZZZZ

Все поля могут быть использованы как по отдельности, так и в любой комбинации друг с другом.

Область действия метода ограничивается доступом view-all-numbers если он есть у пользователя, то с помощью этого метода можно получать доступ даже к чужим номерам. Без этого доступа можно получить доступ только к свободным номерам и своим.

Дополнительно метод целиком закрывается доступом view-numbers.

Пример поиска по статусам:

{ "jsonrpc" : "2.0" , "method" : "search_numbers" , "params" : [ "ttkafq919po8f7ad8hc0lqrm01"  , 
{ "usage_statuses" : [ "free" , "sold" ] } ] , "id" : 9 }

Среди полей возвращаемых записей помимо прочих есть поле display_phone_number, в котором выводится номер телефона с красивой разбивкой по группам знаков, например 133-0-133 а не просто 1330133. Данную разбивку рекомендуется использовать на витринах номеров для улучшения понимания у покупателей почему этот номер красивый и почему за него просят соответствующие деньги.

Форматирование найденных номеров

Функция search_numbers помимо прочих данных о номере возвращает поле display_mask, в котором выводится рекомендованный шаблон красивого форматирования номера. Например, вместо стандартного форматирования 100-02-22, лучше расставить разделители так: 1-000-222 Это позволит подчеркнуть красоту номера и обосновать его принадлежность к тому или иному классу красивости (золото/серебро/платина/etc).

Количество найденных номеров

{ "jsonrpc" : "2.0" , "method" : "search_numbers_count" , "params" : [ "<session-id>" , 
{ "<search-field>" : "<search-pattern>" } ] , "id" : 11 }

Здесь search-field - это поле, по которому осуществляется поиск, а search-pattern – это искомое значение. Поиск может осуществляться сразу по нескольким полям.

В случае успеха метод возвращает

{"result": "<количество номеров>","id":11,"jsonrpc":"2.0"}

Область действия метода ограничивается доступом view-all-numbers если он есть у пользователя, то с помощью этого метода можно получать доступ даже к чужим номерам. Без этого доступа можно получить доступ только к свободным номерам и своим.

Получение списка регионов телефонных номеров 

{ "jsonrpc" : "2.0" , "method" : "get_regions" , "params" : [ "<session-id>" ] , "id" : 13 }

Здесь search-field - это поле, по которому осуществляется поиск, а search-pattern – это искомое значение. Поиск может осуществляться сразу по нескольким полям.

В случае успеха метод возвращает

{"result": <список регионов>, "id":13, "jsonrpc":"2.0"}

Получение списка кодов городов

{ "jsonrpc" : "2.0" , "method" : "get_city_codes" , "params" : [ "<session-id>" ] , "id" : 18 }

В случае успеха метод возвращает

{"result": <список кодов города> , "id":18, "jsonrpc":"2.0"}

Выборка действий пользователя за период

{ "jsonrpc" : "2.0" , "method" : "show_log" , "params" : [ "<session-id>", "<managers-id>" , 
"<date-time-from>" , "<date-time-to>" ] , "id" : 32 }

managers-id – массив идентификаторов менеджеров.

Для работы метода необходим доступ show-log.

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

{ "jsonrpc" : "2.0" , "method" : "show_number_log" , "params" : [ "<session-id>", "<number>" , 
"<date-time-from>" , "<date-time-to>" ] , "id" : 35 }

Для работы метода необходим доступ show-log.

Выборка версий номеров

{ "jsonrpc" : "2.0" , "method" : "show_number_versions" ,
 "params" : [ "<session-id>", "<number>" ] , "id" : 53 }

Для работы метода необходим доступ show-log.

Создание записей

Загрузка диапазона номеров

{ "jsonrpc" : "2.0" , "method" : "load_numbers_range" , "params" : [ "<session-id>" , "<city-code>" , 
"<range-from>" , "<range-to>" , "<abc-def>" , , "<owner>" , "<operator>" , "<approx-price>" , 
"<operator-fas>" , "<notes>" ] , "id" : 12 }

city-code – код города;

range-from – начало диапазона;

range-to – конец диапазона;

owner – владелец номера;

operator – оператор;

approx-price – ориентировочная цена;

operator-fas – оператор по ФАС;

notes – примечания к номеру.

В случае успеха метод возвращает

{"result": {"code" : 0 , "duplicates" : [ "<список дубликатов>" ] , "added" : 
[ "<список добавленных номеров>" ]} ,"id":12, "jsonrpc":"2.0"}

Загрузка одного номера

{ "jsonrpc" : "2.0" , "method" : "create_number" , "params" : [ "<session-id>" , "<city-code>" , 
"<number>" , "<type>" , "<from-block>" , "<abcdef>" , "<owner>" , "<mera-operator-id>" , 
"<operator-fas>" , "<vanity-index>" , "<notes>" ] , "id" : 25 }

Параметры метода аналогичны методу load_numbers_range.

Для выполнения этого метода необходимо доступ create-numbers.

Если type == -1, то класс номера будет рассчитан автоматически.

Создание региона

{ "jsonrpc" : "2.0" , "method" : "create_region" , "params" : [ "<session-id>", "<region>"  ] , "id" : 30 }

Для работы метода необходим доступ create-region.

Модификация полей номеров

Указание примечаний к номеру

{ "jsonrpc" : "2.0" , "method" : "set_notes" , "params" : [ "<session-id>" , 
[ <numbers> ] , <notes> ] , "id" : 27 }

Для выполнения этого метода необходимо доступ set-notes.

Получение групп оборудования

{ "jsonrpc" : "2.0" , "method" : "get_equipment_groups" , "params" : [ "<session-id>" ] , "id" : 28 }

В случае успеха метод возвращает { "result": <список групп оборудования> , "id":28 , "jsonrpc" : "2.0" }

Если у пользователя есть доступ view-operators, то будет возвращены группы оборудования для всех операторов. Иначе только для того оператора, который закреплён за этим пользователей.