Общие принципы взаимодействия с системой
Тестема имеет простой и удобный API, который позволяет управлять персональными заданиями, благодаря чему, может быть легко организовано взаимодействие со сторонними ресурсами. Особенно это может быть востребовано при коммерческом использовании Тестемы, когда создатели обучающих материалов планируют распространять их на платной основе.
В целом механизм реализации таких материалов должен состоять из следующих шагов:
- Создание материала в редакторе приложения Тестема-П.
- Размещение в публичном доступе (на стороннем ресурсе) данных о материале.
- В случае реализации материала конечному пользователю:
- создание персонального задания в приложении Тестема-П или через API (подробнее о персональных заданиях см. Руководство пользователя);
- предоставление пользователю ключа для доступа в приложении Тестема к приобретенному материалу;
- при необходимости – отслеживание действий пользователя и удаление соответствующего персонального задания в приложении Тестема-П или через API.
Следует отметить, что осуществлять распространение своих материалов, созданных в Тестеме, автор может как через собственный веб-ресурс (сайт), так и с привлечением посредников (например, электронных площадок по продаже обучающих курсов и т.п.), размещая информацию об указанных материалах на веб-ресурсах последних и предоставляя им доступ к этим материалам посредством API.
Во всех запросах к API в качестве идентификатора владельца (автора) материалов используется его адрес электронной почты, указанный при создании учетной записи в Тестеме; в качестве идентификатора материала (сценария) используется его внутренний код в приложении Тестема-П, представляющий собой число в диапазоне от 1 до 99. Подробнее о внутреннем коде сценариев см. Руководство пользователя, в главе "Нумерация компонентов системы".
При поступлении любого запроса к API система определяет статус отправителя запроса, исходя из следующих критериев:
- если запрос сделан в отношении конкретного материала, и отправитель запроса не является автором этого материала, отправителю будет присвоен статус «Посредник»;
- если запрос сделан без привязки к какому-либо материалу, и у отправителя запроса нет ни одного созданного ранее персонального задания, либо среди имеющихся персональных заданий нет ни одного задания, содержащего материал, автором которого является отправитель запроса, отправителю будет присвоен статус «Посредник»;
- в остальных случаях отправителю запроса будет присвоен статус «Автор».
У отправителя запроса со статусом «Автор» должен быть подключен любой тарифный план, предусматривающий использование API, а также на балансе его учетной записи должны присутствовать средства, достаточные для работы в Тестеме в рамках указанного тарифного плана.
Отправитель запроса со статусом «Посредник» может использовать API бесплатно. При этом указанные выше требования по наличию тарифного плана и средств на балансе применяются к авторам тех материалов, доступ к которым будет запрашивать посредник. В случае несоблюдения автором данных требований его материалы станут недоступны.
Чтобы использовать API, необходимо получить специальный токен, который выдается для каждого URL, с которого впоследствии будут поступать запросы. Сделать это можно в разделе API-токены личного кабинета.
Для реализации материалов того или иного автора посреднику необходимо:
- создать учетную запись;
- получить API-токен;
- предоставить автору свой URL, с которого будут поступать запросы к API;
- получить от автора его адрес электронной почты в Тестеме;
- получить от автора идентификаторы всех необходимых материалов.
При этом автор должен для каждого материала установить в приложении «Тестема-П» разрешение на доступ к нему через API с URL посредника. Подробнее о разрешениях см. Руководство пользователя.
Алгоритм реализации материала конечным получателям через веб-ресурс автора или посредника с использованием API выглядит следующим образом:
- Размещение информации о материале на стороннем ресурсе.
- Принятие оплаты от конечного получателя материала (при распространении на платной основе).
- Запрос к API на создание персонального задания.
- Получение от API ключа доступа к материалу.
- Предоставление ключа конечному получателю.
Методы API
Доступ к API осуществляются путем отправки POST-запросов на URL https://testema.ru/integration/api в формате JSON.
В случае успешного завершения запроса ответ будет иметь статус 200. При некорректном запросе или невозможности его выполнения ответ будет иметь статус 400 («Bad request»), а также в теле ответа в большинстве случаев будет присутствовать описание проблемы. Тело ответа в этом случае имеет формат TEXT.
Метод checkUser (еще методы: addItem, removeItem, getItems)
Проверяет возможность создания персонального задания с материалом пользователя или другого автора. В качестве параметра ответа достаточно получить его статус (200 – возможность есть, 400 – возможность отсутствует).
Параметры запроса:
| Параметр | Обязательный | Тип | Родитель | Описание |
|---|---|---|---|---|
| method | да | string | - | Название метода. |
| token | да | string | - | API-токен пользователя. |
| data | да | object | - | Объект (массив) с данными запроса. |
| emailUser | да | string | data | Адрес электронной почты автора материала. |
| moduleId | да | integer | data | Идентификатор материала. |
Параметры ответа:
| Статус ответа | Значение |
|---|---|
| 200 | «ok» (формат TEXT). |
| 400 | Описание проблемы (формат TEXT). |
Пример запроса:
JSON:
{
"method":"checkUser",
"token":"989e5e7aa3282072f1cdc79314ecefa",
"data":
{
"emailUser":"author@author.ru",
"moduleId":92,
}
}
Метод addItem (еще методы: checkUser, removeItem, getItems)
Создает персональное задание для конечного получателя с материалом пользователя или другого автора. Возвращает ключ доступа к материалу в приложении Тестема.
Параметры запроса:
| Параметр | Обязательный | Тип | Родитель | Описание |
|---|---|---|---|---|
| method | да | string | - | Название метода. |
| token | да | string | - | API-токен пользователя. |
| data | да | object | - | Объект (массив) с данными запроса. |
| customer | да | object | data | Объект (массив) с данными конечного получателя материала. |
| emailUser | да | string | data | Адрес электронной почты автора материала. |
| moduleId | да | integer | data | Идентификатор материала. |
| sendEmail | нет | boolean | data | Если параметр не указан или имеет значение «true», получателю на адрес электронной почты будет отправлено стандартное сообщение от Тестемы об открытии доступа к материалу, содержащее ключ доступа. |
| message | нет | string | data | При отправке сообщения получателю вводная фраза «Здравствуйте! Вам предоставили доступ к материалу в приложении Тестема!» будет заменена на значение параметра. |
| accessLimit | нет | integer | data | Если параметр не указан или имеет значение 0, пользователь сможет открывать материал неограниченное количество раз. Иначе данная возможность будет ограничена значением параметра. |
| firstName | нет | string | customer | Имя получателя материала. |
| lastName | нет | string | customer | Фамилия получателя материала. |
| emailCustomer | да | string | customer | Адрес электронной почты получателя материала. |
Параметры ответа:
| Статус ответа | Значение |
|---|---|
| 200 | Hash-ключ доступа к материалу в приложении Тестема (формат TEXT, длина 32 знака). |
| 400 | Описание проблемы (формат TEXT). |
Пример запроса с минимальным набором обязательных параметров:
JSON:
{
"method":"addItem",
"token":"989e5e7aa3282072f1cdc79314ecefa",
"data":
{
"customer":
{
"emailCustomer":"customer@customer.ru"
},
"emailUser":"author@author.ru",
"moduleId":92,
}
}
Метод removeItem (еще методы: checkUser, addItem, getItems)
Удаляет персональное задание. Возвращает количество оставшихся персональных заданий пользователя.
Параметры запроса:
| Параметр | Обязательный | Тип | Родитель | Описание |
|---|---|---|---|---|
| method | да | string | - | Название метода. |
| token | да | string | - | API-токен пользователя. |
| data | да | object | - | Объект (массив) с данными запроса. |
| itemKey | да | string | data | Hash-ключ доступа к материалу задания (32 знака). |
Параметры ответа:
| Статус ответа | Значение |
|---|---|
| 200 | Количество оставшихся персональных заданий пользователя (формат TEXT). |
| 400 | Описание проблемы (формат TEXT). |
Пример запроса:
JSON:
{
"method":"removeItem",
"token":"989e5e7aa3282072f1cdc79314ecefa",
"data":
{
"itemKey":"35e2a957f6679e12b58d7559a178a2f1",
}
}
Метод getItems (еще методы: checkUser, addItem, removeItem)
Запрос подробной информации об имеющихся персональных заданиях пользователя. Возвращает объект с данными. При указании в запросе конкретного задания (в параметре itemKey) объект ответа будет содержать информацию только по этому заданию.
Параметры запроса:
| Параметр | Обязательный | Тип | Родитель | Описание |
|---|---|---|---|---|
| method | да | string | - | Название метода. |
| token | да | string | - | API-токен пользователя. |
| data | нет | object | - | Объект (массив) с данными запроса. |
| itemKey | нет | string | data | Hash-ключ доступа к материалу задания (32 знака). |
Параметры ответа:
| Статус ответа | Значение |
|---|---|
| 200 | Сериализованный объект (формат JSON). |
| 400 | Описание проблемы (формат TEXT). |
Объект, возвращаемый при статусе ответа 200, содержит свойство «items», представляющее собой массив объектов заданий.
Свойства объекта задания:
| Свойство | Тип | Описание |
|---|---|---|
| key | string | Hash-ключ доступа к материалу задания (32 знака). |
| user_email | string | Адрес электронной почты автора материала. |
| module_name | string | Публичное название материала. |
| customer_name | string | Фамилия и имя получателя материала. |
| customer_email | string | Адрес электронной почты получателя материала. |
| customer_started | boolean | Значение «true» говорит о том, что получатель материала уже активировал ключ доступа к нему в приложении «Тестема». Фактически, свидетельствует о том, что отправленный получателю ключ был успешно получен. |
| customer_finished | boolean | Значение «true» говорит о том, что получатель материала завершил его прохождение в приложении Тестема. Свидетельствует о том, что была нажата кнопка «ЗАВЕРШИТЬ» на последней странице материала, в результате чего он больше недоступен для получателя. |
| attempts | string | В случае, если материал имеет ограничение по количеству просмотров, отображает количество оставшихся просмотров у получателя. |
| attestation | string | Если материал содержит блоки автоматической оценки знаний (например, тестирование), отображает результат, полученный пользователем в процентах. Может быть использовано в случаях, когда обучающемуся по итогам освоения материала автор или продавец должен выдать соответствующий документ. |
Пример запроса на получение данных о всех заданиях:
JSON:
{
"method":"getItems",
"token":"989e5e7aa3282072f1cdc79314ecefa",
}
Пример ответа:
JSON:
{
"items":
[
{
"key":"35e2a957f6679e12b58d7559a178a2f1",
"user_email":"author@author.ru",
"module_name":"Выращивание клубники",
"customer_name":"Иванов Иван",
"customer_email":"customer1@customer.ru",
"customer_started":false,
"customer_finished":false,
"attempts":"не ограничено",
"attestation":"не предусмотрено"
},
{
"key":"f8fc8e2edf8494c22f348e09dac4679d",
"user_email":"author@author.ru",
"module_name":"Основы программирования",
"customer_name":"Степанова Елена Ивановна",
"customer_email":"customer2@customer.ru",
"customer_started":true,
"customer_finished":false,
"attempts":"3",
"attestation":"75"
},
...
]
}
Для тестирования API:
- Отправьте запрос addItem, указав в параметрах emailUser и emailCustomer один и тот же адрес test@testema.ru, а в параметре moduleId любое число от 1 до 99. Параметр sendEmail не указывайте совсем. В случае успеха на адрес электронной почты вашей учетной записи придет демонстрационное письмо с тем же ключом доступа к материалу, который вернул метод addItem.
- Запросите данные созданного задания при помощи getItems. В результате вы должны получить объект с единственной записью в массиве items. Материал будет иметь название «Как пользоваться мобильным приложением?».
- При необходимости, повторите запрос addItem несколько раз с теми же параметрами и сохраните ключи, полученные в ответ. После этого, используя getItems, убедитесь в том, что было создано соответствующее количество заданий.
- Удалите каждое задание, выполнив запрос removeItem для каждого из сохраненных ключей.
Не указывайте в целях тестирования значение параметра emailCustomer, отличное от test@testema.ru. Тарифный план автора материала, указанного в запросе addItem, может предусматривать удержание комиссии за каждое созданное задание, в котором электронная почта получателя не совпадает с test@testema.ru.
Взаимодействие с получателями материалов
Если в запросе addItem параметр sendEmail не указан или имеет значение «true», получателю на адрес электронной почты будет отправлено стандартное сообщение от Тестемы об открытии доступа к материалу, содержащее также ключ доступа и ссылку на страницу его активации.
В случае, если вы хотите отправить собственное сообщение, создайте в нем ссылки для удобства получателя. Ниже представлены GET-запросы на некоторые страницы сайта Тестемы, а также параметры, которые можно указывать в этих запросах:
|
Активация ключа доступа к материалу: Ссылка открывает страницу активации ключа, и, при наличии параметра addkey, автоматически вставляет указанный ключ в соответствующее поле формы. Если пользователь не авторизован на сайте, сначала ему будет предложено войти в учетную запись, после чего он будет перенаправлен на страницу активации. |
|
Регистрация или вход в личный кабинет: |
|
Страница выбора и скачивания бесплатного приложения для обучающихся: Страница отображает краткую информацию об использовании Тестемы и содержит ссылку на скачивание приложения, предназначенного для устройства, с которого осуществлено открытие страницы. Пользователям IOS демонстрируется ссылка на страницу запуска веб-приложения Тестема для IPhone. |
|
Прямая ссылка на скачивание файла установки Тестемы для Windows: |
|
Прямая ссылка на скачивание файла установки Тестемы для Android: |
|
Прямая ссылка на страницу запуска веб-приложения для IOS: |
При поступлении запроса addItem система проверяет наличие учетной записи в Тестеме у получателя материалов. Идентификация происходит по адресу электронной почты, указанному в параметре emailCustomer. Если пользователь не был зарегистрирован ранее, для него автоматически создается учетная запись, у которой логином является значение параметра emailCustomer. При этом для всех пользователей, созданных таким способом, устанавливается пароль «12345», который владелец учетной записи может впоследствии изменить.
В случае, если в результате запроса addItem пользователь был автоматически зарегистрирован в системе, стандартное сообщение от Тестемы на электронную почту получателю материалов будет содержать указанную выше информацию. Если же вы будете отправлять собственное сообщение, то также должны обязательно обратить на это внимание пользователя. По соображениям конфиденциальности API не предоставляет данные о факте наличия или отсутствия учетной записи, поэтому вам необходимо включать предупреждение об этом в сообщения для всех получателей материалов.
Получение уведомлений от API
Для организации эффективного управления продажами нередко требуется отслеживание действий пользователей (покупателей). С этой целью при возникновении некоторых важных событий, связанных с персональными заданиями, API Тестемы автоматически отправляет уведомления на URL, с которых ранее поступили запросы на создание данных заданий.
Для обработки обратных вызовов API необходимо создать функцию, запуск которой будет осуществляться при поступлении запроса на URL, имеющий следующий шаблон: https://ваш домен/testema/callback. Например, для домена mysite.ru URL для уведомлений будет таким: https://mysite.ru/testema/callback. На указанный URL API Тестемы отправит POST-запрос с телом в формате JSON.
Параметры запроса:
| Параметр | Обязательный | Тип | Описание |
|---|---|---|---|
| token | да | string | API-токен, полученный вами для доступа к API. Передается для верификации того, что запрос поступил действительно от API Тестемы. |
| event | да | string | Тип события, в результате которого отправлен запрос. |
| itemKeys | да | array string | Массив с ключами персональных заданий, в отношении которых произошло событие. |
API не ожидает и не проверяет ответ на свои запросы, поэтому в случае, если на стороне вашего сервера возникнет ошибка, повторной отправки запроса не произойдет.
Событие moduleComplete (еще события: moduleRefused, moduleRemoved)
Возникает, когда пользователь (получатель персонального задания) полностью завершил выполнение задания. Отслеживание данного события будет полезно, например, в том случае, если по итогу выполнения задания пользователь должен получить от вас соответствующий документ (сертификат, диплом и т.п.). Массив itemKeys для данного события будет содержать только один элемент.
Пример запроса:
JSON:
{
"token":"989e5e7aa3282072f1cdc79314ecefa",
"event":"moduleComplete",
"itemKeys":
[
"35e2a957f6679e12b58d7559a178a2f1"
]
}
Событие moduleRefused (еще события: moduleComplete, moduleRemoved)
Возникает, когда пользователь (получатель персонального задания) по какой-либо причине отказался от выполнения задания, удалив его у себя в приложении Тестема. Массив itemKeys для данного события будет содержать только один элемент.
Пример запроса:
JSON:
{
"token":"989e5e7aa3282072f1cdc79314ecefa",
"event":"moduleRefused",
"itemKeys":
[
"35e2a957f6679e12b58d7559a178a2f1"
]
}
Событие moduleRemoved (еще события: moduleComplete, moduleRefused)
Возникает, когда автор материала, на основе которого вами были созданы персональные задания, удалил указанный материал. Данное событие не может произойти, если получатель хотя бы одного персонального задания еще не активировал ключ задания у себя в приложении Тестема, а также полностью не завершил выполнение задания либо не отказался от его выполнения путем удаления в приложении Тестема. Автору будет позволено удалить материал только при соблюдении указанных выше условий в отношении всех персональных заданий, созданных на его основе, поэтому при поступлении запроса с событием moduleRemoved вы можете быть полностью уверены в том, что задания, ключи которых присутствуют в массиве itemKeys, можно удалить без каких-либо негативных последствий для взаимоотношений с получателями этих заданий. Кроме этого, возникновение события moduleRemoved говорит о необходимости удаления из продажи соответствующего материала на вашем веб-ресурсе. Следует отметить, что вы не получите уведомление с событием moduleRemoved в случае, если у вас нет ни одного персонального задания, созданного на основе материала, который был удален его автором.
Пример запроса:
JSON:
{
"token":"989e5e7aa3282072f1cdc79314ecefa",
"event":"moduleRemoved",
"itemKeys":
[
"35e2a957f6679e12b58d7559a178a2f1",
"d8fc8e2edf8494c22f348e09dac4679d"
]
}