Cómo 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:

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.

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],
  "careers": [4,5],
  "groups": [20,15],
  "no_password": true,
  "send_mail": false,
  "user_data": {
    "name": "Pedro",
    "last_name": "Pérez",
    "email": "pedroperez@dominio.com",
    "job": "Analista/programador",
    "department": "Informática",
    "identification_number": "14425125",
    "employee_number": "E14425125",
    "organization_name": "Empresa",
    "phone": "04169998877",
    "external_id": "EXID-123456",
    "update": true
  }
}

El atributo «email» del objeto principal 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 en el objeto principal. 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 en el objeto principal, 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, carreras o grupos que se indicaron (si se enviaron) o con el proceso de actualización de datos.

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.

El atributo «careers» es opcional y, de ser enviado, debe contener un arreglo de IDs de las carreras a las cuales se desea suscribir al usuario que se está invitando.

Condiciones para atributo «careers»:

Los IDs deben pertenecer a carreras de la escuela con al menos un curso activo.
Si alguno de los IDs es de una carrera sin al menos un curso activo, será ignorado sin que falle la petición.
Si alguno de los IDs no pertenece a ninguna carrera de la escuela, la petición fallará.
Si el usuario invitado ya estaba suscrito a alguna o todas las carreras indicadas, se omite el proceso de suscripción a esas carreras 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 las carreras, por lo que es posible que la invitación del usuario a la escuela sea satisfactoria pero que la suscripción a las carreras falle, a lo que el API responde como una petición fallida («400 Bad Request») pero la invitación sí fue realizada exitosamente.

Condiciones para atributo «groups»:

Los IDs deben pertenecer a grupos de la escuela.
Si alguno de los IDs no pertenece a ningún grupo de la escuela, la petición fallará.
Si el usuario invitado ya estaba suscrito a alguno o todos los grupos indicados, se omite el proceso de suscripción a esos grupos 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 grupos, por lo que es posible que la invitación del usuario a la escuela sea satisfactoria pero que la suscripción a los grupos falle, a lo que el API responde como una petición fallida («400 Bad Request») pero la invitación sí fue realizada exitosamente.

El atributo «no_password» es opcional y, de ser enviado, debe contener un valor booleano (true/false). Si no se envía, su valor por defecto es false, esto quiere decir que al usuario invitado se le generará una contraseña. Si se establece en true, indicará que no se le debe generar una contraseña al usuario que se está invitando.

El atributo «send_mail» es opcional y, de ser enviado, debe contener un valor booleano (true/false). Si no se envía, su valor por defecto es true, esto quiere decir que al usuario invitado se le enviará un correo de invitación y también los correos correspondientes a la asignación de cursos, carreras y grupos que se hayan especificado. Si se establece en false, entonces no se le enviará ningún correo al usuario invitado.

El atributo «user_data « es opcional y, de ser enviado, debe contener un objeto JSON con los atributos de usuario que se desean asociar al usuario invitado.

Condiciones para atributo «user_data»:

El objeto JSON de «user_data» puede contener todos o alguno de los siguientes atributos:

Atributo	Longitud máx.	Descripción
email	254	Dirección de correo electrónico
name	100	Nombre
last_name	100	Apellido
job	200	Cargo
department	254	Departamento
phone	30	Teléfono
identification_number	30	Cédula de Identidad
employee_number	254	Número de empleado
organization_name	60	Nombre de la organización
external_id	254	Identificador externo del usuario
update	true/false	¿Actualizar información?

Para el caso de los atributos «email», «employee_number» y «external_id», su valor no debe estar asociado a ningún otro usuario. En caso de que el valor ya esté asociado a otro usuario, entonces el atributo será ignorado.

El atributo «update» debe contener un valor booleano (true/false). Si no se envía, su valor por defecto es false, esto quiere decir que la información del usuario no debe ser actualizada.

Si el usuario a invitar no existe en la plataforma (basado en el atributo «email» del objeto principal) y se envía un objeto «user_data», entonces todos los atributos especificados serán asignados a dicho usuario invitado, independientemente de su atributo «update».

Si el usuario a invitar ya existía en la plataforma, sólo se actualizará la información del usuario si contiene el atributo «update» y su valor es true.

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; además, asignarle el nombre de «Pedro» y apellido «Pérez».

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],
  "user_data": {
    "name": "Pedro",
    "last_name": "Pérez",
    "update": true
  }
}

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], "user_data": {"name":"Pedro", "last_name":"Pérez", "update": true }}),
	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: 200 OK

[
    "true",
    [
        {
            "error": "no_active_courses",
            "json": "[{\"name\":\"Curso prueba\"}]"
        }
    ]
]

Esta respuesta se obtiene cuando una de las carreras a las que se quiere suscribir al usuario no tiene al menos un curso activo, por lo que se ignora el proceso de asignación del usuario a dicha carrera sin que falle la asignación a las otras carreras (si las hay).

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», «courses» y «careers».

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: 409 Conflict

[
    true,
    [
        {
            "error": "remaining_seats_exceeded",
            "json": "[{\"title\":\"Curso prueba\"}]"
        }
    ]
]

Esta respuesta se obtiene cuando en una de las carreras a las que se quiere suscribir al usuario contiene un curso comprado de Teachlr Marketplace que ya no tiene cupos disponibles.