Ver categorias

Como preparar o arquivo CSV para importação de participantes

11 minutos de leitura

Tabela de conteúdos (TOC)

Visão geral #

A importação por arquivo CSV permite cadastrar participantes e registrar as informações que serão usadas para gerar Números da Sorte dentro de uma promoção.

Esse arquivo deve seguir um modelo específico para que a plataforma consiga ler os dados corretamente.

Cada linha do CSV representa uma participação, compra, aplicação, transação ou evento que pode gerar Números da Sorte.

Importante:
O arquivo CSV não é apenas uma lista de pessoas.
Ele é uma lista de registros de participação.
Por isso, uma mesma pessoa pode aparecer mais de uma vez no arquivo, desde que cada linha represente uma transação diferente.

Quando usar este arquivo #

Use o arquivo CSV quando for necessário:

  • importar participantes em lote;
  • registrar compras, aplicações ou eventos que geram participação;
  • gerar Números da Sorte a partir de uma base externa;
  • enviar uma lista de transações para processamento na promoção;
  • atualizar a plataforma com registros vindos de outro sistema.

Antes de começar #

Antes de montar o arquivo, confirme se:

  1. Você tem permissão para importar dados na promoção.
  2. A promoção já está configurada na plataforma.
  3. As regras de geração de Números da Sorte já foram definidas.
  4. Você sabe se o campo Valor será usado como:
    • valor financeiro da compra/aplicação; ou
    • quantidade direta de Números da Sorte.
  5. O arquivo será salvo no formato CSV.
  6. O arquivo terá o cabeçalho com o nome das colunas.

Atenção:
Para conseguir importar arquivos, o usuário precisa estar configurado como responsável pela promoção. Essa configuração é realizada pela Santini.Global. Caso seja necessário alterar ou adicionar responsáveis, solicite o ajuste ao nosso time.

Entendendo o arquivo CSV #

CSV é um tipo de arquivo usado para organizar dados em formato de tabela.

Na prática, ele funciona como uma planilha, mas com uma estrutura simples de texto.

No modelo de importação da Global.Promoções:

  • cada coluna representa uma informação;
  • cada linha representa um registro de participação;
  • as colunas devem ser separadas por ponto e vírgula ;;
  • a primeira linha deve conter o nome das colunas.

Regra principal: cada linha é uma transação #

Cada linha do arquivo deve representar uma transação única.

Exemplo:

ParticipanteTransaçãoComo deve aparecer no CSV
Maria fez 1 compra1 participação1 linha
João fez 3 compras3 participações3 linhas
Empresa fez 2 aplicações2 participações2 linhas

Isso significa que o mesmo CPF ou CNPJ pode aparecer em mais de uma linha.

O que não pode repetir é o campo Id unico cliente, pois ele identifica cada transação de forma única.

Regras obrigatórias do CSV #

O arquivo deve seguir estas regras:

ItemRegra
Formato do arquivo.csv
Separador de colunasPonto e vírgula ;
Separador de textoAspas duplas "
Separador decimalPonto .
Separador de milharNão utilizar
CabeçalhoObrigatório
Ordem das colunasDeve seguir o modelo oficial
Campos obrigatóriosDevem estar preenchidos
DatasDevem seguir o formato indicado

Exemplo de separador correto #

Correto:

data_evento;cpf_cnpj;produto;Id unico cliente;Valor

Incorreto:

data_evento,cpf_cnpj,produto,Id unico cliente,Valor

Atenção:
O separador correto é ponto e vírgula.
Arquivos separados por vírgula podem não ser lidos corretamente pela plataforma.

Campos obrigatórios #

No modelo oficial, os campos obrigatórios são:

CampoPara que serve
data_eventoInforma a data da participação, compra, aplicação ou evento
cpf_cnpjIdentifica o participante
nome_razao_socialIdentifica o nome ou razão social do usuário
produtoIdentifica o produto ou categoria usada na regra da promoção
Id unico clienteIdentifica a transação de forma única
ValorDefine o valor ou a quantidade usada para gerar Números da Sorte

Esses campos precisam estar preenchidos em todas as linhas do arquivo.

Campos do arquivo CSV #

Abaixo está a explicação de cada campo do layout.

0. data_evento #

Campo obrigatório.

Indica a data relacionada à participação.

Pode ser:

  • data da compra;
  • data da aplicação;
  • data do cadastro;
  • data do evento;
  • data da transação.

Formato esperado:

yyyy-mm-dd

Também pode conter horário:

yyyy-mm-dd hh:mm:ss

Exemplo:

2025-03-17 11:09:04

Ou:

2025-03-17

Cuidados com este campo #

Use sempre o formato com ano, mês e dia.

Correto:

2025-03-17

Incorreto:

17/03/2025

1. cpf_cnpj #

Campo obrigatório.

Informa o CPF ou CNPJ do participante.

Deve conter somente números.

Tipo de documentoQuantidade de dígitos
CPF11 dígitos
CNPJ14 dígitos

Exemplo de CPF correto:

12345678901

Exemplo de CNPJ correto:

12345678000199

O que não usar #

Não use pontos, traços ou barras.

Incorreto:

123.456.789-01

Incorreto:

12.345.678/0001-99

Correto:

12345678901

2. username #

Campo usado apenas em promoções de Instagram.

Ele deve ser preenchido com o nome de usuário do participante quando a promoção exigir esse dado.

Exemplo:

cliente_exemplo

Para promoções que não sejam de Instagram, deixe o campo em branco.

Exemplo de linha com campo em branco:

2025-03-17;12345678901;;Maria Silva

Observe que existem dois pontos e vírgulas seguidos ;;.
Isso indica que o campo username ficou vazio, mas a estrutura do arquivo foi mantida.

3. nome_razao_social #

Campo obrigatório.

Informa o nome do participante ou a razão social da empresa.

Exemplo para pessoa física:

Maria Silva

Exemplo para pessoa jurídica:

Empresa Exemplo LTDA

Recomendação: preencha esse campo sempre que a informação estiver disponível, pois ele facilita a conferência dos dados.

4. pais #

Informa o país do participante.

Exemplo:

Brasil

5. estado #

Informa o estado do participante.

Pode ser preenchido com a sigla do estado, conforme o padrão usado pela promoção.

Exemplo:

RS

6. cidade #

Informa a cidade do participante.

Exemplo:

Porto Alegre

7. logradouro #

Informa o nome da rua, avenida, travessa ou outro tipo de endereço.

Exemplo:

Rua das Flores

Não inclua o número neste campo.
O número possui uma coluna própria.

8. numero #

Informa o número do endereço.

Exemplo:

120

Caso o endereço não tenha número, utilize o padrão definido para a promoção, como S/N, se aplicável.

9. email #

Informa o e-mail do participante.

Exemplo:

[email protected]

Recomendação: revise se o e-mail possui @ e domínio válido.

10. telefone #

Informa o telefone do participante.

Recomendação: preencher somente com números.

Exemplo:

51999999999

Evite usar:

(51) 99999-9999

Prefira:

51999999999

11. data_nascimento #

Informa a data de nascimento do participante.

Formato esperado:

yyyy-mm-dd

Exemplo:

1990-05-20

Incorreto:

20/05/1990

12. produto #

Campo obrigatório.

Identifica o produto, serviço, operação ou categoria relacionada à participação.

Esse campo é importante porque a promoção pode ter regras diferentes para gerar Números da Sorte conforme o produto informado.

Exemplos:

PRODUTO_A
CARTAO_CREDITO
APLICACAO
COMPRA

Quando a promoção tem mais de um produto #

Se a promoção gera quantidades diferentes de Números da Sorte por produto, o campo produto deve indicar exatamente qual produto está relacionado àquela linha.

Exemplo:

ProdutoRegra hipotética
PRODUTO_AGera 1 Número da Sorte
PRODUTO_BGera 2 Números da Sorte
PRODUTO_CGera 5 Números da Sorte

Nesse caso, preencher o produto errado pode gerar uma quantidade incorreta de Números da Sorte.

13. Id unico cliente #

Campo obrigatório.

É o identificador único da transação no sistema do cliente.

Esse campo serve para evitar que o mesmo registro seja importado mais de uma vez.

Pode ser, por exemplo:

  • número da nota fiscal;
  • número do pedido;
  • número da aplicação;
  • número da transação;
  • combinação de conta + aplicação;
  • outro código único definido pelo cliente.

Exemplos:

NF123456
PEDIDO98765
CONTA123_APLICACAO456

Por que esse campo é tão importante? #

Porque ele ajuda a plataforma a identificar se aquela transação já foi enviada anteriormente.

Se o mesmo Id unico cliente for repetido, a plataforma pode entender que se trata de uma duplicidade.

Exemplo correto #

NF123456
NF123457
NF123458

Exemplo incorreto #

NF123456
NF123456
NF123456

14. Valor #

Campo obrigatório.

Esse campo é usado para calcular ou definir a quantidade de Números da Sorte que será gerada.

Ele pode ter dois comportamentos, conforme a configuração da promoção.

Opção 1: quando o campo representa valor financeiro #

Nesse caso, informe o valor total da compra, aplicação ou transação.

Exemplo:

250.00

A plataforma utilizará esse valor para calcular quantos Números da Sorte devem ser gerados, de acordo com a regra da promoção.

Exemplo hipotético:

Valor informadoRegra da promoçãoResultado
100.001 número a cada R$ 100,001 Número da Sorte
250.001 número a cada R$ 100,002 Números da Sorte
500.001 número a cada R$ 100,005 Números da Sorte

Opção 2: quando o campo representa quantidade direta #

Nesse caso, o campo Valor não representa dinheiro.

Ele representa diretamente quantos Números da Sorte devem ser gerados para aquela transação.

Exemplo:

10

Nesse cenário, a plataforma entende que aquela linha deve gerar 10 Números da Sorte.

Atenção:
Antes de montar o arquivo, confirme qual regra está configurada para a promoção:
se o campo Valor será tratado como valor financeiro ou como quantidade direta de Números da Sorte.

15. AddInfo1 #

Campo de uso livre.

Pode ser usado para informar um dado adicional da participação.

Exemplos de uso:

  • cooperativa;
  • agência;
  • canal de origem;
  • código interno;
  • campanha relacionada;
  • categoria do participante;
  • informação complementar para consulta.

Exemplo:

COOPERATIVA_001

Esse campo também pode ser usado em cenários nos quais a consulta aos Números da Sorte precisa combinar CPF/CNPJ com uma informação adicional.

16. AddInfo2 #

Campo de uso livre, com a mesma lógica do AddInfo1.

Pode ser usado quando for necessário enviar uma segunda informação complementar.

Exemplo:

CANAL_APP

Ou:

AGENCIA_123

Se não houver informação adicional, o campo pode ficar em branco.

Estrutura completa do cabeçalho #

A primeira linha do arquivo deve conter o cabeçalho com os nomes das colunas.

Use esta estrutura:

data_evento;cpf_cnpj;username;nome_razao_social;pais;estado;cidade;logradouro;numero;email;telefone;data_nascimento;produto;Id unico cliente;Valor;AddInfo1;AddInfo2

Atenção:
Não remova colunas do arquivo.
Mesmo que um campo não seja usado, a coluna deve permanecer no CSV para manter a estrutura esperada pela plataforma.

Exemplo completo de arquivo CSV #

data_evento;cpf_cnpj;username;nome_razao_social;pais;estado;cidade;logradouro;numero;email;telefone;data_nascimento;produto;Id unico cliente;Valor;AddInfo1;AddInfo2
2025-03-17 11:09:04;12345678901;;Maria Silva;Brasil;RS;Porto Alegre;Rua das Flores;120;[email protected];51999999999;1990-05-20;PRODUTO_A;NF123456;250.00;COOPERATIVA_001;CANAL_APP
2025-03-18 09:30:00;98765432100;;João Santos;Brasil;SC;Florianópolis;Avenida Central;500;[email protected];48999999999;1985-10-12;PRODUTO_B;NF123457;100.00;COOPERATIVA_002;CANAL_LOJA

Exemplo com campos opcionais em branco #

Alguns campos podem ficar vazios, mas os separadores devem ser mantidos.

Exemplo:

data_evento;cpf_cnpj;username;nome_razao_social;pais;estado;cidade;logradouro;numero;email;telefone;data_nascimento;produto;Id unico cliente;Valor;AddInfo1;AddInfo2
2025-03-17;12345678901;;Maria Silva;;;;;;;51999999999;;PRODUTO_A;NF123456;250.00;;

Observe que os campos vazios continuam existindo, separados por ;.

Isso é importante para que a plataforma saiba qual informação pertence a cada coluna.

Como montar o arquivo em uma planilha #

Você pode montar o arquivo em uma ferramenta de planilhas, como Excel, Google Sheets ou similar.

Passo 1: crie a linha de cabeçalho #

Na primeira linha, informe os nomes das colunas exatamente na ordem do modelo:

data_evento;cpf_cnpj;username;nome_razao_social;pais;estado;cidade;logradouro;numero;email;telefone;data_nascimento;produto;Id unico cliente;Valor;AddInfo1;AddInfo2

Se estiver usando uma planilha, cada campo deve ficar em uma coluna separada.

Passo 2: preencha uma linha por transação #

Cada nova linha deve representar uma participação ou transação.

Exemplo:

data_eventocpf_cnpjnome_razao_socialprodutoId unico clienteValor
2025-03-1712345678901Maria SilvaPRODUTO_ANF123456250.00
2025-03-1812345678901Maria SilvaPRODUTO_ANF123457100.00

Neste exemplo, a mesma participante aparece duas vezes, porque existem duas transações diferentes.

Isso está correto, desde que o Id unico cliente seja diferente em cada linha.

Passo 3: revise os campos obrigatórios #

Antes de salvar o arquivo, confira se todas as linhas possuem:

  • data_evento;
  • cpf_cnpj;
  • nome_razao_social;
  • produto;
  • Id unico cliente;
  • Valor.

Se algum desses campos estiver vazio, a linha pode não ser processada corretamente.

Passo 4: salve o arquivo como CSV #

Depois de preencher a planilha, salve ou exporte o arquivo no formato CSV.

Ao salvar, verifique se o arquivo está separado por ponto e vírgula ;.

Checklist antes de importar #

Antes de importar o arquivo na plataforma, revise:

  • O arquivo está em formato .csv.
  • A primeira linha contém o cabeçalho.
  • As colunas estão na ordem correta.
  • O separador de colunas é ponto e vírgula ;.
  • Os campos obrigatórios estão preenchidos.
  • CPF/CNPJ contém apenas números.
  • CPF possui 11 dígitos.
  • CNPJ possui 14 dígitos.
  • As datas estão no formato yyyy-mm-dd.
  • Valores decimais usam ponto ..
  • Não há separador de milhar.
  • O campo Id unico cliente não está duplicado.
  • O campo produto está preenchido conforme a regra da promoção.
  • O campo Valor está de acordo com a configuração da campanha.
  • Campos vazios mantêm o separador ;.

Erros comuns e como corrigir #

1. Usar vírgula como separador de colunas #

Incorreto:

data_evento,cpf_cnpj,produto,Valor

Correto:

data_evento;cpf_cnpj;produto;Valor

2. Usar CPF ou CNPJ com pontuação #

Incorreto:

123.456.789-01

Correto:

12345678901

3. Usar data no formato brasileiro #

Incorreto:

17/03/2025

Correto:

2025-03-17

4. Usar vírgula em valor decimal #

Incorreto:

1500,75

Correto:

1500.75

5. Usar separador de milhar #

Incorreto:

1.500.00

Correto:

1500.00

6. Repetir o identificador único da transação #

Incorreto:

NF123456
NF123456

Correto:

NF123456
NF123457

7. Apagar colunas que não serão usadas #

Incorreto:

data_evento;cpf_cnpj;produto;Valor

Correto:

data_evento;cpf_cnpj;username;nome_razao_social;pais;estado;cidade;logradouro;numero;email;telefone;data_nascimento;produto;Id unico cliente;Valor;AddInfo1;AddInfo2

Mesmo que algumas informações não sejam preenchidas, as colunas devem permanecer no arquivo.

Boas práticas #

Para reduzir erros na importação:

  • mantenha uma cópia do modelo original;
  • não altere o nome das colunas;
  • não mude a ordem dos campos;
  • revise uma pequena amostra antes de importar arquivos grandes;
  • evite caracteres especiais desnecessários;
  • padronize os valores usados no campo produto;
  • valide se o Id unico cliente é realmente único;
  • confirme a regra de preenchimento do campo Valor;
  • em caso de dúvida, envie uma amostra para validação antes da importação completa.

administração, cadastro
Este artigo foi útil?