Para suscribir un usuario con un rol 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/invite
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
}
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, la petición fallará.
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 en la plataforma.
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.
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 y con el rol de administrador (rol 2).
La petición al API de Teachlr Organizaciones se debe hacer al siguiente URL:
https://api.teachlr.com/escueladeprueba/api/invite
El cuerpo de la petición sería:
{
"email":"pedroperez@dominio.com",
"role":2
}
Una implementación utilizando la función $.ajax() de jQuery sería como sigue:
$.ajax({
url: "https://api.teachlr.com/escueladeprueba/api/invite", dataType: "json", type: "POST", contentType: "application/json", data: JSON.stringify({"email":"pedroperez@dominio.com", "role":2}), 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
{
"id": 207, "username": "pedroperez",
"email": "pedroperez@dominio.com"
}
Esta respuesta se obtiene cuando la petición fue exitosa. El usuario fue invitado a la escuela con el rol especificado.
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 «role».
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: 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
{
"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.
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": "email_rule_error" } ], "role": [ {
"code": "max_rule_error" } ] } }
Status: 409 Conflict
{
"errors": {
"email": [
{
"code": "active_user", "username": "pedroperez" } ] } }
Esta respuesta se obtiene cuando lo que se envió en el atributo «email» es un correo electrónico que pertenece a un usuario activo de la escuela, es decir, un usuario que ya ha iniciado sesión al menos una vez.
Status: 409 Conflict
{
"errors": {
"email": [
{
"code": "invitation_already_sent", "username": "pedroperez" } ] } }
Esta respuesta se obtiene cuando lo que se envió en el atributo «email» es un correo electrónico que pertenece a un usuario que ya ha sido invitado, pero aún no ha iniciado sesión en la escuela.
Leave A Comment?