documentacion_listas

Documentacion API Listas de Cotejo 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 Lista de Cotejo (Ingreso de formulario)
Verificar y obtener las variables de lista de cotejo.
Editar / Actualizar las variables (opcional)
Crear la lista de cotejo
Obtener la lista de cotejo en texto plano y como archivo Word (.docx)

Método: Crear Variables para Lista de Cotejo

Descripción

Este método genera las variables iniciales necesarias para diseñar una lista de cotejo personalizada, basada en los objetivos de aprendizaje, actividades y características del curso proporcionadas.

Endpoint

Método: POST
URL: https://edtechapi.com:7002/create_checklist_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 lista de cotejo (Ej.: `matemáticas`).
`level`	String	Nivel educativo (Ej.: `educacion básica`).
`course`	String	Curso específico (Ej.: `tercer grado`).
`students_age`	String	Edad promedio de los estudiantes (Ej.: `8 años`).
`objective`	String	Objetivo de aprendizaje relacionado con la actividad (Ej.: `Aprender unidades, decenas y centenas`).
`activity`	String	Descripción de la actividad que se evaluará con la lista de cotejo.
`lang`	String	Idioma en el que se generará la lista de cotejo (`spa` para español).

Ejemplo de Solicitud (JSON)

{
    "user_id": "xxxxx",
    "subject": "matemáticas",
    "level": "educacion básica",
    "course": "tercer grado",
    "students_age": "8 años",
    "objective": "Aprender unidades, decenas y centenas",
    "activity": "Crear números del 0 al 999 usando etiquetas de colores, donde el color define si el dígito es una unidad, una decena o una centena.",
    "lang": "spa"
}

Respuesta

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

Ejemplo de Respuesta (JSON)

{
    "job_id": 5
}

Notas

El job_id obtenido en la respuesta será necesario para los pasos siguientes en el proceso de creación de la lista de cotejo.
Asegúrate de que los datos ingresados en el cuerpo de la solicitud sean correctos y relevantes para el contexto educativo.

Método: Obtener el Estado de las Variables para la Lista de Cotejo

Descripción

Este método permite verificar el estado de las variables generadas para la lista de cotejo. Utilizando el job_id, se puede obtener la lista de variables 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_checklist_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
`job_id`	Integer	ID de la solicitud generado con el método /create_checklist_variables.

Ejemplo de Solicitud (JSON)

{
    "job_id": 5
}

Respuesta

La respuesta incluirá el job_id, el estado de la solicitud y, si está listo, la lista de variables para la lista de cotejo.

Campos de la Respuesta

job_id: ID de la solicitud.
status: Estado de la solicitud, que puede tener los siguientes valores:
- "processing": Las variables están en proceso de generación.
- "ready": Las variables están listas y disponibles.
variables: Lista de variables para la lista de cotejo generadas, disponible solo si el estado es "ready".

Ejemplo de Respuesta (JSON)

{
    "job_id": 5,
    "status": "ready",
    "variables": "1. Identifica correctamente las etiquetas de color para unidades.\n2. Identifica correctamente las etiquetas de color para decenas.\n3. Identifica correctamente las etiquetas de color para centenas.\n4. Forma números de tres dígitos utilizando las etiquetas de color adecuadas.\n5. Coloca los dígitos en el orden correcto (centenas, decenas, unidades).\n6. Verifica que el número formado esté dentro del rango de 0 a 999.\n7. Explica verbalmente el valor posicional de cada dígito en el número formado.\n8. Completa la actividad en el tiempo asignado.\n9. Muestra comprensión del concepto de valor posicional a través de ejemplos adicionales.\n10. Participa activamente en la actividad y colabora con sus compañeros."
}

Notas

Si el status es "processing", espera unos segundos e intenta nuevamente.
Una vez que el status sea "ready", la lista de variables estará disponible en el campo variables.
Las variables generadas proporcionan los criterios específicos para evaluar la actividad definida en el proceso de creación de la lista de cotejo.

Método: Actualizar Variables de la Lista de Cotejo

Descripción

Este método permite modificar o actualizar las variables de una lista de cotejo previamente generada. Se utiliza el checklist_variables_id para identificar el conjunto de variables a editar.

Endpoint

Método: POST
URL: https://edtechapi.com:7002/update_checklist_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
`checklist_variables_id`	Integer	Identificador único de las variables de la lista de cotejo a editar.
`updated_checklist_variables`	String	Nueva redacción de las variables de la lista de cotejo, en el formato deseado.

Ejemplo de Solicitud (JSON)

{
    "checklist_variables_id": 5,
    "updated_checklist_variables": "1. Identifica correctamente las etiquetas de color para unidades.\n2. Identifica correctamente las etiquetas de color para decenas.\n3. Identifica correctamente las etiquetas de color para centenas.\n4. Forma números de tres dígitos utilizando las etiquetas de color adecuadas.\n5. Coloca los dígitos en el orden correcto (centenas, decenas, unidades).\n6. Verifica que el número formado esté dentro del rango de 0 a 999.\n7. Explica verbalmente el valor posicional de cada dígito en el número formado.\n8. Completa la actividad en el tiempo asignado.\n9. Muestra comprensión del concepto de valor posicional a través de ejemplos adicionales.\n10. Participa activamente en la actividad y colabora con sus compañeros."
}

Respuesta

La respuesta confirmará si la actualización de las variables de la lista de cotejo se realizó correctamente o si ocurrió un 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.

Ejemplo de Respuesta (JSON)

Caso exitoso:

{
    "status": "success"
}

Caso de error:

{
    "status": "failed"
}

Notas

Si el status es "success", la actualización fue realizada con éxito.
Si se recibe "failed", verifica los datos proporcionados y vuelve a intentarlo.
Asegúrate de que el checklist_variables_id sea válido y haya sido obtenido previamente mediante el método /get_status_checklist_variables.

Método: Crear Lista de Cotejo

Descripción

Este método genera una lista de cotejo completa utilizando las variables previamente definidas y, si es necesario, actualizadas. Se requiere el checklist_variables_id para identificar las variables asociadas.

Endpoint

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

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
`checklist_variables_id`	Integer	ID de las variables de la lista de cotejo, obtenido en /get_status_checklist_variables.
`lang`	String	Idioma de la lista de cotejo (`spa` para español).

Ejemplo de Solicitud (JSON)

{
    "checklist_variables_id": 5,
    "lang": "spa"
}

Respuesta

La respuesta contendrá un job_id que identifica el proceso de generación de la lista de cotejo.

Campos de la Respuesta

job_id: ID de la solicitud, confirmando que la lista de cotejo se ha generado correctamente. Este id se usará en el método siguiente.

Ejemplo de Respuesta (JSON)

{
    "job_id": 8
}

Notas

El job_id obtenido en la respuesta será necesario para los pasos siguientes, como la generación del documento final de la lista de cotejo.
Asegúrate de que el checklist_variables_id sea válido y que las variables hayan sido revisadas antes de realizar la solicitud.

Método: Obtener Documento de Lista de Cotejo en Formato Word (.docx)

Descripción

Este método permite descargar el documento de la lista de cotejo en formato Word (.docx) codificado en base64, así como una representación HTML de la lista. Se utiliza el job_id obtenido en el método /create_checklist para identificar y recuperar la lista generada.

Endpoint

Método: POST
URL: https://edtechapi.com:7002/get_checklist_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 asociado a la lista de cotejo generada.
`user_name`	String	Nombre del usuario que solicita el documento (opcional, puede ir vacío).
`lang`	String	Idioma en el que se generará el documento de la lista de cotejo (`eng` para inglés).

Ejemplo de Solicitud (JSON)

{
    "job_id": 8,
    "user_name": "Juan Perez",
    "lang": "eng"
}

Respuesta

La respuesta incluirá el job_id, el estado de la solicitud, una representación HTML de la lista de cotejo y el documento codificado en base64.

Campos de la Respuesta

job_id: ID de la solicitud.
status: Estado de la solicitud (debería ser "ready" si la lista está disponible).
checklist: Representación HTML de la lista de cotejo.
base64_docx: Documento de la lista de cotejo en formato Word (.docx) codificado en base64.

Ejemplo de Respuesta (JSON)

{
    "job_id": 8,
    "status": "ready",
    "checklist": "```html\n<table border=\"1\">\n    <tr>\n        <th>Criterio de evaluación</th>\n        <th>Si</th>\n        <th>No</th>\n        <th>Puntaje obtenido</th>\n        <th>Observaciones</th>\n    </tr>\n    <tr>\n        <td>Identifica correctamente las etiquetas de color para unidades.</td>\n        <td></td>\n        <td></td>\n        <td></td>\n        <td></td>\n    </tr>\n    <!-- Más filas -->\n</table>\n\n<table border=\"1\">\n    <tr>\n        <th>Nivel de desempeño</th>\n        <th>Valoración de los criterios</th>\n        <th>Referencia numérica</th>\n    </tr>\n    <tr>\n        <td>Destacado</td>\n        <td>10 criterios demostrados</td>\n        <td></td>\n    </tr>\n    <!-- Más filas -->\n</table>\n```",
    "base64_docx": "UEsDBBQAAAAIAHB9jVmtUqWRlQEAAMoGAAATAAAAW0NvbnRlbnRfVHlwZXNdLnhtbLWVTU/bQBCG7/0Vli8+IHtDDxWq4nAocCyRGkSvm/U4Wdgv7UwC+ffMOolV0VCHBi6RnJn3fR7bsj2............."
}

Notas

Checklist (HTML): Este campo proporciona una representación HTML de la lista de cotejo, útil para mostrarla en aplicaciones web o imprimirla directamente.
Base64 Docx: El contenido en base64_docx puede decodificarse y guardarse como un archivo .docx para su edición o impresión en Word.
Asegúrate de que el job_id sea válido y de que la lista de cotejo haya sido generada correctamente antes de realizar esta solicitud.