{
"title": "Cómo importar tickets en masa usando la API de Zendesk",
"slug": "zendesk-api-bulk-import-tickets",
"locale": "es",
"date": "2026-03-02",
"updated": "2026-03-02",
"template": "default",
"excerpt": "Una guía práctica para importar tickets en masa utilizando la API de Importación de Tickets de Zendesk, con ejemplos de código funcionales y consejos del mundo real de proyectos de migración.",
"categories": [
"Zendesk",
"Guides"
],
"tags": [
"Zendesk",
"API",
"Ticket Import",
"Data Migration",
"Customer Support"
],
"readTime": 9,
"author": 16,
"reviewer": 14,
"seo": {
"title": "Cómo importar tickets en masa usando la API de Zendesk",
"description": "Una guía práctica para importar tickets en masa utilizando la API de Importación de Tickets de Zendesk, con ejemplos de código funcionales y consejos del mundo real de proyectos de migración.",
"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": "Imagen de banner para Cómo importar tickets en masa usando la API de Zendesk",
"coverImageWidth": 1920,
"coverImageHeight": 1080,
"faqs": {
"heading": "Preguntas Frecuentes",
"type": "blog",
"answerType": "html",
"faqs": [
{
"question": "¿Puedo usar el endpoint de la API de Zendesk para importar tickets en masa para actualizar tickets existentes?",
"answer": "No, la API de Importación de Tickets es específicamente para crear nuevos tickets. Para actualizar tickets existentes, use los endpoints de actualización de la API de Tickets estándar."
},
{
"question": "¿Cómo manejo los límites de velocidad cuando uso la función de importación de tickets en masa de la API de Zendesk?",
"answer": "Zendesk permite 700 solicitudes por minuto para la mayoría de los planes. Procese los tickets en lotes de 100, implemente una retroceso exponencial cuando alcance los errores 429 y considere ejecutar importaciones grandes durante las horas de menor actividad."
},
{
"question": "¿Qué sucede con las reglas de negocio cuando uso el endpoint de la API de Zendesk para importar tickets en masa?",
"answer": "Los triggers (disparadores) y las automatizaciones no se ejecutan en los tickets importados. Sin embargo, volverán a funcionar si el ticket se actualiza después de la importación. Esto es por diseño para evitar el envío de spam a los usuarios con notificaciones durante la migración."
},
{
"question": "¿Puedo importar tickets con el endpoint de la API de Zendesk para importar tickets en masa si el solicitante ya no trabaja en mi empresa?",
"answer": "El solicitante debe ser un usuario activo (no suspendido) en Zendesk. Tiene dos opciones: reactivar temporalmente la cuenta del exempleado o asignar sus tickets a una cuenta de marcador de posición como 'Exempleado' antes de la importación."
},
{
"question": "¿El endpoint de la API de Zendesk para importar tickets en masa conserva los ID de ticket de mi antiguo sistema?",
"answer": "No, Zendesk asigna nuevos ID de ticket durante la importación. Si necesita mantener referencias a los ID de ticket antiguos (por ejemplo, enlaces desde su rastreador de problemas), almacene una tabla de mapeo externamente que conecte los ID antiguos con los nuevos ID de Zendesk."
},
{
"question": "¿Cuál es la diferencia entre la API de Tickets estándar y la API de Importación de Tickets?",
"answer": "La API estándar crea nuevos tickets con marcas de tiempo actuales y activa reglas de negocio. La API de Importación conserva las marcas de tiempo históricas, omite los triggers (disparadores), admite el estado cerrado/archivado y está diseñada específicamente para escenarios de migración de datos."
}
],
"supportLink": null
}
}
---
Migrar datos de tickets a Zendesk es un desafío común para los equipos que cambian de plataforma, consolidan instancias o importan registros históricos. Si bien Zendesk ofrece varios métodos de importación, la API de Importación de Tickets es la única opción que conserva las marcas de tiempo históricas y maneja conjuntos de datos grandes correctamente.
Esta guía le guía a través del proceso completo de importación masiva de tickets utilizando la API de Zendesk. Aprenderá a estructurar sus datos, manejar casos extremos y evitar las trampas que pueden convertir un proyecto de fin de semana en un dolor de cabeza de varias semanas.
## Lo que necesitará
Antes de comenzar, asegúrese de tener lo siguiente:
- **Acceso de administrador de Zendesk**: solo los administradores pueden usar la API de importación
- **Token de API**: la autenticación con contraseña por sí sola no funcionará; necesita un token de API adecuado de su configuración de administrador de Zendesk
- **Usuarios existentes**: los solicitantes ya deben existir en Zendesk antes de importar sus tickets
- **Conocimiento de JSON**: trabajará con solicitudes de la API REST y cargas útiles JSON
- **Entorno de scripting**: Python o Node.js facilitarán mucho el procesamiento por lotes
Si está buscando una forma más sencilla de manejar los flujos de trabajo de soporte sin migraciones complejas, las soluciones modernas de IA como [eesel AI](https://www.eesel.ai/product/ai-agent) pueden integrarse directamente con su configuración existente.
## Comprender el endpoint de la API de Zendesk para importar tickets en masa
La API de Importación de Tickets difiere de la API de Tickets estándar en varios aspectos importantes. Esto es lo que necesita saber.
### Diferencias clave del endpoint
El endpoint de importación es `POST /api/v2/imports/tickets` (o `/api/v2/imports/tickets/create_many` para lotes de hasta 100 tickets). A diferencia de la API de creación de tickets estándar, el endpoint de importación:
- Conserva las marcas de tiempo históricas, incluidas `created_at`, `updated_at` y `solved_at`
- Admite el parámetro `archive_immediately` para tickets cerrados
- No activa reglas de negocio ni automatizaciones en la importación
- No envía notificaciones a los usuarios en copia (CC)
- Le permite establecer marcas de tiempo de comentarios personalizadas
Fuente: [Documentación de la API de Importación de Tickets de Zendesk](https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_import/)
### Límites de velocidad y tamaños de lote
Zendesk permite hasta 100 tickets por solicitud de importación masiva. Para conjuntos de datos más grandes, deberá implementar la lógica de procesamiento por lotes en su script. Se aplican los límites de velocidad de la API estándar (700 solicitudes por minuto para la mayoría de los planes), así que planifique su migración en consecuencia.
### Requisitos de autenticación
Todas las solicitudes de importación requieren autenticación básica utilizando su dirección de correo electrónico combinada con un token de API (no su contraseña). El formato es `{email_address}/token:{api_token}` codificado en Base64.
## Paso 1: Prepare sus datos
La preparación de datos es donde la mayoría de las migraciones tienen éxito o fracasan. Tómese el tiempo para hacerlo bien.
### Campos obligatorios y opcionales
Como mínimo, cada ticket necesita un `requester_id` y un `subject`. Aquí hay un ejemplo completo:
```json
{
"ticket": {
"requester_id": 827,
"subject": "Ayuda con el acceso a la cuenta",
"description": "Descripción inicial del 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": "No puedo iniciar sesión en mi cuenta"
}
]
}
}
Requisitos previos del usuario
El solicitante y cualquier autor de comentarios ya deben existir en Zendesk como usuarios activos. La API rechazará los tickets con solicitantes suspendidos o inexistentes. Importe primero sus usuarios utilizando la importación masiva de CSV (hasta 2000 filas) o la API de Usuarios.
Manejo de archivos adjuntos
Los archivos adjuntos requieren un proceso de dos pasos:
- Cargue archivos a Zendesk utilizando el endpoint de archivos adjuntos para obtener tokens de carga
- Incluya esos tokens en su carga útil de importación de tickets
Para imágenes en línea (capturas de pantalla en los comentarios), tenga en cuenta que la documentación de la API no cubre completamente esto. Las migraciones del mundo real revelan que los archivos adjuntos en línea tienen un manejo diferente al de los archivos adjuntos estándar.
Paso 2: Estructure su solicitud de API
Con sus datos preparados, puede comenzar a construir las solicitudes de API reales.
Estructura básica de la solicitud
Aquí hay un ejemplo de Python que muestra cómo estructurar una solicitud de importación básica:
import requests
import base64
email = 'your-email@example.com'
api_token = 'your_api_token_here'
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": "Ayuda",
"description": "Una descripción",
"created_at": "2023-06-25T10:15:18Z",
"comments": [
{
"author_id": 827,
"created_at": "2023-06-25T10:15:18Z",
"value": "Este es un comentario"
}
]
}
}
response = requests.post(
'https://your-subdomain.zendesk.com/api/v2/imports/tickets',
headers=headers,
json=ticket_data
)
Incluir comentarios históricos
La matriz de comentarios admite múltiples entradas con marcas de tiempo individuales. Esto es crucial para preservar el historial completo de conversaciones de su sistema de origen.
Campos y etiquetas personalizados
Asigne los campos personalizados de su sistema de origen a los campos personalizados de Zendesk utilizando la matriz custom_fields con pares id y value. Las etiquetas se pueden pasar como una simple matriz de cadenas.
Paso 3: Maneje casos especiales
Las migraciones del mundo real siempre involucran casos extremos. Aquí le mostramos cómo manejar los más comunes.
Importación de tickets cerrados
Para los tickets con estado cerrado, utilice el parámetro de consulta archive_immediately:
POST /api/v2/imports/tickets?archive_immediately=true
Esto omite el ciclo de vida normal del ticket y crea tickets directamente en su archivo. Zendesk recomienda este enfoque al importar 750 000 o más tickets históricos para evitar afectar el rendimiento de su cola de tickets activa.
Gestión de grandes conjuntos de datos
Para migraciones grandes, implemente estas prácticas:
- Procese los tickets en lotes de 100 (el máximo de la API)
- Registre los resultados de cada lote para el seguimiento de errores
- Cree una lógica de reintento para las solicitudes fallidas
- Considere ejecutar importaciones durante las horas de menor actividad
Tratamiento de usuarios suspendidos
La API requiere que los solicitantes sean usuarios activos. Si sus datos de origen incluyen tickets de usuarios suspendidos o eliminados, tiene dos opciones:
- Reactive los usuarios antes de la importación
- Asigne los usuarios eliminados a una cuenta de marcador de posición de "exempleado"
Un equipo de migración descubrió esto por las malas: "La API se resistirá si los solicitantes y los remitentes están suspendidos. Tuvimos que reactivar a los exempleados temporalmente durante el proceso de importación".
Fuente: Experiencia de migración de la comunidad de Zendesk
Cuerpos de comentarios vacíos
La API rechaza los comentarios con cuerpos vacíos, aunque la interfaz de usuario de Zendesk lo permite (como cuando alguien envía por correo electrónico un archivo adjunto sin texto). Deberá agregar texto de marcador de posición como "(Sin texto de comentario)" para estos casos.
Paso 4: Ejecute y valide
Con sus datos preparados y los casos extremos manejados, es hora de ejecutar la importación.
Envío de solicitudes en lotes
Recorra sus datos de tickets en fragmentos de 100, enviando cada lote al endpoint de importación masiva. Registre la respuesta de cada lote, incluidos los ID de ticket que se crearon correctamente.
Manejo de errores
Códigos de estado HTTP comunes que encontrará:
- 200 OK: Ticket creado correctamente
- 422 Entidad no procesable: Error de validación (verifique su estructura JSON)
- 429 Demasiadas solicitudes: Límite de velocidad alcanzado; implemente una retroceso exponencial
- 401 No autorizado: Problema de autenticación; verifique su token de API
Estrategias de verificación
Después de la importación, verifique el éxito mediante:
- Verificar que los recuentos de tickets coincidan con sus datos de origen
- Muestreo de tickets para verificar que las marcas de tiempo y los comentarios se importaron correctamente
- Confirmar que los archivos adjuntos sean accesibles
- Probar que las etiquetas y los campos personalizados aparezcan correctamente
Trampas comunes y cómo evitarlas
Aprender de los errores de otros puede ahorrarle mucho tiempo. Estos son los mayores problemas que encuentran los equipos de migración.
Los solicitantes deben estar activos
Como se mencionó, los usuarios suspendidos causan fallas en la importación. Reactívelos primero o use cuentas de marcador de posición.
El orden de importación importa
Debe importar en esta secuencia:
- Organizaciones (si las usa)
- Usuarios
- Tickets
Los tickets hacen referencia a usuarios y organizaciones por ID, por lo que esos registros deben existir primero.
Las métricas y los SLA no se calcularán
Las métricas y los SLA de Zendesk no se calculan para los tickets importados. Si necesita informes sobre datos históricos, considere agregar una etiqueta como "importado" para excluir estos tickets de las métricas actuales.
Sin reserva de ID de ticket
No puede conservar las relaciones de ID de ticket de su sistema de origen. Los tickets combinados y las referencias cruzadas deberán manejarse manualmente o mediante tablas de mapeo externas.
Las conversaciones secundarias no son compatibles
Si su sistema de origen tiene conversaciones secundarias o hilos colaborativos, estos no se pueden importar a través de la API. Conviértalos en comentarios internos o acepte que estos datos no se transferirán.
Peculiaridades del análisis JSON
Un equipo de migración que usaba PowerShell encontró problemas inesperados de análisis JSON: "Zendesk se resistió a que no puede analizar el JSON. El JSON que generé era sintácticamente correcto, pero entregué el objeto de PowerShell directamente. Guardar el JSON en un archivo primero, luego alimentarlo a Zendesk funcionó sin problemas".
Fuente: Experiencia de migración de la comunidad de Zendesk
Enfoques alternativos: eesel AI y otras opciones
A veces, la API no es la opción correcta. Considere estas alternativas.
Cuándo usar la importación de CSV en su lugar
La importación masiva de CSV de Zendesk funciona para usuarios y organizaciones (no para tickets) y maneja hasta 2000 filas por archivo. Es más simple que la API, pero tiene limitaciones significativas: sin importación de zona horaria, sin fotos, sin preferencias de idioma y sin soporte de tickets.
Servicios de migración de terceros
Para migraciones complejas, los servicios profesionales como zendesk-import.com o la aplicación Zenplates Import pueden manejar la complejidad técnica. Estos servicios generalmente cobran según el volumen de datos, pero ahorran un tiempo de desarrollo significativo.
Alternativas modernas impulsadas por IA
Si está migrando porque su help desk actual no está satisfaciendo sus necesidades, considere si una solución moderna de IA podría ser una mejor opción que una migración de plataforma tradicional. eesel AI se integra con Zendesk para agregar manejo de tickets impulsado por IA, respuestas automatizadas y enrutamiento inteligente sin requerir un cambio completo de plataforma.
Comience a construir mejores flujos de trabajo de soporte
La importación masiva de tickets a través de la API de Zendesk le brinda un control preciso sobre la migración de datos históricos, pero requiere una planificación cuidadosa y atención a los casos extremos. Los pasos clave son simples: prepare sus datos a fondo, maneje los usuarios suspendidos, procese en lotes y verifique todo después.
Si está considerando una migración porque sus herramientas de soporte actuales no están a la altura de sus necesidades, explore cómo la integración de Zendesk de eesel AI puede mejorar su configuración existente con capacidades impulsadas por IA. O si está evaluando enfoques completamente nuevos para la atención al cliente, consulte los precios de eesel AI para ver cómo se comparan las soluciones modernas de IA con las migraciones de plataforma tradicionales.
Compartir esta entrada
Article by
