• Показать страницу
  • История страницы
  • Ссылки сюда
  • Наверх
    • Наверх

    Различия

    Показаны различия между двумя версиями страницы.

    Ссылка на это сравнение

    Предыдущая версия справа и слева Предыдущая версия
    Следующая версия     		Предыдущая версия
    api [2020/05/12 13:02]
    d.gudkov     		api [2020/11/19 21:12] (текущий)
    d.shiligina
    Строка 1: Строка 1:
    -====== API референсного билетного сервиса ======+===== API референсного билетного сервиса =====
      
     +В данном документе приведено описание API билетного сервиса, который может быть использован в качестве референсного при реализации своего билетного шлюза партнёрами компании Ticketland. По данной API Ticketland подключается к внешней билетной системе.
      
    -API референсного билетного сервиса +{{ :api_referensnogo_biletnogo_servisa.pdf |}}
    -Общая информация. +
    -В данном документе приведено описание API билетного сервиса, который может быть использован в качестве референсного при реализации своего +
    -билетного шлюза партнёрами компании Ticketland. API сервиса спроектирован по подобию RESTful-сервисов. Кодировка обмениваемых сообщений - +
    -UTF-8. Обмен запросами и ответами производится по протоколу HTTP(S). Всё описание API разделено на три основные группы: методы для работы +
    -с конструктивом, методы для работы с мероприятиями и методы для работы с билетами. +
    -Список изменений +
    -Запросы и ответы. +
    -Аутентификация и авторизация. +
    -Типы данных. +
    -Дата/Время. +
    -Дробное число. +
    -Сообщение об ошибке. +
    -Конструктив. +
    -Метод constructive. +
    -Репертуар. +
    -Метод repertoire. +
    -Метод modifiedRepertoire. +
    -Билеты. +
    -Схема продажи билета. +
    -Метод tickets. +
    -Метод lockTicket. +
    -Метод unlockTicket. +
    -Метод lockedTickets. +
    -Метод createOrder. +
    -Метод printableOrderData. +
    -Метод confirmOrder. +
    -Метод orderedTickets. +
    -Метод removeOrder. +
    -Метод returnTickets. +
    -Метод salesReport. +
    -Список изменений +
    -Дата Описание +
    -13 января 2019 Добавлен отдельный метод возврата returnTickets билетов, согласно +
    -закону от 18.07.2019 №193-ФЗ +
    -В методе salesReport для операции возврата (return) поле price теперь +
    -возвращает возвращенную клиенту стоимость билета +
    -26 марта 2015 Добавил информацию о зарезервированных кодах ошибок в разделе +
    -"Сообщение об ошибке". +
    -10 апреля 2015 Добавил свойство "organizerId" в элемент show в примере ответа метода +
    -repertoire. +
    -2 июня 2015 Добавил описание метода modifiedRepertoire. +
    -4 июня 2015 Добавил свойство "time" в примеры запросов методов confirmOrder и +
    -removeOrder +
    -Запросы и ответы. +
    -Сервис должен поддерживать два типа запроса: +
    -GET - клиент хочет получить некоторые данные; +
    -POST - клиент хочет выполнить некоторую операцию, при которой может потребоваться передача данных в теле запроса; +
    -В каждом GET-запросе от клиента, помимо прочего могут быть указаны следующие заголовки: +
    -В каждом GET-запросе от клиента, помимо прочего могут быть указаны следующие заголовки: +
    -Accept - указывает ожидаемый формат сообщения в теле ответа. Например, application/json. Реализация данного сервиса, как +
    -минимум, должна поддерживать обмен сообщениями в формате JSON. Данный заголовок является точкой расширения: в будущем, если +
    -понадобится, реализация сервиса может включить обмен сообщениями в формате XML. В таком случае, все, что понадобится сделать на +
    -клиентской стороне - это указать в запросе "Accept: application/xml". Клиент может не указать данный заголовок, в таком случае +
    -форматом по-умолчанию считается JSON. +
    -Authorization - аутентификационная информация клиента (см. Аутентификация и авторизация). +
    -В каждом POST-запросе от клиента, могут быть указаны следующие заголовки: +
    -Accept (см. выше) +
    -Content-Type - указывает на формат сообщения, передаваемого в теле запроса. Реализация данного сервиса всегда должна быть готова +
    -принять запрос с сообщением в формате JSON (application/json). Клиент может не указать данный заголовок, в таком случае +
    -форматом по-умолчанию считается JSON. +
    -Authorization - аутентификационная информация клиента (см. Аутентификация и авторизация). +
    -Если название параметра в запросе заканчивается двумя квадратными скобками "[]" - это означает, что данный параметр может быть указан в +
    -запросе несколько раз. Пример: GET http://www.example.com/constructive?segment[]=building&segment[]=hall +
    -В каждом ответе, помимо прочего, сервис должен возвращать следующие заголовки: +
    -Content-Type - указывает на формат сообщения, переданного в теле ответа. +
    -Аутентификация и авторизация. +
    -Для аутентификации клиента, в каждом запросе, помимо прочего, должен быть указан заголовок Authorization. Предлагается использовать +
    -простую Basic-аутентификацию. В сочетании с шифрованием канала связи, это даст минимально необходимый уровень безопасности. В конечном +
    -счете, выбор методики аутентификации остается за разработчиком данного сервиса. Клиенту остается лишь передавать в заголовке Authorization +
    -то значение, которое будет согласовано с владельцем данного сервиса. +
    -Если клиент не предоставил данный заголовок, либо заголовок не содержит значения, то сервис должен вернуть ответ с кодом 401. Если +
    -предоставленные клиентом аутентификационные данные не верны, или же клиент не авторизован на выполнение запрошенной операции, то сервис +
    -должен вернуть ответ с кодом 403. +
    -Типы данных. +
    -Дата/Время. +
    -Для обмена датой/временем предлагается использовать следующий формат: +
    -yyyy-MM-ddTHH-mm-ss +
    -yyyy - год (четыре цифры), ММ - месяц (две цифры), dd - число (две цифры), HH - час (24-х часовая система, две цифры), mm - минута (две цифры), ss +
    -- секунда (две цифры). +
    -В качестве тайм-зоны следует использовать некую оговоренную тайм-зону, согласованную представителями компании Ticketland и партнёра, +
    -реализующего данный сервис. +
    -Пример: 2015-03-23T18-45-00 +
    -Дробное число. +
    -Любое дробное число следует указывать в виде строки строго с двумя знаками после разделителя, в качестве которого выступает точка. +
    -Пример: "250.00" +
    -Сообщение об ошибке. +
    -В случае любой ошибки, возникшей при выполнении запроса (за исключением ошибок, связанных с аутентификацией), сервис должен вернуть ответ +
    -с кодом 500, а в теле ответа должно быть сообщение, информирующее о произошедшей ошибке. +
    -Пример сообщения (с пояснениями): +
    -/* ВСЕ АТРИБУТЫ ОБЯЗАТЕЛЬНЫ, ЕСЛИ НЕ УКАЗАНО ИНОЕ */ +
    -{ +
    -"code": 300, // (целое число) код ошибки +
    -"message": "Не удалось создать заказ" // (строка) текстовое сообщение об ошибке +
    -} +
    -Следует иметь ввиду, что коды от 1 до 100 зарезервированы под определенные конкретные ситуации, предусмотренные интеграционной системой +
    -компании Ticketland. Эти коды будут перечислены здесь позже. Соответственно, для описания каких-то своих специфических ошибок, разработчик +
    -сервиса должен воспользоваться кодами в незарезервированном подмножестве от 101 и далее. Если же возникла ситуация (ошибка), упомянутая в +
    -описании зарезервированных кодов, то разработчик сервиса в этом случае должен вернуть зарезервированный код, соответствующий возникшей +
    -ситуации. Также, разработчик сервиса может использовать один и тот же код (от 101 и выше) для информирования о различных ситуациях. +
    -Например, код 300 может описывать все ошибки, связанные с заказом, код 400 - ошибки работы с репертуаром и так далее. +
    -Конструктив. +
    -Конструктив - это общее название всего, что связано с местом проведения мероприятия. Здание, зал (или сцена), секции и места, все это вместе - +
    -конструктив. Для получения информации о конструктиве в API представлен один метод: constructive. +
    -Метод constructive. +
    -Пример вызова: GET http://www.example.com/constructive?hallId=15&hallVersion=2442&segment[]=building&segment[] +
    -=hall&segment[]=section&segment[]=place +
    -Входные параметры: +
    -hallId (строка) - идентификатор зала (сцены), в котором проходит мероприятие. +
    -hallVersion (строка) - версия этого зала (сцены). Как известно, в одном и том же зале могут проходить совершенно различные +
    -мероприятия, причем, нередко, рассадка и количество мест в этом зале различается для разных мероприятий. Например, для зала с +
    -идентификатором 15 может быть 10 версий различных схем рассадок. Следовательно, конкретную версию рассадки в конкретном зале всегда +
    -можно определить парой атрибутов: hallId и hallVersion. Атрибут hallVersion должен быть уникальным в рамках своего зала и +
    -однозначно определять свой уникальный вариант рассадки в этом зале. +
    -segment[] (строка) - указание, какой (или какие) сегмент конструктива вызывающая сторона желает получить в ответе. Возможные +
    -значения: building - информация о здании, в котором расположена сцена, hall - информация о самом зале (сцене), section - +
    -информация о секциях в зале и place - информация о местах в зале. Как видно из примера, параметр segment[] может быть указан +
    -несколько раз, это следует трактовать как желание вызывающей стороны получить несколько сегментов конструктива. +
    -Параметры hallId и hallVersion не являются обязательными, однако, всегда должны быть указаны либо в паре, либо не указаны вовсе. Если они +
    -не указаны, значит в ответе ожидается информация по всем залам, с учетом указанных segment[]. В свою очередь параметр segment[] должен +
    -быть указан как минимум один раз. Если параметр segment[] не был указан ни разу, то сервис может завершить обработку запроса с ошибкой. +
    -Пример ответа: +
    -/* ВСЕ АТРИБУТЫ ОБЯЗАТЕЛЬНЫ, ЕСЛИ НЕ УКАЗАНО ИНОЕ */ +
    -{ +
    -/* +
    -Сегмент "buildings": массив объектов, в каждом из которых описано отдельное здание. Данный сегмент должен +
    -присутствовать в ответе, если в запросе был указан параметр segment[] со значением building. +
    -Как правило, в театрах, обычно, одно здание. +
    -Если в запросе были указаны параметры hallId и hallVersion, то данный массив должен включать в себя лишь один +
    -объект, описывающий здание, в котором находится запрашиваемый зал. +
    -*/ +
    -"buildings": [ +
    -{ +
    -"id": "1", // (строка) идентификатор здания (театра); значение должно быть уникальным в пределах всех зданий в +
    -базе данных +
    -"name": "Большой Театр" // (строка) название здания (театра) +
    -} +
    -], +
    -], +
    -/* +
    -Сегмент "halls": массив объектов, каждый из которых описывает свойства зала (сцены). Данный сегмент должен +
    -присутствовать в ответе, если в запросе был указан параметр segment[] со значением hall. +
    -Если в запросе были указаны параметры hallId и hallVersion, то данный массив должен включать в себя лишь один +
    -объект, описывающий запрошенный зал. +
    -*/ +
    -"halls": [ +
    -{ +
    -"id": "15", // (строка) идентификатор зала; значение должно быть уникальным в пределах всех залов в базе данных +
    -"name": "Основная сцена", // (строка) название зала +
    -"printName": "Основная сцена", // (строка, не обязательно) название зала на печатаемом билете, в случае, если оно +
    -отличается от значения свойства name. +
    -"buildingId": "1" // (строка) идентификатор здания, в котором расположен зал +
    -}, +
    -{ +
    -"id": "23", +
    -"name": "Малая сцена", +
    -"printName": "Малая сцена", +
    -"buildingId": "1" +
    -} +
    -], +
    -/* +
    -Сегмент "sections": массив объектов, каждый из которых описывает свойства секции. Данный сегмент должен +
    -присутствовать в ответе, если в запросе был указан параметр segment[] со значением section. +
    -Если в запросе были указаны параметры hallId и hallVersion, то данный массив должен включать в себя лишь те секции, +
    -которые включены в запрашиваемый зал. +
    -*/ +
    -"sections": [ +
    -{ +
    -"id": "4053", // (строка) идентификатор секции; значение должно быть уникальным в пределах всех секций в базе +
    -данных +
    -"name": "Левая сторона", // (строка) название секции +
    -"printName": "Лев. сторона", // (строка, не обязательно) название секции на печатаемом билете, в случае, если оно +
    -отличается от значения свойства name. +
    -/* +
    -Массив объектов, каждый из которых описывает координату точки в двумерной системе координат; не обязательное, +
    -но весьма желательное свойство, особенно для больших залов. +
    -Начало координат в левом верхнем углу. С помощью указанных точек будет изображена фигура, повторяющая +
    -контуры секции. может быть указано любое количество точек, но не менее трех. +
    -*/ +
    -"coordinates": [ +
    -{ +
    -"x": 10, // (целое число) координата точки по оси X +
    -"y": 20 // (целое число) координата точки по оси Y +
    -}, +
    -{"x": 20, "y": 20}, +
    -{"x": 10, "y": 30}, +
    -{"x": 15, "y": 40}, +
    -{"x": 20, "y": 30} +
    -] +
    -}, +
    -{ +
    -"id": "4055", +
    -"name": "Правая сторона", +
    -"printName": "Прав. сторона", +
    -"coordinates": [ +
    -"coordinates": [ +
    -{"x": 70, "y": 20}, +
    -{"x": 80, "y": 20}, +
    -{"x": 70, "y": 30}, +
    -{"x": 75, "y": 40}, +
    -{"x": 80, "y": 30} +
    -] +
    -}, +
    -{ +
    -"id": "4079", +
    -"name": "Амфитеатр", +
    -"printName": "Амфитеатр", +
    -"coordinates": [ +
    -{"x": 50, "y": 30}, +
    -{"x": 60, "y": 30}, +
    -{"x": 50, "y": 40}, +
    -{"x": 60, "y": 40} +
    -] +
    -} +
    -], +
    -/* +
    -Данный сегмент является вспомогательным и должен автоматически появиться в ответе, если в запросе были указаны +
    -параметры hallId и hallVersion. +
    -Этот сегмент представляет из себя массив из одного объекта, описывающего связь между конкретной версией +
    -запрошенного зала и секциями, перечисленными выше. +
    -*/ +
    -"hallVersions": [ +
    -{ +
    -"hallId": "15", // (строка) идентификатор запрошенного зала +
    -"hallVersion": "2442", // (строка) версия запрошенного зала (см. описание входящего параметра hallVersion) +
    -"sectionIds": ["4053", "4055"] // массив строк, каждая из которых является идентификатором секции, включенной в +
    -запрашиваемый зал; может быть пустым, но это лишено смысла +
    -} +
    -], +
    -/* +
    -Сегмент "places": массив объектов, каждый из которых описывает свойства места. Данный сегмент должен +
    -присутствовать в ответе, если в запросе был указан параметр segment[] со значением place. +
    -Если в запросе были указаны параметры hallId и hallVersion, то данный массив должен включать в себя лишь те места, +
    -которые включены в лишь те секции, которые включены в запрашиваемый зал. +
    -*/ +
    -"places": [ +
    -{ +
    -"id": "20048", // (строка) идентификатор места; значение должно быть уникальным в пределах всех мест в базе +
    -данных +
    -"sectionId": "4053", // (строка) идентификатор секции, в которую включено данное место +
    -"row": "3", // (строка) ряд +
    -"rowMetric": "Ряд", // (строка, не обязательно) название ряда на печатаемом билете; если не указано, будет +
    -использовано название по усмотрению компании Ticketland. +
    -"seat": "10", // (строка) место +
    -"seatMetric": "Место", // (строка, не обязательно) название места на печатаемом билете; если не указано, будет +
    -использовано название по усмотрению компании Ticketland. +
    -/* +
    -Координата места в двумерной системе координат. Начало координат в левом верхнем углу. Свойство является +
    -обязательным для тех мест, которые должны быть отображены на схеме зала. +
    -*/ +
    -"coordinate": { +
    -"x": 10, // (целое число) координата точки по оси X +
    -"y": 20 // (целое число) координата точки по оси Y +
    -"y": 20 // (целое число) координата точки по оси Y +
    -} +
    -}, +
    -{ +
    -"id": "30042", +
    -"sectionId": "4055", +
    -"row": "4", +
    -"rowMetric": "Линия", +
    -"seat": "12", +
    -"seatMetric": "Кресло", +
    -"coordinate": {"x": 20, "y": 30} +
    -} +
    -} +
    -] +
    -} +
    -Репертуар. +
    -Под репертуаром подразумевается информация обо всех мероприятиях, о которых известно билетной системе. Для получения информации о +
    -мероприятиях в API представлен один метод: repertoire. +
    -Метод repertoire. +
    -Пример вызова: GET http://www.example.com/repertoire?fromInclusive=2015-03-23T00-00-00&tillExclusive=2015-05-2 +
    -3T00-00-00 +
    -Входные параметры: +
    -fromInclusive (дата/время, не обязательно) - минимально возможное время (включительно) начала мероприятий, информация о которых +
    -будет представлена в ответе; мероприятия могут начинаться от указанного времени; если не указано, то это следует трактовать как +
    -отсутствие необходимости фильтрации отдаваемых мероприятий по данному критерию. +
    -tillExclusive (дата/время, не обязательно) - максимально возможное время (исключительно) начала мероприятий, информация о +
    -которых будет представлена в ответе; мероприятия должны начинаться строго раньше указанного времени; если не указано, то это следует +
    -трактовать как отсутствие необходимости фильтрации отдаваемых мероприятий по данному критерию. +
    -Пример ответа (с пояснениями): +
    -/* ВСЕ АТРИБУТЫ ОБЯЗАТЕЛЬНЫ, ЕСЛИ НЕ УКАЗАНО ИНОЕ */ +
    -{ +
    -/* +
    -Сегмент "organizers": массив объектов, каждый из которых описывает организаторов шоу, приведенных в ответе +
    -(ниже). Здесь должны быть перечислены только те организаторы, на которых ссылаются шоу, приведенные в следующем +
    -сегменте. +
    -*/ +
    -"organizers": [ +
    -{ +
    -"id": "500", // (строка) идентификатор организатора; значение должно быть уникальным в пределах всех +
    -организаторов в базе данных +
    -"name": "ООО 'Лучшие спектакли'", // (строка) название организатора +
    -}, +
    -{ +
    -"id": "510", +
    -"name": "ООО 'Рога и Копыта'" +
    -} +
    -], +
    -/* +
    -Сегмент "shows": массив объектов, каждый из которых описывает шоу, в рамках которых будут проходить +
    -мероприятия, приведенные в ответе (ниже). Здесь должны быть перечислены только те шоу, на которые ссылаются +
    -мероприятия, приведенные в следующем сегменте. +
    -*/ +
    -"shows": [ +
    -{ +
    -"id": "1000", // (строка) идентификатор шоу; значение должно быть уникальным в пределах всех шоу в базе +
    -данных +
    -"name": "Щелкунчик", // (строка) название шоу +
    -"type": "Балет", // (строка) тип шоу +
    -"minAge": 12, // (целое число, не обязательно) минимально допустимый возраст зрителя +
    -"organizerId": "500" // (строка) идентификатор организатора +
    -"organizerId": "500" // (строка) идентификатор организатора +
    -}, +
    -{ +
    -"id": "1002", +
    -"name": "Ромео и Джульетта", +
    -"type": "Опера", +
    -"minAge": 16, +
    -"organizerId": "510" +
    -} +
    -], +
    -/* +
    -Сегмент "performances": массив объектов, каждый из которых описывает конкретное мероприятие, проходящее в +
    -рамках своего шоу. +
    -*/ +
    -"performances": [ +
    -{ +
    -"id": "20048", // (строка) идентификатор мероприятия; значение должно быть уникальным в пределах всех +
    -мероприятий в базе данных +
    -"hallId": "15", // (строка) идентификатор зала, в котором проходит мероприятие +
    -"hallVersion": "2442", // (строка) версия зала +
    -"showId": "1000", // (строка) идентификатор шоу, в рамках которого проходит мероприятие +
    -"beginTime": "2015-05-28T18-00-00" // (дата/время) время начала мероприятия +
    -}, +
    -{ +
    -"id": "20059", +
    -"hallId": "15", +
    -"hallVersion": "2442", +
    -"showId": "1002", +
    -"beginTime": "2015-04-14T20-00-00" +
    -} +
    -} +
    -] +
    -} +
    -Метод modifiedRepertoire. +
    -Метод предназначен для получения списка мероприятий, в которых "что-то изменилось" с точки зрения билетного сервиса. Данный метод призван +
    -уменьшить нагрузку на сеть и вычислительные ресурсы при постоянном запрашивании (polling) информации о мероприятиях у билетного сервиса. С +
    -мена названия мероприятия, даты или времени его проведения, количества оставшихся свободных мест - всё это может быть причиной, по которой +
    -идентификатор мероприятия попадает в результат вызова данного метода. В конечном счете, разработчик билетного сервиса сам определяет список +
    -факторов, позволяющих мероприятию считаться "модифицированным". Этот метод не является обязательным для реализации. В рамках подготовки к +
    -интеграции с разрабатываемым билетным сервисом его разработчик должен сообщить о том, был ли им реализован данный метод или нет. +
    -Пример вызова: GET http://www.example.com/modifiedRepertoire?modificationTag=hx982c3d331f +
    -Входные параметры: +
    -modificationTag (строка, не обязательно) - метка, возвращенная билетным сервисом в результате последнего вызова данного метода; +
    -разработчик сервиса определяет, чем будет эта метка: строка с датой/временем, например "2015-06-02T12:34:45" или же, некий уникальный +
    -идентификатор последней транзакции в базе данных билетного сервиса, например "2312da42f" и т.д. В любом случае, следует понимать, что +
    -в этом параметре передается та информация, которая, во-первых, будет понятна билетному сервису и, во-вторых, будет им интерпретирована +
    -как некая "метка", которую следует учесть при определении "модифицированности" того или иного мероприятия, идентификаторы которых +
    -будут перечислены в результате вызова данного метода. Также следует иметь ввиду, что если данный аргумент не был указан при вызове +
    -метода, то в результате вызова метода должны быть перечислены идентификаторы всех мероприятий, доступных к продаже. Очевидно, что +
    -данный аргумент не указывается, например, при первом вызове данного метода, когда вызывающая сторона элементарно "не знает" какой mo +
    -dificationTag следует передать. +
    -Пример ответа (с пояснениями): +
    -/* ВСЕ АТРИБУТЫ ОБЯЗАТЕЛЬНЫ, ЕСЛИ НЕ УКАЗАНО ИНОЕ */ +
    -{ +
    -/* +
    -Метка, которую билетная система готова получить при следующем вызове данного метода. На основании ЭТОЙ метки, +
    -которая будет передана в СЛЕДУЮЩЕМ вызове, билетная система сможет принять решение о том, какие мероприятия +
    -изменились с момента завершения ТЕКУЩЕГО вызова данного метода. +
    -*/ +
    -"modificationTag": "20150602_194452", // (строка) +
    -/* +
    -Массив идентификаторов мероприятий, изменившихся с момента, указанного в аргументе modificationTag, переданного +
    -при при вызове данного метода. Массив может быть пустым, в таком случае, предполагается, что ни одно мероприятие +
    -не изменилось. +
    -*/ +
    -"performances": ["20048", "20049"] // (массив строк) +
    -} +
    -Билеты. +
    -Работу с билетами можно разделить на две части: импорт информации о свободных билетах и выполнение билетных операций. Здесь сразу следует +
    -пояснить, что у билета составной идентификатор. Он состоит из двух идентификаторов: performanceId (идентификатор мероприятия) и placeId +
    -(идентификатор места в зале). С помощью этих двух идентификаторов всегда можно четко обозначить продаваемый билет. При всех операциях с +
    -билетами будут передаваться эти два идентификатора. +
    -Для получения информации о свободных билетах в API представлен метод tickets. +
    -Схема продажи билета. +
    -Для продажи билета сначала его следует заблокировать с помощью метода lockTicket. Данный метод возвращает идентификатор корзины (в +
    -Для продажи билета сначала его следует заблокировать с помощью метода lockTicket. Данный метод возвращает идентификатор корзины (в +
    -которую помещен билет). Этот идентификатор, затем, следует передать в метод createOrder, что бы создать заказ на основе корзины. После этого +
    -будет вызван метод printableOrderData, что бы получить данные для печати билетов, входящих в этот заказ. В завершении (после получения +
    -денег от покупателя) будет вызван метод confirmOrder, означающий подтверждение (выкуп) заказа. +
    -Для удаления билета из корзины вызывается метод unlockTicket. Для удаления заказа (независимо от того, был он подтвержден или нет) +
    -вызывается метод removeOrder. +
    -Метод tickets. +
    -Пример вызова: GET http://www.example.com/tickets?performanceId=20048 +
    -Входные параметры: +
    -performanceId (строка) - идентификатор мероприятия, информацию о свободных билетах которого требуется вернуть. +
    -Пример ответа (с пояснениями): +
    -/* ВСЕ АТРИБУТЫ ОБЯЗАТЕЛЬНЫ, ЕСЛИ НЕ УКАЗАНО ИНОЕ */ +
    -{ +
    -/* +
    -Сегмент "tickets": массив объектов, каждый из которых описывает билет, доступный к продаже. +
    -*/ +
    -"tickets": [ +
    -{ +
    -"placeId": "20048", // (строка) идентификатор места в зале +
    -"performanceId": "20059", // (строка) идентификатор мероприятия +
    -"price": "250.55" // (дробное число) цена билета +
    -}, +
    -{ +
    -"placeId": "20049", +
    -"performanceId": "20059", +
    -"price": "100.00" +
    -} +
    -] +
    -} +
    -Метод lockTicket. +
    -Добавление билета в корзину. Если билет уже находится в этой или другой корзине, то метод должен вернуть сообщение об ошибке. +
    -Пример вызова: POST http://www.example.com/lockTicket +
    -Пример запроса (с пояснениями): +
    -/* ВСЕ АТРИБУТЫ ОБЯЗАТЕЛЬНЫ, ЕСЛИ НЕ УКАЗАНО ИНОЕ */ +
    -{ +
    -"performanceId": "20059", // (строка) идентификатор мероприятия +
    -"placeId": "20049", // (строка) идентификатор места в зале +
    -"basketId": "a34b3498f928c" // (строка, не обязательно) идентификатор корзины. Если не задан, то это следует трактовать +
    -как первое добавление билета в корзину, в таком случае, должна быть создана новая корзина и её идентификатор должен +
    -быть возвращен в ответном сообщении. Если же данный параметр указан, то билет должен быть добавлен в +
    -существующую корзину. +
    -} +
    -Пример ответа (с пояснениями): +
    -/* ВСЕ АТРИБУТЫ ОБЯЗАТЕЛЬНЫ, ЕСЛИ НЕ УКАЗАНО ИНОЕ */ +
    -{ +
    -"basketId": "a34b3498f928c", // (строка) идентификатор корзины, в которую добавлен билет +
    -"ttlInSeconds": 900 // (целое число) время (в секундах) в течении которого данный билет будет находиться в +
    -заблокированном состоянии до того, как билет будет разблокирован автоматически +
    -} +
    -Метод unlockTicket. +
    -Удаление билета из корзины. Если билет уже был удален из корзины ранее, метод должен отработать идемпотентно и вернуть такой же результат, как +
    -если бы билет присутствовал в корзине и был успешно удален из неё. +
    -Пример вызова: POST http://www.example.com/unlockTicket +
    -Пример запроса (с пояснениями): +
    -/* ВСЕ АТРИБУТЫ ОБЯЗАТЕЛЬНЫ, ЕСЛИ НЕ УКАЗАНО ИНОЕ */ +
    -{ +
    -"performanceId": "20059", // (строка) идентификатор мероприятия +
    -"placeId": "20049", // (строка) идентификатор места в зале +
    -"basketId": "a34b3498f928c" // (строка) идентификатор корзины. +
    -} +
    -Пример ответа (с пояснениями): +
    -/* ВСЕ АТРИБУТЫ ОБЯЗАТЕЛЬНЫ, ЕСЛИ НЕ УКАЗАНО ИНОЕ */ +
    -{/* +
    -Просто пустой JSON. +
    -Если на момент вызова метода билета не было в корзине ответ также должен представлять из себя пустой JSON. +
    -*/} +
    -Метод lockedTickets. +
    -Получение списка билетов, находящихся в корзине. Если корзина с указанным идентификатором не существует, следует вернуть сообщение об +
    -ошибке. +
    -Пример вызова: GET http://www.example.com/lockedTickets?basketId=a34b3498f928c +
    -Входные параметры: +
    -basketId (строка) - идентификатор корзины. +
    -Пример ответа (с пояснениями): +
    -/* ВСЕ АТРИБУТЫ ОБЯЗАТЕЛЬНЫ, ЕСЛИ НЕ УКАЗАНО ИНОЕ */ +
    -{ +
    -"tickets": [ // массив объектов, каждый из которых описывает билет, находящийся в корзине; может быть пустым. +
    -{ +
    -"performanceId": "20059", // (строка) идентификатор мероприятия +
    -"placeId": "20049" // (строка) идентификатор места +
    -} +
    -] +
    -} +
    -Метод createOrder. +
    -Создание заказа на основе корзины. Метод может вернуть сообщение об ошибке только в случае, если, вообще, не удалось создать заказ в силу +
    -каких-то ограничений или ошибок, например, был указан неверный идентификатор корзины. Если же при создании заказа возникли ошибки лишь с +
    -некоторыми билетами, входящими в корзину, то метод должен проинформировать об этом в теле своего ответа (см. пример ниже). +
    -Пример вызова: POST http://www.example.com/createOrder +
    -Пример запроса (с пояснениями): +
    -/* ВСЕ АТРИБУТЫ ОБЯЗАТЕЛЬНЫ, ЕСЛИ НЕ УКАЗАНО ИНОЕ */ +
    -{ +
    -"basketId": "a34b3498f928c", // (строка) идентификатор корзины. +
    -"customer": { // Информация о покупателе. Данное свойство может отсутствовать в запросе. +
    -"id": "4991", // (строка) идентификатор покупателя +
    -"surname": "Сидоров", // (строка, не обязательно) фамилия покупателя +
    -"name": "Иван", // (строка, не обязательно) имя покупателя +
    -"patronymic": "Петрович", // (строка, не обязательно) отчество покупателя +
    -"phone": "79250000000", // (строка, не обязательно) номер телефона покупателя +
    -"email": "sidorov@example.com" // (строка, не обязательно) адрес электронной почты покупателя +
    -}, +
    -"ticketExtras": [ // массив объектов с дополнительной информацией о билетах, входящих в корзину, на основании +
    -которой будет создан заказ; может быть пустым. +
    -{ +
    -"performanceId": "20059", // (строка) идентификатор мероприятия +
    -"placeId": "20049", // (строка) идентификатор места +
    -"price": "100.00" // (дробное число) цена билета по данным клиента; в случае расхождения этой цены с данными +
    -сервиса, он может заблокировать создание заказа или заблокировать добавление билета в создаваемый заказ +
    -} +
    -] +
    -} +
    -Пример ответа (с пояснениями): +
    -/* ВСЕ АТРИБУТЫ ОБЯЗАТЕЛЬНЫ, ЕСЛИ НЕ УКАЗАНО ИНОЕ */ +
    -{ +
    -"orderId": "10002", // (строка) идентификатор заказа +
    -"ttlInSeconds": 172800, // (целое число) время (в секундах), в течении которого заказ можно подтвердить (оплатить). По +
    -истечении этого времени, заказ может быть автоматически аннулирован. +
    -"tickets": [ // массив с информацией о билетах, вошедших (или тех, которые должны были войти) в заказ; каждому +
    -билету в корзине должен соответствовать один элемент в этом массиве +
    -{ +
    -"performanceId": "20059", // (строка) идентификатор мероприятия +
    -"placeId": "20049", // (строка) идентификатор места +
    -"error": { // информация о причине (ошибке) по которой билет не вошел в заказ; если билет попал в заказ, то данное +
    -свойство должно отсутствовать. +
    -"code": 105, // (целое число) код ошибки +
    -"message": "Несовпадение цены" // (строка) текстовое сообщение об ошибке +
    -} +
    -} +
    -] +
    -} +
    -Метод printableOrderData. +
    -Получение данных для печати заказа. Фактически, данный метод должен быть вызван до подтверждения (оплаты) заказа, непосредственно перед +
    -печатью билетов, входящих в заказ. Если заказа не существует, метод должен вернуть сообщение об ошибке. +
    -Пример вызова: GET http://www.example.com/printableOrderData?orderId=10002 +
    -Входные параметры: +
    -orderId (строка) - идентификатор заказа. +
    -Пример ответа (с пояснениями): +
    -/* ВСЕ АТРИБУТЫ ОБЯЗАТЕЛЬНЫ, ЕСЛИ НЕ УКАЗАНО ИНОЕ */ +
    -{ +
    -"tickets": [ // массив с информацией, требуемой для печати каждого билета; каждому билету в заказе должен +
    -соответствовать один элемент в этом массиве +
    -{ +
    -"performanceId": "20059", // (строка) идентификатор мероприятия +
    -"placeId": "20049", // (строка) идентификатор места +
    -"barcode": { // информация о штрих-коде билета; может отсутствовать, если не удалось её подготовить, но в таком +
    -случае, должна быть указана причина в свойстве "error" +
    -"value": "29384742312031", // (число, выраженное в виде строки) значение штрих-кода +
    -"type": "interleaved_2_of_5" // (строка, не обязательно) тип штрих-кода; в случае отсутствия, в качестве типа будет +
    -принято значение "interleaved_2_of_5"; на данный момент компания Ticketland будет трактовать любой штрих-код как +
    -"interleaved_2_of_5", добавляя слева цифру "0", если в значении штрих-кода указано нечетное количество цифр. +
    -}, +
    -"error": { // информация о причине (ошибке) по которой не удалось подготовить данные для печати билета; если +
    -ошибок нет, то данное свойство должно отсутствовать +
    -"code": 150, // (целое число) код ошибки +
    -"message": "Штрих-код не найден" // (строка) текстовое сообщение об ошибке +
    -} +
    -} +
    -] +
    -} +
    -Метод confirmOrder. +
    -Подтверждение (оплата) заказа. После вызова этого метода заказ считается проданным. Это финальное состояние успешного жизненного цикла +
    -заказа. Метод может вернуть сообщение об ошибке только в случае, если, вообще, не удалось подтвердить заказ целиком в силу каких-то +
    -ограничений или ошибок. Если же при подтверждении заказа возникли ошибки лишь с некоторыми билетами, входящими в него, то метод должен +
    -проинформировать об этом в теле своего ответа (см. пример ниже). +
    -Пример вызова: POST http://www.example.com/confirmOrder +
    -Пример запроса (с пояснениями): +
    -/* ВСЕ АТРИБУТЫ ОБЯЗАТЕЛЬНЫ, ЕСЛИ НЕ УКАЗАНО ИНОЕ */ +
    -{ +
    -"orderId": "10002", // (строка) идентификатор заказа +
    -"time": "2015-03-23T15-45-23" // (дата/время) время "на часах" вызывающей стороны на момент отправки запроса +
    -} +
    -Пример ответа (с пояснениями): +
    -/* ВСЕ АТРИБУТЫ ОБЯЗАТЕЛЬНЫ, ЕСЛИ НЕ УКАЗАНО ИНОЕ */ +
    -{ +
    -"tickets": [ // массив с информацией о билетах, входящих в заказ +
    -{ +
    -"performanceId": "20059", // (строка) идентификатор мероприятия +
    -"placeId": "20049", // (строка) идентификатор места +
    -"error": { // информация о причине (ошибке) по которой не удалось подтвердить покупку данного конкретного билета; +
    -если подтверждение прошло успешно, то данное свойство должно отсутствовать +
    -"code": 250, // (целое число) код ошибки +
    -"message": "Билет не найден" // (строка) текстовое сообщение об ошибке +
    -} +
    -} +
    -] +
    -} +
    -Метод orderedTickets. +
    -Получение списка билетов, входящих в заказ. Если заказ с указанным идентификатором не найден, следует вернуть сообщение об ошибке. Этот +
    -метод может быть вызван как до подтверждения заказа так и после. +
    -Пример вызова: GET http://www.example.com/orderedTickets?orderId=10002 +
    -Входные параметры: +
    -orderId (строка) - идентификатор заказа. +
    -Пример ответа (с пояснениями): +
    -/* ВСЕ АТРИБУТЫ ОБЯЗАТЕЛЬНЫ, ЕСЛИ НЕ УКАЗАНО ИНОЕ */ +
    -{ +
    -"tickets": [ // массив объектов, каждый из которых описывает очередной билет, входящий в заказ +
    -{ +
    -"performanceId": "20059", // (строка) идентификатор мероприятия +
    -"placeId": "20049" // (строка) идентификатор места +
    -} +
    -] +
    -} +
    -Метод removeOrder. +
    -Удаление заказа. Данный метод может быть вызван как для неподтвержденного, так и для подтвержденного заказа и в обоих случаях должен работать +
    -одинаково, приводя к полному удалению заказа. Метод может вернуть сообщение об ошибке только в случае, если, вообще, не удалось удалить заказ +
    -целиком в силу каких-то ограничений или ошибок. Если же при удалении заказа возникли ошибки лишь с некоторыми билетами, входящими в него, +
    -то метод должен проинформировать об этом в теле своего ответа (см. пример ниже). Если на момент вызова метода заказ уже был удален, то метод +
    -должен отработать идемпотентно и вернуть такой же результат, как если бы заказ существовал и был успешно удален. +
    -Пример вызова: POST http://www.example.com/removeOrder +
    -Пример запроса (с пояснениями): +
    -/* ВСЕ АТРИБУТЫ ОБЯЗАТЕЛЬНЫ, ЕСЛИ НЕ УКАЗАНО ИНОЕ */ +
    -{ +
    -"orderId": "10002", // (строка) идентификатор заказа +
    -"time": "2015-03-23T15-45-23" // (дата/время) время "на часах" вызывающей стороны на момент отправки запроса +
    -} +
    -Пример ответа (с пояснениями): +
    -/* ВСЕ АТРИБУТЫ ОБЯЗАТЕЛЬНЫ, ЕСЛИ НЕ УКАЗАНО ИНОЕ */ +
    -{ +
    -/* +
    -Массив объектов, каждый из которых описывает билет, с которым возникла проблема в ходе удаления заказа. +
    -Если при удалении заказа, с очередным билетом не возникло никаких проблем, то информация об этом билете НЕ +
    -ДОЛЖНА попасть в данный массив. +
    -Если на момент вызова метода заказа уже не существовало, то данный массив должен быть пустым. +
    -*/ +
    -"tickets": [ +
    -{ +
    -"performanceId": "20059", // (строка) идентификатор мероприятия +
    -"placeId": "20049", // (строка) идентификатор места +
    -"error": { // информация о причине (ошибке) по которой не удалось удалить данный билет из заказа +
    -"code": 350, // (целое число) код ошибки +
    -"message": "Невозвратный билет" // (строка) текстовое сообщение об ошибке +
    -} +
    -} +
    -] +
    -} +
    -Метод returnTickets. +
    -Возврат билетов. Данный метод может быть вызван только для подтвержденного заказа. Позволяет вернуть как все билеты, так и отдельные. Метод +
    -может вернуть сообщение об ошибке по каждому отдельному билету. Может вызываться несколько раз для одного заказа, пока в заказ содержит +
    -невозвращенные билеты. Если на момент вызова метода билет возвращен, то метод должен отработать идемпотентно и вернуть такой же результат, +
    -как если бы билет еще не был возвращен и был успешно возвращен. +
    -Пример вызова: POST http://www.example.com/returnTickets +
    -/* ВСЕ АТРИБУТЫ ОБЯЗАТЕЛЬНЫ, ЕСЛИ НЕ УКАЗАНО ИНОЕ */ +
    -{ +
    -"orderId": "10002", // (строка) идентификатор заказа +
    -"time": "2015-03-23T15-45-23", // (дата/время) время "на часах" вызывающей стороны на момент отправки запроса +
    -"tickets": [ // массив объектов, каждый из которых описывает возвращаемый билет +
    -{ +
    -"performanceId": "20059", // (строка) идентификатор мероприятия +
    -"placeId": "20049", // (строка) идентификатор места +
    -"price": "100.00", // (дробное число) цена билета на момент выполнения операции +
    -"returnPrice": "50.00" // (дробное число) стоимость билета возвращаемая клиенту, согласно закону от 18.07.2019 +
    -№193-ФЗ +
    -} +
    -] +
    -} +
    -Пример ответа (с пояснениями): +
    -/* ВСЕ АТРИБУТЫ ОБЯЗАТЕЛЬНЫ, ЕСЛИ НЕ УКАЗАНО ИНОЕ */ +
    -{ +
    -/* +
    -Массив объектов, каждый из которых описывает билет, с которым возникла проблема в ходе удаления заказа. +
    -Если при возврате билетов, с очередным билетом не возникло никаких проблем, то информация об этом билете НЕ +
    -ДОЛЖНА попасть в данный массив. +
    -Если на момент вызова метода билет был уже возвращен, то данный массив должен быть пустым. +
    -*/ +
    -"tickets": [ +
    -{ +
    -"performanceId": "20059", // (строка) идентификатор мероприятия +
    -"placeId": "20049", // (строка) идентификатор места +
    -"error": { // информация о причине (ошибке) по которой не удалось удалить данный билет из заказа +
    -"code": 350, // (целое число) код ошибки +
    -"message": "Невозвратный билет" // (строка) текстовое сообщение об ошибке +
    -} +
    -} +
    -] +
    -} +
    -Метод salesReport. +
    -Получение отчета о продажах билетов. Данный метод вызывается для проведения сверки продаж по данным системы компании Ticketland и данным +
    -реализуемого сервиса с целью поиска и корректировки возможных расхождений. Идеологически, этот метод относится к API для работы с билетами. +
    -Пример вызова: GET http://www.example.com/salesReport?fromInclusive=2015-03-23T00-00-00&tillExclusive=2015-03- +
    -24T00-00-00 +
    -Входные параметры: +
    -fromInclusive (дата/время) - время начала (включительно) интересующего периода построения отчета +
    -tillExclusive (/) - () +
    -Пример ответа (с пояснениями): +
    -/* ВСЕ АТРИБУТЫ ОБЯЗАТЕЛЬНЫ, ЕСЛИ НЕ УКАЗАНО ИНОЕ */ +
    -{ +
    -"tickets": [ // массив объектов, каждый из которых описывает информацию об очередном билете с которым была +
    -выполнена та или иная операция (продажа, возврат) +
    -{ +
    -"performanceId": "20059", // (строка) идентификатор мероприятия +
    -"placeId": "20049", // (строка) идентификатор места +
    -"operationTime": "2015-03-23T15-45-23", // (дата/время) время выполнения операции с билетом +
    -"operationType": "sale", // тип выполненной операции; возможные значения "sale" - продажа билета, "return" - возврат +
    -билета; в течении запрашиваемого периода один и тот же билет может выкупаться и возвращаться несколько раз. +
    -"price": "250.00" // (дробное число) цена билета на момент выполнения операции +
    -}, +
    -{ +
    -"performanceId": "20059", +
    -"placeId": "20050", +
    -"operationTime": "2015-03-23T18-19-03", +
    -"operationType": "return", +
    -"price": "3200.00" // (дробное число) стоимость билета возвращенная клиенту +
    -} +
    -] +
    -} +

    api.1589277742.txt.gz · Последнее изменение: 2020/05/12 13:02 — d.gudkov