Usuarios y estudiantes

Carga masiva de Usuarios y Estudiantes

Copy page

Requisitos Previos

Antes de realizar una carga masiva, debes tener:

1. Token de Firebase válido: Un token de autenticación de Firebase que debe incluirse en el header Authorization con el formato Bearer {token}.
2. Tenant ID (ID de Escuela): El identificador de la escuela (tenant) a la cual se desea subir la información. Este debe incluirse en el header x-tenant-id.
3. Archivo Excel válido: Un archivo Excel (.xlsx) con el formato correcto según el tipo de carga masiva que se desee realizar.

Autenticación

Todas las peticiones de carga masiva requieren los siguientes headers:

• Authorization: Bearer {token} - Token de autenticación de Firebase
• x-tenant-id: {tenantId} - Identificador de la escuela (tenant)
• x-current-role - (opcional) solo si el usuario posee mas de un rol en la misma escuela

Endpoints Disponibles

1. Carga Masiva de Docentes (Teachers)

Endpoint: POST /api/v1/teacher/bulk

Descripción: Permite subir múltiples docentes desde un archivo Excel.

Ejemplo con cURL (sobre dev):

Code
 
curl --location 'https://tolk-brein-api-gateway.development.mag.dev/api/v1/teacher/bulk' \
--header 'accept: */*' \
--header 'x-tenant-id: {tenantId}' \
--header 'Authorization: Bearer {token}' \
--form 'file=@"/ruta/al/archivo/Plantilla_docentes.xlsx"'

---

2. Carga Masiva de Familias (Families)

Endpoint: POST /api/v1/family/bulk

Descripción: Permite subir múltiples familias desde un archivo Excel.

Ejemplo con cURL (sobre dev):

Code
 
curl --location 'https://tolk-brein-api-gateway.development.mag.dev/api/v1/family/bulk' \
--header 'accept: */*' \
--header 'x-tenant-id: {tenantId}' \
--header 'Authorization: Bearer {token}' \
--form 'file=@"/ruta/al/archivo/Plantilla_familias.xlsx"'

---

3. Carga Masiva de Grupos (Groups)

Endpoint: POST /api/v1/group/bulk

Descripción: Permite subir múltiples grupos desde un archivo Excel.

Ejemplo con cURL (sobre dev):

Code
 
curl --location 'https://tolk-brein-api-gateway.development.mag.dev/api/v1/group/bulk' \
--header 'accept: */*' \
--header 'x-tenant-id: {tenantId}' \
--header 'Authorization: Bearer {token}' \
--form 'file=@"/ruta/al/archivo/Plantilla_grupos.xlsx"'

---

4. Carga Masiva de Administrativos (Administrative)

Endpoint: POST /api/v1/administrative/bulk

Descripción: Permite subir múltiples usuarios administrativos desde un archivo Excel.

Ejemplo con cURL (sobre dev):

Code
 
curl --location 'https://tolk-brein-api-gateway.development.mag.dev/api/v1/administrative/bulk' \
--header 'accept: */*' \
--header 'x-tenant-id: {tenantId}' \
--header 'Authorization: Bearer {token}' \
--form 'file=@"/ruta/al/archivo/Plantilla_administrativos.xlsx"'

---

Formato de Respuesta

Todas las cargas masivas retornan una respuesta JSON con información sobre el resultado de la operación. La estructura exacta puede variar según el tipo de carga, pero generalmente incluye:

• Información sobre registros procesados exitosamente
• Errores encontrados (si los hay)
• Detalles de validación

Códigos de Estado HTTP

• 200 OK o 201 Created: La carga se procesó correctamente
• 400 Bad Request: Error en el formato de la petición o del archivo
• 401 Unauthorized: Token de autenticación inválido o faltante
• 403 Forbidden: No se tiene permiso para realizar la operación
• 422 Unprocessable Entity: El archivo contiene errores de validación

Notas Importantes

1. Formato de archivo: Todos los endpoints aceptan archivos Excel (.xlsx) en formato multipart/form-data.
2. Validación: El sistema validará los datos antes de procesarlos. Asegúrate de que el formato del archivo Excel coincida con la plantilla esperada.
3. Tenant ID: El x-tenant-id debe corresponder a una escuela válida y el token debe tener permisos para esa escuela.
4. Token de Firebase: El token debe ser válido y no estar expirado. Asegúrate de renovarlo cuando sea necesario.

Solución de Problemas

Error 401 (Unauthorized)

• Verifica que el token de Firebase sea válido y no esté expirado
• Asegúrate de incluir el header Authorization con el formato correcto: Bearer {token}

Error 403 (Forbidden)

• Verifica que el token tenga permisos para la escuela especificada en x-tenant-id
• Confirma que el x-tenant-id sea correcto

Error 400 (Bad Request)

• Verifica que el archivo sea un Excel válido (.xlsx)
• Confirma que el campo del formulario se llame file
• Verifica que el Content-Type sea multipart/form-data

Error 422 (Unprocessable Entity)

• Revisa el formato del archivo Excel
• Verifica que todas las columnas requeridas estén presentes
• Confirma que los datos cumplan con las validaciones del sistema

Ambientes

Los ejemplos mostrados utilizan el ambiente de desarrollo. Asegúrate de usar la URL correcta según el ambiente:

• Desarrollo: https://tolk-brein-api-gateway.development.mag.dev
• Otros entornos: Solicitar url a devops