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

Для інтеграції стороннього застосунку з 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. Натисніть назву вашої організації у верхньому правому куті та виберіть вкладку “Для партнерів".

2. Натисніть кнопку “Зареєструвати застосунок”.

3. Надайте інформацію про застосунок:

• Назва
• Callback URL — адреса, на яку сервіс буде перенаправляти користувача після авторизації або відмови в авторизації  вашого застосунку (ви можете створити застосунок без Callback URL та вказати його пізніше)
• Виберіть області доступу

4. Натисніть “Зареєструватися”.

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

5. Налаштуйте зовнішній вигляд форми авторизації:

• Натисніть "Редагувати";

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

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

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

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

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
}

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)

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

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