documentacion_pruebas.md

Documentacion API Pruebas 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 prueba mediante la API de EDTECH API, a partir de un formulario inicial. Este proceso consta de 5 pasos:

Crear Variables de prueba (Ingreso de formulario)
Verificar y obtener las variables de prueba
Editar / Actualizar las variables (opcional)
Crear la prueba
Obtener el texto de la prueba y el documento en formato Microsoft Word (.docx)

Paso 1: Crear las Variables de la Prueba

Descripción

Este paso permite definir las variables iniciales para la creación de una prueba personalizada. Las variables de la prueba incluyen detalles específicos sobre el objetivo de aprendizaje, la actividad y el número de preguntas que se evaluarán.

Endpoint

Método: POST
URL: https://edtechapi.com:7002/create_test_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 cual se creará la prueba (Ej.: `Matemáticas`).
`level`	String	Nivel educativo (Ej.: `educación básica`).
`course`	String	Curso específico (Ej.: `3ero básico`).
`students_age`	String	Edad promedio de los estudiantes (Ej.: `8 años`).
`objective`	String	Objetivo de aprendizaje a evaluar (Ej.: `aprender unidades, decenas y centenas`).
`activity`	String	Descripción de la actividad relacionada con el objetivo (Ej.: `crear números del 0 al 999 usando etiquetas con números de colores que según el color se definan como unidades, decenas o centenas`).
`num_questions`	String	Número de preguntas en la prueba (Ej.: `6`).
`lang`	String	Idioma en el que se requiere la prueba (`spa` para español).

Ejemplo de Solicitud (JSON)

{
    "user_id": "yyyyyy",
    "subject": "Matemáticas",
    "level": "educacion básica",
    "course": "3ero basico",
    "students_age": "8 años",
    "objective": "aprender unidades, decenas y centenas",
    "activity": "crear números del 0 al 999 usando etiquetas con numeros de colores que según el color se definan como unidades, decenas o centenas",
    "num_questions": "6",
    "lang": "spa"
}

Respuesta

La respuesta confirmará la creación de las variables de la prueba 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 prueba.

Ejemplo de Respuesta (JSON)

{
    "job_id": 2
}

Notas

El job_id obtenido en esta respuesta será necesario para los pasos siguientes en el proceso de creación de la prueba.
Asegúrate de ingresar correctamente los parámetros en el cuerpo de la solicitud para obtener una prueba que esté alineada con el objetivo y el contexto educativo deseado.

Paso 2: Obtener el Estado y las Variables de la Prueba

Descripción

Este paso permite verificar el estado de las variables de la prueba creadas en el Paso 1. Utilizando el job_id, se puede obtener el conjunto de variables de la prueba una vez que el estado 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_test_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": 2
}

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 prueba 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 prueba están disponibles.
variables: Lista de variables de la prueba generadas, disponible solo si el estado es "ready".

Ejemplo de Respuesta (JSON)

{
    "job_id": 2,
    "status": "ready",
    "variables": "1. Comprensión de la relación entre unidades, decenas y centenas.\n2. Capacidad para identificar el valor posicional de un dígito en un número de tres cifras.\n3. Habilidad para descomponer números en unidades, decenas y centenas.\n4. Capacidad para comparar números de tres cifras utilizando unidades, decenas y centenas.\n5. Habilidad para sumar números de tres cifras considerando unidades, decenas y centenas.\n6. Capacidad para restar números de tres cifras considerando unidades, decenas y centenas."
}

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 prueba estará disponible en el campo variables, que incluye una descripción detallada de cada variable generada.
El job_id y las variables obtenidas en este paso serán necesarios para los pasos posteriores en el proceso de creación de la prueba.

Paso 3: Editar/Actualizar las Variables de la Prueba

Descripción

Este paso permite modificar o actualizar las variables de la prueba 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_test_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
`test_variables_id`	Integer	ID de las variables de la prueba obtenidas en el Paso 2.
`updated_test_variables`	String	Texto actualizado que contiene la lista de variables de la prueba en el formato deseado.

Ejemplo de Solicitud (JSON)

{
    "test_variables_id": 2,
    "updated_test_variables": "1. Entendimiento de la posición de las cifras en números de tres dígitos.\n2. Capacidad para descomponer números en unidades, decenas y centenas.\n3. Habilidad para realizar sumas y restas aplicando el concepto de unidades, decenas y centenas.\n4. Capacidad para identificar el valor de posición de una cifra dentro de un número.\n5. Habilidad para comparar números utilizando el conocimiento de unidades, decenas y centenas.\n6. Capacidad para construir números a partir de una cantidad dada de unidades, decenas y centenas."
}

Respuesta

La respuesta confirmará si la actualización de las variables de la prueba 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 test_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. Verifique los datos y vuelva a intentarlo.
En caso de {"error": "not_found"}, revise el test_variables_id proporcionado para asegurarse de que sea correcto y se haya obtenido en el Paso 2.

Paso 4: Crear la Prueba a partir de las Variables

Descripción

Este paso permite generar la prueba completa utilizando las variables definidas y, si fue necesario, actualizadas en los pasos anteriores. Es necesario proporcionar el test_variables_id obtenido en el Paso 2.

Endpoint

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

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
`test_variables_id`	Integer	ID de las variables de la prueba obtenidas en el Paso 2.
`lang`	String	Idioma de la prueba (`spa` para español).

Ejemplo de Solicitud (JSON)

{
    "test_variables_id": 1,
    "lang": "spa"
}

Respuesta

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

Campos de la Respuesta

job_id: ID de la solicitud, confirmando que la prueba 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 prueba en el siguiente paso.
Asegúrate de que el test_variables_id sea válido y que todos los pasos anteriores hayan sido completados correctamente para evitar errores.

Paso 5: Obtener el Documento de la Prueba en Formato Word (.docx)

Descripción

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

Endpoint

Método: POST
URL: https://edtechapi.com:7002/create_test_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 prueba, 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 prueba (`spa` para español).

Ejemplo de Solicitud (JSON)

{
    "user_name": "Juan Pérez",
    "job_id": 1,
    "lang": "spa"
}

Respuesta

La respuesta contendrá el job_id solicitado, el estado de la solicitud, y el documento de la prueba 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 de la prueba se ha generado correctamente.
status: Estado de la solicitud (debería ser "ready" si el documento está disponible).
base64_docx_file: Contenido del documento en formato Word (.docx), codificado en base64.

Ejemplo de Respuesta (JSON)

{
    "job_id": 1,
    "status": "ready",
    "base64_docx_file": "UEsDBBQAAAAIACF8blmtUqWRlQEAAMoGAAATAAAAW0NvbnRlbnRfVHlwZXNdLnhtb....."
}

Notas

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