API для сервисов email-рассылок

Материал из Planfix
Перейти к: навигация, поиск

Это 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.

Перейти