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

Матеріал з Planfix

Цей API призначено для інтеграції з зовнішніми сервісами електронної пошти й дозволяє керувати списками розсилки та контактами через єдину кінцеву точку (наприклад, https://yourserver.com/planfix_integration.php), яка приймає запити у форматі JSON.

Після реалізації інтеграції ви можете звернутися до нашої Служби підтримки з питання додавання вашого сервісу до списку інтеграцій, доступних користувачам в інтерфейсі Planfix.

Підключення в Planfix

  • Перейдіть у розділ Керуючий акаунтом — Інтеграції — Поштова розсилка:
  • У відкритому розділі оберіть в кінці списку Planfix API.
  • Відкриється вікно налаштувань інтеграції.
  • У ньому потрібно буде вказати адресу, куди Planfix буде надсилати запити, та API Key для авторизації.

Формат запиту

Запит передається методом POST у форматі JSON на адресу, вказану в налаштуваннях інтеграції.

Приклад запиту: 

{
  "action": "дія",
  "authToken": "ваш_токен_авторизації",
  "data": {
    // Дані, що залежать від дії
  }
}

Параметри запиту:

Ім'я Опис Тип/формат даних Примітка
action Дія, яку потрібно виконати string
authToken Токен авторизації для доступу до API string
data Дані, що залежать від дії object

Підтримувані дії

  • createList — створення списку розсилки
  • 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.

Перейти