> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Importar
> Importar ou atualizar usuários no OneSignal usando uploads de CSV, API REST ou entrada manual. Suporta email, SMS, tags e muito mais para integração ou migração de usuários.
Importe ou atualize usuários em massa pelo painel do OneSignal usando um arquivo CSV ou entrada manual. Casos de uso comuns incluem migração de usuários de outra plataforma, atualização de detalhes de usuários e organização de usuários com [Tags](./add-user-data-tags) e [Segmentos](./segmentation).
Você também pode atualizar ou criar usuários via [REST API](/reference/create-user).
## Importação CSV
Use um arquivo CSV para importar ou atualizar endereços de email, números de telefone, IDs externos, [Tags](./add-user-data-tags), idioma, fuso horário, país e mais.
### Requisitos do CSV
Certifique-se de que seu arquivo `.csv` atende aos seguintes requisitos:
* Codificação UTF-8 (sem BOM)
* Sem caracteres não imprimíveis (sem caracteres especiais ou não-ASCII)
* Cabeçalhos de coluna limpos e únicos
* Tamanho do arquivo menor que 150MB (cerca de 2 milhões de linhas)
* Pelo menos um identificador dos seguintes:
* `external_id` — Recomendado. Identifica [Users](./users) em todas as [Subscriptions](./subscriptions).
* `email` — Obrigatório para criar novas assinaturas de email. Consulte [Validação de endereço de email](./email-address-validation) para mais informações.
* `phone_number` — Obrigatório para criar novas assinaturas de SMS.
* `subscription_id` — Recomendado apenas para casos onde você já rastreia [IDs de Assinatura](./subscriptions) do OneSignal no seu backend.
Apenas um identificador de cada tipo é permitido por linha. Para associar múltiplos emails ou números ao mesmo usuário, use linhas separadas compartilhando o mesmo `external_id`.
* Inclua `external_id` para desduplicar usuários. Certifique-se de que corresponde ao ID usado no método SDK `login` — caso contrário, ele será redefinido quando o usuário abrir o aplicativo.
* Para alterar o status de assinatura, a linha deve incluir `email`, `phone_number` ou `subscription_id`. Apenas `external_id` não é suficiente.
* `subscription_id` não vincula ou mescla Assinaturas. Use `external_id` para adicionar novos emails ou números de telefone a um usuário existente.
### Colunas CSV disponíveis
Veja [external ID](./users#external-id) para mais informações.
Cria uma [subscription](./subscriptions) de Email. Desduplicada se já estiver presente.
Use [formato E.164](https://en.wikipedia.org/wiki/E.164) como `+15555551234`. Cria uma [subscription](./subscriptions) de SMS.
Recomendado apenas se você já rastreia [IDs de Assinatura](./subscriptions) do OneSignal no seu backend.
Define o status de assinatura. Requer `email`, `phone_number` ou `subscription_id` na mesma linha — não pode ser usado apenas com `external_id`.
`false` remove o email das listas de supressão.
Veja [IANA TZ](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
Veja [ISO 3166-2](https://www.iso.org/obp/ui/).
Veja [ISO 639-1](./multi-language-messaging#supported-languages).
Até 1.000 tags. Use cabeçalhos de coluna como chaves. Veja [Tags](./add-user-data-tags).
#### Limites e restrições de tags
Os [limites de plano](https://onesignal.com/pricing) de tags se aplicam por usuário, não por aplicativo. Por exemplo, se seu plano permite 20 tags por usuário e um usuário já tem 19, você só pode adicionar mais 1 — mesmo que o aplicativo possa ter chaves de tag ilimitadas.
* Use o fluxo de trabalho de [Atualizações em massa de tags](#bulk-tag-updates) para exportar usuários, limpar valores de tags indesejados e reimportar com a opção de exclusão habilitada.
* Evite espaços nas chaves de tag — use underscores em vez disso.
**Chaves de tag reservadas e restritas**
As seguintes chaves de tag são reservadas e não devem ser usadas:
* "user"
* "subscription"
* "message"
* "template"
* "app"
* "org"
* "custom\_data"
* "dynamic\_content"
Se você acidentalmente definir uma delas como chave de tag, remova-a via [API de Atualização de Usuário](/reference/update-user).
**Substituições e exclusões de tags**
Durante uma importação de CSV:
* Tags incluídas no seu CSV são substituídas pelo valor fornecido.
* Tags não incluídas no seu CSV permanecem inalteradas no registro do usuário.
Se uma tag ainda estiver presente após a importação, verifique se:
* A coluna de cabeçalho contém a chave da tag.
* A linha não contém nenhum valor.
* Você selecionou a opção "Excluir tags com valores em branco" na [tela de Revisão](#review-and-confirm).
**Outras fontes de tags sendo adicionadas**
Se tags excluídas reaparecerem após a importação, uma integração pode estar automaticamente escrevendo-as de volta. Fontes comuns incluem:
* Segment
* HubSpot
* Journeys
* Métodos de tagging do SDK
* APIs personalizadas ou pipelines ETL
Revise os mapeamentos de integração e gatilhos de eventos para garantir que eles não estejam substituindo suas alterações no CSV.
#### Importar tags de uma única coluna
Em vez de usar cabeçalhos de coluna separados para cada chave de tag, você pode definir um único cabeçalho `tags`, com cada linha de usuário contendo um mapa JSON de todos os pares chave-valor entre aspas. Isso é especialmente útil se você exportou anteriormente um CSV com tags e deseja reimportá-lo sem reformatação.
Exemplo de cabeçalho:
```csv theme={null}
external_id,email,tags
```
Exemplo de linhas:
As tags devem ser formatadas como um objeto JSON entre aspas.
```csv theme={null}
userA,example@email.com,"{""level"":""30"",""Color"":""teal""}"
```
Quando importado, o OneSignal converte automaticamente cada par chave-valor em tags distintas para o registro de assinatura.
**Exemplo: Excluir tags em massa**
Para remover tags em massa, exporte seus dados atuais, apague os valores das tags e reimporte o CSV com a opção de exclusão habilitada.
* Navegue até **Audience > Subscriptions** no painel do OneSignal. Habilite apenas as colunas **External ID**, **Subscription ID** e **Tags** (e opcionalmente **Email** ou **Phone Number**).
* Clique em **Export** para exportar o CSV.
Abra o CSV exportado em um editor de texto e defina os valores de cada tag que deseja excluir como uma string vazia.
Por exemplo, uma linha com valores de tag antes de editar:
```text Linha antes de editar theme={null}
userA,example@email.com,"{""level"":""30"",""color"":""teal""}"
```
A mesma linha após apagar os valores das tags:
```text Linha após apagar os valores das tags theme={null}
userA,example@email.com,"{""level"":"""",""color"":""""}"
```
Isso resultará na exclusão das tags `level` e `color` do usuário.
* Pegue o CSV editado e importe.
* Na tela de [Revisão](#revisar-e-confirmar), selecione **Sim** para **Excluir tags com valores em branco**. O OneSignal exclui as tags com valores em branco durante a importação.
Para remover apenas tags específicas, apague os valores dessas tags e deixe as outras inalteradas. Apenas valores em branco são excluídos quando a opção de exclusão está habilitada.
Precisa de ajuda?
* Experimente a seção [Use IA para verificar seu CSV antes de importar](#use-ai-to-check-your-csv-before-import) acima.
* Entre em contato com `support@onesignal.com` e compartilhe o arquivo CSV que você enviou junto com uma captura de tela do email de confirmação. Teremos prazer em dar uma olhada!
#### Validação de endereço de email
A validação de endereço de email detecta problemas comuns em endereços de email antes que cheguem ao seu público. Ela sinaliza erros de digitação, domínios inválidos, endereços baseados em função e serviços de email descartáveis que podem aumentar sua taxa de rejeição ou prejudicar sua reputação de remetente.
Valide endereços de email durante a importação de CSV e em massa para reduzir rejeições e proteger sua reputação de remetente.
#### Use IA para verificar seu CSV antes de importar
Se você tiver erros ou dúvidas sobre a formatação do seu CSV, pode descrever o problema do CSV para uma ferramenta de IA (como Claude, ChatGPT ou similar) para limpar ou reconstruir automaticamente seu arquivo antes de importar novamente.
Sempre teste com uma amostra pequena (5-10 linhas) antes de importar milhares de registros.
```text Exemplo de prompt de IA para excluir tags indesejadas theme={null}
Quero remover todas as tags, exceto "user_name" deste CSV.
Por favor:
1. Mantenha apenas a coluna de tag "user_name".
2. Remova todas as outras colunas de tags.
3. Formate o CSV para que corresponda aos requisitos de importação do OneSignal neste documento:
https://documentation.onesignal.com/docs/en/import
Aqui está meu CSV:
[COLAR CSV]
```
```text Exemplo de prompt de IA para corrigir formato de várias colunas de tags theme={null}
Tenho várias colunas de tags como tag_first_name, tag_last_name e tag_city.
De acordo com a documentação de importação do OneSignal, cada tag deve:
- Usar o prefixo tag_
- Conter apenas caracteres alfanuméricos e sublinhados
- Seguir tipos de dados suportados
Você poderia revisar meu CSV, identificar o que está formatado incorretamente e retornar uma versão corrigida que atenda a esses requisitos?
Link da documentação:
https://documentation.onesignal.com/docs/en/import
```
```text Exemplo de prompt de IA para identificar formatação ausente ou inválida theme={null}
O OneSignal rejeitou meu CSV durante a importação.
Por favor:
1. Valide minha estrutura CSV.
2. Identifique quaisquer problemas de formatação (cabeçalhos, colunas de ID, formatos de tags, aspas).
3. Retorne uma versão corrigida que siga os requisitos neste documento:
https://documentation.onesignal.com/docs/en/import#prepare-your-csv
Aqui está o arquivo:
[COLAR CSV]
```
```text Exemplo de prompt de IA para corrigir formatos de número de telefone inválidos (E.164) theme={null}
Minha importação está fallhando porque os números de telefone não estão no formato E.164.
Por favor:
1. Converta todos os números de telefone para o formato E.164.
2. Mantenha todos os outros campos inalterados.
3. Certifique-se de que o CSV corresponda à estrutura exigida do OneSignal:
https://documentation.onesignal.com/docs/en/import
Exemplo de formato atual: (555) 555-1234
Aqui está meu CSV:
[COLAR CSV]
```
```text Exemplo de prompt de IA para migrar de outra plataforma theme={null}
Estou migrando de [Nome da Plataforma] para o OneSignal.
Você poderia transformar este CSV para corresponder ao formato de importação do OneSignal?
Inclua:
- `external_id`
- Quaisquer tags convertidas com o prefixo `tag_` (se desejado)
- Números de telefone no formato E.164 (se aplicável)
Documento de referência:
https://documentation.onesignal.com/docs/en/import
Aqui está meu CSV:
[COLAR CSV]
```
### Etapas de importação
Navegue até **Audience > Import** e clique em **Launch CSV Importer**.
Selecione seu arquivo CSV preparado.
O OneSignal mapeia automaticamente os cabeçalhos do CSV para propriedades conhecidas. Revise os mapeamentos antes de confirmar — use `external_id`, `email`, `phone_number` e/ou `subscription_id` como **identificadores**, não como tags.
Para adicionar um novo email ou número de telefone a um usuário existente, você **deve usar** `external_id`. **Não** use `subscription_id` — ele não vinculará ou mesclará assinaturas.
Se o OneSignal detectar problemas de formato, corrija o CSV e reenvie (recomendado) ou desmarque a coluna afetada para ignorá-la.
A tela de revisão permite que você:
* **Criar automaticamente um Segmento** — Adiciona uma tag a cada usuário importado e cria um [Segmento](./segmentation) correspondente. Fique atento aos [limites do seu plano](https://onesignal.com/pricing).
* **Excluir tags com valores em branco** — Remove qualquer tag com valor em branco no CSV. Útil para limpar tags indesejadas e ficar dentro dos limites do plano.
* **Configurar validação de endereço de email** — Configure as configurações de [validação de endereço de email](./email-address-validation) para reduzir rejeições e proteger sua reputação de remetente.
Por exemplo, dado o seguinte CSV:
```csv theme={null}
external_id,tag1,tag2
UserA,,"tag2value"
UserB,"tag1value",
```
Com "Excluir tags com valores em branco" habilitado, `tag1` é excluída de UserA e `tag2` é excluída de UserB.
Clique em **Confirm and Import**. Uma tela de status mostra o progresso.
A importação foi iniciada. Você receberá um email de confirmação de `contact@onesignal.com` quando ela for concluída.
### Confirmação por email
Quando o import terminar, você receberá um email de confirmação de `contact@onesignal.com` com os dados a seguir. Um único [User](./users) pode ter múltiplas [Subscriptions](./subscriptions) (ex: email + push), portanto as contagens de assinatura podem ser maiores que o número de linhas.
**Registro(s) de assinatura adicionado(s)** — Novas [Subscriptions](./subscriptions) de email ou SMS criadas. `0` significa que nenhum identificador único de `email` ou `phone_number` foi encontrado.
**Registro(s) de assinatura modificado(s)** — [Subscriptions](./subscriptions) com dados alterados (tags, propriedades, etc.). Exemplo: 10 External IDs cada um vinculado a 20 assinaturas = `200` registros modificados.
**Atualizações de assinatura ignoradas** — [Subscriptions](./subscriptions) ignoradas pelo motivo indicado. Se o motivo for "acima do limite de tags do seu app", remova tags e reimporte ou faça upgrade do seu plano.
**Não importado** — Linhas que não foram atualizadas ou importadas. Causas comuns: o `external_id` não corresponde a nenhuma assinatura existente, ou o `email`/`phone_number` já existe sem novos dados a definir.
**Novo segmento criado** — O nome do segmento, se você selecionou essa opção.
No exemplo acima:
* `100` assinaturas foram criadas a partir de endereços de email ou números de telefone únicos que não existiam no app.
* `37,814` assinaturas foram atualizadas (não é a contagem de [Users](./users) — cada usuário pode ter múltiplas assinaturas).
* `621,852` linhas não foram importadas porque seus External IDs não correspondiam a usuários existentes, ou emails/números de telefone já existiam sem novos dados.
[Segments](./segmentation) contam apenas [Subscriptions](./subscriptions) **inscritas**. Assinaturas canceladas são atualizadas pelo import, mas não são refletidas nas contagens de segmentos. Melhorias na segmentação estão em andamento.
***
## Entrada manual
Você pode adicionar manualmente as assinaturas de email e número de telefone do usuário através do painel do OneSignal navegando para **Audience > Users > Update/Import Users > Manually Add Users**.
Na tela **New User**, inclua os dados que você deseja e selecione **Create User**.
***
## Perguntas frequentes
### Quanto tempo leva uma importação CSV?
A duração depende do tamanho do arquivo. A maioria das importações é concluída em alguns minutos. Você recebe um email de `contact@onesignal.com` quando a importação termina — adicione esse endereço aos seus contatos para garantir a entrega.
### Posso desfazer uma importação CSV?
Não. Não há desfazer integrado para importações CSV. Se você precisar reverter alterações, prepare um novo CSV com os valores corretos e reimporte-o. Para exclusões de tags, use o fluxo de trabalho de [Excluir tags em massa](#exemplo-excluir-tags-em-massa).
### Por que as contagens do meu segmento não correspondem às linhas do meu CSV?
Os [Segmentos](./segmentation) contam apenas [Assinaturas](./subscriptions) **inscritas**. As assinaturas canceladas são atualizadas pela importação, mas não são refletidas nas contagens de segmentos.
### Por que minha importação mostrou "não importado" para algumas linhas?
As linhas são ignoradas quando o `external_id` não corresponde a nenhuma assinatura existente no aplicativo, ou quando o `email` ou `phone_number` já existe sem novos dados para definir. Verifique a seção de [Confirmação por email](#confirmação-por-email-e-solução-de-problemas) para obter detalhes sobre cada status.
### Por que as tags excluídas continuam voltando?
Uma integração ou chamada de SDK pode estar readicionando as tags após sua importação. Fontes comuns incluem Segment, HubSpot, Journeys, métodos de marcação do SDK e APIs personalizadas. Revise seus [mapeamentos de integração](#outras-fontes-de-tags-sendo-adicionadas) e gatilhos de eventos.