Como alimentar os dados de uma tabela auxiliar

Depois de definir os campos, a tabela está pronta para receber os registros. A forma de cadastrá-los depende da opção escolhida em Como a tabela será alimentada:

Alimentação	Como os registros chegam	Ideal para
Alimentação manual	Digitados um a um na web ou importados de uma planilha .xlsx ou .csv.	Listas pequenas ou que mudam pouco, ou uma carga inicial a partir de uma planilha.
Via API	Enviados por um sistema externo, que substitui todo o conteúdo da tabela a cada envio.	Listas que já existem em outro sistema (RH, ERP, cadastro de clientes) e precisam ficar sempre iguais a ele.

A forma de alimentação pode ser trocada depois, pela opção Editar do menu da tabela.

1. Alimentação manual

Nas tabelas de Alimentação manual, o bloco Dados fica abaixo dos Campos e mostra os registros da tabela, com uma busca (Buscar nos registros) e paginação.

Adicionar, editar e remover registros

1. No bloco Dados, clique em Adicionar item;
2. No painel Novo registro, preencha os campos. Só a Chave é obrigatória;
3. Clique em Salvar.

Para corrigir um registro, use o botão Editar registro da linha; para apagá-lo, Remover registro.

Adicionando um registro manualmente

Importar uma planilha

Para cadastrar muitos registros de uma vez, importe uma planilha:

1. Prepare o arquivo:
   • formato .xlsx (Excel) ou .csv, com até 50 MB. No .xlsx, só a primeira aba é lida;
   • a primeira linha deve ter os cabeçalhos das colunas, escritos com o Título ou o Nome interno de cada campo (maiúsculas, minúsculas e acentos não importam);
   • cada linha seguinte é um registro;
2. No bloco Dados, clique em Importar planilha e escolha o arquivo;
3. Aguarde a mensagem com o resultado, por exemplo "120 registros importados com sucesso".

O que acontece na importação:

• Registro novo (chave que ainda não existe): é criado;
• Registro existente (mesma chave): é atualizado com os valores da planilha;
• Registros que não estão na planilha continuam na tabela: a importação não apaga nada. Para remover registros, use Remover registro;
• Linhas com problema (por exemplo, sem a chave ou com texto em um campo Número) são ignoradas, e as demais são importadas. A mensagem informa quantas linhas foram rejeitadas, por exemplo "118 registros importados, 2 linhas rejeitadas".

Colunas que não correspondem a nenhum campo

Se o arquivo tiver uma coluna cujo cabeçalho não corresponde a nenhum campo, ou que corresponde a mais de um, nada é importado. O sistema informa quais colunas causaram o problema: renomeie-as com o Título ou o Nome interno de um campo, ou remova-as, e importe novamente.

Números em arquivos .csv

Em arquivos .csv, escreva os números decimais com ponto (10.5), não com vírgula. Em arquivos .xlsx, basta que a célula esteja formatada como número.

2. Alimentação via API

Nas tabelas Via API, os registros são enviados por um sistema externo, normalmente configurado pela equipe de TI. No lugar do bloco Dados, a tabela mostra duas abas:

• Ingestão de dados via API: o endereço de envio, um exemplo dos dados e um exemplo de comando, montados com os campos da tabela, além do token de acesso;
• Dados: os registros recebidos, apenas para consulta.

Cada envio substitui a tabela inteira

"Cada envio substitui o conteúdo total da tabela: registros ausentes no payload são removidos." Ou seja, o sistema externo deve enviar sempre a lista completa, e não apenas o que mudou.

Exemplo: a tabela tem Ana, Bruno e Carla. Para incluir Daniel, o envio precisa trazer Ana, Bruno, Carla e Daniel. Se o sistema enviar só Daniel, a tabela passa a ter apenas Daniel: Ana, Bruno e Carla são removidos.

Gerar o token

O token é a senha que o sistema externo usa para enviar os dados. Cada tabela tem o seu.

1. Na aba Ingestão de dados via API, clique em Gerar token;
2. Copie o token imediatamente e guarde-o em um local seguro, como um cofre de senhas: "por segurança, ele não será exibido novamente";
3. Depois disso, o painel mostra apenas os últimos caracteres do token ativo, por exemplo "Token ativo, terminado em a1b2".

Botão	Quando usar
Gerar novo token	O token foi perdido ou exposto. O token atual deixa de funcionar na hora, e o sistema que envia os dados para até ser atualizado com o novo.
Revogar token	Interromper o envio de dados. Nenhum envio é aceito até que um novo token seja gerado.
Esvaziar tabela	Remover todos os registros da tabela, mantendo os campos definidos.

Para a equipe de TI

O envio é uma requisição POST para o endereço exibido em Endpoint (por exemplo, https://api2.hashdata.app/v1/aux-tables/ingest), com o token no cabeçalho X-HD-Aux-Table-Token e, no corpo, uma lista JSON com um objeto por registro. As chaves de cada objeto são os Nomes internos dos campos:

curl -X POST 'https://api2.hashdata.app/v1/aux-tables/ingest' \
  -H 'Content-Type: application/json' \
  -H 'X-HD-Aux-Table-Token: SEU_TOKEN' \
  -d '[
    { "matricula": "1001", "nome": "Ana Souza", "setor": "Produção", "capacidade": 40 },
    { "matricula": "1002", "nome": "Bruno Lima", "setor": "Qualidade", "capacidade": 35 }
  ]'

Regras do envio:

• Lista completa a cada envio. Registros cuja chave não aparece no envio são removidos da tabela. Para esvaziá-la, use o botão Esvaziar tabela ou a rota PUT .../aux-tables/truncate, com o mesmo cabeçalho; um envio com lista vazia é recusado;
• Só os campos da tabela. Uma chave que não é o Nome interno de um campo faz a linha ser rejeitada. Campos vazios ou null não são gravados;
• Números devem ser enviados como número JSON (40), não como texto com vírgula;
• Limites: até 100.000 registros por envio, até 50 campos por registro, textos de até 10.000 caracteres e no máximo 2 envios por minuto por token;
• Resposta: a quantidade de registros gravados (upserted) e a lista de linhas rejeitadas (rejectedRows), cada uma com o motivo. As linhas rejeitadas não apagam o registro que já existia com a mesma chave.

Enquanto a estrutura da tabela é alterada

Durante o reprocessamento de uma alteração de estrutura, os envios são recusados. O sistema externo deve tentar novamente alguns minutos depois.

3. Problemas comuns

O que você vê	O que fazer
"Defina os campos da tabela antes de cadastrar registros."	Salve os campos da tabela antes de adicionar ou importar registros.
"O arquivo tem colunas que não correspondem a nenhum campo desta tabela"	Renomeie as colunas com o Título ou o Nome interno dos campos, ou remova-as.
"O arquivo excede o tamanho máximo de 50 MB."	Divida a planilha em arquivos menores e importe um de cada vez.
"O arquivo é inválido ou está vazio."	Confira se o arquivo é .xlsx ou .csv e se a primeira aba tem cabeçalho e registros.
Algumas linhas foram rejeitadas	Confira se todas têm a Chave preenchida e se os campos Número contêm apenas números.
Não vejo o botão Adicionar item	A tabela é Via API: os registros só chegam pelo sistema externo. Mude para Alimentação manual em Editar, se for o caso.
O sistema externo deixou de enviar dados	O token pode ter sido revogado ou substituído. Gere um novo e entregue-o à equipe de TI.
Registros sumiram depois de um envio pela API	O envio não trazia esses registros. Cada envio deve conter a lista completa.

Próximos passos

• Saiba mais sobre como usar a tabela em um formulário;
• Saiba mais sobre como limitar os registros por área de trabalho.