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”
• “Access to events and contacts” (adding/updating)
• "Access to messages"

Следующие правила применимы ко всем версиям методов (/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 окажутся под угрозой.