SAO JSON API Beta

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

Механика активации

Маханика процесса активации основана на системе статусов. Каждое действие пользователя или активатора вызывает переход активации от одного статуса к другому. На данный момент существуют следующие статусы:

-3 - активация отменена из-за того, что был заказан один сервис, а SMS пришла от другого -2 - активация была отменена по инициативе активатора -1 - активация была отменена по инициативе пользователя 0 - ожидание отправки SMS от пользователя 1 - ожидание SMS-кода от активатора 2 - ожидание проверки SMS-кода пользователем 3 - ожидание уточнения SMS-кода активатором 4 - ожидание скрина SMS от активатора 5 - ожидание отправки повторной SMS от пользователя 6 - активация завершена пользователем 7 - активация завершена модератором после модерации скрина SMS 8 - активация отменена активатором из-за проблем с номером (номер снят с раздачи) 9 - активация отменена в связи с ошибкой активатора (активатор оштрафован) 10 - активация отменена пользователем из-за проблем с номером (номер снят с раздачи) 11 - ожидание проверки скрина SMS модератором

После того, как клиент получает номер, создается активация со статусом 0. После этого клиенту отводится 10 минут, чтобы отправить SMS на полученный номер. Если SMS удалось отправить, клиент должен установить статус 1, в противном случае (если, например, номер оказался уже занят в активируемом сервисе), статус 10. Активатор узнает о новой активации только после того как она была переведена в статус 1. Ему отводится 10 минут для того, чтобы ввести код из SMS, переведя активацию в статус 2. И так далее.

Подобное взаимодействие и образует процесс активации. С полной картой возможных переходов статусов активации можно ознакомиться в разделе карта статусов.

Карта статусов

На переходы между статусами активаций накладываются строгие ограничения: для каждого из статусов разрешены лишь определенные переходы и доступны они лишь определенному участнику активации (пользователю или активатору). Именно эти ограничения и формируют логику активации.

Ниже представлены карты доступных переходов от одного статуса к другому для каждого из участников активации:

//Карта пользователя Для активации со статусом 0: -1 - Отменить активацию 1 - Сообщить, что SMS отправлена 10 - Сообщить о проблеме с номером Для активации со статусом 1: -1 - Отменить активацию Для активации со статусом 2: 3 - Запросить уточнение SMS-кода* 6 - Подтвердить SMS-код и завершить активацию Для активации со статусом 3: 6 - Подтвердить SMS-код и завершить активацию Для активации со статусом 4: 6 - Подтвердить SMS-код и завершить активацию Для активации со статусом 5: -1 - Отменить активацию 1 - Сообщить, что повторная SMS отправлена

*Обратите внимание, что запросить уточнение SMS-кода можно только один раз. Повторный запрос будет расценён как запрос скрина SMS и активация перейдет в статус 4.

//Карта активатора Для активации со статусом 0: -2 - Отменить активацию 8 - Сообщить о проблеме с номером Для активации со статусом 1: -3 - Сообщить о несовпадении выбранного сервиса и отправителя SMS 2 - Отправить SMS-код 5 - Запросить повторную SMS 8 - Сообщить о проблеме с номером Для активации со статусом 3: 2 - Отправить уточнение SMS-кода 9 - Признать свою ошибку и отменить активацию Для активации со статусом 4: 9 - Признать свою ошибку и отменить активацию 11 - Отправить скрин SMS на модерацию Для активации со статусом 5: -2 - Отменить активацию 8 - Сообщить о проблеме с номером

Пропущеные в этих картах статусы являются конечными для активации и не имеют возможных переходов.

Карта переходов статусов активации

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

Запросы осуществляются к адресу: 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 - постоянные ошибки

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

Общие методы

array getActivationList(string $category)

Описание

Метод предназначен для получения списка текущих активаций (со статусами от 0 до 5). Параметр "category" позволяет указать какие активации нужно получить: заказанные с данного аккаунта (исходящие) или заказанные у данного аккаунта (входящие).

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

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

"getter" - получить список исходящих активаций "setter" - получить список входящих активаций (только для активаторов)

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

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

{ "response": 0, "description": "success", "data": { //массив текущих активаций "activations": [ { //уникальный ID активации "id_activation": 615291, //уникальный ID пользователя заказавшего активацию "id_getter": 1790, //уникальный ID активатора выполняющего активацию "id_setter": 8312, //уникальный ID номера "id_number": 169290, //номер на который проводится активация "number": "79620710510", //символьный ID сервиса для которого проводится активация "service": "tg", //текущий статус активации "status": 2, //массив полученых SMS-кодов "codes": ["invalid code", "valid code"], //время оставшееся до конца текущего шага активации, в секундах "seconds_left": 670 } ] } }

Массив "codes" может содержать от нуля до двух кодов. Он будет пуст до тех пор, пока активатор не отправит полученный код. Если клиент запросит уточнение кода и активатор введет код повторно, то массив будет содежать два кода. Коды располагаются в порядке их получения. Так же следует отметить, что коды предоставляются в том виде, в котором их ввел активатор. А это значит, что перед использованием кода желательно произвести проверку на наличие лишних символов.

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

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

mixed getActivationStatus(int $id_activation)

Описание

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

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

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

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

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

{ "response": 0, "description": "success", "data": { //уникальный ID активации "id_activation": 171835, //уникальный ID пользователя заказавшего активацию "id_getter": 1790, //уникальный ID активатора выполняющего активацию "id_setter": 15271, //уникальный ID номера "id_number": 35411, //номер на который проводится активация "number": "79032680691", //символьный ID сервиса для которого проводится активация "service": "qm", //текущий статус активации "status": 6, //массив полученых SMS-кодов "codes": ["357533"], //полный URL скрина SMS или false, если скрин не был приложен "screen": false, //сумма на которую изменился баланс аккаунта "balance_shift": -9.0, //POSIX-время последнего обновления статуса активации "time": 1424267455 } }

Массив "codes" может содержать от нуля до двух кодов. Он будет пуст до тех пор, пока активатор не отправит полученный код. Если клиент запросит уточнение кода и активатор введет код повторно, то массив будет содежать два кода. Коды располагаются в порядке их получения. Так же следует отметить, что коды предоставляются в том виде, в котором их ввел активатор. А это значит, что перед использованием кода желательно произвести проверку на наличие лишних символов.

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

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

void setActivationStatus(int $id_activation, int $status, mixed $parameters)

Описание

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

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

(обязательный) "id_activation" - уникальный ID активации, статус которой нужно изменить.

(обязательный) "status" - новый статус, который нужно присвоить активации.

(опциональный) "parameters" - дополнительная информация, необходимая для установки некоторых статусов. Так для статуса 2 этот параметр должен содержать строку с кодом из SMS, а для статуса 4 - файл со скрином SMS. Для установки остальных статусов этот параметр следует оставить пустым.

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

В случае успеха метод возвращает положительное число в свойстве "response", значение которого зависит от устанавлимаего статуса. Полный список возможных значений:

//Значения возвращаемые активаторам 305 - the activation has been stoped, you are fined 304 - the screenshot of SMS-code has been submitted for moderation 303 - the resending of SMS has been requested 302 - the SMS-code has been sent 301 - the number has been marked as bad by activator 300 - the activation has been canceled by activator //Значения возвращаемые пользователям 205 - the SMS-code has been confirmed, activation complete 204 - the screenshot of SMS-code has been requested 203 - the correction of SMS-code has been requested 202 - the readiness has been confirmed 201 - the number has been marked as bad by client 200 - the activation has been canceled by client

Свойство "data" всегда остается пустым.

{ "response": 200, "description": "the activation has been canceled by client", "data": {} }

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

-101 - SQL-server error occurred, please try again -200 - such API-key does not exist -203 - such status of activation is invalid -204 - such status of activation is incorrect at current activation-step -205 - such activation does not exist in your activation-list -206 - the length of SMS-code must be less or equal than 16 characters -207 - the size of image must be less than 2Mb -208 - the MIME-type of image must be GIF, PNG, JPG, JPEG or BMP -400 - your account is blocked

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

object getActivationRates()

Описание

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

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

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

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

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

{ "response": 0, "description": "success", "data": { //размеры ставок для каждого сервиса "rates": { "vk": 10.0, "mb": 5.0, "ok": 10.0, "4g": 4.0, "fb": 5.0, "ss": 5.0, "ig": 9.0, "wt": 5.0, "tg": 6.0, "vr": 9.0, "wa": 4.5, "wm": 5.1, "qm": 5.1, "ym": 5.0, "gm": 5.0, "ar": 5.1, "at": 5.0, "or": 5.0 } } }

Ключами объекта "rates" являются символьные ID сервисов. С полным списком символьных ID сервисов можно ознакомиться в описании метода runActivation.

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

-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

mixed setActivationRates(array $rate_list)

Описание

Метод предназначен для выбора размера ставок. Следует учитывать, что ставка не может быть отрицательной, а её максимальный размер не должен превышать 99.9.

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

(обязательный) "rate_list" - объект, ключами которого являются символьные ID сервисов, а значениями размеры ставок. Такой же, какой возвращает метод getActivationRates.

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

Если не произошло критических ошибок, метод возвращает число 0 в свойстве "response". Но это еще не значит, что переданные размеры ставок были сохранены. Переданные значения обрабатываются и разделяются на четыре массива, в зависимости от результата обработки: "updated", "invalid", "outranged" и "unchanged". Эти массивы возвращаются в свойстве "data":

{ "response": 0, "description": "success", "data": { //массив сервисов, ставки на которые были сохранены "updated": ["vk", "ok"], //массив невалидных сервисов или сервисов, ставки на которые не являются числом "invalid": ["invalid key of service"], //массив сервисов, ставки на которые выходят за пределы допустимых значений "outranged": ["or", "ig", "vr"], //массив сервисов, ставки на которые не потребовали изменений "unchanged": ["wa"] } }

Таким образом, если все переданные значения были сохранены, то массивы "invalid", "outranged" и "unchanged" будут пусты.

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

-100 - unexpected error occurred, please try again -101 - SQL-server error occurred, please try again -200 - such API-key does not exist -209 - the input parameter must be an array -400 - your account is blocked

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

Описание

Метод предназначен для получения архивных активаций (со статусами вне диапазона от 0 до 5). Параметр "category" позволяет указать какие активации нужно получить: заказанные с данного аккаунта (исходящие) или заказанные у данного аккаунта (входящие).

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

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

"getter" - получить список исходящих активаций "setter" - получить список входящих активаций (только для активаторов)

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

(опциональный) "id_last" - уникальный ID последней активации. Этот параметр нужен для того, чтобы подгружать данные порционально: например, были получены последние 10 активации и нужно получить активации следующие за ними. Для этого необходимо передать уникальный ID последней полученной активации.

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

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

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

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

{ "response": 0, "description": "success", "data": { //массив архивных активаций "activations": [ { //уникальный ID активации "id_activation": 171835, //уникальный ID пользователя заказавшего активацию "id_getter": 1790, //уникальный ID активатора выполняющего активацию "id_setter": 15271, //уникальный ID номера "id_number": 35411, //номер на который проводится активация "number": "79032680691", //символьный ID сервиса для которого проводится активация "service": "qm", //текущий статус активации "status": 6, //массив полученых SMS-кодов "codes": ["357533"], //полный URL скрина SMS или false, если скрин не был приложен "screen": false, //сумма на которую изменился баланс аккаунта "balance_shift": -9.0, //POSIX-время последнего обновления статуса активации "time": 1424267455 } ] } }

Массив "codes" может содержать от нуля до двух кодов. Он будет пуст до тех пор, пока активатор не отправит полученный код. Если клиент запросит уточнение кода и активатор введет код повторно, то массив будет содежать два кода. Коды располагаются в порядке их получения. Так же следует отметить, что коды предоставляются в том виде, в котором их ввел активатор. А это значит, что перед использованием кода желательно произвести проверку на наличие лишних символов.

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

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

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

Описание

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

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

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

Методы для пользователей

mixed runActivation(string $service, string $pattern)

Описание

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

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

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

"vk" - ВКонтакте "mb" - Mamba "ok" - Одноклассники "4g" - 4Game "fb" - facebook "ss" - SEOsprint "ig" - Instagram "g4" - Gem4me "tg" - Telegram "vr" - Viber "wa" - WhatsApp "wc" - WeChat "wm" - WebMoney "qm" - QIWI "ym" - Yandex "gm" - Google "ar" - auto.ru "at" - Avito "or" - Любой другой сервис

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

"ru_beeline" - Россия/Beeline "ru_mts" - Россия/MTS "ru_megafon" - Россия/Megafon "ru_tele2" - Россия/Tele2 "ru_yota" - Россия/Yota "ru" - Россия/Любой "ua_beeline" - Украина/Beeline "ua_kyivstar" - Украина/Киевстар "ua_djuice" - Украина/djuice "ua_mts" - Украина/MTS "ua_jeans" - Украина/Jeans "ua_life" - Украина/Life :) "ua" - Украина/Любой "by" - Белоруссия/Любой "pl" - Польша/Любой "kz" - Казахстан/Любой

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

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

{ "response": 206, "description": "the activation has been started", "data": { //уникальный ID созданной активации "id_activation": 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 -202 - such service of activation is invalid -300 - your balance less than your rate -301 - your rate less than rates of all online activators -305 - all relevant activators is overloaded now, please try later -307 - no numbers, please try later -400 - your account is blocked

Методы для активаторов

mixed saveNumbers(mixed $number_list)

Описание

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

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

(обязательный) "number_list" - список номеров, над которыми необходимо произвести действия. Номера передаются с кодом страны, без ведущего плюса. Если требуется снять номер с раздачи в некоторых сервисах, то он должен быть передан как ключ, значением которого является массив состоящий из символьных ID сервисов, раздача для которых должна стать недоступна. Ниже представлен пример структуры на PHP:

$number_list = array ( //этот номер будет доступным для активации любого сервиса '79000000001', //как и этот '79000000002' => [], //а этот номер будет снят с раздачи для сервисов "vk" и "or" '79000000003' => ['vk', 'or'], //а вот пример невалидного номера - он не будет обработан '+7900000000' => ['at'] );

Так же следует отметить, что если на номер уже была совершена успешная активация (со статусами 6 или 7) на какой либо сервис, то вернуть его в раздачу для этого сервиса не выйдет.

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

Если не произошло критических ошибок, метод возвращает число 0 в свойстве "response". Но это еще не значит, что переданные номера были добавлены, изменены или восстановлены. Переданные значения обрабатываются и разделяются на шесть массивов, в зависимости от результата обработки: "inserted", "updated", "recovered", "invalid", "taken" и "unchanged". Эти массивы возвращаются в свойстве "data":

{ "response": 0, "description": "success", "data": { //массив добавленных номеров "inserted": ["79000000001", "79000000002"], //массив обновленных номеров "updated": ["79000000003"], //массив восстановленных номеров "recovered": [], //массив невалидных номеров "invalid": ["+7900000000"], //массив номеров, уже занятых другими активаторами "taken": [], //массив номеров, не потребовавших изменений "unchanged": [] } }

Таким образом, если все переданные номера были добавлены, изменены или восстановлены, то массивы "invalid", "taken" и "unchanged" будут пусты.

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

-101 - SQL-server error occurred, please try again -200 - such API-key does not exist -209 - the input parameter must be an array -400 - your account is blocked -401 - access denied

mixed dropNumbers(mixed $number_list)

Описание

Метод предназначен для удаления номеров. Удаление является неполным - номера помечаются как удаленные и снимаются с выдачи при этом оставаясь в базе данных.

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

(обязательный) "number_list" - массив номеров которые нужно удалить. Номера передаются с кодом страны, без ведущего плюса.

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

Если не произошло критических ошибок, метод возвращает число 0 в свойстве "response". Но это еще не значит, что переданные номера были добавлены, изменены или восстановлены. Переданные значения обрабатываются и разделяются на четыре массива, в зависимости от результата обработки: "deleted", "invalid", "unavailable" и "unchanged". Эти массивы возвращаются в свойстве "data":

{ "response": 0, "description": "success", "data": { //массив удаленных номеров "deleted": ["79000000001", "79000000002"], //массив невалидных номеров "invalid": ["+7900000000"], //массив номеров, которые не закреплены за аккаунтом "unavailable": [], //массив номеров, не потребовавших изменений "unchanged": [] } }

Таким образом, если все переданные номера были удалены, то массивы "invalid", "unavailable" и "unchanged" будут пусты.

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

-101 - SQL-server error occurred, please try again -200 - such API-key does not exist -209 - the input parameter must be an array -400 - your account is blocked -401 - access denied

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

Описание

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

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

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

void setActivatorStatus(string $status)

Описание

Метод предназначен для изменения статуса активатора: "online" или "offline". Номера активатора попадают в выдачу для активаций только когда он находится в режиме "online".

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

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

"online" - получать заказы на активации "offline" - не получать заказы на активации

Если в течении 2 минут не было ни одного обращения к методу getActivationList - аккаунт автоматически переводится в режим "offline".

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

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

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

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

-101 - SQL-server error occurred, please try again -200 - such API-key does not exist -210 - the status of activator must be a string: "online" or "offline" -400 - your account is blocked -401 - access denied