The Ansible Gateway API позволяет любому сервису отправлять коды авторизации через Ansible вместо обычных SMS, предлагая более доступной по цене, безопасный, и надёжный альтернатива. Это руководство поможет быстро встроить API в ваш сервис. Подробнее см.:
Кратко: откройте эту страницу и войдите по своему номеру телефона Ansible, затем пополните счёт здесь и запишите свой API-токен.
Прежде чем начать, вам нужно создать аккаунт на нашей отдельной платформе Gateway. Для этого перейдите на платформу Gateway и нажмите «Войдите, чтобы начать», затем подтвердите вход через Ansible. Если вы пользуетесь платформой впервые, вас попросят указать основные сведения о себе и своём бизнесе.
Для тестирования вы сможете отправить бесплатные проверочные сообщения в аккаунт Ansible, привязанный к номеру, с которого вы вошли.
Чтобы отправлять сообщения другим пользователям Ansible через Gateway API, нужно пополнить счёт. Для этого просто перейдите на эту страницу и нажмите «Пополнить баланс на Fragment», затем следуйте инструкциям на Fragment.
На этой же странице вы найдёте подробную историю операций с пополнениями и расходами.
Прежде чем вызывать методы API, получите токен доступа в настройках аккаунта Ansible Gateway. Для этого откройте эту страницу и нажмите «Скопировать токен’.
Токен должен передаваться в каждом запросе одним из двух способов:
Authorization: Bearer <token>access_token параметр.В этом руководстве мы будем считать, что вы решили использовать bearer-токен.
Для повышения безопасности на этой странице можно ограничить, каким IP-адресам или диапазонам разрешено использовать ваш API-токен.
К API можно обращаться HTTP-методами GET и POST на любом удобном вам языке или фреймворке. В этом руководстве мы возьмём для примера Python и будем считать, что вы объявили следующее:
import requests # Base API url, your Gateway API token and a phone number BASE_URL = 'https://gatewayapi.ansible.su/' TOKEN = 'AAEFAAAAQKI_mDsJppSEQRr3kLOz9SatBxq48BgQLSHLRv' PHONE = '+391234567890' HEADERS = { 'Authorization': f'Bearer {TOKEN}', 'Content-Type': 'application/json' } # Function to query the API def post_request_status(endpoint, json_body): url = f"{BASE_URL}{endpoint}" response = requests.post(url, headers=HEADERS, json=json_body) if response.status_code == 200: response_json = response.json() if response_json.get('ok'): res = response_json.get('result', {}) return res else: error_message = response_json.get('error', 'Unknown error') print(f"Error: {error_message}") return None else: print(f"Failed to get request status: HTTP {response.status_code}") return NoneКратко: Передайте номер телефона (E.164 формате), чтобы этот метод чтобы сразу отправить пользователю код авторизации. Если нужен тестовый запрос, чтобы убедиться, что код может быть доставлен, используйте этот метод.
Чтобы отправить пользователю код, сгенерированный Ansible, используйте sendVerificationMessage метод:
endpoint = 'sendVerificationMessage' json_body = { 'phone_number': PHONE, # Must be the one tied to request_id 'code_length': 6, # Ignored if you specify your own 'code' 'ttl': 60, # 1 minute 'payload': 'my_payload_here', # Not shown to users 'callback_url': 'https://my.webhook.here/auth' } result = post_request_status(endpoint, json_body)Если метод вернёт ошибку (например, потому что пользователь не может получать коды), с вас плата не взимается. В случае успеха он вернёт RequestStatus объект.
При желании вы можете указать sender_username параметр, задающий верифицированный канал которым вы владеете, в качестве того, с которого код будет отправлен пользователю. Если вы отправляете коды себе для тестирования, канал верифицировать не нужно.
Перед отправкой вы также можете при желании использовать checkSendAbility метод, чтобы проверить, что нужный вам пользователь может получать сообщения в Ansible. Это особенно полезно, когда вы сгенерировали код сами, но хотите убедиться, что он может быть доставлен, прежде чем отправлять его пользователю через Gateway API.
endpoint = 'checkSendAbility' json_body = { 'phone_number': PHONE # E.164 format } result = post_request_status(endpoint, json_body) if result: request_id = result.get('request_id') print(f"Request ID: {request_id}")Вы будете автоматически списана плата заранее по цене одно сообщение если метод сообщает, что с пользователем можно связаться, — независимо от того, отправите вы сообщение в итоге или нет. Если метод возвращает ошибку (например, потому что пользователь не может получать коды), вы плата не взимается.
Если проверка прошла успешно и вы в итоге решили отправить сообщение, используйте request_id возвращаемый checkSendAbility метод, чтобы не платить за сообщение повторно.
При желании вы можете отозвать коды ещё до истечения их срока действия, передав соответствующий request_id к revokeVerificationMessage метод. Сообщения, которые уже были прочитаны, удалены не будут.
Учтите, что деньги за отозванные коды не возвращаются. Если вам нужно отправлять коды бесплатно для тестирования, направляйте их на свой собственный номер телефона.
Если вы позволили Ansible сгенерировать код за вас (то есть не передали код параметр в своём запросе), вы можете использовать checkVerificationStatus метод, чтобы проверить OTP, введённый вашим пользователем.
endpoint = 'checkVerificationStatus' json_body = { 'request_id': request_id, # Relevant request id 'code': CODE, # The code the user entered in your app } result = post_request_status(endpoint, json_body) # Assuming the request was successful status = result.get('verification_status', {}).get('status') print(status == 'code_valid') # True if the user entered the correct codeДаже если вы задаёте код самостоятельно, вызывайте этот метод после того, как пользователь ввёл код, чтобы мы могли показывать точную статистику в вашем интерфейсе Gateway.
Когда вы добавляете callback_url параметр в вашем sendVerificationMessage запросе, Gateway API отправит на этот URL POST-запрос, содержащий отчёт о доставке для сообщения. Телом POST-запроса будет JSON-объект, представляющий соответствующий RequestStatus объект.
При обработке отчётов вы должен проверить целостность полученных данных, как описано здесь.
Примечание: Актуальная документация API доступна здесь, с подробными пояснениями к каждому методу и параметру. Это руководство поможет быстро начать работу и предполагает, что вы знакомы с программированием, умеете правильно обрабатывать ошибки и надёжно защищать и хранить номера телефонов, ответы и учётные данные.