API форм, версия 1.00 2016-07-25

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

Основной URL

https://sendsay.ru/form/<код сервиса>/<код формы>/

Транспорт - HTTP 1.0/1.1 over TLSv1.2/v1.1/v1 - RFC 2616 http://tools.ietf.org/html/rfc2616, RFC 5246 http://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 подписчика",
    "код поля": "значение поля",
    ...
}

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

Метод

GET

Параметры Query String

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

Ответ

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

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

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

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