Cómo alimentar los datos de una tabla auxiliar

Después de definir los campos, la tabla está lista para recibir los registros. La forma de cargarlos depende de la opción elegida en Cómo se alimentará la tabla:

Alimentación	Cómo llegan los registros	Ideal para
Alimentación manual	Escritos uno a uno en la web o importados de una hoja de cálculo .xlsx o .csv.	Listas pequeñas o que cambian poco, o una carga inicial a partir de una hoja de cálculo.
Vía API	Enviados por un sistema externo, que sustituye todo el contenido de la tabla en cada envío.	Listas que ya existen en otro sistema (RR. HH., ERP, registro de clientes) y deben estar siempre iguales a él.

La forma de alimentación puede cambiarse después, con la opción Editar del menú de la tabla.

1. Alimentación manual

En las tablas de Alimentación manual, el bloque Datos está debajo de los Campos y muestra los registros de la tabla, con una búsqueda (Buscar en los registros) y paginación.

Agregar, editar y eliminar registros

1. En el bloque Datos, haz clic en Agregar elemento;
2. En el panel Nuevo registro, completa los campos. Solo la Clave es obligatoria;
3. Haz clic en Ahorrar.

Para corregir un registro, usa el botón Editar registro de la fila; para borrarlo, Eliminar registro.

Agregando un registro manualmente

Importar una hoja de cálculo

Para cargar muchos registros de una vez, importa una hoja de cálculo:

1. Prepara el archivo:
   • formato .xlsx (Excel) o .csv, de hasta 50 MB. En el .xlsx, solo se lee la primera hoja;
   • la primera fila debe tener los encabezados de las columnas, escritos con el Título o el Nombre interno de cada campo (mayúsculas, minúsculas y acentos no importan);
   • cada fila siguiente es un registro;
2. En el bloque Datos, haz clic en Importar hoja de cálculo y elige el archivo;
3. Espera el mensaje con el resultado, por ejemplo "120 registros importados con éxito".

Qué ocurre en la importación:

• Registro nuevo (clave que todavía no existe): se crea;
• Registro existente (misma clave): se actualiza con los valores de la hoja de cálculo;
• Registros que no están en la hoja de cálculo siguen en la tabla: la importación no borra nada. Para eliminar registros, usa Eliminar registro;
• Filas con problemas (por ejemplo, sin la clave o con texto en un campo Número) se ignoran, y las demás se importan. El mensaje informa cuántas filas fueron rechazadas, por ejemplo "118 registros importados, 2 filas rechazadas".

Columnas que no corresponden a ningún campo

Si el archivo tiene una columna cuyo encabezado no corresponde a ningún campo, o que corresponde a más de uno, no se importa nada. El sistema informa qué columnas causaron el problema: renómbralas con el Título o el Nombre interno de un campo, o elimínalas, e importa de nuevo.

Números en archivos .csv

En archivos .csv, escribe los números decimales con punto (10.5), no con coma. En archivos .xlsx, basta con que la celda tenga formato de número.

2. Alimentación vía API

En las tablas Vía API, los registros los envía un sistema externo, normalmente configurado por el equipo de TI. En lugar del bloque Datos, la tabla muestra dos pestañas:

• Ingesta de datos vía API: la dirección de envío, un ejemplo de los datos y un ejemplo de comando, armados con los campos de la tabla, además del token de acceso;
• Datos: los registros recibidos, solo para consulta.

Cada envío sustituye la tabla entera

"Cada envío sustituye el contenido total de la tabla: los registros ausentes del payload se eliminan." Es decir, el sistema externo debe enviar siempre la lista completa, y no solo lo que cambió.

Ejemplo: la tabla tiene a Ana, Bruno y Carla. Para incluir a Daniel, el envío debe traer a Ana, Bruno, Carla y Daniel. Si el sistema envía solo a Daniel, la tabla queda únicamente con Daniel: Ana, Bruno y Carla se eliminan.

Generar el token

El token es la contraseña que el sistema externo usa para enviar los datos. Cada tabla tiene el suyo.

1. En la pestaña Ingesta de datos vía API, haz clic en Generar token;
2. Copia el token de inmediato y guárdalo en un lugar seguro, como un gestor de contraseñas: "por seguridad no se mostrará de nuevo";
3. Después de eso, el panel muestra solo los últimos caracteres del token activo, por ejemplo "Token activo, terminado en a1b2".

Botón	Cuándo usarlo
Generar nuevo token	El token se perdió o quedó expuesto. El token actual deja de funcionar en el momento, y el sistema que envía los datos se detiene hasta que se actualice con el nuevo.
Revocar token	Detener el envío de datos. No se acepta ningún envío hasta que se genere un nuevo token.
Vaciar tabla	Eliminar todos los registros de la tabla, manteniendo los campos definidos.

Para el equipo de TI

El envío es una solicitud POST a la dirección mostrada en Endpoint (por ejemplo, https://api2.hashdata.app/v1/aux-tables/ingest), con el token en el encabezado X-HD-Aux-Table-Token y, en el cuerpo, una lista JSON con un objeto por registro. Las claves de cada objeto son los Nombres internos de los campos:

curl -X POST 'https://api2.hashdata.app/v1/aux-tables/ingest' \
  -H 'Content-Type: application/json' \
  -H 'X-HD-Aux-Table-Token: SU_TOKEN' \
  -d '[
    { "matricula": "1001", "nombre": "Ana Souza", "sector": "Producción", "capacidad": 40 },
    { "matricula": "1002", "nombre": "Bruno Lima", "sector": "Calidad", "capacidad": 35 }
  ]'

Reglas del envío:

• Lista completa en cada envío. Los registros cuya clave no aparece en el envío se eliminan de la tabla. Para vaciarla, usa el botón Vaciar tabla o la ruta PUT .../aux-tables/truncate, con el mismo encabezado; un envío con la lista vacía se rechaza;
• Solo los campos de la tabla. Una clave que no es el Nombre interno de un campo hace que la fila se rechace. Los campos vacíos o null no se guardan;
• Los números deben enviarse como número JSON (40), no como texto con coma;
• Límites: hasta 100.000 registros por envío, hasta 50 campos por registro, textos de hasta 10.000 caracteres y como máximo 2 envíos por minuto por token;
• Respuesta: la cantidad de registros guardados (upserted) y la lista de filas rechazadas (rejectedRows), cada una con el motivo. Las filas rechazadas no borran el registro que ya existía con la misma clave.

Mientras se cambia la estructura de la tabla

Durante el reprocesamiento de un cambio de estructura, los envíos se rechazan. El sistema externo debe intentarlo de nuevo unos minutos después.

3. Problemas comunes

Lo que ves	Qué hacer
"Defina los campos de la tabla antes de agregar registros."	Guarda los campos de la tabla antes de agregar o importar registros.
"El archivo tiene columnas que no corresponden a ningún campo de esta tabla"	Renombra las columnas con el Título o el Nombre interno de los campos, o elimínalas.
"El archivo supera el tamaño máximo de 50 MB."	Divide la hoja de cálculo en archivos más pequeños e impórtalos de uno en uno.
"El archivo es inválido o está vacío."	Verifica que el archivo sea .xlsx o .csv y que la primera hoja tenga encabezado y registros.
Algunas filas fueron rechazadas	Verifica que todas tengan la Clave completada y que los campos Número contengan solo números.
No veo el botón Agregar elemento	La tabla es Vía API: los registros solo llegan por el sistema externo. Cambia a Alimentación manual en Editar, si corresponde.
El sistema externo dejó de enviar datos	Es posible que el token haya sido revocado o sustituido. Genera uno nuevo y entrégalo al equipo de TI.
Desaparecieron registros después de un envío por la API	El envío no traía esos registros. Cada envío debe contener la lista completa.

Próximos pasos

• Más información sobre cómo usar la tabla en un formulario;
• Más información sobre cómo limitar los registros por área de trabajo.