> ## Documentation Index
> Fetch the complete documentation index at: https://docs.intrena.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Importar usuarios

> Cargar o actualizar cientos de personas desde un archivo CSV, con validación previa.

La importación masiva es el camino normal para poblar la base de usuarios y
para mantenerla al día. Funciona en dos fases: **validar** y luego **importar**.

<Warning>
  Antes de importar personas, crea las [Áreas](/personas/areas) y los
  [Cargos](/personas/cargos). El archivo los referencia por **código**, y un
  código que no existe deja al usuario sin área o sin cargo.
</Warning>

## El archivo

Un CSV con una fila de encabezados y una fila por persona. Las columnas
reconocidas son:

| Columna                               | Obligatoria | Descripción                                                                      |
| ------------------------------------- | :---------: | -------------------------------------------------------------------------------- |
| `username`                            |      ✅      | Nombre de usuario. Normalmente igual al correo.                                  |
| `email`                               |      ✅      | Correo electrónico. Debe ser único y no repetirse dentro del archivo.            |
| `first_name`                          |      ✅      | Nombres.                                                                         |
| `last_name`                           |             | Apellidos.                                                                       |
| `identification_number`               |             | Número de documento.                                                             |
| `mobile`                              |             | Celular en formato internacional (`+573001234567`).                              |
| `password`                            |             | Mínimo 6 caracteres. Si se omite, se asigna la primera parte del correo.         |
| `role`                                |             | `admin`, `reader` o `user`. Si se omite, queda como `user`.                      |
| `area_code`                           |             | **Código** del área (no el nombre).                                              |
| `position_code`                       |             | **Código** del cargo (no el nombre).                                             |
| `location`                            |             | Sede, ciudad o planta.                                                           |
| `manager_username`                    |             | `username` del jefe, que debe existir.                                           |
| `avatar`                              |             | URL de la foto, con `http://` o `https://`.                                      |
| `extended_field1` … `extended_field7` |             | Los [campos personalizados](/personas/campos-personalizados) de tu organización. |

<Tip>
  Descarga la [plantilla CSV](/referencia/plantillas-csv) para no tener que
  escribir los encabezados a mano.
</Tip>

## El proceso

<Steps>
  <Step title="Sube el archivo">
    **Usuarios → Importar**, y selecciona el CSV.
  </Step>

  <Step title="Espera la validación">
    El sistema revisa el archivo completo fila por fila, sin escribir nada
    todavía. En archivos grandes toma un momento; la pantalla muestra el avance.
  </Step>

  <Step title="Revisa el resultado">
    Se muestran tres pestañas: **Errores**, **Advertencias** y **Correctos**, con
    el número de línea y el campo exacto de cada problema.
  </Step>

  <Step title="Confirma la importación">
    Si el resultado te convence, confirmas. El sistema procesa el archivo en
    segundo plano y puedes seguir trabajando; el estado se actualiza solo.
  </Step>
</Steps>

## Errores y advertencias

<Tabs>
  <Tab title="Errores">
    Impiden importar la fila. Los más comunes:

    | Mensaje                                            | Qué hacer                                         |
    | -------------------------------------------------- | ------------------------------------------------- |
    | *El nombre es requerido*                           | Llena `first_name`.                               |
    | *La contraseña debe tener mínimo 6 caracteres*     | Alárgala o déjala vacía.                          |
    | *La imagen de perfil del usuario debe ser una URL* | `avatar` debe empezar por `http://` o `https://`. |
    | Correo inválido o repetido en el archivo           | Corrige el duplicado.                             |
  </Tab>

  <Tab title="Advertencias">
    No impiden importar, pero conviene revisarlas: un `area_code` o
    `position_code` que no existe, un `manager_username` que no corresponde a
    ningún usuario, o datos de una persona que ya existe y van a ser
    sobrescritos.
  </Tab>
</Tabs>

## Crear vs. actualizar

La importación **no duplica personas**. Si el correo ya existe en tu
organización, la fila **actualiza** a esa persona con los datos del archivo. Es
la forma habitual de sincronizar cambios de área, cargo o jefe después de una
reestructuración.

<Warning>
  Una columna presente pero vacía **borra** el valor que la persona tenía. Si
  solo quieres actualizar el cargo, incluye únicamente las columnas de
  identificación y `position_code`.
</Warning>

## Activación e inactivación masiva

Aparte de la importación completa, existe la carga de un archivo solo para
**habilitar o inhabilitar** en bloque. Es más rápida y segura cuando lo único que
necesitas es dar de baja a un grupo de personas.

## Recomendaciones

<AccordionGroup>
  <Accordion title="Prueba con diez filas primero" icon="flask">
    Importa un archivo pequeño, revisa cómo quedaron esas personas en el panel y
    solo entonces sube el archivo completo.
  </Accordion>

  <Accordion title="Cuida la codificación" icon="font">
    Guarda el CSV como **UTF-8**. En otras codificaciones las tildes y las eñes
    llegan corruptas al panel.
  </Accordion>

  <Accordion title="Revisa los celulares" icon="phone">
    Excel suele comerse el `+` inicial y los ceros. Formatea la columna como
    texto antes de guardar.
  </Accordion>

  <Accordion title="Exporta antes de importar" icon="download">
    Una exportación previa de la base de usuarios es tu copia de seguridad si
    algo sale mal.
  </Accordion>
</AccordionGroup>