API и вебхуки

API позволяет системам организации (CRM, сайту, учётной системе) читать мероприятия, программу, участников, заявки, заказы и отметки входа, добавлять участников и решать по заявкам. Вебхуки сообщают этим системам о событиях в PrimePlanner. API и вебхуки доступны на тарифах «Бизнес» и «Корпоративный». Раздел «Администрирование» → «API и вебхуки» доступен ролям с правом «API и вебхуки организации». Запросы и события для разработчиков описаны на странице «API для разработчиков».

1. Создайте роль с правами, которые нужны интеграции, например «Управление участниками мероприятия» для участников и «Билеты, заказы и возвраты мероприятия» для заказов, см. «Роли и права».
2. Откройте «API и вебхуки» и нажмите «Создать ключ».
3. Укажите название ключа и выберите роль.
4. Скопируйте ключ. PrimePlanner показывает его один раз и хранит только отпечаток.

Ключ передаётся в заголовке запроса и действует с правами роли в вашей организации. Отзовите ключ кнопкой в его строке, если он больше не нужен или мог попасть к посторонним: запросы с ним перестают выполняться сразу. В организации может быть до 20 действующих ключей, один ключ выполняет до 600 запросов в минуту.

Журнал запросов показывает время, ключ, запрос и код ответа за последние 30 дней. Содержимое запросов и ответов в журнал не записывается.

Система организации может добавлять участников пачкой до 500 человек. Профиль ищется по внешнему ID, затем по телефону, адресу электронной почты и совпадающему ФИО. Если профиль не найден, PrimePlanner создаёт его. Внешний ID — номер человека в вашей системе: по нему PrimePlanner находит профиль при следующих запросах. Данные найденного профиля не меняются, их правят в кабинете.

1. В блоке «Вебхуки» нажмите «Добавить адрес».
2. Укажите адрес вашей системы, который начинается с https://.
3. Выберите события и нажмите «Сохранить».
4. Скопируйте секрет подписи: по нему ваша система проверяет, что событие отправил PrimePlanner.

События:

• участник добавлен в мероприятие;
• группы или внешний ID участника изменены;
• участник удалён из мероприятия;
• новая заявка на участие;
• заявка одобрена;
• заявка отклонена;
• заказ билета оплачен или оформлен бесплатно;
• возврат по заказу;
• участник отмечен на входе или на событии.

Кнопка «Проверить» отправляет на адрес пробное событие и показывает ответ. Если адрес не ответил кодом 2xx, PrimePlanner повторяет отправку через 1 мин, 5 мин, 30 мин, 2 ч, 6 ч, 12 ч. После 10 неудачных доставок подряд адрес выключается, владелец организации и сотрудники с правом «API и вебхуки организации» получают уведомление. Кнопка «Доставки» показывает последние события адреса, неудачную доставку можно отправить ещё раз. История доставок хранится 30 дней.

Адрес должен быть доступен из интернета: адреса внутренних сетей PrimePlanner не вызывает.

API и вебхуки передают данные участников, в том числе телефоны и адреса электронной почты, в системы организации. Организация — оператор этих данных и отвечает за их обработку в своих системах. Выдавайте ключи и адреса только системам, которым это разрешено.