&Allan.Anderson; &Allan.Anderson.mail;

# 'Plugin' de Importação de CSV

## Razões para importar os ficheiros em CSV

De um modo geral, é preferível importar em OFX. Contudo, nem todas as instituições oferecem dados nesse formato. Os ficheiros em CSV (valores separados por vírgulas) estão quase sempre disponíveis, sendo em alguns casos referidos como ficheiros de folhas de cálculo ou ficheiros de Excel. Da mesma forma, os mesmos podem ser criados de forma relativamente simples se capturar os dados que deseja importar, como os de um ficheiro de texto, editando-os manualmente.

O objectivo primário do 'plugin' é a importação de dados a partir de extractos bancários, mas existe também a capacidade de importar alguns extractos de investimentos. Este 'plugin' foi criado inicialmente, antes de se tornar um importador de ficheiros CSV, para produzir ficheiros em QIF a partir de CSV, os quais poderiam então ser importados. Esta funcionalidade ainda está presente, mas provavelmente virá a ser removida, dado que o 'plugin' se foca agora na importação directa de ficheiros em CSV. Da mesma forma, o &kappname; tem a capacidade nativa de exportar ficheiros em QIF, pelo que não existe nenhuma razão em concreto para produzir dados em QIF a partir de um ficheiro em CSV.

## Obter o 'Plugin'

O &kappname; irá importar os ficheiros em CSV. Esta funcionalidade é fornecida sob a forma de um 'plugin', fazendo agora parte do programa de base, tanto nos pacotes das distribuições como nos ficheiros de código. Assim que o pacote da distribuição for instalado ou o código for compilado e instalado, a opção do menu para importar ficheiros em CSV irá aparecer automaticamente sob o menu Ficheiro Importar.

O 'plugin' de importação de CSV é muito mais recente que o 'plugin' de OFX, mas a maioria das distribuições já trazem incluído o importador de CSV ou disponível como um pacote à parte. Certifique-se que está activo dentro do &kappname;. Verifique na opção do menu Configuração Configurar o KMyMoney Plugins. Se o importador de CSV não parecer estar instalado na sua versão, o primeiro local a verificar é o mesmo onde obteve o seu pacote de base do &kappname;. Verifique se já está disponível uma versão posterior ou se o importador está disponível num pacote separado.

Se tiver instalado a partir de um pacote RPM ou DEB, o 'plugin' de importação em CSV deverá constar dentro do pacote do &kappname;. Se tiver compilado a partir do código-fonte, não deverão existir requisitos adicionais. O processo de compilação do &kappname; deverá detectar o código do 'plugin' e compilar o mesmo.

## Importar um ficheiro em CSV

Para importar um ficheiro em CSV, escolha o importador a partir do menu: Ficheiro Importar CSV.... Se o CSV não aparecer sob a opção 'Importar', não tem o 'plugin' de Importação de CSV instalado correctamente. Nesse caso, veja a secção anterior.

A Importação de CSV tem a forma de um assistente, com uma página separada para cada passo individual do processo. Poderão existir pequenas diferenças menores entre o texto neste manual, as legendas nas imagens e os textos que vê de facto no assistente. Nesses casos, o manual descreve o que o assistente deverá vir a ter na próxima versão.

### Assistente de Importação de CSV: Início

Quando é iniciado, o importador de CSV mostra a página de Início. A área superior, onde os dados serão apresentados, está inicialmente vazia. Por baixo dela, à esquerda, existe uma lista com os passos do processo de importação, estando o actual realçado. À direita do mesmo, existem algumas breves instruções e duas opções exclusivas, permitindo a escolha de Banca ou Investimento. De seguida, existem um campo de selecção do perfil, o qual fica activo assim que uma das opções exclusivas for seleccionada. No fundo do ecrã existem botões para passar para o passo seguinte do assistente, para Recuar para o passo anterior ou para Cancelar a importação. No passo inicial, existe também um botão Seleccionar o Ficheiro para seleccionar inicialmente o ficheiro a importar.

Da mesma forma, repare na opção Ignorar a configuração a seguir ao selector de perfis. Inicialmente, não deverá assinalar esta opção. Assim que tiver configurado um perfil e terminado o assistente, esses parâmetros são gravados no ficheiro do recurso. Da próxima vez que usar o mesmo perfil, os parâmetros serão carregados na interface do utilizador. O assistente irá então assumir os parâmetros nas páginas seguintes, caso não tenha necessidade de os alterar. Em vez disso, caso se sinta satisfeito com um dado perfil, poderá ser útil assinalar esta opção. O assistente irá então passar directamente para a página final e, assumindo que não foram encontrados problemas, apenas terá de carregar no botão Importar.

Primeiro, seleccione uma das opções Banca ou Investimento, carregando depois no selector, o qual apresenta o texto "Adicionar um Novo Perfil". Caso tenha criado anteriormente algum perfil, poderá seleccionar um deles; caso contrário, indique um nome para o novo perfil, sendo provavelmente o nome da conta que deseja importar. Se introduzir o nome de um novo perfil, carregue em &Enter; para o criar. Depois, carregue em Seleccionar o Ficheiro, para que apareça uma janela de selecção de ficheiros, onde poderá escolher o ficheiros em CSV que deseja importar.

### Assistente de Importação de CSV: Separadores

O assistente terá agora avançado para a página de Separadores, pelo que deverá agora ver os seus dados.

Poderá parecer que os itens apresentados na secção superior da janela do 'plugin' podem ser editados e, de certa forma, os mesmos podem ser, mas as alterações não serão registadas. A tabela serve apenas para apresentar os dados, não para os editar. O ficheiro de entrada nunca é alterado pelo 'plugin', pelo que os dados importados de facto vêm sempre do ficheiro, não dos dados apresentados. A única excepção para isto está coberta na secção de Títulos e Símbolos em baixo.

O 'plugin' já deverá ter detectado o Separador de Campos apropriado a usar, sendo que não é normalmente possível seleccionar um diferente. De facto, se tentar fazê-lo, irá limpar todas as escolhas de campo que já possa ter feito. Existe também um selector para o Separador de Texto, mas normalmente as aspas (") estão correctas. Agora, carregue no botão Seguinte. Dependendo da selecção anterior que tenha efectuado, tanto poderá estar na página de Banca ou de Investimento.

### Assistente de Importação de CSV: Banca

Nesta página, poderá seleccionar os números das colunas a partir dos quais serão importados os campos relevantes.

Para a maioria dos campos, apenas terá de usar a lista apropriada para seleccionar a coluna desejada. Contudo, existem algumas considerações especiais.

- No centro encontram-se duas opções exclusivas. Se o seu ficheiro tiver uma única coluna para todos os valores, seleccione a coluna do Montante. Contudo, se existirem colunas separadas para os débitos e para os créditos, seleccione a opção Coluna de débito/crédito. Isto irá activar o selector da coluna do Montante ou da coluna do Débito e Crédito.

- É possível seleccionar mais que uma coluna para o campo do Memorando, através de selecções sucessivas. As colunas de memorando já seleccionadas são marcadas na lista com um asterisco (*). Se seleccionou várias colunas desta forma, o seu conteúdo será concatenado no campo de Memorando.

- Caso tente escolher o mesmo número de coluna para dois campos, o 'plugin' alertá-lo-á e irá limpar ambas as selecções. Contudo, pode usar a mesma coluna nos campos de Beneficiário/Descrição e de Memo. Se seleccionar uma coluna para o campo de Beneficiário/Descrição e depois seleccionar o mesmo campo para o Memorando, irá receber um aviso por ter seleccionado colunas duplicadas, mas que lhe pergunta se deseja prosseguir. Se o desejar fazer, carregue em Sim.

- Uma razão em particular para também capturar o campo de Beneficiário/Descritor no campo de Memorando é que o campo de Beneficiário/Descrição pode ficar completamente alterado na importação quando o &kappname; fizer a correspondência das transacções. Se seleccionar esse campo também como Memorando irá preservar esses dados, caso contrário perder-se-iam.

Se reparar que fez uma escolha incorrecta, basta alterar essa selecção. Se tiver de efectuar várias alterações, carregue no botão Limpar.

Assim que tiver seleccionado as colunas para todos os campos obrigatórios, ficará activo o botão Seguinte pelo que, ao carregar no mesmo, irá avançar no assistente.

### Assistente de Importação de CSV: Investimento

Esta página é semelhante à da Banca, ainda que seja ligeiramente mais complexa. A maioria das selecções são relativamente óbvias, mas existem alguns itens que poderão ser parecer confusos até que tenha terminado o processo uma ou duas vezes.

- Tal como na página de Banca, poderá seleccionar mais que uma coluna para o campo de Memorando

- O selector Tipo/Acção serve para identificar a coluna que contém o tipo de acção, como por exemplo Comprar, Vender, Dividendo, etc.

- O selector da Fracção do Preço serve para indicar a fracção/multiplicação para fins de compatibilidade entre os preços importados e os gravados. Por exemplo, se o preço do ficheiro importado estiver em cêntimos mas a sua conta no &kappname; estiver em euros, seleccione o valor 0,01. Por outro lado, se os preços do seu ficheiro de dados estiverem em euros, assim como o ficheiro em CSV a importar, configure a Fracção do Preço como 1,0.

- Use o selector da Coluna da Taxa se o seu ficheiro tiver uma coluna específica para as taxas. Lembre-se, contudo, que a taxa poderá ter sido incluída no preço. Se existir uma taxa e a mesma for uma percentagem, em vez de um valor, assinale a opção A taxa é uma percentagem. Repare que, nesta página, este é o único campo que inclui "coluna" na legenda, para demarcar que é para a coluna da taxa, não para nenhuma taxa em especial.

- Por baixo dos selectores das colunas existem duas áreas para a identidade do título. Dependendo da sua instituição de corretagem/financeira, o seu ficheiro poderá conter elementos para apenas um ou vários títulos.

  - Se o ficheiro tiver transacções para apenas um título, estando o nome possivelmente numa linha do cabeçalho, o nome deverá ser introduzido no campo Nome do Título. O nome que introduzir será adicionado à lista para uso posterior. Poderá desejar depois remover esse nome da lista. Se assim for, seleccione-o, carregando depois no botão Esconder o título. Este remove-o apenas desta lista, não tendo qualquer efeito no seu ficheiro principal do &kappname;.

  - Se o ficheiro inclui transacções para diversos títulos, cada um será identificado pelo seu símbolo numa coluna e com mais detalhes noutra coluna. Seleccione essas colunas nos selectores Símbolo e Detalhe. Poderá acontecer que um título não tenha um símbolo oficial, pelo que nesse caso poderá ser inventado um pseudo-símbolo; isto não é nenhum problema, desde que identifique de forma única esse título no ficheiro da importação. Em algumas vezes o tipo de actividade actual está incorporado na coluna de detalhes, antecedido possivelmente de um texto-padrão. Por exemplo, se o campo tiver type: dividend, indique no campo Texto do filtro type: , incluindo o espaço final.

Quando todos os botões necessários estiverem seleccionados, o botão Seguinte ficará activo pelo que, ao carregar nele, irá avançar no assistente.

### Assistente de Importação de CSV: Linhas

Nesta página, poderá indicar se algumas das linhas deverão ser ignoradas no início ou no fim do ficheiro. Também poderá indicar o formato de qualquer coluna de datas.

### Linha inicial

Configure este campo para que o importador ignore as linhas de cabeçalho no ficheiro. A sua escolha será gravada neste perfil para utilização futura. As linhas de início e de fim interagem, pelo que a linha de início não poderá ser superior à linha de fim. Se o selector da Linha inicial não responder, verifique a configuração da linha final.

### Linha final

O importador irá configurar automaticamente este campo com a última linha no ficheiro ou com o último valor gravado. Só terá de o ajustar se existirem linhas de rodapé no ficheiro que o importador deva ignorar. Caso contrário, irá provavelmente obter um aviso de erro nos dados quando o 'plugin' tentar processar dados incorrectos. Uma vez mais, se o selector da Linha final não responder, assinale a opção Linha inicial.

### Formato da data

Este terá de ser configurado de acordo com a ordem do ano, mês e dia nas data do ficheiro. Se o 'plugin' encontrar dados incompatíveis com esta definição, ele queixar-se-á quando tentar importar os dados. Contudo, se a opção estiver errada, mas não produzir dados inválidos (como datas em que o dia é inferior a 12, pelo que não irá interferir entre o mês e o dia) irá simplesmente obter dados incorrectos, porque o 'plugin' não consegue saber que cometeu um erro. Nesse caso, o erro será óbvio no livro de registos após a importação.

Assim que estiver pronto, o botão Seguinte ficará activo pelo que, ao carregar nele, irá avançar no assistente.

### Assistente de Importação de CSV: Títulos e Símbolos

Para um ficheiro de investimentos, depois de ter aceite a página das Linhas, terá de garantir que cada título no ficheiro corresponde ao título correcto no seu ficheiro do &kappname;, antes de prosseguir com a importação. Nesta altura, outra janela irá abrir, mostrando os títulos e os símbolos existentes no ficheiro de importação. Lembre-se que, ao contrário da apresentação dos dados nas janelas principais do assistente, as alterações que fizer nesta página serão importadas.

A finalização desta página será intuitiva, caso tenha em consideração estes itens:

- Cada linha representa uma transacção, pelo que poderá parecer que existem linhas duplicadas. Isto é normal.

- Todos os nomes de títulos deverão corresponder de forma exacta ao título existente, tal como definido no &kappname;. Se não corresponder, será criado como um novo título, o qual poderá não ser do seu agrado, a menos que represente a compra de um novo título.

- Deverá ser apresentado um símbolo para cada título.

- A única informação nesta página deverá ser o símbolo e o nome do título. Todas as outras informações apresentadas inicialmente (como a data ou o tipo de actividade) consta à mesma no ficheiro de importação actual, mas não deverá ser apresentada aqui.

Poderá editar o nome ou o símbolo de um título se fizer duplo-click numa célula. Para cada título, se necessário, edite o nome numa das suas linhas. Se o nome correcto do título aparecer no ficheiro importado, faça duplo-click sobre o mesmo para o seleccionar e depois copie-o e cole-o/edite-o, tendo em atenção se usou uma variante ou uma abreviatura dentro do &kappname;. Se editar o nome de um título, essa edição será aplicada a todas as linhas com o mesmo símbolo.

Qualquer linha sem um símbolo será tratada como um item de corretagem. Se qualquer transacção envolver outra conta, ⪚, uma conta à ordem ou de corretagem para um dividendo recebido ou para fazer um pagamento, irá aparecer uma janela de mensagem para o nome da conta usada na transferência. Esta será normalmente a conta de Corretagem que seleccionou ou criou quando criou a conta de Investimento. Da mesma forma, indique o número da coluna que contém o beneficiário, caso seja pedido. Se for cometido um erro ao introduzir o nome da conta, a importação irá prosseguir mas o &kappname; não o irá reconhecer, pelo que irá marcar essas transacções como não tendo uma categoria atribuída. Se o nome da conta desejado for demasiado longo, basta indicar alguns caracteres. A importação irá prosseguir mas as transacções serão marcadas pelo &kappname; como não tendo uma categoria atribuída, pelo que terá de seleccionar a conta de transferência correcta após a importação. Carregue em OK quando terminar. O processo de importação prossegue então para o &kappname;

Se tiver mais que uma transacção que se refira ao mesmo título, podê-las-á editar a todas de uma vez, usando a selecção múltipla. Por exemplo, para adicionar um símbolo a várias linhas, carregue e deixe carregada a tecla CTRL e, na coluna do símbolo, seleccione cada uma das transacções. Mantendo à mesma carregada a tecla CTRL, todas essas células de símbolos ainda deverão estar seleccionadas, pelo que poderá carregar numa e introduzir o símbolo. Carregue dentro da janela mas fora dessa coluna, ou então carregue em Enter (não em OK). Agora que essas transacções têm todas o mesmo símbolo, faça duplo-click sobre um item de detalhe e edite o nome do título como desejar. Carregue noutro local da janela (ou em Enter) para aceitar a edição, o que irá então alterar todos esses elementos. Os itens restantes irão mostrar os símbolos recolhidos a partir das transacções no ficheiro de importação.

Agora carregue em OK e depois em Importar. No campo Indicar a Conta, indique o nome da conta de corretagem/conta à ordem para os fundos. Se introduzir um nome válido, será usada essa conta. Se não se quiser incomodar a introduzir um nome correcto mas extenso, indique apenas alguns caracteres. A importação aceitá-lo-á, mas as transacções no livro de registos irão precisar de uma conta válida seleccionada, após a importação. Para o campo Item de Corretagem, indique o número da coluna que contém esse detalhe. Agora, no campo Transacção inválida, poderá obter alguns itens porque o tipo de actividade não corresponde à combinação da quantidade/preço/montante. Em cada mensagem, carregue em Seleccionar o Tipo de Transacção, onde aparecerá uma lista que indica os tipos de actividade válidos para essa combinação de valores.

Agora a importação tomou lugar e está no KMM para seleccionar a conta de investimento a usar. Depois deverá indicar a conta à ordem, caso existissem algumas contas de corretagem.

### Assistente de Importação de CSV: Fim

Ao chegar à página Final, o 'plugin' irá validar automaticamente os valores. Se as colunas dos valores numéricos estiverem realçadas a verde, então a validação foi bem sucedida e tudo o que é necessário é carregar em Importar o CSV, passando o controlo ao programa principal do &kappname;. Contudo, se as linhas iniciais e finais estiverem mal definidas, ou se as colunas erradas estiverem seleccionadas, o realce será feito a vermelho, aparecendo uma mensagem de erro a indicar onde se passa o problema. O utilizador terá então de carregar em Recuar para voltar à página relevante para corrigir o erro.

Também poderá ser o caso de que existam colunas de débito e crédito, sendo que uma dessas colunas possa não conter quaisquer itens. Isso iria significar que a essa coluna não teria um símbolo decimal presente, pelo que isso daria origem a um aviso. Se for esse o caso, poderá carregar num dos botões Aceitar (Aceitar isto ou Aceitar tudo.)

### Símbolo Decimal

Outro problema possível poderá ser que o símbolo decimal seleccionado esteja incorrecto. Se seleccionar o símbolo para corresponder aos dados, deverá limpar esse erro. Normalmente não terá de alterar esta selecção. Lembre-se que o Símbolo Decimal deverá ser configurado para corresponder ao seu ficheiro e não às suas definições regionais. Se a sua configuração regional tiver um valor diferente, a conversão deverá ser testada então. A apresentação do ficheiro na parte superior da janela irá mostrar os campos numéricos realçados a verde, caso a configuração actual produza resultados válidos, caso contrário aparecerão a vermelho. O realce também reflecte as definições da Linha inicial e Linha final. Poderão ocorrer avisos, caso alguma das células seleccionadas não pareça conter o símbolo seleccionado.

### Símbolo de Milhares

Este não tem de ficar seleccionado, dado que é configurado automaticamente com base no Símbolo Decimal. É fornecido apenas como uma guia. Para além disso, o selector ficará inactivo, caso nenhum dos valores a importar seja maior ou igual a 1000.

### Importar o CSV

Se carregar neste botão, irá indicar ao 'plugin' para importar de facto os dados a partir do ficheiro, baseando-se nas opções que tiver efectuado acima. O &kappname; pedir-lhe-á a conta correcta para onde importar os dados.

### Criar um Ficheiro QIF

Este botão dá-lhe a capacidade, após terminar a importação, de gravar os dados do ficheiro CSV como um ficheiro QIF, caso precise por alguma razão. Aliás, esta era a funcionalidade original que levou à criação deste 'plugin'. Contudo, como o &kappname; propriamente dito agora é capaz de exportar um ficheiro QIF, a capacidade em si agora é pouco útil e provavelmente virá a ser removida.

### Finalizar

Para uma importação de Banca, o 'plugin' terminou e o &kappname; perguntar-lhe-á, como referido acima, a conta correcta para onde importar os dados. Para uma importação de Investimento, contudo, ainda será necessária mais alguma informação. Se, durante a importação de uma transacção, o 'plugin' não achar nenhum tipo de transacção válido, irá mostrar a transacção afectada e o utilizador poderá seleccionar um tipo válido de substituição, dependendo da combinação dos valores da quantidade, preço e montante. Para cada transacção, o 'plugin' irá validar o conteúdo das colunas para garantir que correspondem ao tipo de acção. Por exemplo, se aparecer uma quantidade mas não o seu preço ou montante, assume-se que a transacção só poderá ser para Adicionar ou Remover Acções. Por outro lado, se existir um montante mas não uma quantidade ou preço, então assumir-se-á um Dividendo, etc..

Se desejar gravar a sua configuração, lembre-se de carregar no botão Terminar, para que o 'plugin' termine então.

### Adicionar Tipos de Actividades de Investimento

Se descobrir que os seus extractos de investimentos continuam a incluir tipos de actividades que não sejam reconhecidos, basta adicioná-los à secção no ficheiro de recursos (veja em baixo mais detalhes sobre este ficheiro). Por exemplo, na secção [InvestmentSettings] do ficheiro, o campo 'BuyParam' inclui os itens para Purchase, Buy, New Inv e Switch In. Se encontrar um diferente, adicione-o à lista correcta e reinicie o 'plugin'. Irá reparar que existem semelhanças nos itens em campos diferentes, podendo chegar à conclusão que está a ser seleccionado o tipo de de actividade errado. O 'plugin' verifica essas listas pela seguinte ordem: Shrsin, DivX, Reinvdiv, Brokerage, Buy, Sell, Remove. A reordenação das listas para se adequar a isto não funciona como seria de esperar, dado que os itens no ficheiro de recursos ficam ordenados alfabeticamente. Se o parâmetro em causa é um que não necessita, basta apagá-lo do ficheiro. Se isso não for possível, poderá ter de editar o seu ficheiro antes da introdução.

### Configuração do 'plugin' de importação de CSV

Uma desvantagem bastante conhecida do formato QIF é que é um formato relativamente permissivo. Com os ficheiros CSV, existe o mesmo problema mas ainda em maior escala, dado que não existe qualquer norma absoluta de facto. Com os ficheiros de investimentos, em particular, existe muito mais espaço para variações na definição dos diferentes tipos de actividades representadas nos dados. O 'plugin' lida com isso, apresentando esses tipos de actividades num ficheiro de recursos chamado 'csvimporterrc'. A localização desse ficheiro depende da sua distribuição. Normalmente estará localizado em '~/.kde4/share/config/' ou em '~/.kde/'... . Ao usar esse ficheiro de recursos, permitirá ao utilizador adicionar um tipo de actividade que o programador ainda não encontrou. Se o ficheiro não existir quando o importador for executado pela primeira vez, o 'plugin' irá criar uma versão predefinida, contendo algumas das descrições mais óbvias.

É fornecido um conjunto de ficheiros CSV de exemplo (na pasta 'kmymoney/contrib/csvimporter/' da estrutura do código-fonte), na esperança de que possam ajudar. Por exemplo, no exemplo de investimentos, um tipo de actividade é o ReInvestorContract Buy : ReInvested Units". No processo de validação, a primeira ocorrência bem sucedida é a de 'ReInv' no 'ReInvestorContract Buy', pelo que a transacção ficará então classificada como 'Reinvdiv' (reinvestimento de dividendos), mesmo que o 'Buy' (compra) também apareça mencionado. Outro exemplo que foi também observado é o tipo de actividade 'Reinvest', mesmo que a transacção não incluísse o preço ou o montante, mas apenas uma quantidade - neste último caso, teria de ser tratado como 'Adicionar Acções' ou 'Shrsin'.

Quando este 'plugin' foi criado, somente alguns exemplos de formatos de investimento é que estavam definidos, pelo que é fácil que encontre algum que não consiga ser tratado correctamente. Se encontrar um desses ficheiros, envie por favor um exemplo adequado (editado para remover ou substituir dados pessoais) para a lista de correio dos utilizadores do &kappname; em &userlist; ou para a lista dos programadores em &devlist;, pelo que a equipa irá tentar o seu melhor para modificar o 'plugin' de forma a conseguir lidar com ele.