API для сервисов email-рассылок
Это API предназначено для интеграции с внешними сервисами электронной почты и позволяет управлять списками рассылки и контактами через единый конечный пункт (например, https://yourserver.com/planfix_integration.php), который принимает запросы в формате JSON.
После реализации интеграции вы можете обратиться в нашу Службу поддержки по вопросу добавления вашего сервиса в список интеграций, доступных пользователям в интерфейсе ПланФикса.
Подключение в ПланФиксе
- Перейдите в раздел Управление аккаунтом — Интеграции — Почтовая рассылка:
- В открывшемся разделе выберите находящиеся в конце списка Planfix API.
- Откроется окно настроек интеграции.
- В нём надо будет указать адрес, куда ПланФикс будет слать запросы и API Key для авторизации.
Формат запроса
Запрос передаётся методом POST в формате JSON на адрес, указанный в настройках интеграции.
Пример запроса:
{ "action": "действие", "authToken": "ваш_токен_авторизации", "data": { // Данные, зависящие от действия } }
Параметры запроса:
Имя | Описание | Тип/формат данных | Примечание |
---|---|---|---|
action | Действие, которое необходимо выполнить | string | |
authToken | Токен авторизации для доступа к API | string | |
data | Данные, зависящие от действия | object |
Поддерживаемые действия
- createList — cоздание списка рассылки
- deleteList — удаление списка рассылки
- importContacts — импорт контактов в список
- updateContact — обновление контакта
createList — Создание списка рассылки
Описание: Создает новый список рассылки с указанным именем.
Запрос:
{ "action": "createList", "authToken": "ваш_токен_авторизации", "data": { "listName": "Название списка" } }
Ответ (успех):
{ "success": true, "listId": "уникальный_идентификатор_списка" }
Ответ (ошибка):
{ "error": "Описание ошибки" }
deleteList — Удаление списка рассылки
Описание: Удаляет список рассылки по его идентификатору.
Запрос:
{ "action": "deleteList", "authToken": "ваш_токен_авторизации", "data": { "listId": "идентификатор_списка" } }
Ответ (успех):
{ "success": true }
Ответ (ошибка):
{ "error": "Описание ошибки" }
importContacts — Импорт контактов в список
Описание: Импортирует контакты в указанный список рассылки.
Запрос:
{ "action": "importContacts", "authToken": "ваш_токен_авторизации", "data": { "listId": "идентификатор_списка", "contacts": [ { "id": 123, "email": "email@example.com", "firstName": "Имя", "lastName": "Фамилия" } ] } }
Ответ (успех):
{ "success": true }
Ответ (ошибка):
{ "error": "Описание ошибки" }
updateContact — Обновление контакта
Описание: Обновляет контакт в списке рассылки. Поддерживает действия: добавление (add), обновление (update), удаление (delete).
Запрос:
{ "action": "updateContact", "authToken": "ваш_токен_авторизации", "data": { "listId": "идентификатор_списка", "action": "add|update|delete", "contact": { "id": 123, "email": "email@example.com", "firstName": "Имя", "lastName": "Фамилия" }, "oldEmail": "старый_email@example.com" // только для action=update } }
Ответ (успех):
{ "success": true }
Ответ (ошибка):
{ "error": "Описание ошибки" }
Важно
- Все запросы должны возвращать ответ в формате JSON.
- В случае ошибки всегда должно присутствовать поле "error" с описанием ошибки.
- В случае успеха всегда должно присутствовать поле "success": true.
- Авторизация происходит через поле authToken в каждом запросе.
- Все текстовые поля должны быть в кодировке UTF-8.