Основные принципы
- Формат запроса
- Возвращаемые значения
Общий раздел
- getBalance
- loadPaymentHistory
Раздел аренды
Раздел активации
- runActivation
- getActivationList
- getActivationDetails
- setActivationStatus
- setActivatorStatus
- getActivationRates
- setActivationRates
- saveNumbers
- dropNumbers
- loadNumbers
- loadActivationHistory

SAO JSON API Beta

Основные принципы

Формат запроса

Запросы осуществляются к адресу: http://sms-area.org/api/handler.php

Параметрами, общими для всех запросов, являются:

(обязательный) "key" - API-ключ учетной записи.

(обязательный) "method" - вызываемый API-метод.

Так же стоит отметить, что в качестве разделителя целой и дробной частей числа является точка.

Возвращаемые значения

Возвращаемые значения передаются в JSON-формате.

Любой метод возвращает объект состоящий из трех элементов:


						{
						    //числовой идентификатор статуса операции
						    "response": 0,
						    //краткое описание статуса операции
						    "description": "success",
						    //объект хранящий возвращаемые методом данные
						    "data": {}
						}

Если параметр "response" больше или равен нулю - значит операция завершилась успешно. Отрицательные же значения указывают на то что произошла ошибка.

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


						 3XX - статусы характерные для исполнителей
						 2XX - статусы характерные для заказчиков
						 1XX - общие статусы
						-1XX - общие ошибки сервера
						-2XX - неверные параметры запроса
						-3XX - временные ошибки
						-4XX - постоянные ошибки

На основе этой группировки может быть построена логика обработки ошибок: так, например, "общие ошибки сервера" предписывают сделать повторный запрос через короткий промежуток времени, в то время как при получении ошибки из категории "постоянные ошибки" повторный запрос делать бесполезно.

Общий раздел

float getBalance()

Описание

Метод предназначен для получения текущего баланса аккаунта.

Принимаемые параметры

Вызывается без параметров.

Возвращаемые значения

В случае успеха метод возвращает число 0 в свойстве "response" и текущий баланс аккаунта "balance" в свойстве "data":


						{
						    "response": 0,
						    "description": "success",
						    "data":
						    {
						        //текущий баланс аккаунта
						        "balance": 11119.4
						    }
						}

Возможные ошибки


						-100 - unexpected error occurred, please try again
						-101 - SQL-server error occurred, please try again
						-200 - such API-key does not exist
						-400 - your account is blocked

Пример запроса


						http://sms-area.org/api/handler.php?
						    /* API ключ */
						    key=XXX&
						    /* получить баланс данного аккаунта */
						    method=getBalance

array loadPaymentHistory(string $category, int $limit, int $id_last)

Описание

Принимаемые параметры

Возвращаемые значения

Возможные ошибки

Пример запроса

Раздел аренды

mixed runRent(int $lease, string pattern)

Описание

Метод предназначен для получения номера в аренду. Параметр "pattern" позволяет найти номер с помощью регулярного выражения, что дает большую свободу: можно выбрать номер определенной страны, оператора и даже определенного региона.

Принимаемые параметры

(обязательный) "lease" - время аренды выраженное в часах.

(опциональный) "pattern" - регулярное выражение или предопределенная константа для выбора номера. Список предопределенных констант:


						    "ru_beeline"  - Россия/Beeline
						    "ru_mts"      - Россия/MTS
						    "ru_megafon"  - Россия/Megafon
						    "ru_tele2"    - Россия/Tele2
						    "ru_other"    - Россия/Любой кроме перечисленных
						    "ru"          - Россия/Любой из перечисленных

						    "ua_beeline"  - Украина/Beeline
						    "ua_kyivstar" - Украина/Киевстар
						    "ua_djuice"   - Украина/djuice
						    "ua_mts"      - Украина/MTS
						    "ua_jeans"    - Украина/Jeans
						    "ua_life"     - Украина/Life :)
						    "ua_other"    - Украина/Любой кроме перечисленных
						    "ua"          - Украина/Любой из перечисленных

						    "kz"          - Казахстан/Любой

						    "pl"          - Польша/Любой

Возвращаемые значения

В случае успеха метод возвращает число 220 в свойстве "response" и информацию о аренде в свойстве "data":


						{
						    "response": 220,
						    "description": "the rent has been started",
						    "data":
						    {
						        //уникальный ID созданной аренды
						        "id_rent": 620115,
						        //арендованный номер
						        "number": "79250279950"
						    }
						}

Возможные ошибки


						-100 - unexpected error occurred, please try again
						-101 - SQL-server error occurred, please try again
						-200 - such API-key does not exist
						-217 - the lease must be unsigned integer
						-218 - the lease must be greater than zero
						-300 - your balance too low
						-307 - no numbers, please try later
						-400 - your account is blocked

Пример запроса


						http://sms-area.org/api/handler.php?
						    /* API ключ */
						    key=XXX&
						    /* арендовать номер */
						    method=runRent&
						    /* на одну неделю */
						    lease=168&
						    /* страна Россия, оператор Мегафон */
						    pattern=ru_megafon

void renewRent(int $id_rent, int $lease)

Описание

Метод предназначен для продления аренды номера.

Принимаемые параметры

(обязательный) "id_rent" - уникальный ID аренды, которую нужно продлить.

(обязательный) "lease" - время аренды выраженное в часах.

Возвращаемые значения

В случае успеха метод возвращает число 221 в свойстве "response". Свойство "data" остается пустым.


						{
						    "response": 221,
						    "description": "success",
						    "data": {}
						}

Возможные ошибки


						-100 - unexpected error occurred, please try again
						-101 - SQL-server error occurred, please try again
						-200 - such API-key does not exist
						-216 - such rent does not exist in your rent-list
						-217 - the lease must be unsigned integer
						-218 - the lease must be greater than zero
						-300 - your balance too low
						-400 - your account is blocked
						-401 - access denied

Пример запроса


						http://sms-area.org/api/handler.php?
						    /* API ключ */
						    key=XXX&
						    /* продлить аренду */
						    method=renewRent&
						    /* c ID равным 5874 */
						    id_rent=5874&
						    /* на три часа */
						    lease=3

array getRentSummary()

Описание

Метод предназначен для получения информации о количестве доступных для аренды номеров.

Принимаемые параметры

Вызывается без параметров.

Возвращаемые значения

В случае успеха метод возвращает число 0 в свойстве "response" и объект "summary", содержащий информацию о количетсве доступных номеров, в свойстве "data".


						{
						    "response": 0,
						    "description": "success",
						    {
						        "summary":
						        {
						            "ru":
						            {
						                //количество доступных для аренды русских номеров оператора "Beeline"
						                "ru_beeline": 15,
						                //количество доступных для аренды русских номеров оператора "MTS"
						                "ru_mts": 5,
						                //etc
						                "ru_megafon": 10,
						                "ru_tele2": 7,
						                "ru_other": 0
						            },
						            "ua":
						            {
						                "ua_beeline": 0,
						                "ua_kyivstar": 0,
						                "ua_djuice": 0,
						                "ua_mts": 0,
						                "ua_jeans": 0,
						                "ua_life": 0,
						                "ua_other": 0
						            },
						            "pl":
						            {
						                "pl_other": 4
						            },
						            "kz":
						            {
						                "kz_other": 2
						            }
						        }
						    }
						}

Возможные ошибки


						-100 - unexpected error occurred, please try again
						-101 - SQL-server error occurred, please try again
						-200 - such API-key does not exist
						-400 - your account is blocked

Пример запроса


						http://sms-area.org/api/handler.php?
						    /* API ключ */
						    key=XXX&
						    /* получить информацию о количестве доступных номеров */
						    method=getRentSummary

array getRentRates()

Описание

Метод предназначен для получения информации о тарифах аренды и базовых ставках.

Принимаемые параметры

Вызывается без параметров.

Возвращаемые значения

В случае успеха метод возвращает число 0 в свойстве "response" и объект "rates", содержащий информацию о тарифах аренды и базовых ставках, в свойстве "data".


						{
						    "response": 0,
						    "description": "success",
						    {
						        "rates":
						        {
						            //цена за час аренды
						            "rate_per_hour": 10,
						            //цена за день аренды
						            "rate_per_day": 100,
						            //цена за неделю аренды
						            "rate_per_week": 450,
						            //цена за месяц аренды
						            "rate_per_month": 1600,
						            "rate_bases":
						            {
						                "ru":
						                {
						                    //базовая ставка за русский номер оператора "Beeline"
						                    "ru_beeline": 50,
						                    "ru_mts": 50,
						                    "ru_megafon": 50,
						                    //базовая ставка за русский номер оператора "Tele2"
						                    "ru_tele2": 100,
						                    "ru_other": 50
						                },
						                "ua":
						                {
						                    "ua_beeline": 80,
						                    "ua_kyivstar": 80,
						                    "ua_djuice": 80,
						                    "ua_mts": 80,
						                    "ua_jeans": 80,
						                    "ua_life": 70,
						                    "ua_other": 80
						                },
						                "pl":
						                {
						                    "pl_other": 100
						                },
						                "kz":
						                {
						                    "kz_other": 100
						                }
						            }
						        }
						    }
						}

Возможные ошибки


						-100 - unexpected error occurred, please try again
						-101 - SQL-server error occurred, please try again
						-200 - such API-key does not exist
						-400 - your account is blocked

Пример запроса


						http://sms-area.org/api/handler.php?
						    /* API ключ */
						    key=XXX&
						    /* получить информацию о тарифах и базовых ставках */
						    method=getRentRates

array getRentList(string $category)

Описание

Метод предназначен для получения списка текущих аренд (номеров, срок аренды которых еще не закончился).

Принимаемые параметры

(обязательный) "category" - категория аренд, которые нужно получить. Возможные значения:


						    "getter" - получить список арендованных номеров
						    "setter" - получить список сданных в аренду номеров (только для провайдеров)

Возвращаемые значения

В случае успеха метод возвращает число 0 в свойстве "response" и массив объектов текущих аренд "rents" в свойстве "data":


						{
						    "response": 0,
						    "description": "success",
						    "data":
						    {
						        //массив текущих аренд
						        "rents":
						        [
						            {
						                //уникальный ID активации
						                "id_rent": 2204,
						                //уникальный ID пользователя заказавшего аренду
						                "id_getter": 40272,
						                //уникальный ID провайдера предоставившего аренду
						                "id_setter": 95,
						                //арендованный номер
						                "number": "79858941964",
						                //сумма на которую изменился баланс аккаунта
						                "balance_shift": -140,
						                //POSIX-время начала аренды
						                "time_start": 1453280304,
						                //POSIX-время конца аренды
						                "time_end": 1453312704
						            }
						        ]
						    }
						}

Возможные ошибки


						-100 - unexpected error occurred, please try again
						-101 - SQL-server error occurred, please try again
						-200 - such API-key does not exist
						-215 - the category of rent list must be a string: "getter" or "setter"
						-400 - your account is blocked
						-401 - access denied

Пример запроса


						http://sms-area.org/api/handler.php?
						    /* API ключ */
						    key=XXX&
						    /* получить список текущих аренд */
						    method=getRentList&
						    /* которые были заказаны данным аккаунтом */
						    category=getter

mixed getRentDetails(int $id_rent)

Описание

Метод предназначен для получения подробной информации о конкретной аренде. Как текущей, так и архивной.

Принимаемые параметры

(обязательный) "id_rent" - уникальный ID аренды, информацию о которой нужно получить.

Возвращаемые значения

В случае успеха метод возвращает число 0 в свойстве "response" и информацию о аренде в свойстве "data":


						{
						    "response": 0,
						    "description": "success",
						    "data":
						    {
						        //уникальный ID активации
						        "id_rent": 2204,
						        //уникальный ID пользователя заказавшего аренду
						        "id_getter": 40272,
						        //уникальный ID провайдера предоставившего аренду
						        "id_setter": 95,
						        //арендованный номер
						        "number": "79858941964",
						        //сумма на которую изменился баланс аккаунта
						        "balance_shift": -140,
						        //POSIX-время начала аренды
						        "time_start": 1453280304,
						        //POSIX-время конца аренды
						        "time_end": 1453312704
						    }
						}

Возможные ошибки


						-100 - unexpected error occurred, please try again
						-101 - SQL-server error occurred, please try again
						-200 - such API-key does not exist
						-216 - such rent does not exist in your rent-list
						-400 - your account is blocked

Пример запроса


						http://sms-area.org/api/handler.php?
						    /* API ключ */
						    key=XXX&
						    /* получить подробную информацию о аренде */
						    method=getRentDetails&
						    /* c ID равным 788 */
						    id_rent=788

array loadMessages(int $id_rent, int $limit, int $id_last)

Описание

Метод предназначен для получения списка входящих сообщений с арендованного номера.

Принимаемые параметры

(обязательный) "id_rent" - уникальный ID аренды, сообщения с которой нужно получить.

(обязательный) "limit" - максимальное количество сообщений, которые нужно получить. Должно быть целым числом в диапазоне от 1 до 1000.

(опциональный) "id_last" - [Документация отсутствует]

Возвращаемые значения

В случае успеха метод возвращает число 0 в свойстве "response" и массив объектов входящих сообщений "messages" в свойстве "data":


						{
						    "response": 0,
						    "description": "success",
						    "data":
						    {
						        //массив входящих сообщений
						        "messages":
						        [
						            {
						                //уникальный ID сообщения
						                "id_message": 785541,
						                //уникальный ID аренды
						                "id_rent": 9864,
						                //отправитель сообщения
						                "sender": "Beeline",
						                //текст сообщения
						                "text": "Ваш номер 9035648999",
						                //POSIX-время получния сообщения
						                "time_receive": 1424259842
						            }
						        ]
						    }
						}

Возможные ошибки


						-100 - unexpected error occurred, please try again
						-101 - SQL-server error occurred, please try again
						-200 - such API-key does not exist
						-212 - the limit of list must be unsigned integer
						-213 - the limit of list must be between 1 and 1000
						-216 - such rent does not exist in your rent-list
						-400 - your account is blocked

Пример запроса


						http://sms-area.org/api/handler.php?
						    /* API ключ */
						    key=XXX&
						    /* получить список входящих сообщений */
						    method=loadMessages&
						    /* с аренды ID которой равен 3647 */
						    id_rent=3647&
						    /* не больше 23 штук */
						    limit=23

array loadRentHistory(string $category, int $limit, int $id_last, string $pattern)

Описание

Метод предназначен для получения списка архивных аренд (номеров, срок аренды которых уже закончился).

Принимаемые параметры

(обязательный) "category" - категория аренд, которые нужно получить. Возможные значения:


						    "getter" - получить список арендованных номеров
						    "setter" - получить список сданных в аренду номеров (только для провайдеров)

(обязательный) "limit" - максимальное количество аренд, которые нужно получить. Должно быть целым числом в диапазоне от 1 до 1000.

(опциональный) "id_last" - [Документация отсутствует]

(опциональный) "pattern" - шаблон для фильтрации аренд по номерам. Могут использоваться цифры, а так же два управляющих символа:


						    "_" - одна любая цифра
						    "%" - любое количество любых цифр

Возвращаемые значения

В случае успеха метод возвращает число 0 в свойстве "response" и массив объектов архивных аренд "rents" в свойстве "data":


						{
						    "response": 0,
						    "description": "success",
						    "data":
						    {
						        //массив текущих аренд
						        "rents":
						        [
						            {
						                //уникальный ID активации
						                "id_rent": 3860,
						                //уникальный ID пользователя заказавшего аренду
						                "id_getter": 44580,
						                //уникальный ID провайдера предоставившего аренду
						                "id_setter": 95,
						                //арендованный номер
						                "number": "79165806229",
						                //сумма на которую изменился баланс аккаунта
						                "balance_shift": -50,
						                //POSIX-время начала аренды
						                "time_start": 1453286526,
						                //POSIX-время конца аренды
						                "time_end": 1453290126
						            }
						        ]
						    }
						}

Возможные ошибки


						-100 - unexpected error occurred, please try again
						-101 - SQL-server error occurred, please try again
						-200 - such API-key does not exist
						-212 - the limit of list must be unsigned integer
						-213 - the limit of list must be between 1 and 1000
						-215 - the category of rent list must be a string: "getter" or "setter"
						-400 - your account is blocked
						-401 - access denied

Пример запроса


						http://sms-area.org/api/handler.php?
						    /* API ключ */
						    key=XXX&
						    /* получить список архивных аренд */
						    method=loadRentHistory&
						    /* которые были заказаны данным аккаунтом */
						    category=getter&
						    /* не больше 23 штук */
						    limit=23&
						    /* самые новые */
						    id_last=0&
						    /* только русские */
						    pattern=79%