API-ключі

Що таке API?

API — універсальний спосіб зв'язку між різними додатками.

API-ключі дозволять іншим додаткам отримати доступ до вашого облікового запису в eSputnik без потреби передавати їм ваш пароль.

Використання API-ключа

Щоб налаштувати інтеграцію з вашою організацією в eSputnik, використовуйте API-ключ.

Ключ надає доступ до даних про ваш обліковий запис eSputnik, тому він має бути захищений від несанкціонованого доступу.

eSputnik API підтримує Basic HTTP Access Authentication з використанням API-ключа.

Щоб авторизуватися і звернутися до ресурсів вашого акаунта в eSputnik:

• введіть будь-яке значення для username;
• введіть значення вашого API-ключа в полі password.

Приклад авторизації за допомогою API-ключа для додатка Postman:

Створення та редагування API-ключа

Щоб налаштувати інтеграцію зі своїм обліковим записом eSputnik, вам треба згенерувати API-ключ.

1. Перейдіть до розділу "Налаштування", після чого виберіть вкладку API та натисніть кнопку "Додати ключ". Відкриється сторінка додавання (редагування) API-ключа.

2. У полі "Опис" можна додати інформацію про те, який саме додаток/сайт буде використовувати цей ключ для доступу до вашого профілю в eSputnik. Це допоможе в подальшому легко ідентифікувати цей API-ключ.

3. Ви можете обмежити доступ за API-ключем до ризикованих частин вашого акаунта в eSputnik.

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

Після додавання нового API-ключа в таблиці з'явиться рядок із відповідними даними:

• власне ключ (у прихованому вигляді), його можна скопіювати, просто клікнувши його;
• інформація про те, ким створено ключ;
• дата його створення;
• доступ;
• опис;
• статус (доступний/недоступний).

Права доступу

Доступ з API-ключем до ресурсів eSputnik налаштовується на етапі створення ключа. Ви можете надати повний доступ до всіх ресурсів і методів eSputnik API, вибравши опцію "Full access to API», або обмежити його, вибравши "Access to events" або "Access to events and contacts":

Ці правила застосовуються до всіх версій методів (/v1, /v2 тощо), якщо немає окремих уточнень.

1. Методи API, доступ до яких надається за замовчуванням

Наступні методи не потребують жодних спеціальних дозволів та є доступними в будь-якій з опцій.

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

GET version

Інформація про акаунт:

GET    account/info
GET    balance
GET    subscriptions
GET    addressbooks

Управління повідомленнями:

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}

Управління інтерфейсами:

GET    interfaces/email
GET    interfaces/sms

Статистика:

GET   contact/token/activated/{app_uuid}/{token_id}
PUT   contact/token/activated/{app_uuid}/{token_id}
PUT   interactions/{interaction_id}/status

2. Читання контактів та груп(Read contacts and segments)

Доступные методы API:

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

3. Оновлення контактів та груп (Write contacts and segments)

Доступні методи API:

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

4. Управління активністю контактів (Manage contact activity in campaign)

Доступні методи API:

GET  contacts/activity

5. Управління івентами (Manage events)

Доступні методи API:

POST   event
POST   past_events
DELETE past_events

6. Відправлення повідомлень (Send messages)

Доступні методи API:

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

Блокування ключа

Якщо ключ скомпрометований, ви можете деактивувати його.

Для цього вам треба перемістити повзунок навпроти ключа в положення "Вимкнути ключ". Після того як ви підтвердите свою дію у спливаючому вікні, система заблокує доступ із цим ключем до API.

Порядок дій для розблокування ключа є таким самим.

Якщо ключ не використовується протягом 90 днів, він вимикається автоматично.

Видалення ключа

Ви можете назавжди видалити ключ, і тоді відновити його буде неможливо.

Для цього натисніть три крапки навпроти ключа та у випадаючому списку виберіть "Видалити".

Безпека API-ключа

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

1. Не допускайте, щоб ключ було видно на скріншотах або демо-відео. Затирання ключа може бути недостатньо — краще "вирізати" його в графічному редакторі.
2. Не відправляйте API-ключ поштою, бо якщо ваш поштовий акаунт зламають, дані в eSputnik опиняться під загрозою.