JSON-ответ

Предыдущее: 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; см. пример на странице "Формат общения".)

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