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.

Перейти

• Разработчикам: API