🌐EN🛠️ Developer Guide
User Guide

Авторизація за допомогою OAuth 2.0

Suggest Edits

Для інтеграції стороннього застосунку з eSputnik ми рекомендуємо налаштувати авторизацію за допомогою OAuth 2.0. 

OAuth 2.0 — це протокол авторизації, що дозволяє стороннім застосункам отримувати безпечний доступ до певних даних та можливостей eSputnik, не надаючи користувацькі облікові дані та API-ключі.

Надання прав доступу до акаунту eSputnik

З OAuth 2.0 ви можете обмежити доступ до ваших ресурсів у eSputnik. Наприклад:

  • Stripo.email дозволяє лише експортувати шаблони листів до eSputnik.
  • CRM (наприклад, AmoCRM) дозволяє лише додавати та редагувати контакти в eSputnik, коли вони змінюються у CRM. Або CRM також може отримувати дані про активність контактів та відображати їх у себе.
  • CMS (наприклад, Wix) дозволяє лише використовувати стандартні форми підписки, щоб додавати підписників безпосередньо до eSputnik.

Доступ до ресурсів eSputnik обмежений наданими під час реєстрації застосунку правами:

  • Повний доступ до API
  • Доступ до подій
  • Доступ до подій і контактів
  • Доступ до повідомлень

Ви можете обмежити доступ до будь-якого з прав з цього списку.

Групи API-методів за функціями в системі

1. Загальні методи

Методи з цієї групи не вимагають спеціальних дозволів, потрібна лише авторизація акаунту eSputnik.

1.1 Інформація про версію протоколу:

  • GET version

1.2 Інформація про обліковий запис:

  • GET account/info
  • GET balance
  • GET subscriptions
  • GET addressbooks

1.3 Керування повідомленнями

  • POST messages/email
  • GET messages/email
  • GET messages/email/{id}
  • DELETE messages/email/{id}
  • PUT messages/email/{id}
  • DELETE messages/email/{id}/{language}
  • PUT messages/email/{id}/{language}
  • GET messages/email/{id}/viewLink
  • GET messages/sms
  • GET messages/sms/{id}

1.4 Керування інтерфейсами

  • GET interfaces/email
  • GET interfaces/sms

1.5 Статистика

  • `GET callouts/sms
  • GET contact/token/activated/{app_uuid}/{token_id}
  • PUT contact/token/activated/{app_uuid}/{token_id}
  • PUT interactions/{interaction_id}/status

2. Методи для оновлення контактів та груп

Зазвичай інтеграція передбачає оновлення контактів, а не їх зчитування. Тому, щоб уникнути витоку даних, можна обмежити права доступу лише оновленням контактів.

  • POST contacts
  • POST contacts/upload
  • GET importstatus/{sessionId}
  • POST contact
  • PUT contact/{id}
  • DELETE contact/{id}
  • PUT contact/{id}/subscriptions
  • POST contact/subscribe
  • POST emails/unsubscribed/add
  • POST emails/unsubscribed/delete
  • POST group/{id}/contacts/detach

3. Методи для читання контактів та груп

  • GET contacts
  • GET contact/{id}
  • GET contacts/email
  • GET contact/{id}/subscriptions
  • GET groups
  • GET group/{id}/contacts

4. Методи для отримання даних щодо активності контактів

  • GET contacts/activity

5. Методи для керування подіями

  • POST event
  • POST past\_events
  • DELETE past\_events

6. Методи для керування повідомленнями

  • POST message/{id}/smartsend
  • POST message/{id}/send OLD
  • GET message/status
  • POST message/email
  • GET message/email/status OLD
  • POST message/sms
  • GET message/sms/status OLD
  • POST message/viber
  • GET message/viber/status OLD
  • POST broadcast
  • GET broadcast/{broadcast_id}
  • DELETE broadcast/{broadcast_id}
  • GET broadcasts

Реєстрація, редагування та видалення застосунку в eSputnik

Перед тим, як почати інтегруватися за допомогою OAuth 2.0, зареєструйте свій застосунок в eSputnik.

Реєстрація застосунку

  1. Натисніть назву вашої організації у верхньому правому куті та виберіть вкладку Для партнерів.
Для партнерів
  1. Натисніть кнопку Зареєструвати застосунок.
Зареєструвати застосунок
  1. Надайте інформацію про застосунок:
  • Назва
  • Callback URL — адреса, на яку сервіс буде перенаправляти користувача після авторизації або відмови в авторизації  вашого застосунку (ви можете створити застосунок без Callback URL та вказати його пізніше)
  • Виберіть області доступу
Інформація про застосунок
  1. Натисніть Зареєструватися.
Зареєструвати

Після реєстрації застосунку йому буде присвоєно ID клієнта (Client ID) та клієнтський ключ (Client Secret). Запишіть їх у надійному та безпечному сховищі.

Client ID / Client Secret
  1. Налаштуйте зовнішній вигляд форми авторизації:
  • Натисніть Редагувати;
Редагувати
  • Перейдіть на вкладку Форма авторизації;
  • У разі потреби введіть назву застосунку;
  • Завантажте логотип: максимальний розмір JPG, GIF або PNG – 1 МБ; співвідношення сторін, що рекомендується, — 1:1 (96×96 пікселів); зображення більшого розміру будуть обрізані до 100% ширини та вирівняні по центру.
Завантажте логотип

Після реєстрації застосунку на вкладці Для партнерів з'явиться вікно з інформацією про нього.

Натисніть три крапки, щоб переглянути форму авторизації або видалити застосунок. Після видалення всі ключі/токени/інтеграції стануть недійсними.

Видалення та попередній перегляд

Інтеграція з OAuth 2.0

📘

Зверніть увагу

Реалізація підтримана лише для застосунків, що мають серверну частину, тобто response_type=code.

1. Авторизація

Відправте GET-запит на URL-адресу авторизації https://uaa.esputnik.com/uaa/oauth/authorize.

Запит має містити ID клієнта, що ви отримали при реєстрації застосунку в eSputnik. 

Формат запиту:

https://uaa.esputnik.com/uaa/oauth/authorize/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_CALLBACK_URL

В результаті з’явиться вікно авторизації.

Введіть логін та пароль облікового запису eSputnik та підтвердьте доступ.

Запит буде перенаправлено на Callback URL із кодом, що використовуватиметься для отримання токенів.

> HTTP/1.1 302 Found
> Location: http://awesome_host/callback?code=YOUR_CODE

2. Отримання токенів авторизації та оновлення

Відправте POST-запит на URL-адресу токена доступу https://uaa.esputnik.com/uaa/oauth/token.

Запит має містити:

  • ID клієнта та клієнтський ключ, що ви отримали при реєстрації застосунку в eSputnik 
  • код, що ви отримали при авторизації

Формат запиту:

https://esputnik.com/uaa/oauth/token?grant_type=authorization_code&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&code=YOUR_CODE&redirect_uri=YOUR_CALLBACK_URL

У відповіді ви отримаєте токен для доступу до API eSputnik (Access Token) та токен для оновлення токена доступу (Refresh Token).

Формат відповіді:

{
  "access_token": "YOUR_TOKEN",
  "token_type": "bearer",
  "refresh_token": "YOUR_REFRESH_TOKEN",
  "scope": "UseRestApi",
  "expires_in": 172541
}

📘

Примітка

Термін дії токена стартує з моменту його створення. За замовчуванням це 172800 секунд для токена доступу і 2592000 секунд для токена оновлення.

3. Оновлення токена

Відправте POST-запит на URL-адресу токена доступу https://uaa.esputnik.com/uaa/oauth/token.

Запит має містити:

  • ID клієнта та клієнтський ключ, що ви отримали при реєстрації застосунку в eSputnik
  • код, що ви отримали при авторизації
  • останній отриманий вами токен оновлення

Формат запиту:

https://esputnik.com/uaa/oauth/token?grant_type=refresh_token&refresh_token=YOUR_REFRESH_TOKEN&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&code=YOUR_CODE&redirect_uri=YOUR_CALLBACK_URL

Відповідь міститиме новий токен доступу та новий токен оновлення, який потрібно використати при наступному оновленні токена доступу.

4. Тестування авторизації

Відправте GET-запит на URL https://esputnik.com/api/v2/version з авторизацією у вигляді заголовка Authorization: Bearer \<YOUR\_ACCESS\_TOKEN>.

У відповіді ви маєте побачити поточну версію API та версію API-протоколу.

Приклад авторизації за допомогою Python

import requests, json
import subprocess
import sys
authorize_url = "https://uaa.esputnik.com/uaa/oauth/authorize"
token_url = "https://uaa.esputnik.com/uaa/oauth/token"
callback_uri = "http://my_host:8081/test/callback"
protected_api_contacts = "https://esputnik.com/api/v1/contacts"
test_api_url = protected_api_contacts
client_id = 'daf4ba310fe44961fabc80ce2d1f67cd'
client_secret = '6c573654f43bc05c13c6b0d0bc65d6a65fe38a09f84e84ac37c3210e78b06b3e'
#step A - simulate a request from a browser on the authorize_url - will return an authorization code after the user is
# prompted for credentials.
authorization_redirect_url = authorize_url + '?response_type=code&client_id=' + client_id + '&redirect_uri=' + callback_uri
print("go to the following url on the browser and enter the code from the returned url: ")
print("---  " + authorization_redirect_url + "  ---")
authorization_code = input('code: ')
# step I, J - turn the authorization code into a access token, etc
data = {'grant_type': 'authorization_code', 'code': authorization_code, 'redirect_uri': callback_uri}
print("requesting access token")
access_token_response = requests.post(token_url, data=data, verify=False, allow_redirects=False, auth=(client_id, client_secret))
print("response")
print(access_token_response.headers)
print('body: ' + access_token_response.text)
# we can now use the access_token as much as we want to access protected resources.
tokens = json.loads(access_token_response.text)
access_token = tokens['access_token']
print("access token: " + access_token)
api_call_headers = {'Authorization': 'Bearer ' + access_token}
#api_call_response = requests.post(test_api_url, headers=api_call_headers, verify=False, json=json)
api_call_response = requests.get(test_api_url, headers=api_call_headers, verify=False)
print(api_call_response.text)

Підключені застосунки

Інтегровані застосунки відображаються на вкладці “Підключені застосунки” у налаштуваннях вашої організації. Щоб відключити застосунок, натисніть на три точки навпроти її назви та виберіть відповідну опцію.

Підключені застосунки

Updated 5 days ago