Importacao de Dispositivos IoT

Ao adicionar multiplos dispositivos IoT a sua frota, o recurso de importacao CSV economiza tempo significativo comparado a adicionar dispositivos individualmente. Este guia explica como preparar seu arquivo CSV e importar dispositivos com sucesso em massa.

Visao Geral do Processo de Importacao

O processo de importacao de dispositivos IoT segue estas etapas:

1. Prepare seu arquivo CSV com dados dos dispositivos
2. Faca upload do arquivo atraves da pagina de Dispositivos IoT
3. O sistema valida os dados e mostra quaisquer erros
4. Os dados sao preparados em uma tabela de importacao temporaria
5. A funcao de importacao executa para criar/atualizar registros de dispositivos
6. O cache de identidade de veiculos e limpo para garantir vinculacao adequada

Requisitos do Arquivo CSV

Formato do Arquivo

• Formato: CSV (Valores Separados por Virgula)
• Delimitador: Ponto e virgula (;) - NAO virgula
• Codificacao: UTF-8 recomendado
• Cabecalhos: A primeira linha deve conter cabecalhos de colunas
• Aspas: Use aspas duplas (") para campos de texto contendo caracteres especiais

Colunas Obrigatorias

Colunas Opcionais

Tipos IoT Validos

O campo iot_type deve ser um destes valores:

Preparando Seu Arquivo CSV

Usando Microsoft Excel

1. Abra uma nova pasta de trabalho Excel
2. Digite os cabecalhos das colunas na linha 1
3. Adicione os dados do seu dispositivo a partir da linha 2
4. Salvar Como e escolha "CSV (delimitado por virgula)"
5. Abra o arquivo CSV salvo em um editor de texto
6. Localizar e Substituir todas as virgulas (,) por ponto e virgula (;)
7. Salve o arquivo

Usando Google Sheets

1. Crie uma nova planilha
2. Digite os cabecalhos das colunas na linha 1
3. Adicione os dados do seu dispositivo a partir da linha 2
4. Va para Arquivo > Fazer download > Valores separados por virgula (.csv)
5. Abra o arquivo baixado em um editor de texto
6. Localizar e Substituir todas as virgulas (,) por ponto e virgula (;)
7. Salve o arquivo

Baixar Template CSV

Em vez de criar um arquivo do zero, voce pode baixar um template pre-formatado:

1. Va para Dispositivos IoT na barra lateral
2. Clique em Importar para abrir o dialogo de importacao
3. Clique em Baixar Template
4. O template CSV inclui todos os cabecalhos de colunas e dados de exemplo
5. Substitua os dados de exemplo pelas informacoes reais do seu dispositivo
6. Salve e faca upload do arquivo modificado

Exemplo de Conteudo CSV

imei;iccid;iot_type;iot_model;owner_name;notes
867648045123456;8901260123456789012;queclink;GL530M;Equipe de Operacoes;Frota A
867648045123457;8901260123456789013;queclink;GL530M;Equipe de Operacoes;Frota A
867648045123458;8901260123456789014;segway;;Equipe de Operacoes;Frota B
867648045123459;8901260123456789015;okai;ZK200;;Nova remessa

Fazendo Upload do Arquivo CSV

Upload Passo a Passo

O Que Acontece Durante a Importacao

Processo de Preparacao

1. O sistema limpa a tabela de preparacao (iot_devices_import)
2. Seus dados CSV sao inseridos na tabela de preparacao
3. Validacao basica e realizada nos campos obrigatorios

Funcao de Importacao

A funcao de banco de dados import_iot_devices():

1. Valida cada linha na tabela de preparacao
2. Cria novos registros de dispositivos para novos IMEIs
3. Atualiza registros existentes se o IMEI ja existe
4. Define valores padrao para campos faltantes:
   • online_status: false
   • activation_status: pending
   • total_rides: 0
   • trips_current_month: 0
   • current_month_revenue: 0
   • previous_month_revenue: 0
   • iot_added_on: carimbo de data/hora atual

Limpeza de Cache

Apos uma importacao bem-sucedida, o cache de identidade de veiculos e automaticamente limpo. Isso garante:

• Novos mapeamentos IMEI-para-veiculo sao reconhecidos
• Informacoes atualizadas do dispositivo entram em vigor imediatamente
• Nenhum dado obsoleto afeta o processamento de telemetria

Lidando com Erros de Importacao

Erros Comuns de Validacao

Erros de Formato de Arquivo

Resolvendo Erros

1. Baixe o relatorio de erros se disponivel
2. Corrija os problemas na sua planilha original
3. Re-exporte com o formato correto
4. Faca upload do arquivo corrigido

Atualizando Dispositivos Existentes

Se voce importar um CSV contendo IMEIs que ja existem no sistema:

• Dispositivos existentes sao atualizados com novos valores do CSV
• Celulas vazias nao sobrescrevem dados existentes
• A data iot_added_on e preservada para dispositivos existentes

Isso permite que voce use a importacao CSV tanto para configuracao inicial quanto para atualizacoes em massa.

Vinculando Dispositivos a Veiculos Apos Importacao

Apos importar dispositivos IoT, voce normalmente ira querer vincula-los a veiculos. Ha varias abordagens:

Opcao 1: Importar Veiculos com IMEIs

Ao importar veiculos via CSV, inclua a coluna iot_imei. O sistema vinculara automaticamente dispositivos a veiculos com base nos valores de IMEI correspondentes.

Opcao 2: Vinculacao Manual

1. Va para Veiculos
2. Clique em um veiculo
3. Edite e adicione o IMEI no campo IMEI IoT
4. Salve o veiculo

Opcao 3: Vincular pela Pagina de Dispositivos IoT

1. Va para Dispositivos IoT
2. Clique em um dispositivo nao vinculado
3. Clique em Vincular a Veiculo
4. Selecione o veiculo de destino
5. Confirme o vinculo

Melhores Praticas

Antes da Importacao

• Valide os IMEIs - Certifique-se de que todos os IMEIs de 15 digitos estao corretos
• Verifique duplicatas - Remova quaisquer linhas de IMEI duplicadas
• Verifique subcontas - Confirme que os UUIDs de subconta existem
• Teste com lote pequeno - Tente importar 5-10 dispositivos primeiro

Preparacao do Arquivo

• Use formatacao consistente - Mesmo formato de data, maiusculas/minusculas, etc.
• Remova linhas vazias - Exclua quaisquer linhas em branco no final
• Salve um backup - Mantenha sua planilha original
• Documente seus mapeamentos - Anote quais colunas voce usou

Apos a Importacao

• Verifique a contagem - Verifique se o total de dispositivos corresponde ao esperado
• Verifique registros aleatoriamente - Abra alguns dispositivos para verificar os dados
• Teste a conectividade - Confirme que os dispositivos podem se comunicar
• Vincule a veiculos - Associe dispositivos aos veiculos da frota

Importacao Programatica

Para usuarios avancados, dispositivos IoT tambem podem ser importados via API:

Endpoint da API

POST /api/iot-devices/import

Formato da Requisicao

{
  "csv_data": [
    {
      "imei": "867648045123456",
      "iccid": "8901260123456789012",
      "iot_type": "queclink",
      "iot_model": "GL530M",
      "notes": "Frota A"
    },
    {
      "imei": "867648045123457",
      "iccid": "8901260123456789013",
      "iot_type": "queclink"
    }
  ]
}

Resposta

{
  "success": true,
  "message": "Dispositivos IoT importados com sucesso",
  "total_count": 150
}

Vinculando Dispositivo a Veiculo via API

Voce tambem pode vincular um dispositivo IoT a um veiculo programaticamente:

PUT /api/iot-devices/import

Corpo da Requisicao

{
  "imei": "867648045123456",
  "vehicle_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Resposta

{
  "success": true,
  "message": "Dispositivo IoT vinculado ao veiculo com sucesso",
  "vehicle_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "imei": "867648045123456"
}

Este endpoint:

1. Atualiza o campo iot_imei do veiculo com o IMEI fornecido
2. Limpa o cache de identidade do veiculo para garantir reconhecimento imediato
3. Retorna confirmacao do vinculo

Solucao de Problemas

Importacao Bem-Sucedida Mas Dispositivos Nao Aparecem

1. Verifique o filtro de subconta - voce pode estar visualizando uma subconta diferente
2. Atualize a pagina para garantir que os dados mais recentes sejam carregados
3. Pesquise por IMEI para localizar dispositivos especificos

Dispositivos Importados Mas Nao Vinculados a Veiculos

1. Verifique se o IMEI corresponde exatamente (sem espacos ou tracos)
2. Verifique se os veiculos existem com valores iot_imei correspondentes
3. Tente desvincular e revincular manualmente

Telemetria Nao Chegando Apos Importacao

1. Confirme que o dispositivo esta ligado e tem conectividade
2. Verifique se as configuracoes do servidor no dispositivo correspondem ao seu endpoint
3. Verifique a lista "Dispositivos Nao Correspondidos" para quaisquer problemas
4. Aguarde 5-10 minutos para o primeiro heartbeat

---