Общая информация.
Все функции API доступны как при использовании HTTP-метода GET, так и POST (т.к. глагол уже содержится в названиях функций).
В случае POST аргументы можно передавать как с использованием Content-Type <i>x-www-form-urlencoded</i>, так и <i>application/json</i>.
Все функции, кроме <i>AddStudyRequest</i> требуют передачи ключа доступа через аргумент <i>authkey</i>. Получить ключ можно разделе Настройки->Интеграция->API.
Любая из функций API может принимать аргумент culture. На данный момент поддерживаются два значения: «ru-RU» и «en-US». Если аргумент не указан, берётся культура по умолчанию: «ru-RU».
Передавать данный аргумент можно только через URL.
Его значение влияет на приём/возврат чисел (разные десятичные разделители и разделители групп разрядов) и транслитерацию имён филиалов и валют.
Вызывать функции можно как с серверной стороны сайта (это предпочтительный вариант), так и с клиентской (поддерживается jsonp).
При вызове с клиентской стороны имейте в виду, что ключ размещается в открытом доступе. Поэтому используйте для этого специальный ключи (только для одной ф-ции) и только для ф-ций, не возвращающих конфиденциальную информацию.
В случае ошибки при вызове любой из функций возвращается два поля: "errorType" и "errorMessage". Поле "errorMessage" может отсутствовать, однако, "errorType" в случае ошибки присутствует всегда. Таким образом, наличие ошибки можно проверять по наличию поля "errorType".
Пример:
{
"errorType": "UnauthorizedAccessException",
"errorMessage": "Попытка выполнить несанкционированную операцию."
}
Запрос филиалов.
Для получения списка филиалов необходимо отправить GET-запрос на следующий url: https://schooldomain.t8s.ru//Api/V1/GetSchools (где schooldomain - субдомен школы).
Список параметров (ни один не является обязательным):
Название | Описание |
id | Идентификатор филиала |
name | Наименование филиала (по полному совпадению, без учёта регистра) |
license | По номеру лицензии (по частичному совпадению, без учёта регистра) |
Пример результата:
{
"Schools":
[{
"Id": 5, // Идентификатор филиала
"Name": "Главный филиал", // Наименование филиала
"Location": "Основная локация", // Наименование локации
"Address": "г. Москва", // Адрес филиала
"EMail": "[email protected]", // E-mail филиала
"Phone": "+71111111111", // Телефон филиала
"IsVirtual": false, // Если true, то филиал является филиалом виртуального типа (для дистанционного обучения)
"TimeZone": "+3:00", // Часовой пояс филиала
"License": "№123" // Номер лицензии филиала
},
...]
}
Запрос компаний (корп. клиентов).
Url: https://schooldomain.t8s.ru//Api/V1/GetCompanies
Список параметров (ни один не является обязательным):
Название | Описание |
id | Идентификатор компании |
clientId | Идентификатор компании как клиента (клиентом может быть как ученик, так и компания) |
name | Наименование компании (по полному совпадению, без учёта регистра) |
Пример результата:
{
"Companies":
[{
"Id": 8, // Идентификатор компании
"ClientId": 10, // Идентификатор компании как клиента
"Name": "Microsoft", // Наименование компании
"Address": "г. Москва", // Адрес компании
"EMail": "[email protected]", // E-mail компании
"Phone": "+71111111111" // Телефон компании
},
...]
}
Запрос заявок на обучение.
Url: https://schooldomain.t8s.ru//Api/V1/GetStudyRequests
Список параметров (ни один не является обязательным):
Название | Описание |
id | Идентификатор заявки |
begin | Начальные дата и время создания заявки |
end | Конечные дата и время создания заявки |
status | Битовая маска статуса заявки (1 - необработанная, 2 - обработанная, 4 - удалённая в архив без обработки, 8 - удалённая из архива) |
location | Наименование локации в заявке |
school | Наименование филиала в заявке |
leadId | Идентификатор лида, подтверждённого по заявке |
studentId | Идентификатор ученика, подтверждённого по заявке |
studentClientId | Идентификатор клиента-ученика, подтверждённого по заявке |
Результат возвращается в формате json в виде массива объектов “StudyRequests”.
Пример результата:
{
"StudyRequests":
[{
"Id": 123, // Идентификатор заявки (отсутствует для удалённых из архива)
"Created": "2019-10-09T15:30:23", // Дата и время создания заявки в UTC
"Status": 1, // Статус заявки (0 - необработанная, 1 - обработанная, 2 - удалённая в архив без обработки, отсутствует для удалённых из архива)
"Location": "Москва", // Локация
"School": "Основной филиал", // Филиал
"Name": "Иван Иванов", // Имя
"EMail": "[email protected]", // E-mail
"Phone": "+71111111111" // Телефон
"Birthday": "1981-01-20", // Дата рождения ученика в формате YYYY-MM-DD
"AgentName": "Ольга Иванова", // Имя контактного лица
"AgentEMail": "[email protected]", // E-mail контактного лица
"AgentPhone": "+71111111112" // Телефон контактного лица
"Discipline": "Английский", // Дисциплина
"LearningLevel": "Начальный", // Уровень
"Teacher": "Сидоров Иван", // Преподаватель
"BeginDate": "2019-10-20", // Желаемая дата начала занятий
"EndDate": "2019-11-01", // Желаемая дата окончания занятий
"Weekdays": 15, // Маска желаемых дней недели
"BeginTime": "15:30", // Желаемое время начала занятий
"EndTime": "16:30", // Желаемое время окончания занятий
"Type": "Заявка с сайта школы", // Тип заявки
"Description": "Примечание от ученика",
"ExtraData": "someData", // Произвольные пользовательские данные
// UTM-метки
"Utm": {
"Source": "SomeSource", // utm_source
"Medium": "SomeMedium", // utm_medium
"Campaign": "SomeCampaign", // utm_campaign
"Term": "SomeTerm", // utm_term
"Content": "SomeContent" // utm_content
},
"Referrer": "http://somesite.ru", // Ссылка на источник заявки
"Comment": "Комментарий от сотрудника",
"LeadId": 23, // Идентификатор лида, подтверждённого по заявке
"StudentId": 24, // Идентификатор ученика, подтверждённого по заявке
"StudentClientId": 52 // Идентификатор клиента-ученика, подтверждённого по заявке
},
...]
}
Запрос лидов.
Url: https://schooldomain.t8s.ru//Api/V1/GetLeads
Список параметров (ни один не является обязательным):
Название | Описание |
id | Идентификатор лида |
schoolId | Идентификатор школы/компании |
term | Общее выражение для поиска (ФИО, ФИ, ИФ, телефон или email) |
byAgents | Булевский признак того, что выражение term будет использоваться и для поиска по конт. лицам. По умолчанию false. |
attached | Булевский признак: true – только прикреплённые к ученикам, false – только неприкреплённые к ученикам, null – все. По умолчанию null. |
studentId | Идентификатор ученика, к которому прикреплены лиды |
studentClientId | Идентификатор клиента-ученика, к которому прикреплены лиды |
extraFieldName | Имя пользовательского поля |
extraFieldValue | Значение пользовательского поля |
Результат возвращается в формате json в виде массива объектов “Leads”.
Пример результата:
{
"Leads":
[{
"Id": 123, // Идентификатор лида
"Created": "2019-10-09T15:30:23", // Дата и время создания лида в UTC
"FirstName": "Иван", // Имя лида
"LastName": "Иванов", // Фамилия лида
"MiddleName": "Иванович", // Отчество лида
"Birthday": "1981-01-20", // Дата рождения лида в формате YYYY-MM-DD
"Phone": "+71111111111" // Телефон лида
"Mobile": "+79611111111" // Мобильный лида ученика
"UseMobileBySystem": false, // Если true, то моб. телефон отмечен как разрешённый для использования системой для рассылок/уведомлений
"EMail": "[email protected]", // E-mail лида
"UseEMailBySystem": true, // Если true, то e-mail отмечен как разрешённый для использования системой для рассылок/уведомлений
"Discipline": "Английский", // Дисциплина лида
"Level": "Начальный", // Уровень лида
// Массив контактных лиц
"Agents": [
{
"FirstName": "Ирина", // Имя контактного лица
"LastName": "Иванова", // Фамилия контактного лица
"MiddleName": "Ивановна", // Отчество контактного лица
"WhoIs": "Мать", // Кем приходится ученику
"Phone": "+71111111112" // Телефон контактного лица
"Mobile": "+79611111112" // Мобильный телефон контактного лица
"UseMobileBySystem": true, // Если true, то моб. телефон отмечен как разрешённый для использования системой для рассылок/уведомлений
"EMail": "[email protected]", // E-mail контактного лица
"UseEMailBySystem": false // Если true, то e-mail отмечен как разрешённый для использования системой для рассылок/уведомлений
},
...],
// Массив филиалов/компаний лица
"Schools": [
{
"Id": 5, // Идентификатор филиала
"Name": "Главный филиал" // Наименование филиала
},
...],
// Массив пользовательских полей лица
"ExtraFields": [
{
"Name": "Наименование пользовательского поля",
"Value": "Значение пользовательского поля"
},
...],
"StudentId": 23, // Ученик, к которому прикреплён лид
"StudentClientId": 52 // Клиент-ученик, к которому прикреплён лид
},
...]
}
Запрос учеников.
Url: https://schooldomain.t8s.ru//Api/V1/GetStudents
Список параметров (ни один не является обязательным):
Название | Описание |
id | Идентификатор ученика |
clientId | Идентификатор ученика как клиента (клиентом может быть как ученик, так и компания) |
schoolId | Идентификатор школы/компании |
term | Общее выражение для поиска (ФИО, ФИ, ИФ, телефон или email) |
byAgents | Булевский признак того, что выражение term будет использоваться и для поиска по конт. лицам. По умолчанию false. |
status | Имя статуса как оно указано в настройках (пустое значение – поиск учеников без статуса) |
extraFieldName | Имя пользовательского поля |
extraFieldValue | Значение пользовательского поля |
Результат возвращается в формате json в виде массива объектов “Students”.
Пример результата:
{
"Students":
[{
"Id": 123, // Идентификатор ученика
"Created": "2019-10-09T15:30:23", // Дата и время создания ученика в UTC
"ClientId": 236, // Идентификатор ученика как клиента
"FirstName": "Иван", // Имя ученика
"LastName": "Иванов", // Фамилия ученика
"MiddleName": "Иванович", // Отчество ученика
"Status": "Занимается", // Статус ученика
"Birthday": "1981-01-20", // Дата рождения ученика в формате YYYY-MM-DD
"Phone": "+71111111111" // Телефон ученика
"Mobile": "+79611111111" // Мобильный телефон ученика
"UseMobileBySystem": false, // Если true, то моб. телефон отмечен как разрешённый для использования системой для рассылок/уведомлений
"EMail": "[email protected]", // E-mail ученика
"UseEMailBySystem": true, // Если true, то e-mail отмечен как разрешённый для использования системой для рассылок/уведомлений
// Массив пар дисциплина-уровнь
"Disciplines": [
{
"Discipline": "Английский",
"Level": "Средний"
},
...],
// Массив контактных лиц
"Agents": [
{
"FirstName": "Ирина", // Имя контактного лица
"LastName": "Иванова", // Фамилия контактного лица
"MiddleName": "Ивановна", // Отчество контактного лица
"WhoIs": "Мать", // Кем приходится ученику
"Phone": "+71111111112" // Телефон контактного лица
"Mobile": "+79611111112" // Мобильный телефон контактного лица
"UseMobileBySystem": true, // Если true, то моб. телефон отмечен как разрешённый для использования системой для рассылок/уведомлений
"EMail": "[email protected]", // E-mail контактного лица
"UseEMailBySystem": false // Если true, e-mail отмечен как разрешённый для использования системой для рассылок/уведомлений
},
...],
// Массив филиалов/компаний ученика
"Schools": [
{
"Id": 5, // Идентификатор филиала
"Name": "Главный филиал" // Наименование филиала
},
...],
// Массив пользовательских полей ученика
"ExtraFields": [
{
"Name": "Наименование пользовательского поля",
"Value": "Значение пользовательского поля"
},
...]
},
...]
}
Запрос учебных единиц.
Url: https://schooldomain.t8s.ru//Api/V1/GetLearners
Список параметров:
Название | Описание |
id | Идентификатор учебной единицы |
types | Типы единиц обучения, которые необходимо получить. Возможные значения: Groups (группы), MiniGroups (мини-группы), OpenLessons (открытые уроки), Exams (экзамены), Tours (поездки), Individuals (инд. занятия). Данный параметр обязателен, если не указан id. |
beginDate | Начальная дата диапазона (если не указана, берётся текущая дата) в формате YYYY-MM-DD. |
endDate | Конечная дата диапазона (если не указана, не ограничивается) в формате YYYY-MM-DD. |
beginTime | Начальное время диапазона (если не указано, не ограничивается). |
endTime | Конечное время диапазона(если не указано, не ограничивается). |
weekdays | Дни недели. Целое число, которое формируется следующим образом: каждому дню недели соответствует определённая степень двойки. Для того, чтобы получить набор дней необходимо их просуммировать. Пн: 1, Вт: 2, Ср: 4, Чт: 8, Пт: 16, Сб: 32, Вс: 64 Например, Пн/Ср = 1 + 4 = 5 |
onlyForming | Выдавать только формирующиеся группы (true/false), по умолчанию false. На другие типы обучения не влияет. |
schoolId | Идентификатор школы (филиала) или компании-клиента. |
school | Название школы (филиала) или компании-клиента в виде строки. Например, Главный филиал. |
corporative | Если true, то возвращаются только корпоративные единицы обучения, false – только некорпоративные. По умолчанию не задано (возвращаются и те, и другие). |
discipline | Название языка в виде строки. Например, Английский. |
level | Название уровня в виде строки. Например, Intermediate. |
learningType | Название типа обучения в виде строки. Например, Общий. |
maturity | Название возрастной категории в виде строки. Например, Подростки. |
teacherId | Идентификатор преподавателя. |
queryPayableInfo | Булевский признак необходимости в запросе финансовой информации (будут возвращён объект «PayableInfo»). Принимает значения false и true, по умолчанию false. Может замедлить выполнение запроса. |
Примеры использования:
Все группы с 15:00 до 21:00:
Все группы и открытые уроки в Главном филиале:
Все английские группы с уровнем Intermediate:
Результат возвращается в формате json в виде массива объектов “Learners”. У каждого объекта есть ряд свойств и вложенный массив элементов расписания
Пример результата:
{
"Learners":
[{
"Id": 1535, // Идентификатор учебной единицы
"Type": "Groups", // Тип учебной единицы
"Name": "General Intermediate 108", // Название учебной единицы
"School": "Главный филиал", // Наименование филиала/компании
"SchoolId": 5, // Идентификатор филиала/компании
"IsCompany": false, // Если true, то уч. единица корпоративная, а в поле School указано наименование компании
"SchoolAddress": "Адрес филиала/компании",
"Discipline": "Английский", // Дисциплина
"Level": "Intermediate", // Уровень владения дисциплиной
"LearningType": "Общий", // Тип обучения
"Maturity": "Взрослые", // Возрастная категория
"StudentsCount": 5, // Количество учеников в группе/экзамене
"Vacancies": 2, // Количество свободных мест
"StudyUnitsInRange": "12 а.ч.", // Количество посещаемых (не пропусков) единиц в рамках диапазона [beginDate, endDate]
"Description": "Лучшая группа", // Примечание к учебной единице
// Финансовая информация (при queryPayableInfo = true)
"PayableInfo":
{
"Units": "24 а.ч.", // Кол-во оплачиваемых единиц (а.ч., дней) за весь период обучения (может отсутствовать, если расписание бесконечно)
"Units7": "2 а.ч.", // Кол-во оплачиваемых единиц за первые 7 дней обучения
"Units28": "8 а.ч.", // Кол-во оплачиваемых единиц за первые 28 дней обучения
"PriceId": 9, // Идентификатор цены по умолчанию
"Price": "Пакет (5 000,00 руб. за 10 а.ч.)", // Наименование цены по умолчанию
"PriceValue": "5 000,00 руб.", // Значение цены по умолчанию
"Value": "10 000 руб.", // Стоимость всего периода обучения по цене по умолчанию (может отсутствовать, если расписание бесконечно или не задана цена)
"Value7": "1 000 руб.", // Стоимость первых 7 дней обучения по цене по умолчанию (может отсутствовать, если не задана цена)
"Value28": "4 000 руб." // Стоимость первых 28 дней обучения по цене по умолчанию (может отсутствовать, если не задана цена)
},
// Массив расписаний
"ScheduleItems": [
{
"BeginDate": "13.11.2014", // Начальная дата
"EndDate": "26.03.2015", // Конечная дата
"Weekdays": 10, // Дни недели (в том же формате, что и в фильтре)
"BeginTime": "19:30", // Начальное время
"EndTime": "21:30", // Конечное время
"TeacherId": 123, // Идентификатор преподавателя
"Teacher": "Иванов И.И.", // ФИО преподавателя
"ClassroomId": 2, // Идентификатор аудитории (если отсутствует, то занятия проводятся на территории учащегося)
"Classroom": "№2", // Наименование аудитории (если отсутствует, то занятия проводятся на территории учащегося)
"Description": "Какое-либо описание элемента расписания" // Идентификатор аудитории (если отсутствует, то занятия проводятся на территории учащегося)
},
...]
},
...]
}
Запрос связок «Учебная единица - ученик».
Url: https://schooldomain.t8s.ru//Api/V1/GetLearnerStudents
Список параметров (ни один не является обязательным):
Название | Описание |
learnerId | Идентификатор единицы обучения (для получения всех учеников одной единицы обучения). |
learnerTypes | Типы единиц обучения, которые необходимо получить. Возможные значения: Groups (группы), MiniGroups (мини-группы), OpenLessons (открытые уроки), Exams (экзамены), Tours (поездки), Individuals (инд. занятия). |
learnerSchoolId | Идентификатор школы (филиала) или компании-клиента учебной единицы в виде строки. |
learnerSchool | Название школы (филиала) или компании-клиента учебной единицы в виде строки. Например, Главный филиал. |
learnerCorporative | Если true, то возвращаются только корпоративные единицы обучения, false – только некорпоративные. По умолчанию не задано (возвращаются и те, и другие). |
learnerDiscipline | Название языка учебной единицы в виде строки. Например, Английский. |
learnerLevel | Название уровня учебной единицы в виде строки. Например, Intermediate. |
learnerMaturity | Название возрастной категории учебной единицы в виде строки. Например, Подростки. |
studentId | Идентификатор ученика (для получения всех единиц обучения одного ученика) |
studentClientId | Идентификатор ученика как клиента |
beginDate | Начальная дата диапазона связки в формате YYYY-MM-DD. |
endDate | Конечная дата диапазона связки в формате YYYY-MM-DD. |
status | Статус ученика в учебной единице (может быть «Normal», «Reserve» , «WorkingOff» или «Stopped») |
contractExists | Если true, то возвращаются только связки, по которым в данный момент имеется заключенный договор. false – только без договора. По умолчанию не задано (возвращаются и те, и другие). |
queryDays | Булевский признак необходимости в запросе информации по дням (занятиям) связки. |
queryPayers | Булевский признак необходимости в запросе информации по плательщикам (будут возвращён объект «Payers»). Принимает значения false и true, по умолчанию false. Может замедлить выполнение запроса. |
Результат возвращается в формате json в виде массива объектов “LearnerStudents”.
Пример результата:
{
"LearnerStudents":
[{
"LearnerId": 1535, // Идентификатор учебной единицы
"LearnerType": "Group", // Тип учебной единицы
"LearnerName": "General Intermediate 108", // Название учебной единицы
"LearnerSchool": "Главный филиал", // Наименование филиала/компании учебной единицы
"LearnerSchoolId": 5, // Идентификатор филиала/компании учебной единицы
"LearnerCorporative": false, // Если true, то уч. единица корпоративная, а в поле School указано наименование компании
"LearnerDiscipline": "Английский", // Дисциплина учебной единицы
"LearnerLevel": 1535, "Intermediate", // Уровень владения дисциплиной, заданный для учебной единицы
"LearnerLearningType": "Общий", // Тип обучения учебной единицы
"LearnerMaturity": "Взрослые", // Возрастная категория учебной единицы
"StudentId": 123, // Идентификатор ученика
"StudentClientId": 236, // Идентификатор ученика как клиента
"StudentName": "Иванов Иван Иванович", // ФИО ученика
"BeginDate": "2017-01-20", // Начальная дата диапазона занятий связки в формате YYYY-MM-DD
"EndDate": "2017-02-01", // Конечная дата диапазона занятий связки (может отсутствовать)
"BeginTime": "7:40", // Время начала занятий в указанном диапазоне
"EndTime": "8:25", // Время окончания занятий в указанном диапазоне
"Status": "Reserve", // Статус ученика в учебной единице (может быть «Normal», «Reserve» , «WorkingOff» или «Stopped»)
"StudyUnits": "16 а.ч.", // Количество единиц занятий (может отсутствовать)
// Массив дней (только если указан диапазон, и queryDays = true)
"Days": [
{
"Date": "2016-07-11", // Дата
"Minutes": 45.0, // Длительность занятия в минутах
"Pass": false, // Признак пропуска
"StudentPayableMinutes": 22.5, // Количество оплачиваемых учеником минут
"TeacherPayableMinutes": 45.0, // Количество оплачиваемых преподавателю минут
"Description": "Опоздал", // Комментарий к занятию
"Accepted": true, // Признак того, что посещение подтверждено
"AcceptedDescription": "Установлено через API" // Примечание к подтверждению посещения/пропуска (устанавливается только через API)
},
...]
// Массив плательщиков за занятия связки (только если учебная единица некорпоративная, и queryPayers = true)
"Payers": [
{
"ClientId": 3264, // Идентификатор клиента (ученика или компании)
"StudentId": 3183, // Идентификатор ученика (если плательщик - ученик)
"CompanyId": 61, // Идентификатор компании (если плательщик - компания)
"Name": "Иванов Иван", // Имя плательщика
"Actual": true, // Если false, то данный плательщик является учеником, но, при этом, плательщик-компания полностью оплачивает его занятия
"ContractNumber": "№24-46", // Номер заключенного на данный момент договора с данным плательщиком (может отсутствовать)
"ContractDate": "2017-01-20", // Дата заключенного на данный момент договора с данным плательщиком (может отсутствовать)
// Массив расторгнутых договоров с данным плательщиком (если таковых нет, отсутствует)
"TerminatedContracts": [
{
"Number": "№24-45", // Номер договора
"Date": "2016-07-11", // Дата заключения договора
"TerminateDateTime": "2016-08-19T15:16:17", // Дата и время расторжения договора в UTC
"Reason": "Отказался заниматься", // Причина расторжения договора
"ReasonDescription": "Заболел" // Комментарий к причине расторжения договора
},
...]
"PriceId": 9, // Идентификатор цены по договору (может отсутствовать)
"PriceName": "Основная (250,00 руб./а.ч.)", // Наименование цены по договору (может отсутствовать)
"PayableUnits": "16 а.ч.", // Количество оплачиваемых единиц (может отсутствовать)
"PayableUnitsRanged": "12 а.ч.", // Количество оплачиваемых единиц в указанном диапазоне дат (может отсутствовать)
"Value": "4 000,00 руб.", // Фактическая стоимость занятий (может отсутствовать)
"ValueRanged": "3 000,00 руб.", // Фактическая стоимость занятий в указанном диапазоне дат (может отсутствовать)
"ContractValue": "4 000,00 руб.", // Стоимость занятий по договору (может отсутствовать)
"ContractValueRanged": "3 000,00 руб.", // Стоимость занятий по договору в указанном диапазоне дат (может отсутствовать)
"DebtDate": "2017-03-01", // Дата возникновения задолженности (может отсутствовать)
// Массив оплат (списаний) за обучение от данного плательщика (если таковых нет, отсутствует)
"LearnerPayments": [
{
"Paid": true, // Признак того, что оплата имеет статус «Оплачено»
"Date": "2017-02-09", // Дата оплаты
"PaidDate": "2017-02-10", // Дата принятия оплаты (может отсутствовать)
"BillNumber": "211", // Номер счёта (отсутствует, если со списанием не связано поступление)
"Units": "2 а.ч.", // Количество единиц оплаты
"PriceId": 9, // Идентификатор цены оплаты
"PriceName": "Основная (250,00 руб./а.ч.)", // Наименование цены оплаты
"Value": "1 000,00 руб." // Сумма оплаты
},
...]
},
...]
},
...]
}
Запрос планов занятий (домашних заданий).
Url: https://schooldomain.t8s.ru//Api/V1/GetLessonPlans
Список параметров (ни один не является обязательным):
Название | Описание |
id | Идентификатор плана занятий. |
schoolId | Идентификатор школы/компании. |
learnerId | Идентификатор уч. единицы. |
beginDate | Начальная дата диапазона занятий. |
endDate | Конечная дата диапазона занятий. |
visibleForClients | Признак того, что план занятия видим для клиентов (т.е. является домашним заданием). |
Пример результата:
{
"LessonPlans":
[{
"Id": 2, // Идентификатор плана занятий
"LearnerId": 123, // Идентификатор уч. единицы
"Date": "2019-08-01", // Дата занятия, для которого создан данный план/ДЗ
"VisibleForClients": false, // Признак того, что план занятия видим для клиентов (т.е. является домашним заданием).
"Content": "Глаголы и времена", // Содержимое плана/ДЗ (может содержать теги HTML)
}
...]
}
Запрос платежей.
Url: https://schooldomain.t8s.ru//Api/V1/GetPayments
Список параметров (ни один не является обязательным):
Название | Описание |
id | Идентификатор платежа |
type | Наименование типа платежа (как они именуются в настройках) |
beginDate | Начальная дата платежа |
endDate | Конечная дата платежа |
beginPaidDate | Начальная дата установки для платежа статуса "Оплачено" |
endPaidDate | Конечная дата установки для платежа статуса "Оплачено" |
schoolId | Идентификатор филиала/компании, к которому прикреплён платёж |
state | Битовая маска состояния платежа (1 - не оплачен, 2 - не подтверждён, 4 - оплачен) |
clientId | Идентификатор клиента-плательщика |
Результат возвращается в формате json в виде массива объектов “Payments”.
Пример результата:
{
"Payments":
[{
"Id": 123, // Идентификатор платежа
"Created": "2019-10-09T15:30:23", // Дата и время создания платежа в UTC
"Type": "Обучение", // Тип платежа
"Date": "2019-10-01", // Дата платежа в формате YYYY-MM-DD
"PaidDate": "2019-10-09", // Дата оплаты платежа в формате YYYY-MM-DD (отсутствует у неоплаченных платежей)
"SchoolId": 7, // Идентификатор филиала/компании, к которому прикреплён платёж
"SchoolName": "Основной филиал", // Наименование филиала/компании, к которому прикреплён платёж
"State": "Paid", // Состояние платежа (“Unpaid”, “Unconfirmed” или “Paid”)
"ClientId": 23, // Идентификатор клиента-плательщика
"ClientName": "Иванов Иван", // Имя клиента-плательщика
"Value": "1 000,00 руб.", // Сумма платежа
"Description": "Комментарий к платежу"
},
...]
}
Запрос цен.
Url: https://schooldomain.t8s.ru//Api/V1/GetPrices
Список параметров (ни один не является обязательным):
Название | Описание |
id | Идентификатор цены. |
schoolId | Идентификатор школы |
corporative | Корпоративные учащиеся. Булевский признак, по умолчанию null. |
calendar | Календарные цены. Булевский признак, по умолчанию null. |
packet | Пакетные цены. Булевский признак, по умолчанию null. |
Пример результата:
{
"Prices":
[{
"Id": 9, // Идентификатор цены
"Name": "Общая", // Наименование цены
"Value": "5 000,00 руб.", // Значение цены
"Units": "10 а.ч.", // Количество единиц, входящих в цену
"Calendar": false, // Признак календарной цены
"Packet": true, // Признак пакетной цены (отсутствует для календарной цены)
"PartlyPayable": true, // Может оплачиваться частично
"DaysActual": 15, // Срок действия, дней (может отсутствовать)
"Corporative": true, // Признак того, что цена может использоваться в корп. отделе
// Массив филиалов, в которых может используется цена (если таковых нет, отсутствует)
"Schools": [
{
"Id": 5, // Идентификатор филиала
"Name": "Главный филиал" // Наименование филиала
},
}
...]
}
Установка информации о занятиях/пропусках.
Url: https://schooldomain.t8s.ru//Api/V1/SetStudentPasses
Метод принимает параметр authkey (через URL), а также массив объектов, каждый из которых состоит из следующих полей:
Название | Описание |
date | Дата занятия |
learnerId | Идентификатор учебной единицы |
studentId | Идентификатор ученика |
pass | Булевский признак пропуска |
payable | Булевский признак оплачиваемости для учеников и преподавателей * |
description | Примечание к занятию * |
acceptedDescription | Примечание к подтверждению посещения/пропуска (отображается в интерфейсе, но устанавливается только через данный метод) * |
overwriteAcceptedManually | Булевский признак, позволяющий перезаписывать подтверждённое вручную занятие, по умолчанию: true |
* Если данный параметр не указан или равен null, его значение не меняется.
Пример POST-вызова с использованием jQuery:
$.ajax({
url: "http://schooldomain.t8s.ru/Api/V1/SetStudentDayPasses?authkey=...",
data: JSON.stringify([
{ Date: '2017-03-26', LearnerId: 4563, StudentId: 3206, Pass: false, Payable: false },
{ Date: '2017-04-02', LearnerId: 4563, StudentId: 3206, Pass: false, Payable: true }
]),
contentType: "application/json; charset=utf-8",
type: "post"
});
Пример GET-вызова с теми же параметрами:
Если в процессе работы метода возникли ошибки, возвращается массив Errors, содержащий ошибки по каждому из занятий, например:
{"Errors": [
{
"errorType": "Exception",
"errorMessage": "The day info was set manually",
"Date": "2017-04-02",
"LearnerId": 4563,
"StudentId": 3206
},
...]}
Если состояние пропуска объединённого дня (дня уч. единицы, объединённого с днём ученика) в результате вызова метода остаётся неизменным, то возвращается ошибка «The pass state will not be changed», и параметры этого дня не изменяются. Однако подтверждение пропуска/занятия всё равно устанавливается, но только если значение параметра Pass совпадает с текущим состоянием пропуска объединённого дня.
Добавление платежа (прихода на ЛС).
Url: https://schooldomain.t8s.ru//Api/V1/AddPayment
Список параметров (обязательны параметры clientId, schoolOrCompanyId и value):
Название | Описание |
clientId | Идентификатор клиента |
schoolOrCompanyId | Идентификатор филиала или корп. клиента |
date | Дата платежа. Если не указана, берётся текущая. |
value | Сумма и валюта платежа. Валюта должна указываться в том же виде, что используется для возврата денежных сумм (например, в GetPrices). |
paymentMethodId | Идентификатор способа оплаты. Если не указан, берётся в первый в соответствии с установленным в настройках порядком. |
state | Состояние платежа: «Unpaid», «Unconfirmed» или «Paid». Если не указан, принимается равным «Paid». |
description | Комментарий к платежу. |
requiredPaidDate | Требуемая дата оплаты. Имеет смысл только при State = «Unpaid». |
paidDate | Дата оплаты платежа (приёма средств). Имеет смысл только при State = «Paid». Если не указана, берётся текущая дата. |
paidEmployeeId | Идентификатор принявшего платёж сотрудника. |
notifyClient | Булевский признак, позволяющий уведомить клиента об успешной оплате или выставлении счёта (в зависимости от State). |
Пример POST-вызова с использованием jQuery:
$.ajax({
url: "http://schooldomain.t8s.ru/Api/V1/AddPayment",
data: {
authkey: ...,
clientId: 236,
schoolOrCompanyId: 5,
date: "2018-10-15",
value: "1 234,12 руб.",
state: "Paid",
description: "Какое-то описание",
paidEmployeeId: 40,
notifyClient: true
},
type: "post"
});
Пример успешного результата:
{
"id": 1425 // Идентификатор добавленного платежа
}
Редактирование платежа.
Url: https://schooldomain.t8s.ru//Api/V1/ EditPayment
Список параметров (обязательны только параметр id):
Название | Описание |
id | Идентификатор платежа (можно передавать в виде EditPayment/id) |
state | Состояние платежа (0 – не оплачен, 1 – ожидает подтверждения, 2 - оплачен) * |
description | Комментарий (чтобы добавить текст к существующему комментарию, необходимо начать параметр с «+», а чтобы удалить – передать пустую строку) * |
chequeNumber | Номер добавляемого к платежу чека (если к платежу уже прикреплён чек, возвращается ошибка) * |
acquiring | Булевский признак того, что оплата произведена посредством эквайринга (свойство чека. не имеет смысла без chequeNumber) * |
* Если данный параметр не указан или равен null, его значение не меняется.
Пример POST-вызова с использованием jQuery:
$.ajax({
url: "http://schooldomain.t8s.ru/Api/V1/EditPayment",
data: {
authkey: ...,
id: 1234,
state: 2,
description: '+Оплачено через Сбербанк',
chequeNumber: 123,
acquiring: true
},
type: "post"
});
Добавление оплаты за уч. единицу (расхода с ЛС).
Url: https://schooldomain.t8s.ru//Api/V1/AddLearnerPayment
Список параметров (обязательны параметры clientId, learnerId, priceId, beginDate для календарных оплат, multiplier или units):
Название | Описание |
clientId | Идентификатор клиента |
learnerId | Идентификатор уч. единицы |
date | Дата платежа. Если не указана, берётся текущая. |
priceId | Идентификатор цены. Цена должна соответствовать типу уч. единицы (календарной, либо некалендарной) и типу добавляемой оплаты (параметр Multiplier). |
beginDate | Начальная дата диапазона оплачиваемых занятий. Имеет смысл только для календарных оплат. |
multiplier | Множитель целой (не частичной) пакетной оплаты. По наличию данного параметра определяется тип добавляемой оплаты: частичная пакетная или почасовая, либо полная пакетная. |
units | Количество единиц для почасовой или частичной пакетной оплаты. Число или строка. Для некалендарной оплаты должен содержать количество а.ч. (того типа а.ч., что указан в цене). Для календарной оплаты должен содержать JSON-строку объекта, содержащего целочисленные поля Months и Days. Если объект содержит только одно из них, второе принимается равным нулю. |
description | Комментарий к оплате. |
validDate | Дата, после которой оплата считается недействительной. Имеет смысл только для некалендарных оплат. |
studyPaymentId | Идентификатор прихода, который необходимо связать с добавляемым расходом. Сумма прихода должна соответствовать сумме расхода. Приход должен быть свободен от связи с другим расходом. |
notifyClient | Булевский признак, позволяющий уведомить клиента об успешной оплате или выставлении счёта (в зависимости от состояния прихода StudyPaymentId). Без прихода игнорируется (клиент не уведомляется о расходах с ЛС). По умолчанию: false. |
Примеры POST-вызовов с использованием jQuery.
Добавление некалендарной частичной пакетной, либо почасовой (в зависимости от типа цены) оплаты:
$.ajax({
url: "http://schooldomain.t8s.ru/Api/V1/AddLearnerPayment",
data: {
authkey: ...,
clientId: 236,
learnerId: 123,
date: "2018-10-15",
priceId: 9,
units: 2.5,
description: "Какое-то описание",
validDate: "2018-10-22"
notifyClient: true
},
type: "post"
});
Добавление календарной полной пакетной оплаты, связанной с приходом на ЛС:
$.ajax({
url: "http://schooldomain.t8s.ru/Api/V1/AddLearnerPayment",
data: {
authkey: ...,
clientId: 236,
learnerId: 456,
priceId: 15,
beginDate: "2018-06-01",
multiplier: 2,
studyPaymentId: 3618
},
type: "post"
});
Добавление календарной частичной пакетной оплаты:
$.ajax({
url: "http://schooldomain.t8s.ru/Api/V1/AddLearnerPayment",
data: {
authkey: ...,
clientId: 236,
learnerId: 456,
priceId: 15,
beginDate: "2018-06-01",
units: "{Months: 1, Days: 5}"
},
type: "post"
});
Пример успешного результата:
{
"id": 1425, // Идентификатор добавленной оплаты
"value": "1 234,12 руб." // Вычисленная на основе указанных параметров итоговая сумма оплаты
}
Пример добавления заявки в CRM из javascript:
(ни один из параметров не является обязательным)
$.ajax({
url: "http://schooldomain.t8s.ru/Api/V1/AddStudyRequest",
data: {
id: null, // Идентификатор заявки (используется только для обновления существующей заявки)
fullName: "Иванов Иван Иванович",
eMail: "[email protected]",
phone: "+712312312312",
birthday: "1984-02-25",
agentFullName: "ФИО конт. лица",
agentEMail: "[email protected]",
agentPhone: "+72342342323",
discipline: "Английский",
learningLevel: "Средний",
location: "Тверь",
school: "Главный филиал",
teacher: "Петров Пётр Петрович",
beginDate: "17.03",
endDate: "20.04",
weekdays: "ср/чт",
beginTime: "15:30",
endTime: "16:10",
learnerId: null, // Идентификатор группы/экзамена/инд. занятий
type: "Заявка на обучение", // Тип заявки
firstCommunicationType: "Заявка с сайта", // Тип обращения
description: "Примечание к заявке",
utm_source: "Yandex-Direct", // UTM-метка «Рекламная система»
utm_medium: "CPC", // UTM-метка «Тип трафика»
utm_campaign: "Первая рекламная кампания", // UTM-метка «Обозначение рекламной кампании»
utm_term: "Ключевое слово", // UTM-метка «Условие поиска кампании»
utm_content: "red-button", // UTM-метка «Содержание кампании»
extraData: "someData", // Произвольные пользовательские данные, доступные при экспорте заявок
deleted: false, // Если true, заявка создаётся сразу как удалённая и помещается в архив заявок
roistat: getCookie("roistat_visit"), // Для интеграции с системой Roistat (ф-ция «getCookie» реализуется самостоятельно)
...
},
type: "GET",
crossDomain: true,
dataType: "jsonp",
success: function (result) {
if (result.errorType) alert("Ошибка. Тип: " + result.errorType + " Сообщение: " + result.errorMessage);
else alert("Успешно: " + result.id);
},
error: function (jqXhr) {
alert("Ошибка: " + jqXhr.statusText + " (" + jqXhr.readyState + ", " + jqXhr.status + ", " + jqXhr.responseText + ")");
}
});
Принимается как GET-, так и POST-запрос. GET желательно использовать только для JSONP.
Внимание: Если UTM-метки содержатся в обратной ссылке (referrer), то добавлять их в качестве параметров нет необходимости. Однако если таковые параметры есть, они сильнее соответствующих параметров из ссылки.
Также имеется возможность указывать дополнительные произвольные параметры. Они будут сохранены в базе данных и могут быть использованы для специальных целей.