API форм, версия 1.02 2021-12-10¶

Предназначение¶

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

Данное API НЕ ПРЕДНАЗНАЧАНО для какого-либо автоматизированного вызова вами - вызовы API должны производиться из браузера посетителя сайта.

Общие правила выполнения запросов¶

Основной URL¶

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

Транспорт - HTTP 1.0/1.1 over TLSv1.2/v1.1/v1 - RFC 2616 https://tools.ietf.org/html/rfc2616, RFC 5246 https://tools.ietf.org/html/rfc5246

Основной протокол - TLSv1.2

Рекомендуемые расширения - SNI и NPN/ALPN

Возможная альтернатива - TLSv1.1

Поддерживается, но не рекомендуется - TLSv1

Настоятельно рекомендуется уметь обрабатывать статусы 30x возможные при работе по HTTP.

Имя sendsay.ru имеет несколько ip-адресов. При невозможности соединения с каким-то из этих адресов необходимо повторять запрос с использованием других.

В зависимости от запроса используются соответствующие методы GET или POST.

Структура ответа¶

{
    -- возможные поля в случае успеха
    "obj": { ... }, -- данные запрашиваемого объекта
    "page": "...", -- HTML код страницы
    "redirect": "http(s)://...", -- URL для дальнейшей переадресации подписчика

    -- в случае ошибки
    "errors": [ -- список ошибок
        {
            "id": "код ошибки",
            "explain" : "описание ошибки" 
        },

        ...
    ]
}

Получение данных формы¶

Метод¶

GET

Обязательные заголовки¶

Accept: application/json

Ответ¶

{
    "obj": {
        "fields": [ -- набор полей формы
            {
                "name": "код поля", -- разрешены латинские буквы, цифры и знак подчеркивания
                "label": "название поля", -- любой набор символов
                "default": "значение по умолчанию",
                "required": "1|0", -- 1 - обязательно для заполнения, 0 - не обязательно
-- тип Свободный ввод

                "type": "text",
                "max_length": "максимальная длина значения в поле",

-- тип Дата
                "type": "dt", 
                "max_length": "YD|Yh|Ym|Ys" -- точность до дня, часа, минуты или секунды соответственно,

-- тип Выбор одного или нескольких ответов
                "type": "select",
                "multiselect": "1" -- разрешен ли выбор нескольких
                "variants": [
                    {
                        "value": "значение опции",
                        "label": "название опции",
                        "selected": "1|0" -- выбрано по умолчанию или нет
                    },
                    ...
                ],

            },
        ...
        ],
        "state": "1|0", -- 1 - форма включена, 0 - форма отключена
        "settings": { ... } -- настройки формы, которые можно предварительно установить вызовом sys.storage.set. Идентификатор хранимых данных должен иметь формат form_<ID ФОРМЫ> (например form_33)
    },
    "page": "HTML код cтраницы с формой" 
}

Сохранение данных подписчика¶

Метод¶

POST

Обязательные заголовки¶

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

Запрос¶

{
    "_member_email": "email подписчика",
    "_member_id": "id подписчика, если подписчик уже в базе и id известен",
    "код поля": "значение поля",
    ...
}

Валидация e-mail адреса¶

Метод¶

GET

Параметры Query String¶

?_action=email_validate&_member_email=<e-mail адрес>

Ответ¶

{
    -- в случае успеха
    "obj: { 
        "email": "нормализованный адрес" 
    },

    -- в случае ошибки
    "errors": [ -- список ошибки
        {
            "id": "wrong_member_email",
            "explain": "причина ошибки" 
        }
    ]
}

История изменений¶

1.02     2021-10-12     * Специальное разъяснение для особо одарённых

1.01     2017-04-06     * Описан параметр _member_id при сохранении данных

1.00     2016-07-25     * Первый релиз