Servicio web: Solicitudes avanzado

Introducción

Este servicio web permite crear solicitudes del tipo "añadir participante a grupo", enviando información desde un sistema externo hacia Gesforma.

Incluye las opciones del servicio web Solicitudes-básico, más la posibilidad de crear o vincular acciones formativas y grupos, y realizar la matriculación directa del participante.

Proceso de consumo

Se utiliza el protocolo de comunicación HTTP. Los pasos son:

1. Autenticación

Se requiere autenticación HTTP Basic con las credenciales de un usuario Gesforma con perfil de coordinador (loginname y contraseña).

Además, todas las peticiones deben incluir obligatoriamente la siguiente cabecera HTTP:

Para obtener tu token API consulta: más info

2. Consumir el servicio

La URL del endpoint te la proporcionamos desde Gesforma.

• Solicitud: los datos se envían en formato x-www-form-urlencoded, como pares clave=valor en el cuerpo de la petición HTTP.
• Respuesta: se recibe una respuesta en formato JSON.

Campos disponibles

Identificación del participante

La lógica de identificación del participante sigue este orden:

Si se envía usuario_nif

• El NIF existe en Gesforma → se vincula la solicitud a esa cuenta. No son necesarios usuario_nombre, usuario_apellido_1 ni usuario_email.
• El NIF no existe→ se crea la cuenta. Son obligatorios:

  Campo	Descripción
  usuario_nombre	Nombre del participante
  usuario_apellido_1	Primer apellido
  usuario_email	Email del participante

  Si no se reciben estos campos, el proceso termina con error.

Si NO se envía usuario_nif

Se busca al participante por usuario_email.

• El email existe en Gesforma → se vincula la solicitud a esa cuenta. No son necesarios usuario_nombre ni usuario_apellido_1.
• El email no existe→ se crea la cuenta. Son obligatorios:

  Campo	Descripción
  usuario_nombre	Nombre del participante
  usuario_apellido_1	Primer apellido
  usuario_apellido_2	Segundo apellido
  usuario_email	Email del participante

  Si no se reciben estos campos, el proceso termina con error.

Campos obligatorios para crear la solicitud

Para identificar el destino, es obligatorio enviar uno de estos tres:

Para crear una acción formativa nueva

Solo necesario si no se envía id_aaff ni id_grupo.

Para crear un grupo nuevo

Solo necesario si no se envía id_grupo.

Para matricular directamente al participante

Ejemplos en Postman

Hemos preparado una colección en Postman con los escenarios más habituales, lista para importar con un clic.

Crear solicitud con datos del participante, empresa y curso.

Licencia requerida: ESTRATEGIA

Está pensado para trasladar los datos mínimos necesarios para que un usuario, comercial o gestora recoja el testigo y siga avanzando con la solicitud.

Es el escenario más sencillo: no crea ni acción formativa ni grupo, simplemente registra al participante y lo asocia al curso y empresa indicados.

Resultado en Gesforma:

Crear solicitud + AAFF + grupo y matricular al participante

Disponible en: todas las licencias

En una sola llamada crea la acción formativa, el grupo y matricula directamente al participante.

Si no tienes contratada la licencia ESTRATEGIA no tendrás acceso al listado de Solicitudes, pero sí podrás ver la acción formativa, el grupo y el participante creados.

Las diferencias con respecto al escenario anterior son que se crea la acción formativa y el grupo, se matricula directamente al participante, y la solicitud ya aparece con estado Tramitada. El proceso se acelera bastante.

Resultado en Gesforma:

Crear grupo desde AAFF existente y matricular al participante.

Disponible en: todas las licencias

Crea un grupo nuevo a partir de una acción formativa que ya existe en Gesforma y matricula directamente al participante en ese grupo.

Si no tienes contratada la licencia ESTRATEGIA no tendrás acceso al listado de Solicitudes, pero sí podrás ver el grupo y el participante.

Este escenario está pensado para matricular al participante en una AAFF existente creando un grupo nuevo.

Matricular en grupo existente con los datos del participante.

Disponible en: todas las licencias

Matricula directamente al participante en un grupo que ya existe en Gesforma.

Si no tienes contratada la licencia ESTRATEGIA no tendrás acceso al listado de Solicitudes, pero sí podrás ver el grupo y el participante.

Es el escenario más directo: tanto la acción formativa como el grupo ya existen, y solo es necesario incorporar al participante.

Respuesta

Se recibe en todos los casos al finalizar el proceso.

Ejemplo de respuesta correcta:

{ "success": 1 }

Errores

Cuando la operación no se completa se devuelve:

{ "success": 0, "error_code": X, "error_message": "descripción del error" }

Log de registros

Accesible desde Cuenta → Informes → Formación → Log de cursos.