Integração CSV

O que é a integração CSV

A integração CSV serve para usar arquivos no formato .CSV como fonte de banco de dados. Facilita o uso e mapeamento de campos dentro do sistema sem precisar ter um banco de dados ou uma API complexa no primeiro momento, facilitando testes e criação de bancos de dados simples.

Requisitos

Toda integração CSV deve estar vinculada a uma Conexão previamente configurada do tipo CSV.

Listagem de integrações CSV

[TELA: Listagem de Integrações da Conexão CSV] 1. Navegação: Acessada ao clicar em uma Conexão do tipo CSV na listagem geral. 2. Topologia: A tabela lista os uploads específicos (as integrações) vinculados àquela conexão. 3. Ações: Adicionar nova planilha, Editar e Duplicar integrações.

Para acessar suas integrações:

Navegue até Conexões no menu lateral
Selecione uma conexão existente do tipo CSV
Visualize todas as integrações vinculadas àquela conexão

Nesta tela você pode:

➕ Adicionar novas integrações
✏️ Editar integrações existentes
📋 Duplicar integrações
🔴 Inativar integrações

Adicionar uma nova integração CSV

Campos marcados com * são obrigatórios.

ETAPA 1: Configuração Geral

[FLUXO: Adicionar Integração CSV - Configuração Geral] 1. Topologia: O modal exige 'Nome da integração *', 'Separador *' (Vírgula ou Ponto e vírgula) e 'Situação *'. 2. Regra de Upload: É nesta tela que o arquivo físico é anexado. A zona de upload é restrita ao formato .csv com limite máximo de 20MB por arquivo e codificação UTF-8. 3. Conclusão: O usuário clica em 'Avançar'.

Nome da Integração*

Descrição: Nome amigável e único para identificar esta integração.

Exemplos: CPF Blocklist, Endereço das CIAS.

Separador*

Descrição: Selecionar o tipo de separador do arquivo .CSV, indicando o formato do arquivo anexado.

Tipos:

Ponto e Vírgula (;): Utilizado em arquivos CSV de origem europeia ou quando exportado do Excel
Vírgula (,): Padrão internacional, mais comum em sistemas norte-americanos

Situação*

Descrição: Indica se a integração está ativa ou inativa para uso.

Tipos:

Ativo: a integração poderá ser utilizada nas execuções, opção preenchida por padrão como ativa.
Inativo: a integração ficará salva, mas não será utilizada. O campo fica bloqueado caso a conexão pai esteja inativa no momento do cadastro.

Alerta*

Descrição: Define se o sistema deve emitir notificações em caso de falha ou indisponibilidade.

Tipos:

Sim: o usuário recebe uma notificação no e-mail informando.
Não: não será notificado sobre indisponibilidades.

Descrição

Descrição: Campo opcional para adicionar informações relacionadas à integração que está sendo cadastrada.

Arquivo Integração*

Descrição: Arquivo no formato .CSV que será usado como fonte de dados da integração.

Especificações:

Formato aceito: .CSV (Comma-Separated Values)
Tamanho máximo: 20MB
Codificação recomendada: UTF-8
Estrutura: Primeira linha deve conter os cabeçalhos (nomes das colunas)

Avançar - Clique em Avançar para seguir para etapa 2.

ETAPA 2: Mapeamento dos Campos

[FLUXO: Integração CSV - Mapeamento de Campos] 1. Topologia: A tela relaciona os 'Campos de Origem' (colunas lidas do arquivo) aos 'Campos de Destino' (variáveis do sistema). 2. Regra de Bloqueio: A integração não suporta estruturas aninhadas, bloqueando o mapeamento com campos de Array ou Objeto. 3. Conclusão: O usuário vincula as variáveis e clica em 'Cadastrar'.

Aqui será necessário fazer o mapeamento dos campos do arquivo .CSV com os campos existentes no sistema.

Como funciona

Campos de origem

Os campos encontrados dentro do arquivo CSV, usando o padrão de colunas sendo cada campo. Estes são extraídos automaticamente da primeira linha (cabeçalho) do arquivo CSV anexado.

Campos de destino

Campos do sistema previamente cadastrados que vão representar o valor que será passado a ele pelo arquivo .CSV durante a execução da política.

Tabela de mapeamento

A tabela possui 2 colunas para configurar o mapeamento:

Campo de origem	Campo de destino
Nome da coluna no arquivo CSV	Campo do sistema que receberá o valor

Campo de origem:

Automaticamente listado com base nos cabeçalhos do arquivo CSV anexado
Representa cada coluna do seu arquivo
Exemplo: se o CSV tem colunas “Nome”, “CPF”, “Email”, esses serão os campos de origem

Campo de destino:

Selecione qual campo do sistema receberá e armazenará este valor
Deve ser um campo previamente cadastrado no sistema
O valor da coluna CSV será gravado neste campo durante a execução

Exemplo de mapeamento:

Se o arquivo CSV contém:

Nome;CPF;Email;Telefone
João Silva;12345678900;joao@email.com;11999999999
Maria Santos;98765432100;maria@email.com;11888888888

Mapeamento possível:

Campo de origem	Campo de destino
Nome	`cliente.nome_completo`
CPF	`cliente.cpf`
Email	`cliente.email`
Telefone	`cliente.telefone`

Cadastrar

Após concluir o mapeamento dos campos, clique em Cadastrar para salvar a integração.

Duplicar Integração

Editar Integração

Após configurar suas integrações, você pode precisar atualizar informações. O processo de edição é simples e direto.

Como editar uma integração

[FLUXO: Editar Integração CSV] 1. Ação: Clique no ícone de lápis na listagem. 2. Regra Crítica: Alterar nome ou situação não afeta o mapeamento, mas alterar (substituir) o arquivo CSV faz com que todo o mapeamento atual seja descartado e precise ser refeito. 3. Conclusão: Salva as modificações.

Acesse a tela de Conexões
Localize na lista a conexão do tipo CSV desejada
Dentro da conexão, selecione a integração que deseja editar
Clique no ícone de edição (formato de lápis)
Faça as alterações necessárias
Salve as modificações

Atenção ao editar

Tipo de Alteração	Impacto no Mapeamento
Alterar arquivo CSV	⚠️ Todo o mapeamento será descartado e precisará ser refeito
Alterar nome ou descrição	✅ Não afeta mapeamento
Alterar situação ou alerta	✅ Não afeta mapeamento

Em caso de dúvida sobre o preenchimento: Consulte o tópico de Adicionar Integração nesta documentação. Os campos e suas regras de preenchimento são os mesmos quando adiciona uma nova integração.

Limitações conhecidas

Exemplos Práticos

Exemplo 1: Lista de bloqueio de CPFs

Cenário: Criar uma integração para verificar se um CPF está em uma lista de bloqueio.

Arquivo CSV (cpf_blocklist.csv):

CPF;Motivo;Data_Bloqueio
12345678900;Fraude confirmada;15/01/2024
98765432100;Documentação irregular;22/03/2024
45678912300;Suspeita de fraude;10/05/2024

Configuração:

Nome: CPF Blocklist
Separador: Ponto e Vírgula
Situação: Ativo

Mapeamento:

Campo de origem	Campo de destino
CPF	`cpf`
Motivo	`motivo_bloqueio`
Data_Bloqueio	`data`

Exemplo 2: Base de endereços das agências

Cenário: Importar lista de endereços das agências para uso em políticas.

Arquivo CSV (enderecos_agencias.csv):

Codigo_Agencia,Nome,Rua,Numero,Bairro,Cidade,UF,CEP
001,Agência Centro,Rua das Flores,100,Centro,São Paulo,SP,01000-000
002,Agência Paulista,Av Paulista,1500,Bela Vista,São Paulo,SP,01310-100
003,Agência Pinheiros,Rua dos Pinheiros,800,Pinheiros,São Paulo,SP,05422-001

Configuração:

Nome: Endereço das Agências
Separador: Vírgula
Situação: Ativo

Mapeamento:

Campo de origem	Campo de destino
Codigo_Agencia	`codigo`
Nome	`nome`
Rua	`rua`
Numero	`numero`
Bairro	`bairro`
Cidade	`cidade`
UF	`uf`
CEP	`cep`

Exemplo 3: Lista de produtos e preços

Cenário: Manter lista de produtos com preços atualizados.

Arquivo CSV (produtos.csv):

SKU;Nome_Produto;Categoria;Preco;Estoque
PROD001;Mouse Wireless;Informática;89.90;150
PROD002;Teclado Mecânico;Informática;299.90;75
PROD003;Monitor 24";Informática;899.90;30
PROD004;Webcam HD;Informática;199.90;100

Configuração:

Nome: Catálogo de Produtos
Separador: Ponto e Vírgula
Situação: Ativo

Mapeamento:

Campo de origem	Campo de destino
SKU	`codigo_sku`
Nome_Produto	`nome`
Categoria	`categoria`
Preco	`preco_unitario`
Estoque	`quantidade_estoque`