API

Для автоматизации взаимодействия с сервисом мы разработали API, документация по которому размещена на этой странице.

Корневой путь к API https://sms-online.pro/api/. Во всех ответах от сервера используется Content-Type: application/json.

Каждый запрос к API должен быть типа GET и включать параметр api_token (ваш API-ключ).

Обработка ошибок

При возникновении ошибки в ходе выполнения запроса вместо ожидаемого ответа вы получите объект с полем message, содержащим описание ошибки. Возможные ошибки:

  • Общие ошибки
    • PERMISSION_DENIED - был передан некорректный api_token
    • INVALID_IDENTIFIER - был передан некорректный идентификатор (номер сервиса, заказа и т.д.)
    • COMMON_ERROR - неспецифическая ошибка при выполнении запроса
  • Заказы
    • NEW_ORDERS_TEMPORARILY_UNAVAILABLE - прием новых заказов для всех сервисов временно недоступен
    • NO_NUMBERS - ошибка при получении номера (нет доступных номеров)
    • SMS_TIMEOUT - истекло время ожидания смс
    • CANNOT_RECEIVE_SMS - ошибка при получении смс
    • ORDER_QUEUE_ERROR - ошибка при обработке очереди заказов
    • SERVICE_UNAVAILABLE - сервис временно недоступен (нет свободных номеров)
    • LOW_BALANCE - недостаточный баланс для выполнения операции
    • ORDER_LIMIT_ERROR - превышен лимит потоков для аккаунта
    • UNCANCELLABLE_ORDER - невозможно отменить заказ (текущий статус заказа не позволяет этого сделать)
    • ORDER_ERROR - неспецифическая ошибка при обработке заказа

Пример ответа:

Баланс

GET https://sms-online.pro/api/balance/get?api_token=YOUR_API_TOKEN


При успешном выполнении запроса в ответ вернется текущее состояние счета.

  • balance - баланс
  • frozen - замороженные средства (больше 0, если имеются незавершенные заказы)

Пример ответа:

Сервисы

GET https://sms-online.pro/api/services?api_token=YOUR_API_TOKEN


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

  • id - номер сервиса
  • country - страна
  • name - название сервиса
  • price - цена
  • quantity - кол-во доступных номеров (может принимать занчение true, если точное кол-во неизвестно)

Пример ответа:

Заказы

GET https://sms-online.pro/api/orders?api_token=YOUR_API_TOKEN


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

Внимание! Не используйте данный метод API для мониторинга свежих заказов. Вместо этого используйте метод для получения статуса конкретного заказа по его id (см. раздел Статус заказа).

  • id - номер заказа
  • sms_service_name - название сервиса
  • country - страна
  • phone - номер телефона
  • state - статус заказа (одно из значений):
    • awaiting_phone - ожидается выдача телефонного номера
    • awaiting_sms - номер выдан, ожидается СМС на него
    • success - СМС принято
    • error - произошла ошибка
    • cancelled - заказ отменен
    • sms_timeout - не дождались СМС
  • cancelling_required - true, если была запрошена отмена, иначе false
  • description - описание статуса (код из смс или описание ошибки)
  • reorder - возможность повторного заказа смс на номер в данный момент (false - нельзя, иначе содержит численное значение стоимости повтора)
  • created_at - дата и время создания заказа (ГГГГ-ММ-ДД чч:мм:сс)

Пример ответа:

Workflow обработки заказов

После получения номера заказа ваше приложение должно периодически отслеживать состояние заказа (см. раздел Статус заказа). Отслеживание рекомендуется повторять каждые 5 секунд.

Типичный порядок возможного взаимодействия с сервисом (пользовательские действия и статусы заказов):

workflow

Новый заказ

GET https://sms-online.pro/api/orders/create/{service_id}?api_token=YOUR_API_TOKEN

service_id - номер сервиса для заказа


GET https://sms-online.pro/api/orders/create/random?api_token=YOUR_API_TOKEN - для заказа случайного сервиса из выбранных на странице Настройки в личном кабинете.


Если вы принимаете участие в реферальной программе, то вы можете указать дополнительный GET-параметр ref=REF_ID при запросе от другого аккаунта. REF_ID доступен в личном кабинете на странице История баланса.

При успешном выполнении запроса в ответ вернется актуальное описание нового заказа.

  • id - номер заказа
  • sms_service_name - название сервиса
  • country - страна
  • phone - номер телефона
  • state - статус заказа (одно из значений):
    • awaiting_phone - ожидается выдача телефонного номера
    • awaiting_sms - номер выдан, ожидается СМС на него
    • success - СМС принято
    • error - произошла ошибка
    • cancelled - заказ отменен
    • sms_timeout - не дождались СМС
  • cancelling_required - true, если была запрошена отмена, иначе false
  • description - описание статуса (код из смс или описание ошибки)
  • reorder - возможность повторного заказа смс на номер в данный момент (false - нельзя, иначе содержит численное значение стоимости повтора)
  • created_at - дата и время создания заказа (ГГГГ-ММ-ДД чч:мм:сс)

Пример ответа:

Статус заказа

GET https://sms-online.pro/api/orders/status/{order_id}?api_token=YOUR_API_TOKEN

order_id - номер заказа


При успешном выполнении запроса в ответ вернется актуальное описание заказа.

  • id - номер заказа
  • sms_service_name - название сервиса
  • country - страна
  • phone - номер телефона
  • state - статус заказа (одно из значений):
    • awaiting_phone - ожидается выдача телефонного номера
    • awaiting_sms - номер выдан, ожидается СМС на него
    • success - СМС принято
    • error - произошла ошибка
    • cancelled - заказ отменен
    • sms_timeout - не дождались СМС
  • cancelling_required - true, если была запрошена отмена, иначе false
  • description - описание статуса (код из смс или описание ошибки)
  • reorder - возможность повторного заказа смс на номер в данный момент (false - нельзя, иначе содержит численное значение стоимости повтора)
  • created_at - дата и время создания заказа (ГГГГ-ММ-ДД чч:мм:сс)

Пример ответа:

Отмена заказа

GET https://sms-online.pro/api/orders/cancel/{order_id}?api_token=YOUR_API_TOKEN

order_id - номер заказа


При успешном выполнении запроса в ответ вернется актуальное описание заказа. Параметр cancelling_required будет установлен в значение true

Внимание! Заказ можно отменить, только если он имеет один из следующих статусов: awaiting_phone, awaiting_sms, и cancelling_required == false (заказ не находится в состоянии отмены).

  • id - номер заказа
  • sms_service_name - название сервиса
  • country - страна
  • phone - номер телефона
  • state - статус заказа (одно из значений):
    • awaiting_phone - ожидается выдача телефонного номера
    • awaiting_sms - номер выдан, ожидается СМС на него
    • success - СМС принято
    • error - произошла ошибка
    • cancelled - заказ отменен
    • sms_timeout - не дождались СМС
  • cancelling_required - true, если была запрошена отмена, иначе false
  • description - описание статуса (код из смс или описание ошибки)
  • reorder - возможность повторного заказа смс на номер в данный момент (false - нельзя, иначе содержит численное значение стоимости повтора)
  • created_at - дата и время создания заказа (ГГГГ-ММ-ДД чч:мм:сс)

Пример ответа:

Повтор заказа

GET https://sms-online.pro/api/orders/repeat/{order_id}?api_token=YOUR_API_TOKEN

order_id - номер успешно завершенного заказа, который нужно повторить


При успешном выполнении запроса в ответ вернется актуальное описание заказа.

Внимание! Заказ можно повторить, только если он имеет статус success. Параметр reorder при этом должен быть численным (равен или больше нуля) - это стоимость повтора заказа. Если он имеет значение false, то повтор невозможен.

  • id - номер заказа
  • sms_service_name - название сервиса
  • country - страна
  • phone - номер телефона
  • state - статус заказа (одно из значений):
    • awaiting_phone - ожидается выдача телефонного номера
    • awaiting_sms - номер выдан, ожидается СМС на него
    • success - СМС принято
    • error - произошла ошибка
    • cancelled - заказ отменен
    • sms_timeout - не дождались СМС
  • cancelling_required - true, если была запрошена отмена, иначе false
  • description - описание статуса (код из смс или описание ошибки)
  • reorder - возможность повторного заказа смс на номер в данный момент (false - нельзя, иначе содержит численное значение стоимости повтора)
  • created_at - дата и время создания заказа (ГГГГ-ММ-ДД чч:мм:сс)

Пример ответа: