Тестема имеет простой и удобный API, благодаря которому, может быть легко организовано взаимодействие со сторонними ресурсами при ее коммерческом использовании, когда обучающие материалы распространяются на платной основе. Подробнее о продаже материалов, а также о применении API для этой цели, можно узнать, ознакомившись с описанием типичных сценариев использования Тестемы.
Алгоритм реализации материала с применением API через сторонний веб-ресурс, принадлежащий автору или посреднику, выглядит следующим образом:
- Запрос к API на получение информации о доступности материала.
- Размещение информации о материале на стороннем ресурсе (самостоятельно).
- Принятие оплаты от покупателя материала, а также получение его адреса электронной почты (самостоятельно).
- Запрос к API на создание системного персонального задания и получение в ответ ключа для доступа к материалу.
- Предоставление покупателю ссылки, сформированной на базе ключа (самостоятельно или средствами Тестемы при условии передачи соответствующего параметра в рамках запроса к API, указанному в п. 4).
- Получение от API на свой URL обратного вызова информации о наличии результатов выполнения заданий материала покупателем (необязательно).
- Запрос к 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 | да | string | 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 | да | string | 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 влечет за собой списание средств с баланса учетной записи автора материалов, не следует использовать для тестирования API адреса электронной почты реальных пользователей. Для этих целей в Тестеме предусмотрен специальный пользователь с адресом электронной почты test@testema.ru. Все пробные запросы следует отправлять только с указанием данного адреса в качестве идентификатора автора материала. Ниже представлен рекомендуемый алгоритм отладки вашего ПО для взаимодействия с API Тестемы:
- Отправьте запрос addItem, указав в параметрах emailUser и emailCustomer один и тот же адрес test@testema.ru, а в параметре moduleId текст 00_00. Параметр sendEmail не указывайте совсем. В случае успеха на адрес электронной почты вашей учетной записи придет демонстрационное письмо со ссылкой для доступа к материалу на базе того же ключа, который вернул метод addItem.
- Запросите данные созданного системного персонального задания при помощи getItems. В результате вы должны получить объект с единственной записью в массиве items. Материал будет иметь название «Как пользоваться мобильным приложением?».
- При необходимости, повторите запрос addItem несколько раз с теми же параметрами и сохраните ключи, полученные в ответ. После этого, используя getItems, убедитесь в том, что было создано соответствующее количество системных персональных заданий.
- Удалите все системные персональные задания, поочередно выполнив запрос removeItem для каждого из сохраненных ключей.
Взаимодействие с получателями материалов
Если в запросе addItem параметр sendEmail не указан или имеет значение «true», получателю на адрес электронной почты будет отправлено стандартное сообщение от Тестемы, содержащее ссылку для доступа к материалу и краткую инструкцию.
В случае, если вы хотите отправить собственное сообщение, установите значение «false» для параметра sendEmail. При этом в тексте вашего сообщения обязательно потребуется указать ссылку для доступа к материалу. В противном случае у получателя не будет возможности просмотра приобретенного им материала. Ссылка должна иметь следующий вид: https://app.testema.ru/?key=accesskey&start=moduleId, где вместо accesskey укажите ключ доступа, полученный в ответе на запрос addItem (32 знака), а вместо moduleId - идентификатор материала, который вы использовали в качестве значения параметра moduleId при отправке этого запроса.
При поступлении запроса addItem система проверяет наличие учетной записи в Тестеме у получателя материалов. Идентификация происходит по адресу электронной почты, указанному в параметре emailCustomer. Если пользователь не был зарегистрирован ранее, для него автоматически создается учетная запись, логином которой является значение параметра emailCustomer. При этом стандартное сообщение от Тестемы будет содержать соответствующее предупреждение с указанием логина и пароля для входа в личный кабинет. Из соображений безопасности пароль не может быть передан в ответ на запросы к API, поэтому в случае отправки вами собственного сообщения получателю материала, вы не сможете предоставить ему указанный выше пароль. В этой ситуации потребуется предоставить получателю ссылку для восстановления пароля https://testema.ru/password-recovery, а также уведомить его о необходимости ее использования, если учетная запись в Тестеме не была создана ранее самим получателем.
Получение уведомлений от 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"
]
}