--- title: Como preparar o arquivo CSV para importação de participantes description: "## 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…" url: "https://help.globalpromocoes.com/docs/plataforma/como-preparar-o-arquivo-csv-para-importacao-de-participantes/" updated: "2026-06-03" category: Plataforma tags: - administração - cadastro --- # Como preparar o arquivo CSV para importação de participantes ## 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: | Participante | Transação | Como deve aparecer no CSV | | --- | --- | --- | | Maria fez 1 compra | 1 participação | 1 linha | | João fez 3 compras | 3 participações | 3 linhas | | Empresa fez 2 aplicações | 2 participações | 2 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: | Item | Regra | | --- | --- | | Formato do arquivo | `.csv` | | Separador de colunas | Ponto e vírgula `;` | | Separador de texto | Aspas duplas `"` | | Separador decimal | Ponto `.` | | Separador de milhar | Não utilizar | | Cabeçalho | Obrigatório | | Ordem das colunas | Deve seguir o modelo oficial | | Campos obrigatórios | Devem estar preenchidos | | Datas | Devem 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: | Campo | Para que serve | | --- | --- | | `data_evento` | Informa a data da participação, compra, aplicação ou evento | | `cpf_cnpj` | Identifica o participante | | `nome_razao_social` | Identifica o nome ou razão social do usuário | | `produto` | Identifica o produto ou categoria usada na regra da promoção | | `Id unico cliente` | Identifica a transação de forma única | | `Valor` | Define 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 documento | Quantidade de dígitos | | --- | --- | | CPF | 11 dígitos | | CNPJ | 14 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: ``` cliente@email.com ``` 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: | Produto | Regra hipotética | | --- | --- | | PRODUTO_A | Gera 1 Número da Sorte | | PRODUTO_B | Gera 2 Números da Sorte | | PRODUTO_C | Gera 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 ``` NF123456NF123457NF123458 ``` ### Exemplo incorreto ``` NF123456NF123456NF123456 ``` --- ## 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 informado | Regra da promoção | Resultado | | --- | --- | --- | | 100.00 | 1 número a cada R$ 100,00 | 1 Número da Sorte | | 250.00 | 1 número a cada R$ 100,00 | 2 Números da Sorte | | 500.00 | 1 número a cada R$ 100,00 | 5 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;maria@email.com;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;joao@email.com;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_evento | cpf_cnpj | nome_razao_social | produto | Id unico cliente | Valor | | --- | --- | --- | --- | --- | --- | | 2025-03-17 | 12345678901 | Maria Silva | PRODUTO_A | NF123456 | 250.00 | | 2025-03-18 | 12345678901 | Maria Silva | PRODUTO_A | NF123457 | 100.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: ``` NF123456NF123456 ``` Correto: ``` NF123456NF123457 ``` --- ## 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.