Cinema Park API

PHP библиотека для интеграции с информационными системами Синема Парк.

Старт
- Composer
- Инициализация
Использование
- Получение информации по кинотеатрам, фильмам и сеансам
- Организация интернет-бронирования и продаж
Вспомогательная информация
Автор
Лицензия

Старт

Установка через composer

$ composer require axp-dev/cinemapark-api

Инициализация

$CinemaPark = new AXP\CinemaPark\CinemaPark();

// Получаем информаицю по фильму "Гадкий я 3"
$film = $CinemaPark->getFilmInfo(3679);

Использование

Получение списка мультиплексов и городов

public function getMultiplexes() : array

Результат ответа

Поле	Тип	Описание
id	integer	Идентификатор мультиплекса
short_name	string	Короткое название мультиплекса
full_name	string	Полное название мультиплекса
description	string	Описание кинотеатра
phone	string	Телефон кинотеатра
formats	array	Список форматов показа фильмов
city_id	integer	Идентификатор города мультиплекса
city_name	string	Наименование города мультиплекса
address	string	Адес мультиплекса
multiplex_geo	string	Географические координаты мультиплекса

Получение списка фильмов

В список могут попадать фильмы, не значащиеся в расписании мультиплексов (к примеру, поставленные в прокат на будущее, но без конкретного расписания).

public function getFilms() : array

Результат ответа

Поле	Тип	Описание
has_subtitles	bool	Если фильм идёт с субтитрами (скорее всего, с оригинальной звуковой дорожкой)
age_id	integer	Код возрастных ограничений. Подробнее
startdate	string	Дата старта проката в нашей сети (без учёта возможных премьерных показов)
genre	string	Текстовое описание жанра фильма
original_title	string	Оригинальное название фильма (для иностранных фильмов)
timing	integer	Продолжительность фильма в минутах
age_limit	integer	Возрастное ограничение. В будущем будет произведён полный переход от age_id к age_limit
category	string	Slug категории
title	string	Русскоязычное название фильма с учётом формата
film_id	integer	Идентификатор фильма
youtubeid	string	Список трейлеров с Youtube (через запятую)

Привязка фильмов к мультиплексам

В список могут попадать фильмы, не значащиеся в расписании мультиплексов (к примеру, поставленные в прокат на будущее, но без конкретного расписания).

public function getFilmsMultiplexes() : array

Результат ответа

Поле	Тип	Описание
id	integer	Идентификатор фильма
multiplex	array	Идентификатор мультиплекса, к которому привязан фильм

Получение расписания фильма

Выводится всё известное расписание, в т.ч. и прошедшие сеансы.

public function getRepertoir($id) : array

Параметры метода

Аргумент	Тип	Описание
id	integer	Идентификатор фильма

Результат ответа

Поле	Тип	Описание
format_id	integer	Идентификатор формата показа, соответствующий выгрузке formats
hall	integer	Идентификатор зала (уникален для всей сети)
base_price	integer	Цена билета на сеанс без учёта скидок (в российских рублях)
id	integer	Идентификатор сеанса
state	bool	Состояние сеанса (открыт, либо фильмокопия не поступила / произошёл срыв сеанса / сеанс отменён). Подробнее
datetime	string	Дата/время сеанса (местное время соответствующего мультиплекса)
multiplex	integer	Идентификатор мультиплекса
glasses_price	integer	Дополнительная стоимость, взимаемая на кассе за 3D-очки

Получение расписания мультиплекса

public function getMultiplexRepertoir($id) : array

Параметры метода

Аргумент	Тип	Описание
id	integer	Идентификатор мультиплекса

Результат ответа

Поле	Тип	Описание
format_id	integer	Идентификатор формата показа, соответствующий выгрузке formats
hall	integer	Идентификатор зала (уникален для всей сети)
base_price	integer	Цена билета на сеанс без учёта скидок (в российских рублях)
id	integer	Идентификатор сеанса
state	bool	Состояние сеанса (открыт, либо фильмокопия не поступила / произошёл срыв сеанса / сеанс отменён). Подробнее
datetime	string	Дата/время сеанса (местное время соответствующего мультиплекса)
multiplex	integer	Идентификатор мультиплекса
glasses_price	integer	Дополнительная стоимость, взимаемая на кассе за 3D-очки

Получение дополнительной информации по фильму

public function getFilmInfo($id) : array

Параметры метода

Аргумент	Тип	Описание
id	integer	Идентификатор фильма

Результат ответа

Поле	Тип	Описание
hit	bool	Присвоен ли фильму статус «Хит»
description	string	Описание фильма
addinfo	array	Дополнительная информация, тип которой указан в атрибуте «title» (режиссёр, актёры, озвучка)
year	integer	Год выпуска фильма
country	string	Страна фильма

Получение списка залов по всем мультиплексам

public function getHalls() : array

Результат ответа

Поле	Тип	Описание
multiplex_id	integer	Идентификатор мультиплекса
title	string	Идентификатор зала внутри мультиплекса
id	integer	Идентификатор зала внутри мультиплекса

Получение списка форматов показа фильмов

public function getFormats() : array

Результат ответа

Поле	Тип	Описание
id	integer	Идентификатор формата (показываемый в выгрузке repertoir как format_id)
short_name	string	Наименование формата
title_suffix	sting	Текстовая строка, которую нужно добавить к названию фильма, чтобы получить «название фильма с учётом формата»
priority	integer	Очерёдность показа формата в списке форматов

Комплексная выгрузка текущего расписания мультиплекса

public function getTimeTable($id) : array

Параметры метода

Аргумент	Тип	Описание
id	integer	Идентификатор мультиплекса

Результат ответа

Поле	Тип	Описание
hall	integer	Идентификатор зала (уникален для всей сети)
hall_title	string	Маркетинговое/коммерческое наименование зала
datetime	string	Дата/время сеанса (местное время соответствующего мультиплекса)
base_price	integer	Цена билета на сеанс без учёта скидок (в российских рублях)
age_limit	integer	Возрастное ограничение на фильм
title	string	Название фильма с учётом формата
hall_website_id	integer	Идентификатор зала на сайте СИНЕМА ПАРК
has_subtitles	bool	Наличие субтитров на сеансе

Проверка возможности начать сессию выбора мест для бронирования или покупки мест

public function checkBSession($multiplex_id, $repertoir_id, $mode) : array

Параметры метода

Аргумент	Тип	Описание
multiplex_id	integer	Идентификатор мультиплекса
repertoir_id	integer	Идентификатор сеанса (уникален в пределах мультиплекса)
mode	integer	Режим открытия сессии выбора мест. Подробнее

Результат ответа

Поле	Тип	Описание
status	integer	Можно ли начать сессию выбора мест. 0 - Нельзя, 1- Можно.
mode_available	integer/array	Доступность режимов открытия сессии выбора мест. 0 - Нельзя, 1- Можно.
b_session_availability	integer	Код доступности инициализации сессии. Подробнее
repertoir_status	integer	Возможность работы с сеансом. Подробнее

Инициализация сессии выбора мест для бронирования или покупки

public function initBSession($multiplex_id, $repertoir_id, $mode) : array

Параметры метода

Аргумент	Тип	Описание
multiplex_id	integer	Идентификатор мультиплекса
repertoir_id	integer	Идентификатор сеанса (уникален в пределах мультиплекса)
mode	integer	Режим открытия сессии выбора мест. Подробнее

Результат ответа

Поле	Тип	Описание
status	integer	Можно ли начать сессию выбора мест. 0 - Нельзя, 1- Можно.
b_session_id	string	Идентификатор сессии выбора мест, использующийся в дальнейшем при выборе мест и отмене/фиксации сессии

Получение геометрической схемы зала

Схему зала можно кешировать, рассчитывая на то, что в данном конкретном сеансе она не изменится.

public function seatsLayout($multiplex_id, $repertoir_id) : array

Параметры метода

Аргумент	Тип	Описание
multiplex_id	integer	Идентификатор мультиплекса
repertoir_id	integer	Идентификатор сеанса (уникален в пределах мультиплекса)

Результат ответа

Поле	Тип	Описание
id	integer	ID места. Используется для выбора или для отмены выбора места
number	integer	Номер зрительского кресла (расположен на спинке кресла)
row	integer	Ряд зрительских кресел
xpos	integer	X-координата кресла на схеме зала
ypos	integer	Y-координата кресла на схеме зала
block_No	integer	Номер блока для групповых мест (диванов). Присутствует, если место является частью группового.

Получение состояния мест

public function seatStates($multiplex_id, $repertoir_id, $b_session_id, $timestamp_tz = 0) : array

Параметры метода

Аргумент	Тип	Описание
multiplex_id	integer	Идентификатор мультиплекса
repertoir_id	integer	Идентификатор сеанса (уникален в пределах мультиплекса)
b_session_id	string	Идентификатор сессии выбора мест
timestamp_tz	integer	Дата/время в формате Unix Timestamp

Результат ответа

Поле	Тип	Описание
sql_date	array	Время на стороне нашей системы, соответствующее выводимым данным
b_session_data	array	Данные сессии выбора мест (при наличии)
seat_states	array	Данные по месту (при наличии)

Данные в `b_session_data`

Поле	Тип	Описание
ts_start_tz	integer	Время начала сессии в формате Unix Timestamp
status	integer	Текущий статус сессии выбора мест. Подробнее

Данные в `seat_states`

Поле	Тип	Описание
is_mine	bool	Принадлежит ли место текущей сессии выбора мест
seat_id	integer	ID места, соответствующее выгрузке `seatsLayout()`.
state	integer	Состояние места. Подробнее

Действие с местом в сессии выбора мест

Выбор места или снятие выбора

public function seatAction($multiplex_id, $repertoir_id, $b_session_id, $action_type, $seat_id) : array

Параметры метода

Аргумент	Тип	Описание
multiplex_id	integer	Идентификатор мультиплекса
repertoir_id	integer	Идентификатор сеанса (уникален в пределах мультиплекса)
b_session_id	string	Идентификатор сессии выбора мест
action_type	integer	Тип запроса. 0 - Снятие выбора, 1 - Выбор места
seat_id	integer	Идентификатор места

Результат ответа

Поле	Тип	Описание
status	bool	Удалось или нет произвести действие с местом
statustext	string	Текстовое описание проблемы, возникшей при попытке произвести действие с местом. В зависимости от проблемы может выводиться либо примерное описание проблемы (к примеру, «Сеанс отменён»), либо информация о внутренних системных ошибках с соответствующими номерами ошибок.

Отмена или закрытие сессии выбора мест

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

public function cancelBSession($multiplex_id, $repertoir_id, $b_session_id) : array

Параметры метода

Аргумент	Тип	Описание
multiplex_id	integer	Идентификатор мультиплекса
repertoir_id	integer	Идентификатор сеанса (уникален в пределах мультиплекса)
b_session_id	string	Идентификатор сессии выбора мест

Результат ответа

Поле	Тип	Описание
status	bool	Удалось или нет произвести закрытие сессии выбора мест
statustext	string	Текстовое описание проблемы, возникшей при попытке произвести действие с местом. В зависимости от проблемы может выводиться либо примерное описание проблемы (к примеру, «Сеанс отменён»), либо информация о внутренних системных ошибках с соответствующими номерами ошибок.

Закрытие сессии выбора мест

Фиксация выбора мест

public function commitBSession($multiplex_id, $repertoir_id, $b_session_id, $mode, $email, $phone, $provider_id) : array

Параметры метода

Аргумент	Тип	Описание
multiplex_id	integer	Идентификатор мультиплекса
repertoir_id	integer	Идентификатор сеанса (уникален в пределах мультиплекса)
b_session_id	string	Идентификатор сессии выбора мест
mode	integer	Режим открытия сессии выбора мест. Подробнее
email	string	Адрес электронной почты для получения уведомлений об изменении состояния заказа
phone	integer	Номер телефона (10 цифр) для получения sms-уведомлений об изменении состояния заказа
provider_id	integer	Идентификатор платёжного агента. Подробнее

Результат ответа

Поле	Тип	Описание
status	bool	Удалось или нет закрыть сессию выбора мест
statustext	string	Текстовое описание проблемы, возникшей при попытке произвести действие с местом. В зависимости от проблемы может выводиться либо примерное описание проблемы (к примеру, «Сеанс отменён»), либо информация о внутренних системных ошибках с соответствующими номерами ошибок.
order_id	integer	Номер заказа. В случае бронирования он соответствует номеру брони, в случае продажи – будущему номеру продажи

Открытие сессии выбора мест после фиксации

Для брони – редактирование существующей брони, для продажи – возврат в режим выбора мест до осуществления оплаты Если существующая бронь была переведена в режим редактирования и после этого не произошло завершение сессии с фиксацией выбора мест через commitBSession(), то бронь будет отменена по тайм-ауту.

public function editBooking($multiplex_id, $repertoir_id, $codeword) : array

Параметры метода

Аргумент	Тип	Описание
multiplex_id	integer	Идентификатор мультиплекса
repertoir_id	integer	Идентификатор сеанса (уникален в пределах мультиплекса)
codeword	string	Кодовое слово заказа. Вводится пользователем и передаётся в нашу систему в момент фиксации выбора мест. Максимум 16 символов

Результат ответа

Поле	Тип	Описание
status	bool	Удалось или нет перевести бронь в режим редактирования
statustext	string	Текстовое описание проблемы, возникшей при попытке произвести действие с местом. В зависимости от проблемы может выводиться либо примерное описание проблемы (к примеру, «Сеанс отменён»), либо информация о внутренних системных ошибках с соответствующими номерами ошибок.
b_session_id	string	Идентификатор сессии выбора мест, который впоследствии используется для выбора мест и последующей отмены или завершения сессии с фиксацией выбора мест

Инициализация сессии оплаты

Вызывается перед направлением пользователя на страницу оплаты (после того, как был зафиксирован выбор мест, сформирована цена заказа и пользователь изъявил желание оплатить заказ)

public function initSSession($multiplex_id, $order_id, $codeword, $provider_id) : array

Параметры метода

Аргумент	Тип	Описание
multiplex_id	integer	Идентификатор мультиплекса
order_id	integer	Идентификатор заказа в конкретном мультиплексе
codeword	string	Кодовое слово заказа. Вводится пользователем и передаётся в нашу систему в момент фиксации выбора мест. Максимум 16 символов
provider_id	integer	Идентификатор платёжного агента. Подробнее

Результат ответа

Поле	Тип	Описание
status	bool	Удалось или нет произвести инициализацию сессии оплаты
statustext	string	Текстовое описание проблемы, возникшей при попытке инициализировать сессию оплаты. В зависимости от проблемы может выводиться либо примерное описание проблемы (к примеру, «Время на оплату истекло»), либо информация о внутренних системных ошибках с соответствующими номерами ошибок.
order_number	string	Номер заказа для последующего сообщения клиенту. Формат – MM-NNNNNN
amount	integer	Сумма заказа в российских рублях на момент инициализации сессии. Должна совпадать с суммой оплаты, передаваемой в `commitSSession()`.
timestamp_validuntil	integer	Время, до которого необходимо оплатить заказ (UTC)
timestamp_validuntil_tz	integer	Это же время в формате timestamp tz
security_key	string	Цифровая подпись запроса на оплату. Формируется в соответствии с индивидуальными для каждого платёжного агента договорённостями

Фиксация факта оплаты заказа

public function commitSSession($multiplex_id, $order_id, $provider_id, $amount, $dt_payment, $transaction_id, $payment_type, $payment_info, $security_key) : array

Параметры метода

Аргумент	Тип	Описание
multiplex_id	integer	Идентификатор мультиплекса
order_id	integer	Идентификатор заказа в конкретном мультиплексе
provider_id	integer	Идентификатор платёжного агента. Подробнее
amount	integer	Сумма оплаты в российских рублях. Должна соответствовать сумме, полученной в результате обращения к `initSSession()`
dt_payment	string	Дата/время платежа в соответствии с данными платёжной системы, UTC, формат «YYYY-MM-DD HH:MM:SS»
transaction_id	mixed	Идентификатор транзакции в платёжной системе (или в вашей системе обработки платежей)
payment_type	string	Наименование механизма оплаты (к примеру, Card – банковская карта, Qiwi – платёжная система Qiwi и т.д.). Строка, максимум 20 символов.
payment_info	string	Информация о плательщике, которая может помочь дежурному администратору кинотеатра определить «владельца заказа» в случае, когда клиент не может вспомнить номер заказа и кодовое слово
security_key	string	Цифровая подпись подтверждения платежа. Формируется по тем же правилам, что в методе `initSSession()`

Результат ответа

Поле	Тип	Описание
status	bool	Оплаты прошла успешно

Фиксация факта неудачи оплаты заказа

public function registerPaymentFailure($multiplex_id, $order_id, $provider_id, $amount, $dt_payment, $transaction_id, $payment_type, $payment_info, $security_key) : array

Параметры метода

Параметры полностью идентичны используемым в commitSSession(). Подробнее

Результат ответа

Поле	Тип	Описание
result	string	Сообщение от сервиса

Вспомогательная информация

Код возрастных ограничений

Значение	Описание
1	без ограничений по возрасту
2	до 12 лет в сопровождении родителей
3	достигшим 14 лет
4	достигшим 16 лет
5	достигшим 18 лет
6	для детей старше 6 лет

Состояние сеанса

Значение	Описание
1	Сеанс открыт, в нём можно бронировать и покупать билеты
не 1	Сеанс не открыт, в нём нельзя бронировать и покупать билеты

Вопрос «показывать ли пользователю сеансы, где state != 1» остаётся на ваше усмотрение.

Режим открытия сессии выбора мест

Значение	Описание
0	Проверка режимов бронирования и покупки
1	Бронирование
2	Покупка

Код доступности инициализации сессии

Значение	Описание
0	Ошибка получения статуса
1	Можно инициализировать сессию
2	Превышено общее количество активных сессий
3	Превышено количество активных сессий в мультиплексе
4	Превышено количество активных сессий в сеансе
5	Превышено количество активных сессий по IP-адресу
6	Превышено общее количество сессий по IP-адресу
7	Превышено количество бронирований по IP-адресу
8	Система недоступна, ведутся технические работы

Для IP, внесённых в «белый список», всегда должно возвращаться 1.

Возможность работы с сеансом

Значение	Описание
0	Различные нарушения целостности базы данных
1	Нет соединения с базой данных
2	Отсутствует сеанс
3	Сеанс не открыт
4	В зале нет ни одного свободного места, бронь и продажи закрыты
5	Всё OK, сеанс открыт – можно бронировать и продавать
6	Слишком мало времени до сеанса, продажа запрещена
7	Слишком мало времени до сеанса, бронирование запрещено
8	Сеанс прошёл
9	В зале осталось мало свободных мест — разрешена только продажа
10	В данном сеансе разрешено только бронирование

Статус сессии выбора мест

Значение	Описание
1	Идёт выбор мест
2	Выбор мест отменён (пользователь отказался от бронирования/покупки на стадии выбора мест)
3	Таймаут выбора (сессия закрыта по тайм-ауту, пользователь не отказался от выбора мест, но и не подтвердил его)
4	Места забронированы
5	Бронь снята (после подтверждения брони пользователь отказался от неё)
6	Таймаут оплаты (после фиксации выбора мест оплата не поступила в установленное время)
7	Покупка совершена, места оплачены

Состояние места

Значение	Описание
0	Место свободно
1	Место блокировано (в настоящий момент выбрано для бронирования или продажи)
2	Место забронировано
3	Место продано (билет выдан на руки клиенту)

Идентификаторы платёжного агента

Значение	Описание
1	PayOnline
2	Рамблер/Афиша
3	Киноход

Автор

Alexander Pushkarev, e-mail: axp-dev@yandex.com

Лицензия

Основой Cinema Park API являет открытый исходный код, в соответствии MIT license

Name		Name	Last commit message	Last commit date
Latest commit History 31 Commits
examples		examples
src		src
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
composer.json		composer.json

License

axp-dev/cinemapark-api

Folders and files

Latest commit

History

Repository files navigation

Cinema Park API

Оглавление

Старт

Установка через composer

Инициализация

Использование

Получение списка мультиплексов и городов

Результат ответа

Получение списка фильмов

Результат ответа

Привязка фильмов к мультиплексам

Результат ответа

Получение расписания фильма

Параметры метода

Результат ответа

Получение расписания мультиплекса

Параметры метода

Результат ответа

Получение дополнительной информации по фильму

Параметры метода

Результат ответа

Получение списка залов по всем мультиплексам

Результат ответа

Получение списка форматов показа фильмов

Результат ответа

Комплексная выгрузка текущего расписания мультиплекса

Параметры метода

Результат ответа

Проверка возможности начать сессию выбора мест для бронирования или покупки мест

Параметры метода

Результат ответа

Инициализация сессии выбора мест для бронирования или покупки

Параметры метода

Результат ответа

Получение геометрической схемы зала

Параметры метода

Результат ответа

Получение состояния мест

Параметры метода

Результат ответа

Данные в b_session_data

Данные в seat_states

Действие с местом в сессии выбора мест

Параметры метода

Результат ответа

Отмена или закрытие сессии выбора мест

Параметры метода

Результат ответа

Закрытие сессии выбора мест

Параметры метода

Результат ответа

Открытие сессии выбора мест после фиксации

Параметры метода

Результат ответа

Инициализация сессии оплаты

Параметры метода

Результат ответа

Фиксация факта оплаты заказа

Параметры метода

Результат ответа

Фиксация факта неудачи оплаты заказа

Параметры метода

Результат ответа

Вспомогательная информация

Код возрастных ограничений

Состояние сеанса

Режим открытия сессии выбора мест

Код доступности инициализации сессии

Возможность работы с сеансом

Статус сессии выбора мест

Состояние места

Идентификаторы платёжного агента

Автор

Лицензия

Данные в `b_session_data`

Данные в `seat_states`

Packages