Para crear, actualizar o eliminar una videoconferencia para un usuario de una escuela de Teachlr Organizaciones se debe realizar una petición al API de Teachlr Organizaciones. Dependiendo del caso, los URLs son los siguientes:
Creación de videoconferencia, petición de tipo POST:
https://api.teachlr.com/<dominio>/api/meetings
Actualización de videoconferencia, petición de tipo PUT:
https://api.teachlr.com/<dominio>/api/meetings/<meeting_id>
Eliminación de videoconferencia, petición de tipo DELETE:
https://api.teachlr.com/<dominio>/api/meetings/<meeting_id>
en donde <dominio> se debe sustituir por el dominio teachlr de la escuela (no el dominio personalizado) y <meeting_id> (cuando aplique) por el ID de la videoconferencia que se quiere actualizar o eliminar.
En cualquier tipo de petición se deben enviar las siguientes dos cabeceras:
| Key | Value |
| Content-Type | application/json |
| Authorization | key_0123456789ABCDEFGHIJK |
Nota: El valor de Authorization mostrado arriba es ficticio. Cada escuela tendrá su propia llave (key) que debe ser solicitada por el cliente.
Para crear o actualizar una videoconferencia, el cuerpo de la petición debe ser un objeto JSON con la siguiente estructura:
{
"email": "pedroperez@dominio.com",
"topic": "Tópico de la videoconferencia",
"date": "2020-05-12",
"time": "21:00",
"duration": 30,
"timezone": "America/Caracas",
"participants": [
"luisvelasquez@dominio.com",
"mariaperez@dominio.com"
]
}Para eliminar una videoconferencia, el cuerpo de la petición debe ser un objeto JSON con la siguiente estructura:
{
"email": "pedroperez@dominio.com"
}El atributo «email» es obligatorio y debe contener la dirección de correo electrónica del usuario que será el anfitrión (para el caso de crear) o del anfitrión actual (para los casos de actualizar y eliminar) de la videoconferencia.
Condiciones para el atributo «email»:
- Se debe enviar sólo una (1) dirección de correo electrónico. Si se envía más de una dirección de correo electrónico (separadas por coma o cualquier otro carácter), la petición fallará.
- Si no se envía el campo email o éste se envía vacío, la petición fallará.
- La dirección de correo electrónico debe tener un formato válido, de lo contrario la petición fallará.
- Si la dirección de correo electrónico no está registrada en la base de datos, la petición fallará.
El atributo «topic» es obligatorio para la creación, pero opcional para la actualización, y establece el tópico de la videoconferencia.
El atributo «date» es obligatorio para la creación, pero opcional para la actualización, y establece la fecha de la videoconferencia, que debe expresarse con el formato «aaaa-mm-dd». Ej.: «2020-05-12» (para indicar 12 de mayo de 2020).
El atributo «time» es obligatorio para la creación, pero opcional para la actualización, y establece la hora de la videoconferencia, que debe expresarse con el formato «hh:mm» de 24 horas. Ej.: «20:30» (para indicar 8:30 p.m.).
El atributo «duration» es obligatorio para la creación, pero opcional para la actualización, y establece la duración de la videoconferencia, expresado en minutos. Debe ser un número entero entre 30 y 765. Ej.: 120 (para indicar 2 horas).
El atributo «timezone» es obligatorio para la creación, pero opcional para la actualización, y establece la zona horaria asociada a la fecha y hora de la videoconferencia. Ej.: «America/Caracas». Los valores soportados para este atributo se listan en el Apéndice A.
El atributo «participants» es opcional y, de ser enviado, debe contener un arreglo con los correos electrónicos de los usuarios de la escuela que serán invitados a la videoconferencia.
Condiciones para el atributo «participants»:
- Si se envía vacío o un arreglo vacío, la petición fallará.
- Las direcciones de correo electrónico deben tener un formato válido, de lo contrario la petición fallará
- Las direcciones de correo electrónico deben pertenecer a usuarios de la escuela.
- Si algunas de las direcciones de correo electrónico no pertenecen a un usuario de la escuela, dicho correo será ignorado y no será invitado a la videoconferencia.
- Si alguna de las direcciones de correo electrónico es la del anfitrión, ésta será ignorada.
Casos de ejemplo:
Creación de videoconferencia (POST):
Se desea crear una videoconferencia cuyo anfitrión será el usuario con la dirección de correo electrónico pedroperez@dominio.com de la escuela https://escueladeprueba.teachlr.com, con la siguiente información:
Tópico: Educación a distancia
Fecha: 14 de mayo de 2020
Hora: 3:00 p.m. de Caracas, Venezuela
Duración: 2 horas.
Participantes: luisvelasquez@dominio.com y mariaperez@dominio.com
La petición al API de Teachlr Organizaciones se debe hacer al siguiente URL:
https://api.teachlr.com/escueladeprueba/api/meetings
El cuerpo de la petición sería:
{
"email": "pedroperez@dominio.com",
"topic": "Educación a distancia",
"date": "2020-05-14",
"time": "15:00",
"duration": 120,
"timezone": "America/Caracas",
"participants": [
"luisvelasquez@dominio.com",
"mariaperez@dominio.com"
]
}Una implementación utilizando la función $.ajax() de jQuery sería como sigue:
$.ajax({
url: "https://api.teachlr.com/escueladeprueba/api/meetings",
dataType: "json",
type: "POST",
contentType: "application/json",
data: JSON.stringify {"email": "pedroperez@dominio.com", "topic": "Educación a
distancia", "date": "2020-05-14", "time": "15:00", "duration": 120,
"timezone": "America/Caracas", "participants": ["luisvelasquez@dominio.com",
"mariaperez@dominio.com"]}),
headers: {
"Authorization": "key_0123456789ABCDEFGHIJK"
},
success: function(data) {
// la petición fue exitosa
console.log('data', data);
},
error: function(xhr, status, err) {
// falló la petición
console.log('xhr', xhr);
console.log('status', status);
console.log('err', err);
}
});Actualización de videoconferencia (PUT):
Se desea actualizar alguno de los datos de una videoconferencia cuyo ID es 179 y el anfitrión es el usuario con la dirección de correo electrónico pedroperez@dominio.com de la escuela https://escueladeprueba.teachlr.com, con la siguiente nueva información:
Fecha: 14 de mayo de 2020
Hora: 3:00 p.m. de Caracas, Venezuela
Participantes: luisvelasquez@dominio.com y mariaperez@dominio.com
Nota: pueden enviarse sólo algunos atributos para actualizar sólo la información que se necesite, pero debe enviarse al menos uno (distinto al atributo «email», que es obligatorio), de lo contrario la petición fallará.
¡Atención!: si se envía el atributo «participants», se le removerá la videoconferencia a aquellos usuarios que no estén presentes en este nuevo listado, y se invitará sólo a los usuarios de ese nuevo listado que no habían sido invitados previamente. Si no se envía este atributo, los participantes actuales continuarán teniendo la videoconferencia asociada.
La petición al API de Teachlr Organizaciones se debe hacer al siguiente URL:
https://api.teachlr.com/escueladeprueba/api/meetings/179
El cuerpo de la petición sería:
{
"email": "pedroperez@dominio.com",
"date": "2020-05-14",
"time": "15:00",
"timezone": "America/Caracas",
"participants": [
"luisvelasquez@dominio.com",
"mariaperez@dominio.com"
]
}Una implementación utilizando la función $.ajax() de jQuery sería como sigue:
$.ajax({
url: "https://api.teachlr.com/escueladeprueba/api/meetings/179",
dataType: "json",
type: "PUT",
contentType: "application/json",
data: JSON.stringify {"email": "pedroperez@dominio.com", "date": "2020-05-14",
"time": "15:00", "timezone": "America/Caracas", "participants":
["luisvelasquez@dominio.com", "mariaperez@dominio.com"]}),
headers: {
"Authorization": "key_0123456789ABCDEFGHIJK"
},
success: function(data) {
// la petición fue exitosa
console.log('data', data);
},
error: function(xhr, status, err) {
// falló la petición
console.log('xhr', xhr);
console.log('status', status);
console.log('err', err);
}
});Eliminación de videoconferencia (DELETE):
Se desea eliminar la videoconferencia cuyo ID es 179 y el anfitrión es el usuario con la dirección de correo electrónico pedroperez@dominio.com de la escuela https://escueladeprueba.teachlr.com:
La petición al API de Teachlr Organizaciones se debe hacer al siguiente URL:
https://api.teachlr.com/escueladeprueba/api/meetings/179
El cuerpo de la petición sería:
{
"email": "pedroperez@dominio.com"
}Una implementación utilizando la función $.ajax() de jQuery sería como sigue:
$.ajax({
url: "https://api.teachlr.com/escueladeprueba/api/meetings/179",
dataType: "json",
type: "DELETE",
contentType: "application/json",
data: JSON.stringify {"email": "pedroperez@dominio.com"}),
headers: {
"Authorization": "key_0123456789ABCDEFGHIJK"
},
success: function(data) {
// la petición fue exitosa
console.log('data', data);
},
error: function(xhr, status, err) {
// falló la petición
console.log('xhr', xhr);
console.log('status', status);
console.log('err', err);
}
});Posibles respuestas del API:
Status: 200 OK (creación y actualización)
{
"id": 183,
"duration": 120,
"start_time": "2020-05-14 19:00:00",
"timezone": "America/Caracas",
"topic": "Educación a distancia",
"start_url": "https://teachlr.zoom.us/s/99265850000?zak=eyJ6bV9XX00aaiJ6bV9vMm0iLCJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJjbGllbnQiLCJ1aWQiOiJsQmpIRVFJcVRtcUF5RUIxZndVZy1nIiwiaXNzIjoid2ViIiwic3R5Ijo5OSwid2NkIjoiYXcxIiwiY2x0IjowLCJzdGsiOiJodmpMQXh0S0VqR0lrTy1MYnZIbEQxQWkxV0RNTVdDanN6Y1JwMHRXOS1nLkJnVWdkelJMWVhOS1VVVjJkSE40V2xob2VWWjRUVVJ4TWpCRGJVUnhSbHB6WVhZQUFBd3pRMEpCZFc5cFdWTXpjejBBQTJGM01RIiwiZXhwIjoxNTk3MDkxMzkyLCJpYXQiOjE1ODkzMTUzOTI...",
"join_url": "https://teachlr.zoom.us/j/99265850000",
"uuid": "XiKLEbsrSau2atK2XXAA11==",
"zoom_meeting_id": 99265850000,
"host_id": "lBjHEQIqTmqAyXX44wUg-g",
"created_at": "2020-05-12 16:29:52",
"updated_at": "2020-05-12 16:29:52",
"user_id": 98,
"deleted_at": null,
"gmt_time": "2020-05-14 15:00:00",
"type": "scheduled",
"offset": "-04:00",
"expired": false,
"sent": false,
"date_sent": null,
"host": [
{
"id": 98,
"username": "pedroperez",
"name": "Pedro",
"last_name": "Pérez",
"email": "pedroperez@dominio.com",
"about": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit.",
"job": "Analista/programador",
"department": "Informática",
"picture": {
"thumb": "https://d2j3j1vpt0andh.cloud.../avatars/D01-32x32.jpg",
"small": "https://d2j3j1vpt0andh.cloud.../avatars/D01-54x54.jpg",
"medium": "https://d2j3j1vpt0andh.cloud.../avatars/D01-64x64.jpg",
"medium_large": "https://d2j3j1vpt0andh.cloud.../avatars/D01-98x98.jpg",
"large": "https://d2j3j1vpt0andh.cloud.../avatars/D01-198x198.jpg"
}
}
],
"participants": [
{
"username": "luisvelasquez",
"name": "Luis",
"last_name": "Velásquez",
"email": "luisvelasquez@dominio.com",
"about": "Etiam ultricies nisi vel augue",
"job": "Asistente Administrativo",
"department": "Administración",
"picture": {
"thumb": "https://d2j3j1vpt0andh.cloud.../avatars/D02-32x32.jpg",
"small": "https://d2j3j1vpt0andh.cloud.../avatars/D02-54x54.jpg",
"medium": "https://d2j3j1vpt0andh.cloud.../avatars/D02-64x64.jpg",
"medium_large": "https://d2j3j1vpt0andh.cloud.../avatars/D02-98x98.jpg",
"large": "https://d2j3j1vpt0andh.cloud.../avatars/D02-198x198.jpg"
}
},
{
"username": "mariaperez",
"name": "María",
"last_name": "Pérez",
"email": "mariaperez@dominio.com",
"about": null,
"job": null,
"department": null,
"picture": {
"thumb": "https://d2j3j1vpt0andh.../img/default_user_icon-32x32.jpg",
"small": "https://d2j3j1vpt0andh.../img/default_user_icon-54x54.jpg",
"medium": "https://d2j3j1vpt0andh.../img/default_user_icon-64x64.jpg",
"medium_large": "https://d2j3j1vpt0andh.../img/default_user_icon-98x98.jpg",
"large": "https://d2j3j1vpt0andh.../img/default_user_icon-198x198.jpg"
}
}
]
}Esta respuesta se obtiene cuando la petición fue exitosa al crear o actualizar una videoconferencia. La respuesta de ejemplo muestra la información de la videoconferencia, del anfitrión (host) y de los participantes. Cabe destacar que el URL del anfitrión se especifica en el atributo «start_url» y el URL de los invitados se especifica en el atributo «join_url».
Status: 200 OK (eliminación)
[«Ok»]
Esta respuesta se obtiene cuando la petición fue exitosa al eliminar una videoconferencia.
Status: 400 Bad Request
[«Bad request»]
Esta respuesta se obtiene cuando la petición falla. También se puede obtener esta respuesta cuando no se envían otros atributos distintos al atributo «email» en la actualización.
Status: 401 Unauthorized
[«Unauthorized»]
Esta respuesta se obtiene cuando la llave (key) enviada en la cabecera «Authorization» de la petición no es válida. También es posible recibir esta respuesta si el rol del usuario anfitrión no tiene permitido crear videoconferencias o la escuela no tiene habilitado el complemento de videoconferencias.
Status: 404 Not Found
[«Not Found»]
Esta respuesta se obtiene cuando la dirección de correo electrónico enviada no está registrada en la base de datos o el URL al cual se está haciendo la petición está incorrecto.
Status: 404 Not Found
[«Meeting Not Found»]
Esta respuesta se obtiene cuando el meeting_id enviado en la petición de la actualización o eliminación de una videoconferencia no existe o no pertenece al usuario asociado a la dirección de correo electrónico enviada en el atributo «email».
Status: 409 Conflict
[«Expired Meeting»]
Esta respuesta se obtiene cuando la videoconferencia que se quiere actualizar ha expirado, es decir, su fecha de inicio ya pasó.
Status: 409 Conflict
[«Past Date»]
Esta respuesta se
obtiene cuando la combinación de fecha, hora y zona horaria a la que se quiere
actualizar la videoconferencia ya pasó. Si sólo se envían algunos de estos
atributos, se tomarán los valores originales registrados en la videoconferencia
para los restantes atributos para realizar el cálculo.
Status: 422 Unprocessable Entity
{
"errors": {
"email": [
{
"code": "required_rule_error"
}
]
}
}Esta respuesta se obtiene cuando no se envía el atributo «email» o se envía vacío. Esta misma respuesta aplica para todos los demás atributos: topic, date, time, duration, timezone y participants (cuando es enviado), cambiando sólo el nombre del atributo dentro de «errors».
Status: 422 Unprocessable Entity
{
"errors": {
"email": [
{
"code": "email_rule_error"
}
]
}
}Esta respuesta se obtiene cuando lo que se envió en el atributo «email» no tiene un formato de correo electrónico válido.
Status: 422 Unprocessable Entity
{
"errors": {
"duration": [
{
"code": "integer_rule_error"
}
]
}
}Esta respuesta se obtiene cuando lo que se
envió en el atributo «duration» no es un número entero.
Status: 422 Unprocessable Entity
{
"errors": {
"duration": [
{
"code": "min_rule_error"
}
]
}
}Esta respuesta se obtiene cuando lo que se envió en el atributo «duration» es un número entero menor a 30 (30 minutos).
Status: 422 Unprocessable Entity
{
"errors": {
"duration": [
{
"code": "max_rule_error"
}
]
}
}Esta respuesta se obtiene cuando lo que se envió en el atributo «duration» es un número entero mayor a 765 (12 horas, 45 minutos).
Status: 422 Unprocessable Entity
{
"errors": {
"date": [
{
"code": "dateformat_rule_error"
}
]
}
}Esta respuesta se obtiene cuando lo que se
envió en el atributo «date» no es una fecha válida o no tiene el
formato «yyyy-mm-dd».
Status: 422 Unprocessable Entity
{
"errors": {
"time": [
{
"code": "dateformat_rule_error"
}
]
}
}Esta respuesta se obtiene cuando lo que se envió en el atributo «time» no es una hora válida o no tiene el formato «hh:mm» de 24 horas.
Status: 422 Unprocessable Entity
{
"errors": {
"timezone": [
{
"code": "timezone_rule_error"
}
]
}
}Esta respuesta se obtiene cuando lo que se envió en el atributo «timezone» no tiene un formato de zona horaria.
Status: 422 Unprocessable Entity
{
"errors": {
"timezone": [
{
"code": "in_rule_error"
}
]
}
}Esta respuesta se obtiene cuando lo que se
envió en el atributo «timezone» no es ninguna de las zonas horarias soportadas
para crear las videoconferencias (Apéndice A).
Status: 422 Unprocessable Entity
{
"errors": {
"participants": [
{
"email": "pedroperez@ dominio.com",
"code": "email_rule_error"
},
{
"email": "luisvelazquezdominnio.com",
"code": "email_rule_error"
}
]
}
}Esta respuesta se obtiene cuando uno de los elementos enviados en el atributo «participants» no tiene un formato de correo electrónico válido.
Es posible que el API devuelva varios de los errores 422 descritos anteriormente en una misma respuesta si no se cumplen varias condiciones al mismo tiempo, como se muestra a continuación:
{
"errors": {
"email": [
{
"code": "required_rule_error"
}
],
"topic": [
{
"code": "required_rule_error"
}
],
"date": [
{
"code": "dateformat_rule_error"
}
]
}
}LISTADO DE ZONAS HORARIAS SOPORTADAS POR LAS VIDEOCONFERENCIAS.
| ID | Nombre |
| Pacific/Midway | Midway Island, Samoa |
| Pacific/Pago_Pago | Pago Pago |
| Pacific/Honolulu | Hawaii |
| America/Anchorage | Alaska |
| America/Vancouver | Vancouver |
| America/Los_Angeles | Pacific Time (US and Canada) |
| America/Tijuana | Tijuana |
| America/Edmonton | Edmonton |
| America/Denver | Mountain Time (US and Canada) |
| America/Phoenix | Arizona |
| America/Mazatlan | Mazatlan |
| America/Winnipeg | Winnipeg |
| America/Regina | Saskatchewan |
| America/Chicago | Central Time (US and Canada) |
| America/Mexico_City | Mexico City |
| America/Guatemala | Guatemala |
| America/El_Salvador | El Salvador |
| America/Managua | Managua |
| America/Costa_Rica | Costa Rica |
| America/Montreal | Montreal |
| America/New_York | Eastern Time (US and Canada) |
| America/Indianapolis | Indiana (East) |
| America/Panama | Panama |
| America/Bogota | Bogota |
| America/Lima | Lima |
| America/Halifax | Halifax |
| America/Puerto_Rico | Puerto Rico |
| America/Caracas | Caracas |
| America/Santiago | Santiago |
| America/St_Johns | Newfoundland and Labrador |
| America/Montevideo | Montevideo |
| America/Araguaina | Brasilia |
| America/Argentina/Buenos_Aires | Buenos Aires, Georgetown |
| America/Godthab | Greenland |
| America/Sao_Paulo | Sao Paulo |
| Atlantic/Azores | Azores |
| Canada/Atlantic | Atlantic Time (Canada) |
| Atlantic/Cape_Verde | Cape Verde Islands |
| UTC | Universal Time UTC |
| Etc/Greenwich | Greenwich Mean Time |
| Europe/Belgrade | Belgrade, Bratislava, Ljubljana |
| CET | Sarajevo, Skopje, Zagreb |
| Atlantic/Reykjavik | Reykjavik |
| Europe/Dublin | Dublin |
| Europe/London | London |
| Europe/Lisbon | Lisbon |
| Africa/Casablanca | Casablanca |
| Africa/Nouakchott | Nouakchott |
| Europe/Oslo | Oslo |
| Europe/Copenhagen | Copenhagen |
| Europe/Brussels | Brussels |
| Europe/Berlin | Amsterdam, Berlin, Rome, Stockholm, Vienna |
| Europe/Helsinki | Helsinki |
| Europe/Amsterdam | Amsterdam |
| Europe/Rome | Rome |
| Europe/Stockholm | Stockholm |
| Europe/Vienna | Vienna |
| Europe/Luxembourg | Luxembourg |
| Europe/Paris | Paris |
| Europe/Zurich | Zurich |
| Europe/Madrid | Madrid |
| Africa/Bangui | West Central Africa |
| Africa/Algiers | Algiers |
| Africa/Tunis | Tunis |
| Africa/Harare | Harare, Pretoria |
| Africa/Nairobi | Nairobi |
| Europe/Warsaw | Warsaw |
| Europe/Prague | Prague Bratislava |
| Europe/Budapest | Budapest |
| Europe/Sofia | Sofia |
| Europe/Istanbul | Istanbul |
| Europe/Athens | Athens |
| Europe/Bucharest | Bucharest |
| Asia/Nicosia | Nicosia |
| Asia/Beirut | Beirut |
| Asia/Damascus | Damascus |
| Asia/Jerusalem | Jerusalem |
| Asia/Amman | Amman |
| Africa/Tripoli | Tripoli |
| Africa/Cairo | Cairo |
| Africa/Johannesburg | Johannesburg |
| Europe/Moscow | Moscow |
| Asia/Baghdad | Baghdad |
| Asia/Kuwait | Kuwait |
| Asia/Riyadh | Riyadh |
| Asia/Bahrain | Bahrain |
| Asia/Qatar | Qatar |
| Asia/Aden | Aden |
| Asia/Tehran | Tehran |
| Africa/Khartoum | Khartoum |
| Africa/Djibouti | Djibouti |
| Africa/Mogadishu | Mogadishu |
| Asia/Dubai | Dubai |
| Asia/Muscat | Muscat |
| Asia/Baku | Baku, Tbilisi, Yerevan |
| Asia/Kabul | Kabul |
| Asia/Yekaterinburg | Yekaterinburg |
| Asia/Tashkent | Islamabad, Karachi, Tashkent |
| Asia/Calcutta | India |
| Asia/Kathmandu | Kathmandu |
| Asia/Novosibirsk | Novosibirsk |
| Asia/Almaty | Almaty |
| Asia/Dacca | Dacca |
| Asia/Krasnoyarsk | Krasnoyarsk |
| Asia/Dhaka | Astana, Dhaka |
| Asia/Bangkok | Bangkok |
| Asia/Saigon | Vietnam |
| Asia/Jakarta | Jakarta |
| Asia/Irkutsk | Irkutsk, Ulaanbaatar |
| Asia/Shanghai | Beijing, Shanghai |
| Asia/Hong_Kong | Hong Kong |
| Asia/Taipei | Taipei |
| Asia/Kuala_Lumpur | Kuala Lumpur |
| Asia/Singapore | Singapore |
| Australia/Perth | Perth |
| Asia/Yakutsk | Yakutsk |
| Asia/Seoul | Seoul |
| Asia/Tokyo | Osaka, Sapporo, Tokyo |
| Australia/Darwin | Darwin |
| Australia/Adelaide | Adelaide |
| Asia/Vladivostok | Vladivostok |
| Pacific/Port_Moresby | Guam, Port Moresby |
| Australia/Brisbane | Brisbane |
| Australia/Sydney | Canberra, Melbourne, Sydney |
| Australia/Hobart | Hobart |
| Asia/Magadan | Magadan |
| SST | Solomon Islands |
| Pacific/Noumea | New Caledonia |
| Asia/Kamchatka | Kamchatka |
| Pacific/Fiji | Fiji Islands, Marshall Islands |
| Pacific/Auckland | Auckland, Wellington |
| Asia/Kolkata | Mumbai, Kolkata, New Delhi |
| Europe/Kiev | Kiev |
| America/Tegucigalpa | Tegucigalpa |
| Pacific/Apia | Independent State of Samoa |
Leave A Comment?