API для партнеров

1.0

Общее описание

Данное API предназначено для текущих и потенциальных партнеров Onlinesim. Оно позволяет монетизировать Ваши номера,предоставляя их нашим клиентам для приема SMS от различных сервисов и приложений. На данный момент реализовано две версии API:

  • v1 служит для запросов у Вашего сервера номеров с определенными параметрами;
  • v2 имеет обратную схему: Вы отправляете нам все имеющиеся номера, которые становятся доступны для использования клиентами.

Счет клиенту выставляется за операцию, а не за отдельные SMS. Зачисление средств производится при успешном завершении операции.
Операция может длится от 15 минут (для услуги "Прием SMS") до нескольких месяцев (для услуги "Аренда номера") и включать в себя несколько SMS.
Обратите внимание, что продолжая, Вы соглашаетесь с данным условием!

Оба API требуют активации партнерского аккаунта Onlinesim!
Вам необходимо зарегистрировать профиль Onlinesim и связаться с поддержкой для получении информации о подключении, чтобы получить доступ к этим API. В этой документации мы будем использовать аутентификацию по API ключу для простоты, однако помимо этого доступны и другие методы аутентификации (более подробно можно посмотреть в соответствующем разделе (Авторизация).

Фильтрация сообщений в обоих API может производиться как на нашей стороне, так и с Вашей.
Перед подключением Вам необходимо сообщить сотруднику поддержки, на какой стороне должна производиться фильтрация SMS.
Фильтрация подразумевает под собой проверку на соответствие отправляемых Вами SMS шаблонам сообщений заказанного сервиса. Это необходимо, чтобы недобросовестные клиенты не могли использовать более дешевые сервисы для получения SMS от более дорогих.
По умолчанию фильтрация сообщений производится на нашей стороне.

v1 API

Соединение и конфигурация для каждого партнера индивидуальны индивидуальны, поэтому Вам нужно связаться с техподдержкой для уточнения подробностей интеграции. Все взаимодействие происходит через HTTP POST и/или GET запросы между указанным Вами и нашей поддержкой endpoint'ами.

API v1

Это API также потребует имплементации функционала для исключения выдачи номеров по их маскам.

Требования для v1:

  1. Формат запроса / ответа: JSON4
  2. Кодировка: UTF-8
  3. Убедитесь, что user-agent включен в заголовки запроса
  4. Все запросы / ответы используют метод компрессии gzip
  5. Используемые названия стран и сервисов в ответе GET_SERVICES должны совпадать с соответсвующими списками стран и сервисов
  6. Один номер должен использоваться только для одной операции одновременно: Ваш сервер может выдать этот же номер для другого сервиса только после того, как предыдущая операция будет завершена
  7. Необходимо реализовать функционал для исключения выдачи номеров с определенными масками: если в запросе указана маска исключения, номера с такой последовательностью цифр не должны выдаваться (для запроса GET_NUMBER)
  8. Webhook PUSH_SMS: Ваш сервер должен автоматически пересылать SMS, полученные номерами с активными операциями, на сервер Onlinesim
  9. Фильтрация может производиться как на нашей, так и на Вашей стороне. Перед интреграцией сообщите, какой из вариантов является предпочтительным для Вас
  10. Выдача номера должна производиться в течение 10 секунд с момента получения запроса GET_NUMBER (и GET_NUMBER (RENT)), в противном случае заказ номера отменяется

Чек-лист для интеграции:

  1. Необходимо реализовать 3 метода и webhook:

    GET_SERVICES - запрашивает у Вашего сервера количество номеров по странам и сервисам

    GET_NUMBER - резервирует номер на 15 минут с заданными параметрами для получения SMS сообщений от одного конкретного сервиса за указанную сумму

    PUSH_SMS (webhook) - при получении SMS зарезервированным номером, Ваш сервер отправляет их к нам на сервер

    FINISH_ACTIVATION - закрывает операцию с определенными параметрами (в зависимости от результата)

  2. Написать нам на e-mail или в Telegram для создания профиля партнера, предоставления URL для запросов с нашей стороны, получения ссылки для webhook'a и тестирования номеров.

  3. После успешно проведенных тестов Ваши номера будут доступны нашим клиентам в течение нескольких часов

v2 API

Reseller API v2 дает возможность интегрировать Ваше оборудование и номера для их последующего использования клиентами под прием SMS через наш сайт. Мы постарались сделать его настолько простым для интеграции, насколько это возможно. Для начала работы вам необходимо:

  1. Реализовать 2 метода:

  • sendNumbersOnline - передает список Ваших номеров к нам на сервер, данный запрос должен отправляться каждые 5 минут для обновления списка номеров и как подтверждение аптайма Вашего сервера;

    Если Вы планируете использовать большое количество номеров и отправка sendNumbersOnline каждые 5 минут в качестве подтверждения аптайма для Вас будет затруднительна, мы рекомендуем воспользоваться альтернативным вариантом - запросом checkWork.

  • addMessage - пересылает полученные Вашим сервером сообщения нам.

  1. Связаться с поддержкой, чтобы получить _SERVER_URL_
  2. Остальные запросы опциональны, реализовывать их необязательно, но их описание доступно в документации.
  3. У запросов есть необязательный параметр test, который может быть использован для тестирования. Он может принимать значения test1 и test2, будучи равным первому, он позволит запросу дойти до сервера, однако не вызовет исполнения функции. Если ему задать значение test2, то он вернет тело Вашего запроса в ответе.

После того как Вы получите ответ об успешно выполненном запросе sendNumbersOnline, свяжитесь с партнерской поддержкой, чтобы сотрудники проверили, получает ли наш сервер сообщения с помощью запроса addMessage. В случае успеха Ваши номера будут доступнынашим клиентам уже через нескольких часов.

Приложения

Схема процесса workflow

Серверы