{
"title": "Como importar tickets em massa usando a API do Zendesk",
"slug": "zendesk-api-bulk-import-tickets",
"locale": "pt",
"date": "2026-03-02",
"updated": "2026-03-02",
"template": "default",
"excerpt": "Um guia prático para importar tickets em massa usando a API de Importação de Tickets do Zendesk, com exemplos de código funcionais e dicas do mundo real de projetos de migração.",
"categories": [
"Zendesk",
"Guides"
],
"tags": [
"Zendesk",
"API",
"Ticket Import",
"Data Migration",
"Customer Support"
],
"readTime": 9,
"author": 16,
"reviewer": 14,
"seo": {
"title": "Como importar tickets em massa usando a API do Zendesk",
"description": "Um guia prático para importar tickets em massa usando a API de Importação de Tickets do Zendesk, com exemplos de código funcionais e dicas do mundo real de projetos de migração.",
"image": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-999beaa9-181f-4e09-bc7c-36af8cde5ed8"
},
"coverImage": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-999beaa9-181f-4e09-bc7c-36af8cde5ed8",
"coverImageAlt": "Imagem do banner para Como importar tickets em massa usando a API do Zendesk",
"coverImageWidth": 1920,
"coverImageHeight": 1080,
"faqs": {
"heading": "Perguntas Frequentes",
"type": "blog",
"answerType": "html",
"faqs": [
{
"question": "Posso usar o endpoint de importação em massa de tickets da API do Zendesk para atualizar tickets existentes?",
"answer": "Não, a API de Importação de Tickets é especificamente para criar novos tickets. Para atualizar tickets existentes, use os endpoints de atualização da API de Tickets padrão."
},
{
"question": "Como lidar com os limites de taxa ao usar o recurso de importação em massa de tickets da API do Zendesk?",
"answer": "O Zendesk permite 700 solicitações por minuto para a maioria dos planos. Processe os tickets em lotes de 100, implemente o backoff exponencial quando atingir erros 429 e considere executar grandes importações durante horários de menor movimento."
},
{
"question": "O que acontece com as regras de negócios quando uso o endpoint de importação em massa de tickets da API do Zendesk?",
"answer": "Gatilhos e automações não são executados em tickets importados. No entanto, eles voltarão a funcionar se o ticket for atualizado após a importação. Isso é por design para evitar o envio de spam aos usuários com notificações durante a migração."
},
{
"question": "Posso importar tickets com o endpoint de importação em massa de tickets da API do Zendesk se o solicitante não trabalhar mais na minha empresa?",
"answer": "O solicitante deve ser um usuário ativo (não suspenso) no Zendesk. Você tem duas opções: reativar temporariamente a conta do ex-funcionário ou mapear seus tickets para uma conta de espaço reservado como 'Ex-Funcionário' antes da importação."
},
{
"question": "O endpoint de importação em massa de tickets da API do Zendesk preserva os IDs de ticket do meu sistema antigo?",
"answer": "Não, o Zendesk atribui novos IDs de ticket durante a importação. Se você precisar manter referências aos IDs de ticket antigos (por exemplo, links do seu rastreador de problemas), armazene uma tabela de mapeamento externamente que conecte os IDs antigos aos novos IDs do Zendesk."
},
{
"question": "Qual é a diferença entre a API de Tickets padrão e a API de Importação de Tickets?",
"answer": "A API padrão cria novos tickets com carimbos de data/hora atuais e aciona regras de negócios. A API de Importação preserva os carimbos de data/hora históricos, ignora os gatilhos, oferece suporte ao status fechado/arquivado e foi projetada especificamente para cenários de migração de dados."
}
],
"supportLink": null
}
}
---
Migrar dados de tickets para o Zendesk é um desafio comum para equipes que trocam de plataformas, consolidam instâncias ou importam registros históricos. Embora o Zendesk ofereça vários métodos de importação, a API de Importação de Tickets é a única opção que preserva os carimbos de data/hora históricos e lida adequadamente com grandes conjuntos de dados.
Este guia orienta você durante todo o processo de importação em massa de tickets usando a API do Zendesk. Você aprenderá como estruturar seus dados, lidar com casos extremos e evitar as armadilhas que podem transformar um projeto de fim de semana em uma dor de cabeça de várias semanas.
## O que você vai precisar
Antes de começar, certifique-se de ter o seguinte em vigor:
- **Acesso de administrador do Zendesk** apenas administradores podem usar a API de importação
- **Token da API** a autenticação por senha sozinha não funcionará; você precisa de um token de API adequado nas configurações de administrador do Zendesk
- **Usuários existentes** os solicitantes já devem existir no Zendesk antes de você importar seus tickets
- **Conhecimento de JSON** você estará trabalhando com solicitações da API REST e payloads JSON
- **Ambiente de script** Python ou Node.js facilitarão muito o processamento em lote
Se você está procurando uma maneira mais simples de lidar com fluxos de trabalho de suporte sem migrações complexas, soluções modernas de IA como [eesel AI](https://www.eesel.ai/product/ai-agent) podem se integrar diretamente à sua configuração existente.
## Entendendo o endpoint de importação em massa de tickets da API do Zendesk
A API de Importação de Tickets difere da API de Tickets padrão em vários aspectos importantes. Aqui está o que você precisa saber.
### Principais diferenças do endpoint
O endpoint de importação é `POST /api/v2/imports/tickets` (ou `/api/v2/imports/tickets/create_many` para lotes de até 100 tickets). Ao contrário da API de criação de tickets padrão, o endpoint de importação:
- Preserva os carimbos de data/hora históricos, incluindo `created_at` (criado em), `updated_at` (atualizado em) e `solved_at` (resolvido em)
- Suporta o parâmetro `archive_immediately` (arquivar imediatamente) para tickets fechados
- Não aciona regras de negócios ou automações na importação
- Não envia notificações para usuários em cópia (CC)
- Permite definir carimbos de data/hora de comentários personalizados
Fonte: [Documentação da API de Importação de Tickets do Zendesk](https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_import/)
### Limites de taxa e tamanhos de lote
O Zendesk permite até 100 tickets por solicitação de importação em massa. Para conjuntos de dados maiores, você precisará implementar a lógica de lote em seu script. Os limites de taxa da API padrão se aplicam (700 solicitações por minuto para a maioria dos planos), portanto, planeje sua migração de acordo.
### Requisitos de autenticação
Todas as solicitações de importação exigem autenticação básica usando seu endereço de e-mail combinado com um token de API (não sua senha). O formato é `{email_address}/token:{api_token}` codificado em Base64.
## Passo 1: Prepare seus dados
A preparação dos dados é onde a maioria das migrações tem sucesso ou falha. Dedique um tempo para fazer isso corretamente.
### Campos obrigatórios e opcionais
No mínimo, cada ticket precisa de um `requester_id` (ID do solicitante) e um `subject` (assunto). Aqui está um exemplo completo:
```json
{
"ticket": {
"requester_id": 827,
"subject": "Ajuda com o acesso à conta",
"description": "Descrição inicial do ticket",
"assignee_id": 19,
"tags": ["migration", "account-issue"],
"created_at": "2023-06-25T10:15:18Z",
"comments": [
{
"author_id": 827,
"created_at": "2023-06-25T10:15:18Z",
"value": "Não consigo fazer login na minha conta"
}
]
}
}
Pré-requisitos do usuário
O solicitante e todos os autores de comentários já devem existir no Zendesk como usuários ativos. A API rejeitará tickets com solicitantes suspensos ou inexistentes. Importe seus usuários primeiro usando a importação em massa de CSV (até 2.000 linhas) ou a API de Usuários.
Lidando com anexos
Os anexos exigem um processo de duas etapas:
- Envie arquivos para o Zendesk usando o endpoint de anexos para obter tokens de upload
- Inclua esses tokens em seu payload de importação de tickets
Para imagens embutidas (capturas de tela em comentários), observe que a documentação da API não cobre totalmente isso. Migrações do mundo real revelam que anexos embutidos têm um tratamento diferente dos anexos padrão.
Passo 2: Estruture sua solicitação de API
Com seus dados preparados, você pode começar a construir as solicitações de API reais.
Estrutura básica da solicitação
Aqui está um exemplo em Python mostrando como estruturar uma solicitação de importação básica:
import requests
import base64
email = 'seu-email@example.com'
api_token = 'seu_token_api_aqui'
auth_string = base64.b64encode(f"{email}/token:{api_token}".encode()).decode()
headers = {
'Content-Type': 'application/json',
'Authorization': f'Basic {auth_string}'
}
ticket_data = {
"ticket": {
"requester_id": 827,
"subject": "Ajuda",
"description": "Uma descrição",
"created_at": "2023-06-25T10:15:18Z",
"comments": [
{
"author_id": 827,
"created_at": "2023-06-25T10:15:18Z",
"value": "Este é um comentário"
}
]
}
}
response = requests.post(
'https://seu-subdomínio.zendesk.com/api/v2/imports/tickets',
headers=headers,
json=ticket_data
)
Incluindo comentários históricos
O array de comentários suporta várias entradas com carimbos de data/hora individuais. Isso é crucial para preservar o histórico completo de conversas do seu sistema de origem.
Campos e tags personalizados
Mapeie os campos personalizados do seu sistema de origem para os campos personalizados do Zendesk usando o array custom_fields com pares id e value. As tags podem ser passadas como um simples array de strings.
Passo 3: Lide com casos especiais
Migrações do mundo real sempre envolvem casos extremos. Veja como lidar com os mais comuns.
Importando tickets fechados
Para tickets com status fechado, use o parâmetro de consulta archive_immediately:
POST /api/v2/imports/tickets?archive_immediately=true
Isso ignora o ciclo de vida normal do ticket e cria tickets diretamente em seu arquivo. O Zendesk recomenda esta abordagem ao importar 750.000 ou mais tickets históricos para evitar o impacto no desempenho de sua fila de tickets ativos.
Gerenciando grandes conjuntos de dados
Para grandes migrações, implemente estas práticas:
- Processe os tickets em lotes de 100 (o máximo da API)
- Registre os resultados de cada lote para rastreamento de erros
- Crie uma lógica de repetição para solicitações com falha
- Considere executar importações durante horários de menor movimento
Lidando com usuários suspensos
A API exige que os solicitantes sejam usuários ativos. Se seus dados de origem incluem tickets de usuários suspensos ou excluídos, você tem duas opções:
- Reative os usuários antes da importação
- Mapeie os usuários excluídos para uma conta de espaço reservado "ex-funcionário"
Uma equipe de migração descobriu isso da maneira mais difícil: "A API reclamará se os solicitantes e remetentes estiverem suspensos. Tivemos que reativar os ex-funcionários temporariamente durante o processo de importação."
Fonte: Experiência de Migração da Comunidade Zendesk
Corpos de comentários vazios
A API rejeita comentários com corpos vazios, mesmo que a interface do usuário do Zendesk permita isso (como quando alguém envia um anexo por e-mail sem texto). Você precisará adicionar um texto de espaço reservado como "(Nenhum texto de comentário)" para esses casos.
Passo 4: Execute e valide
Com seus dados preparados e casos extremos tratados, é hora de executar a importação.
Enviando solicitações em lotes
Percorra seus dados de ticket em blocos de 100, enviando cada lote para o endpoint de importação em massa. Registre a resposta de cada lote, incluindo quaisquer IDs de ticket que foram criados com sucesso.
Tratamento de erros
Códigos de status HTTP comuns que você encontrará:
- 200 OK Ticket criado com sucesso
- 422 Entidade Não Processável Erro de validação (verifique sua estrutura JSON)
- 429 Muitas Solicitações Limite de taxa atingido; implemente backoff exponencial
- 401 Não Autorizado Problema de autenticação; verifique seu token de API
Estratégias de verificação
Após a importação, verifique o sucesso por:
- Verificar se as contagens de tickets correspondem aos seus dados de origem
- Amostrar tickets para verificar se os carimbos de data/hora e os comentários foram importados corretamente
- Confirmar se os anexos estão acessíveis
- Testar se as tags e os campos personalizados aparecem corretamente
Armadilhas comuns e como evitá-las
Aprender com os erros dos outros pode economizar um tempo significativo. Aqui estão os maiores problemas que as equipes de migração encontram.
Os solicitantes devem estar ativos
Como mencionado, usuários suspensos causam falhas na importação. Reative-os primeiro ou use contas de espaço reservado.
A ordem de importação é importante
Você deve importar nesta sequência:
- Organizações (se estiver usando)
- Usuários
- Tickets
Os tickets fazem referência a usuários e organizações por ID, portanto, esses registros devem existir primeiro.
Métricas e SLAs não serão calculados
As métricas e os SLAs do Zendesk não são calculados para tickets importados. Se você precisar de relatórios sobre dados históricos, considere adicionar uma tag como "importado" para excluir esses tickets das métricas atuais.
Nenhuma reserva de ID de ticket
Você não pode preservar os relacionamentos de ID de ticket do seu sistema de origem. Tickets mesclados e referências cruzadas precisarão ser tratados manualmente ou por meio de tabelas de mapeamento externas.
Conversas paralelas não são suportadas
Se o seu sistema de origem tiver conversas paralelas ou threads colaborativos, eles não poderão ser importados por meio da API. Converta-os em comentários internos ou aceite que esses dados não serão transferidos.
Peculiaridades da análise JSON
Uma equipe de migração que usava o PowerShell encontrou problemas inesperados de análise JSON: "O Zendesk reclamou que não consegue analisar o JSON. O JSON que gerei estava sintaticamente correto, mas entreguei o objeto do PowerShell diretamente. Salvar o JSON em um arquivo primeiro e, em seguida, alimentá-lo ao Zendesk funcionou sem problemas."
Fonte: Experiência de Migração da Comunidade Zendesk
Abordagens alternativas: eesel AI e outras opções
Às vezes, a API não é a escolha certa. Considere estas alternativas.
Quando usar a importação de CSV em vez disso
A importação em massa de CSV do Zendesk funciona para usuários e organizações (não tickets) e lida com até 2.000 linhas por arquivo. É mais simples do que a API, mas tem limitações significativas: sem importação de fuso horário, sem fotos, sem preferências de idioma e sem suporte a tickets.
Serviços de migração de terceiros
Para migrações complexas, serviços profissionais como zendesk-import.com ou o Aplicativo de Importação Zenplates podem lidar com a complexidade técnica. Esses serviços normalmente cobram com base no volume de dados, mas economizam um tempo de desenvolvimento significativo.
Alternativas modernas alimentadas por IA
Se você está migrando porque seu help desk atual não está atendendo às suas necessidades, considere se uma solução moderna de IA pode ser uma opção melhor do que uma migração de plataforma tradicional. eesel AI se integra ao Zendesk para adicionar tratamento de tickets alimentado por IA, respostas automatizadas e roteamento inteligente sem exigir uma troca completa de plataforma.
Comece a construir melhores fluxos de trabalho de suporte
A importação em massa de tickets por meio da API do Zendesk oferece controle preciso sobre a migração de dados históricos, mas exige planejamento cuidadoso e atenção aos casos extremos. As etapas principais são simples: prepare seus dados completamente, lide com usuários suspensos, processe em lotes e verifique tudo depois.
Se você está considerando uma migração porque suas ferramentas de suporte atuais não estão acompanhando suas necessidades, explore como a integração do eesel AI com o Zendesk pode aprimorar sua configuração existente com recursos alimentados por IA. Ou, se você está avaliando abordagens totalmente novas para o suporte ao cliente, confira os preços do eesel AI para ver como as soluções modernas de IA se comparam às migrações de plataforma tradicionais.
Compartilhe esta postagem
Article by
