documentacion_rubricas.md

Documentacion API Rúbricas EDTECH API

Autor: Ivo Perich
Contacto: iperich@smartpaper.ai
Versión: 1.0
Fecha de Creación: 11 de noviembre de 2024

Descripción

A continuación se describen los pasos necesarios para obtener una rúbrica mediante la API de EDTECH API, a partir de un formulario inicial. Este proceso consta de 5 pasos:

Crear Variables de rúbrica (Ingreso de formulario)
Verificar y obtener las variables de rúbrica
Editar / Actualizar las variables (opcional)
Crear la rúbrica
Obtener la rúbrica en formato Microsoft Word (.docx)

### Paso 1: Crear las Variables de la Rúbrica

Descripción

Este paso permite definir las variables iniciales para la creación de una rúbrica personalizada. La rúbrica se basa en la asignatura, el nivel educativo, la actividad y el objetivo de aprendizaje específicos del usuario.

Endpoint

Método: POST
URL: https://edtechapi.com:7002/create_rubric_variables

Autenticación

Tipo de Autenticación: Basic Auth
Credenciales:
- username: [Tu clave de API]
- password: [Tu secreto de API]

Encabezados

No se especifican encabezados adicionales.

Cuerpo de la Solicitud (JSON)

El cuerpo de la solicitud debe enviarse en formato JSON con los siguientes parámetros:

Parámetro	Tipo	Descripción
`user_id`	String	Identificador único del usuario.
`subject`	String	Asignatura para la que se creará la rúbrica (Ej.: `matemáticas`).
`level`	String	Nivel educativo (Ej.: `enseñanza básica`).
`course`	String	Curso específico (Ej.: `cuarto básico`).
`students_age`	String	Edad promedio de los estudiantes (Ej.: `9 años`).
`objective`	String	Objetivo de aprendizaje específico que se evaluará (Ej.: `aprender a sumar fracciones`).
`activity`	String	Actividad relacionada con el objetivo de aprendizaje (Ej.: `suma de fracciones con igual denominador`).
`lang`	String	Idioma en el que se requiere la rúbrica (`spa` para español).

Ejemplo de Solicitud (JSON)

{
    "user_id": "xxxxxxz",
    "subject": "matemáticas",
    "level": "enseñanza básica",
    "course": "cuarto básico",
    "students_age": "9 años",
    "objective": "aprender a sumar fracciones",
    "activity": "suma de fracciones con igual denominador y con denominadores que son múltiplos entre sí",
    "lang": "spa"
}

Respuesta

La respuesta confirmará la creación de las variables de la rúbrica y proporcionará un job_id para continuar con los pasos posteriores.

Campos de la Respuesta

job_id: ID de la solicitud, que identifica el proceso de creación de la rúbrica.

Ejemplo de Respuesta (JSON)

{
    "job_id": 4
}

Notas

El job_id recibido en esta respuesta será necesario para los pasos siguientes del proceso de creación de la rúbrica.
Asegúrese de ingresar correctamente los parámetros en el cuerpo de la solicitud para obtener una rúbrica que se ajuste al contexto y los objetivos de aprendizaje.

Paso 2: Verificar el Estado de las Variables de la Rúbrica

Descripción

Este paso permite verificar el estado de la creación de las variables de la rúbrica generadas en el Paso 1. Utilizando el job_id, se puede obtener el conjunto de variables de la rúbrica una vez que el estado de la solicitud esté marcado como "ready". Si el estado es "processing", se recomienda intentar nuevamente después de unos segundos.

Endpoint

Método: POST
URL: https://edtechapi.com:7002/get_status_rubric_variables

Autenticación

Tipo de Autenticación: Basic Auth
Credenciales:
- username: [Tu clave de API]
- password: [Tu secreto de API]

Encabezados

No se especifican encabezados adicionales.

Cuerpo de la Solicitud (JSON)

El cuerpo de la solicitud debe enviarse en formato JSON e incluir el siguiente parámetro:

Parámetro	Tipo	Descripción
`job_id`	Integer	ID de la solicitud generada en el Paso 1

Ejemplo de Solicitud (JSON)

{
    "job_id": 4
}

Respuesta

La respuesta contendrá el job_id solicitado, el estado de la solicitud y, si el estado es "ready", una lista de las variables de la rúbrica generadas.

Campos de la Respuesta

job_id: ID de la solicitud.
status: Estado de la solicitud, que puede tener uno de los siguientes valores:
- "processing": La solicitud está en proceso.
- "ready": La solicitud ha sido procesada y las variables de la rúbrica están disponibles.
rubric_variables: Lista de variables de la rúbrica generadas, disponible solo si el estado es "ready".

Ejemplo de Respuesta (JSON)

{
    "job_id": 4,
    "status": "ready",
    "rubric_variables": "1. Comprensión del concepto de fracción\n2. Identificación de fracciones con igual denominador\n3. Realización correcta de la suma de fracciones con igual denominador\n4. Identificación de denominadores que son múltiplos entre sí\n5. Realización correcta de la suma de fracciones con denominadores múltiplos\n6. Uso adecuado de procedimientos matemáticos\n7. Presentación clara y ordenada de los cálculos\n8. Verificación de resultados obtenidos\n9. Capacidad para explicar el proceso de suma de fracciones"
}

Notas

Si el valor de status es "processing", se recomienda esperar unos segundos e intentar nuevamente.
Una vez que el status es "ready", la lista de variables de la rúbrica estará disponible en el campo rubric_variables, que incluye una descripción detallada de cada variable generada.
El job_id y las variables de la rúbrica obtenidos en este paso serán necesarios para los pasos posteriores del proceso de creación de la rúbrica.

Paso 3 (Opcional): Editar/Actualizar las Variables de la Rúbrica

Descripción

Este paso permite modificar o actualizar las variables de la rúbrica previamente generadas en el Paso 2. Es útil en caso de que se necesiten ajustes específicos en las variables para adaptarse mejor a los objetivos de evaluación.

Endpoint

Método: POST
URL: https://edtechapi.com:7002/update_rubric_variables

Autenticación

Tipo de Autenticación: Basic Auth
Credenciales:
- username: [Tu clave de API]
- password: [Tu secreto de API]

Encabezados

No se especifican encabezados adicionales.

Cuerpo de la Solicitud (JSON)

El cuerpo de la solicitud debe enviarse en formato JSON con los siguientes parámetros:

Parámetro	Tipo	Descripción
`rubric_variables_id`	Integer	ID de las variables de la rúbrica obtenidas en el Paso 2.
`updated_rubric_variables`	String	Texto actualizado que contiene la lista de variables de la rúbrica en el formato deseado.

Ejemplo de Solicitud (JSON)

{
    "rubric_variables_id": 29,
    "updated_rubric_variables": "1. Comprensión del concepto de fracción\n2. Identificación de fracciones con igual denominador\n3. Realización correcta de la suma de fracciones con igual denominador\n4. Identificación de denominadores que son múltiplos entre sí\n5. Realización correcta de la suma de fracciones con denominadores múltiplos\n6. Uso adecuado de procedimientos matemáticos\n7. Presentación clara y ordenada de los cálculos\n8. Verificación de resultados obtenidos\n9. Capacidad para explicar el proceso de suma de fracciones"
}

Respuesta

La respuesta confirmará si la actualización de las variables de la rúbrica se realizó correctamente o si ocurrió algún error.

Campos de la Respuesta

status: Indica el resultado de la solicitud, con los siguientes posibles valores:
- "success": La actualización de las variables fue exitosa.
- "failed": Hubo un error en el sistema al intentar realizar la actualización.
"error": "not_found": Indica que el rubric_variables_id proporcionado no es válido o no se encontró.

Ejemplo de Respuesta (JSON)

Caso exitoso:

{
    "status": "success"
}

Caso de error (ID incorrecto):

{
    "error": "not_found"
}

Notas

Si el status es "success", la actualización se realizó correctamente.
Si se recibe "failed", ocurrió un error en el sistema, se recomienda comunicarlo al área de soporte de EDTECH API.
En caso de {"error": "not_found"}, revise el rubric_variables_id proporcionado para asegurarse de que sea correcto y se haya obtenido en el Paso 2.

Aquí tienes la documentación completa para el Paso 4:

Paso 4: Crear la Rúbrica a partir de las Variables

Descripción

Este paso permite generar la rúbrica completa utilizando las variables previamente definidas y actualizadas (si fue necesario) en los pasos anteriores. Es necesario proporcionar el rubric_variables_id obtenido en el Paso 2.

Endpoint

Método: POST
URL: https://edtechapi.com:7002/create_rubric

Autenticación

Tipo de Autenticación: Basic Auth
Credenciales:
- username: [Tu clave de API]
- password: [Tu secreto de API]

Encabezados

No se especifican encabezados adicionales.

Cuerpo de la Solicitud (JSON)

El cuerpo de la solicitud debe enviarse en formato JSON con los siguientes parámetros:

Parámetro	Tipo	Descripción
`rubric_variables_id`	Integer	ID de las variables de la rúbrica obtenidas en el Paso 2.
`lang`	String	Idioma de la rúbrica (`spa` para español).

Ejemplo de Solicitud (JSON)

{
    "rubric_variables_id": 4,
    "lang": "spa"
}

Respuesta

La respuesta contendrá el job_id que confirma la creación de la rúbrica. Este job_id se utilizará en los pasos siguientes, como la generación de un documento de la rúbrica.

Campos de la Respuesta

job_id: ID de la solicitud, confirmando que la rúbrica se ha generado correctamente.

Ejemplo de Respuesta (JSON)

{
    "job_id": 1
}

Notas

Este job_id obtenido en la respuesta será necesario para generar y descargar el documento de la rúbrica en el paso 5.
Asegúrate de haber completado correctamente los pasos anteriores y que el rubric_variables_id sea válido para evitar errores.

Aquí tienes la documentación para el Paso 5 del proceso de creación de rúbricas utilizando la API REST:

Paso 5: Obtener el Documento de la Rúbrica en Formato Word (.docx)

Descripción

Este paso permite descargar el documento de la rúbrica en formato Word (.docx), codificado en base64 para su transmisión segura. Se requiere el job_id obtenido en el Paso 4 para identificar la rúbrica generada. Opcionalmente, se puede incluir el nombre del usuario.

Endpoint

Método: POST
URL: https://edtechapi.com:7002/get_rubric_docx

Autenticación

Tipo de Autenticación: Basic Auth
Credenciales:
- username: [Tu clave de API]
- password: [Tu secreto de API]

Encabezados

No se especifican encabezados adicionales.

Cuerpo de la Solicitud (JSON)

El cuerpo de la solicitud debe enviarse en formato JSON con los siguientes parámetros:

Parámetro	Tipo	Descripción
`job_id`	Integer	ID de la solicitud de rúbrica, obtenido en el Paso 4.
`user_name`	String	Nombre del usuario para personalizar el documento (opcional, puede enviarse vacío).
`lang`	String	Idioma del documento de la rúbrica (`spa` para español).

Ejemplo de Solicitud (JSON)

{
    "job_id": 1,
    "user_name": "Ivo Perich",
    "lang": "spa"
}

Respuesta

La respuesta contendrá el job_id solicitado y el documento de la rúbrica en formato base64, en el campo base64_docx_file. Este archivo puede decodificarse para obtener el documento en formato Word (.docx).

Campos de la Respuesta

job_id: ID de la solicitud, confirmando que el documento se ha generado correctamente.
base64_docx_file: Contenido del documento en formato Word (.docx), codificado en base64.

Ejemplo de Respuesta (JSON)

{
    "job_id": 1,
    "base64_docx_file": "UEsDBBQAAAAIAM9la1mtUqWRlQEAAMoGAAATAAA..."
}

Notas

El contenido en base64 del campo base64_docx_file puede decodificarse y guardarse como un archivo .docx para visualizar la rúbrica en formato Word.
Asegúrate de que el job_id y los parámetros sean correctos para recibir el documento deseado.