Gateway API — это интерфейс на основе HTTP, созданный для разработчиков, которым нужно доставлять автоматические сообщения, например коды подтверждения, пользователям, зарегистрировавшим свой номер телефона в Ansible.
На этой странице приведена полная документация API для разработчиков. Дополнительную информацию об API и его возможностях смотрите в нашем Обзор платформы верификации и Руководство по Gateway API.
Все запросы к Ansible Gateway API должны выполняться по HTTPS и должны быть представлены в такой форме: https://gatewayapi.ansible.su/METHOD_NAME. Например, вот так:
https://gatewayapi.ansible.su/sendVerificationMessageМы поддерживаем GET и POST HTTP-методы. Мы поддерживаем три способа передачи параметров в запросах Gateway API:
Ответ содержит объект JSON, у которого всегда есть поле типа Boolean ok. If ok равно true, запрос был выполнен успешно, и результат запроса можно найти в result поле. В случае неуспешного запроса, ok равно false, и ошибка объясняется в error поле (например, ACCESS_TOKEN_INVALID).
Перед вызовом методов API вы должны получить токен доступа в настройках аккаунта Ansible Gateway.
Токен должен передаваться в каждом запросе одним из двух способов:
Authorization: Bearer <token>access_token параметр.Мы поддерживаем GET и POST HTTP-методы. Используйте либо Строка запроса URL or application/json or application/x-www-form-urlencoded для передачи параметров в запросах Ansible Gateway API.
При успешном вызове будет возвращён JSON-объект, содержащий результат.
Используйте этот метод, чтобы отправить проверочное сообщение. За каждую успешную доставку сообщения взимается плата согласно тарифному плану. Обратите внимание, что этот метод всегда бесплатен, если используется для отправки кодов на ваш собственный номер телефона. В случае успеха возвращает RequestStatus объект.
| Параметр | Тип | Обязательно | Описание |
|---|---|---|---|
| phone_number | String | Да | Номер телефона, на который вы хотите отправить проверочное сообщение, в E.164 формате. |
| request_id | String | Необязательное | Уникальный идентификатор предыдущего запроса от checkSendAbility. Если указано, этот запрос будет бесплатным. |
| sender_username | String | Необязательное | Имя пользователя канала Ansible, из которого будет отправлен код. Указанный канал, если он есть, должен быть верифицирован и принадлежать тому же аккаунту, которому принадлежит токен Gateway API. |
| код | String | Необязательное | Код подтверждения. Используйте этот параметр, если хотите задать код подтверждения самостоятельно. Поддерживаются только полностью числовые строки длиной от 4 до 8 символов. Если этот параметр задан, code_length игнорируется. |
| code_length | Integer | Необязательное | Длина кода подтверждения, если Ansible должен сгенерировать его за вас. Поддерживаются значения от 4 до 8. Это актуально, только если вы не используете код параметр, чтобы задать свой код. Используйте checkVerificationStatus метод с код параметр для проверки кода, введённого пользователем. |
| callback_url | String | Необязательное | HTTPS URL, на который вы хотите получать отчёты о доставке связанные с отправленным сообщением, 0-256 байт. |
| полезная нагрузка | String | Необязательное | Произвольный payload, 0-128 байт. Он не будет показан пользователю, используйте его для своих внутренних процессов. |
| ttl | Integer | Необязательное | Время жизни (в секундах) до истечения срока действия сообщения. Если сообщение не будет доставлено или прочитано в течение этого времени, плата за запрос будет возвращена. Поддерживаются значения от 30 до 3600. |
Используйте этот метод, чтобы при необходимости проверить возможность отправки проверочного сообщения на указанный номер телефона. Если возможность отправки подтверждена, будет начислена плата согласно тарифному плану. После проверки вы можете отправить проверочное сообщение с помощью sendVerificationMessage метод, передав request_id из этого ответа.
В рамках области действия request_id, может быть списана только одна комиссия. Вызов sendVerificationMessage один раз с возвращённым request_id будут бесплатными, а повторные вызовы приведут к ошибке. И наоборот, вызовы, которые не содержат request_id будет порождать новые запросы и, соответственно, приводить к списанию соответствующей платы. Обратите внимание, что этот метод всегда бесплатен, если используется для отправки кодов на ваш собственный номер телефона.
В случае, если сообщение может быть отправлено, возвращает RequestStatus объект. В противном случае будет возвращена соответствующая ошибка.
| Параметр | Тип | Обязательно | Описание |
|---|---|---|---|
| phone_number | String | Да | Номер телефона, для которого вы хотите проверить нашу возможность отправить сообщение с кодом подтверждения, в E.164 формате. |
Используйте этот метод, чтобы проверить статус ранее отправленного проверочного сообщения. Если код был сгенерирован для вас Ansible, с помощью этого метода вы также можете проверить правильность введённого пользователем кода. Даже если вы задали код самостоятельно, рекомендуется вызвать этот метод после того, как пользователь успешно ввёл код, передав правильный код в код параметр, чтобы мы могли отслеживать конверсию ваших верификаций. В случае успеха возвращает RequestStatus объект.
| Параметр | Тип | Обязательно | Описание |
|---|---|---|---|
| request_id | String | Да | Уникальный идентификатор запроса на верификацию, статус которого вы хотите проверить. |
| код | String | Необязательное | Код, введённый пользователем. Если указан, метод проверяет, действителен ли код для соответствующего запроса. |
Используйте этот метод, чтобы отозвать ранее отправленное сообщение о верификации. Возвращает True если запрос на отзыв был получен. Однако это не гарантирует, что сообщение будет удалено. Например, если сообщение уже было доставлено или прочитано, оно не будет удалено.
| Параметр | Тип | Обязательно | Описание |
|---|---|---|---|
| request_id | String | Да | Уникальный идентификатор запроса, проверочное сообщение которого вы хотите отозвать. |
Все типы, используемые в ответах Ansible Gateway API, представлены в виде объектов JSON.
Безопасно использовать 32-битные знаковые целые числа для хранения всех Integer поля, если не указано иное.
Необязательное поля могут не возвращаться, если они неактуальны.
Этот объект представляет статус запроса на верификационное сообщение.
| Поле | Тип | Описание |
|---|---|---|
| request_id | String | Уникальный идентификатор запроса на верификацию. |
| phone_number | String | Номер телефона, на который был отправлен код подтверждения, в E.164 формате. |
| request_cost | Float | Общая стоимость запроса, понесённая либо checkSendAbility or sendVerificationMessage. |
| is_refunded | Boolean | Необязательное. If True, плата за запрос была возвращена. |
| remaining_balance | Float | Необязательное. Оставшийся баланс в кредитах. Возвращается только в ответ на запрос, который влечёт списание. |
| delivery_status | DeliveryStatus | Необязательное. Текущий статус доставки сообщения. Возвращается, только если пользователю было отправлено проверочное сообщение. |
| verification_status | VerificationStatus | Необязательное. Текущий статус процесса проверки. |
| полезная нагрузка | String | Необязательное. Произвольные данные (payload), если они были переданы в запросе, 0-256 байт. |
Этот объект представляет статус доставки сообщения.
| Поле | Тип | Описание |
|---|---|---|
| status | String | Текущий статус сообщения. Одно из следующих значений: - sent – сообщение было отправлено на устройство(а) получателя, - delivered – сообщение доставлено на устройство(а) получателя, - прочитать – сообщение прочитано получателем, - expired – срок действия сообщения истёк, оно не было доставлено или прочитано, - revoked – сообщение было отозвано. |
| updated_at | Integer | Момент времени, когда статус обновлялся в последний раз. |
Этот объект представляет статус проверки кода.
| Поле | Тип | Описание |
|---|---|---|
| status | String | Текущий статус процесса верификации. Один из следующих: - code_valid – код, введённый пользователем, верен, - code_invalid – код, введённый пользователем, неверен, - code_max_attempts_exceeded – превышено максимальное количество попыток ввода кода, - expired – срок действия кода истёк, и он больше не может использоваться для верификации. |
| updated_at | Integer | Временная метка для данного статуса. Обозначает время последнего обновления статуса. |
| code_entered | String | Необязательное. Код, введённый пользователем. |
Ansible Gateway API может отправлять отчёты о доставке на указанный пользователем callback URL. Когда вы включаете callback_url параметр в вашем запросе, API отправит HTTP POST запрос на этот URL с отчётом о доставке сообщения. Телом POST-запроса будет JSON-объект, представляющий RequestStatus объект.
Ваш URL должен отвечать HTTP-кодом состояния 200 чтобы подтвердить получение отчёта. Любой другой код состояния будет считаться ошибкой, и сервис повторит отправку того же отчёта до 10 раз с увеличивающимися задержками между попытками. Если все повторные попытки завершатся неудачей, отчёт будет считаться потерянным.
Все отчёты, отправленные вашему callback_url, если вы его указали, будет также содержать следующие заголовки:
X-Request-Timestamp – Unix timestamp, указывающий, когда сервер отправил отчёт.X-Request-Signature – Сгенерированная сервером подпись, необходимая для проверки подлинности отчёта на вашей стороне.Вы можете подтвердить происхождение и проверить целостность получаемых отчётов, сравнив подпись, содержащуюся в X-Request-Signature заголовок с шестнадцатеричным представлением HMAC-SHA-256 подпись data-check-string с помощью SHA256 хэш API-токена, показанного в настройках вашего аккаунта Gateway API.
The data-check-string представляет собой конкатенацию временной метки отчёта, предоставленной X-Request-Timestamp заголовок, символ перевода строки ('\n', 0x0A), используемый в качестве разделителя, и необработанное тело HTTP-запроса.
Пример:
data_check_string = X-Request-Timestamp + '\n' + post_body secret_key = SHA256(api_token) if (hex(HMAC_SHA256(data_check_string, secret_key)) == X-Request-Signature) { // данные от Ansible }Чтобы предотвратить использование устаревших данных, вам следует дополнительно проверять
X-Request-Timestampзаголовок, который содержит Unix-метку времени, когда соответствующий отчёт был отправлен сервером.