Invitar un usuario a una escuela y opcionalmente, suscribirlo a uno o varios cursos usando el API de Teachlr Organizaciones

Para suscribir un usuario a una escuela de Teachlr Organizaciones se debe realizar una petición de tipo POST al API de Teachlr Organizaciones utilizando el siguiente URL:

https://api.teachlr.com/<dominio>/api/invitations

en donde <dominio> se debe sustituir por el dominio teachlr de la escuela (no el dominio personalizado).

En la petición se deben enviar las siguientes dos cabeceras:

Nota: El valor de Authorization mostrado arriba es ficticio. Cada escuela tendrá su propia llave (key), que debe ser solicitada por el cliente.

El cuerpo de la petición debe ser un objeto JSON con la siguiente estructura: 

{
 "email":"usuario@dominio.com", "role":4,
 "courses":[1,2,3] 
}

El atributo «email» es obligatorio y debe contener la dirección de correo electrónica del usuario que se desea invitar.

Condiciones para el atributo «email»:

  • Se debe enviar sólo una (1) dirección de correo electrónica. Si se envía más de una dirección de correo electrónica (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ónica debe tener un formato válido, de lo contrario la petición fallará.
  • Si la dirección de correo electrónica ya estaba registrada en la base de datos, se omite la invitación sin que falle la petición y el proceso continúa con la suscripción del usuario a los cursos que se indicaron (si se enviaron). El atributo «role» es opcional y establece el tipo de rol que tendrá el usuario que se desea invitar, a saber:
  • Rol 2: rol de administrador. Este tipo de usuario puede crear cursos, suscribirse a ellos y tiene acceso al módulo de Administración.
  • Rol 3: rol de instructor. Este tipo de usuario puede crear cursos y suscribirse a ellos, pero no tiene acceso al módulo de Administración.
  • Rol 4: rol de usuario común. Este tipo de usuario sólo puede suscribirse a cursos, no puede crearlos ni acceder al módulo de Administración. Es el rol más bajo.

Condiciones para el atributo «role»:

  • Debe ser un número entero entre 2 y 4, de lo contrario la petición fallará.
  • Si no se envía este atributo, se le asignará el rol de usuario común (rol 4) al usuario que se está invitando.

El atributo «courses» es opcional y, de ser enviado, debe contener un arreglo de IDs de los cursos a los cuales se desea suscribir al usuario que se está invitando. Condiciones para atributo «courses»:

  • Los IDs deben pertenecer a cursos activos de la escuela.
  • Si alguno de los IDs es de un curso no activo (borrador, pendiente o desactivado) la petición fallará.
  • Si alguno de los IDs no pertenece a ningún curso de la escuela, la petición fallará.
  • Si el usuario invitado ya estaba suscrito a alguno o todos los cursos indicados, se omite el proceso de suscripción a esos cursos sin que falle la petición.

El proceso de la invitación del usuario a la escuela está separado del proceso de suscripción del usuario a los cursos, por lo que es posible que la invitación del usuario a la escuela sea satisfactoria pero que la suscripción a los cursos falle, a lo que el API responde como una petición fallida («400 Bad Request») pero la invitación sí fue realizada exitosamente.

Caso de ejemplo:

Se desea invitar a un usuario, cuya dirección de correo electrónica es pedroperez@dominio.com, a la escuela https://escueladeprueba.teachlr.com con el rol de administrador (rol 2) y suscribirlo a tres cursos activos de esa escuela cuyos IDs son: 12, 41 y 58.

La petición al API de Teachlr Organizaciones se debe hacer al siguiente URL:

https://api.teachlr.com/escueladeprueba/api/invitations

El cuerpo de la petición sería:

 {
 "email":"pedroperez@dominio.com", 
 "role":2,
 "courses":[12,41,58]
 }

Una implementación utilizando la función $.ajax() de jQuery sería como sigue: 

$.ajax({ 
url: "https://api.teachlr.com/escueladeprueba/api/invitations", dataType: "json", type: "POST", contentType: "application/json", data: JSON.stringify({"email":"pedroperez@dominio.com", "role":2, "courses":[12,41,58]}), 
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

[«Ok»]

Esta respuesta se obtiene cuando la petición fue exitosa. El usuario fue invitado a la escuela (si ya no lo estaba antes) y fue suscrito a los cursos indicados (si se enviaron).

Status: 400 Bad Request 

["Bad request"]

Esta respuesta se obtiene cuando la petición falla por alguna de las razones descritas en las condiciones para los atributos «email» y «courses».

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.

Status: 404 Not Found 

["Not Found"]

Esta respuesta se obtiene cuando el URL al cual se está haciendo la petición está incorrecto.

Status: 409 Conflict 

[ 
true, [ 
{ 
"error": "courses_expired", "json": "[{\"title\":\"Curso prueba\",\"date\":\"2017-03-07 00:00:00\"}]" } ] ]

Esta respuesta se obtiene cuando uno de los cursos a los que se quiere suscribir al usuario es un curso comprado de Teachlr Marketplace que ya ha expirado.

Status: 409 Conflict 

[ 
true, 
[ 
{ 
"error": "no_quotas_left", "json": "[{\"title\":\"Curso prueba\",\"left\":0}]" } ] ]

Esta respuesta se obtiene cuando uno de los cursos a los que se quiere suscribir al usuario es un curso comprado de Teachlr Marketplace que ya no tiene cupos disponibles.

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.

Status: 422 Unprocessable Entity 

 invite_users_subscribe_courses_es
 {
 "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": { 
"role": [ { 
"code": "min_rule_error" } ] } }

Esta respuesta se obtiene cuando lo que se envió en el atributo «role» es un número entero menor a 2.

Status: 422 Unprocessable Entity 

{ 
"errors": { 
"role": [ { 
"code": "max_rule_error" } ] } }

Esta respuesta se obtiene cuando lo que se envió en el atributo «role» es un número entero mayor a 4.

Status: 422 Unprocessable Entity 

{ 
"errors": { 
"role": [ { 
"code": "integer_rule_error" } ] } }

Esta respuesta se obtiene cuando lo que se envió en el atributo «role» no es un número entero.