JSON-ответ

Установите ActiveTag чтобы распознавать активные теги повсюду



+ Плагины для сайтов

Плагины для сайтов чтобы показывать активные теги

Предыдущее: JSON-запрос.

Получив запрос от потребителя, бекенд обязан дать на него ответ в формате этой json-схемы. Рассмотрим ее в подробностях...

Обязательные поля

  • $schema (string) - версия JSON-схемы;
    Аналогичное поле описано в разделе json-запрос.
  • result (array) - содержимое ответа.
    В этом массиве содержится ответ на запрос потребителя. Здесь, как и в некоторых других случаях, используется именно массив, а не объект, чтобы передать на клиента правильный порядок отображения данных.

    Состав ответа result - произвольный и ничем не ограничен; можно использовать любое сочетание отображаемых элементов, но следует помнить, что некоторые клиенты (например, бот Телеграмма) будут выводить каждый элемент отдельным сообщением и большое количество элементов может вызвать некоторое неудобство на стороне потребителя в виде вереницы поступивших сообщений.

    Элементы массива result - это объекты, содержащие поля:

    • markdown - форматированный текст
      В этом поле может содержаться как обычный текст, так и отформатированный с помощью синтаксиса Markdown.
    • text - неформатированный текст
      Текст из этого поля не будет никак отформатирован и отобразится на клиенте "как есть".
    • imgURL - ссылка на изображение
      Клиент покажет потребителю изображение по данной ссылке, если она потребителю в настоящий момент доступна.
    • videoURL - ссылка на видео Youtube или Vimeo;
      Клиент покажет потребителю ролик с видеохостинга Youtube или Vimeo по этой ссылке. Ссылка используется та же, что отображается в строке URL браузера при просмотре этого видео на Youtube или Vimeo.
    • redirectURL - ссылка для безусловного перехода

      Это особое поле! Если оно присутствует в списке, все остальные поля будут проигнорированы и потребитель будет безусловно направлен на сайт по указанному URL.

Необязательные поля

  • menu (object) - варианты действий
    Бекенд может предложить потребителю выбрать действие и заполнить связанную с ним форму. Для этого в поле menu есть массив items, содержащий описание пунктов меню и связанные с ним формы.

    Каждый пункт меню (элемент массива) содержит обязательное поле name - название пункта меню и следующие необязательные свойства:

    • url (string) - по какому URL передать заполненные данные

      Это очень важное поле, позволяющее удобно планировать логику, принимая и обрабатывая разные данные разными частями бекенда. Или даже разными бекендами.

      Например, заполнив поле "доставка по адресу", данные могут быть переданы в один бекенд, а "звонок менеджера" - в совершенно другой.
    • cost (string) - стоимость (размер платежа)

      Если бекенд подключен к приему платежей через Платформу, в этом поле может содержаться стоимость товара или размер оплаты за услугу.

      О полях basketID и instantCheckout - читайте в разделе "Потребительские корзины".
    • req (array) - запрашиваемые данные (поля формы)

      Этот массив содержит список связанных с элементом меню полей формы, которые предлагается заполнить потребителю.

      Каждое поле массива req описывается тремя обязательными элементами:

      • name (string) - неотображаемое имя поля
      • title (string) - отображаемое название поля
      • type (string) - тип поля

        Типы полей похожи на привычные типы полей html-форм: address, date, email, name, number, phone, select, text, text-multiline, time и password.

        В зависимости от типа, поля по-разному отображаются в клиентском приложении, по-разному проверяют введенные данные и могут по-разному тарифицироваться. Поэтому, тип следует указывать честно и точно, чтобы не нарушать правила использования Платформы.
      Из необязательных полей массива req следует обратить внимание на:

      • desc (string) - подсказка для потребителя; выводится рядом с полем для ввода
      • value (string) - предустановленное в поле значение; например, рекомендуемое
      • options (array) - список возможных вариантов для типа select
      • isHidden (boolean) - скрытое поле, не отображаемое потребителю
      • needVerification (boolean) - флаг, предписывающий Платформе проверить введенные данные перед отправкой на бекенд.

        Например, с помощью этого флага можно обязать Платформу проверить введенный номер телефона (через отправку проверочного SMS) или введенный адрес email (через отправку проверочного письма). Но эта услуга тарифицируется по отдельным правилам и следует быть осторожным с этим флагом!
    Итого: menu в ответах бекенда позволяет выстраивать самые головоломные сценарии общения с потребителем.

  • additionalData (object) - контейнер для передачи дополнительных данных
    Аналогичное поле описано в разделе json-запрос.
  • error (object) - ошибка
    Если бекенд не понял запроса или не смог на него ответить, должна быть возвращена ошибка. Она состоит из кода ошибки и текстового описания.

    (А сообщение, которое будет при этом показано пользователю, должно быть размещено в поле result; см. пример на странице "Формат общения".)

Далее: простой магазин...