Как получать и сохранять данные через API форм

API форм пригодится, если готовая форма из конструктора не подходит, и вы хотите собрать свою форму на сайте, а данные передавать в форму Sendsay напрямую. Для этого создайте в Sendsay форму-дубль — с такими же полями, как в форме на сайте, — и передавайте данные в неё через API форм.

Документация API форм

С помощью API форм можно:

• получить структуру формы — список полей, их типы и настройки,
• передать в форму Sendsay данные клиента, который заполнил форму на сайте,
• проверить синтаксис email-адреса перед сохранением.

Важно

API форм предназначено для вызова из браузера посетителя сайта. Не используйте его для автоматизированных серверных запросов.

Как сохранить данные клиента

Чтобы сохранить данные, которые клиент ввёл в форму на сайте, отправьте POST-запрос с заголовками:

Accept: application/json
Content-Type: application/json

В теле запроса обязательно передайте _member_email — email клиента. Если клиент уже есть в базе и известен его id, можно передать _member_id вместо email.

Пример запроса, который передаёт только email:

curl -X POST https://sendsay.ru/form/<логин>/<id формы>/ \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{"_member_email":"test@test.ru"}'

Альтернативный вариант — через x-www-form-urlencoded:

curl --location --request POST 'https://sendsay.ru/form/АККАУНТ/ФОРМА' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode '_member_email=xxxx@xxxx.ru'

Как получить структуру формы

Чтобы получить список полей формы и её настройки, отправьте GET-запрос:

GET https://sendsay.ru/form/<код аккаунта>/<код формы>/

Добавьте заголовок:

Accept: application/json

В ответе придёт:

• fields — список полей формы: код, название, тип (текст, дата, выбор одного или нескольких вариантов), обязательность заполнения,
• state — включена форма или отключена,
• settings — настройки формы,
• page — HTML-код страницы с формой.

Как проверить email

Запрос проверяет синтаксис email-адреса — соответствует ли он формату email, а не то, существует ли такой адрес на самом деле.

Чтобы проверить email на корректность, отправьте GET-запрос с параметрами:

GET https://sendsay.ru/form/<код аккаунта>/<код формы>/?_action=email_validate&_member_email=<email адрес>

Если email прошёл проверку, в ответе придёт нормализованный адрес в поле obj.email. Если нет — в ответе придёт ошибка:

{
  "errors": [
    {
      "id": "wrong_member_email",
      "explain": "причина ошибки"
    }
  ]
}