Cómo actualizar tickets usando la API de Zendesk en 2026

Gestionar tickets de soporte programáticamente es esencial para los equipos que buscan automatizar flujos de trabajo, integrarse con otros sistemas o crear herramientas personalizadas. La API de tickets de Zendesk le brinda control total sobre las actualizaciones de tickets, desde simples cambios de estado hasta complejas operaciones masivas que involucran campos personalizados.

Esta guía lo guiará a través de todo lo que necesita saber para comenzar a actualizar tickets a través de la API, con ejemplos de código funcional que puede adaptar para sus propios proyectos.

Lo que necesitará para comenzar

Antes de realizar su primera llamada a la API, asegúrese de tener lo siguiente:

• Una cuenta de Zendesk Support con acceso de administrador o agente. Necesitará permisos para generar tokens de API y ver datos de tickets.
• Autenticación de token de API habilitada. El acceso con token debe estar activado en su Centro de administración en Aplicaciones e integraciones > API > Tokens de API.
• Familiaridad básica con las API REST. Debe comprender los métodos HTTP (GET, PUT, POST) y los formatos de datos JSON.
• Sus herramientas preferidas. Esta guía incluye ejemplos en cURL y Python utilizando la biblioteca Requests, pero puede usar Postman, JavaScript o cualquier cliente HTTP.

Si recién está comenzando con la API de Zendesk, es posible que desee revisar primero la guía de inicio rápido de la API. Cubre los conceptos básicos de cómo realizar solicitudes y manejar respuestas.

Configuración de la autenticación de la API

Zendesk utiliza la autenticación basada en tokens para el acceso a la API. Aquí le mostramos cómo configurarlo.

Generación de un token de API

1. Inicie sesión en su cuenta de Zendesk como administrador
2. Vaya a Centro de administración > Aplicaciones e integraciones > API > Tokens de API
3. Haga clic en el icono más para agregar un nuevo token
4. Dele un nombre descriptivo como "Script de actualización de tickets"
5. Copie el token inmediatamente. Zendesk solo lo muestra una vez.

Formato de autenticación

Zendesk espera credenciales en este formato:

{dirección_de_correo_electrónico}/token:{api_token}

Por ejemplo, si su correo electrónico es admin@company.com y su token es abc123xyz, su cadena de autenticación sería:

admin@company.com/token:abc123xyz

Almacenamiento seguro de credenciales

Nunca codifique su token de API en scripts. En su lugar, utilice variables de entorno:

export ZENDESK_SUBDOMAIN="suempresa"
export ZENDESK_EMAIL="admin@company.com"
export ZENDESK_TOKEN="su_api_token_aquí"

Luego acceda a ellas en Python:

import os

subdomain = os.getenv('ZENDESK_SUBDOMAIN')
email = os.getenv('ZENDESK_EMAIL')
token = os.getenv('ZENDESK_TOKEN')

auth = (f"{email}/token", token)

Prueba de su autenticación

Realice una solicitud GET simple para verificar que todo funcione:

curl "https://suempresa.zendesk.com/api/v2/tickets.json?per_page=1" \
  -u "admin@company.com/token:su_api_token"

Si recibe una respuesta JSON con datos de tickets, está autenticado y listo para continuar. Si recibe un error 401, verifique su token y dirección de correo electrónico.

Actualización de un solo ticket

El endpoint para actualizar tickets es sencillo:

PUT /api/v2/tickets/{ticket_id}.json

Actualización básica con cURL

Aquí le mostramos cómo actualizar el estado de un ticket y agregar un comentario:

curl "https://suempresa.zendesk.com/api/v2/tickets/12345.json" \
  -X PUT \
  -u "admin@company.com/token:su_api_token" \
  -H "Content-Type: application/json" \
  -d '{
    "ticket": {
      "status": "solved",
      "comment": {
        "body": "Este problema se ha resuelto. La solución ya está activa.",
        "public": true
      }
    }
  }'

Implementación en Python

Usando la biblioteca Requests, la misma operación se ve así:

import requests
import os

subdomain = os.getenv('ZENDESK_SUBDOMAIN')
email = os.getenv('ZENDESK_EMAIL')
token = os.getenv('ZENDESK_TOKEN')

url = f"https://{subdomain}.zendesk.com/api/v2/tickets/12345.json"
auth = (f"{email}/token", token)

data = {
    "ticket": {
        "status": "solved",
        "priority": "normal",
        "assignee_id": 987654321,
        "comment": {
            "body": "Este problema se ha resuelto. La solución ya está activa.",
            "public": True
        }
    }
}

response = requests.put(url, json=data, auth=auth)

if response.status_code == 200:
    print("Ticket actualizado correctamente")
    updated_ticket = response.json()['ticket']
    print(f"Nuevo estado: {updated_ticket['status']}")
else:
    print(f"Error: {response.status_code}")
    print(response.text)

Campos comunes que puede actualizar

Al actualizar el campo comment, establecer "public": true lo convierte en una respuesta pública visible para el solicitante. Omitir esto o establecerlo en false crea una nota interna.

Trabajar con campos personalizados

Los campos personalizados son comunes en las configuraciones de Zendesk para rastrear datos específicos como categorías de productos, niveles de clientes o tipos de problemas. Actualizarlos a través de la API requiere conocer el ID del campo.

Encontrar ID de campos personalizados

Puede encontrar los ID de los campos personalizados de dos maneras:

1. Centro de administración: Vaya a Objetos y reglas > Tickets > Campos personalizados. El ID aparece en la URL cuando edita un campo.
2. API: Enumere todos los campos personalizados con GET /api/v2/ticket_fields.json

Actualización de campos personalizados

Los campos personalizados utilizan un formato específico en la API. Debe proporcionar una matriz de objetos con propiedades id y value:

{
  "ticket": {
    "custom_fields": [
      {"id": 25356371, "value": "enterprise"},
      {"id": 25356372, "value": 42},
      {"id": 25356373, "value": "billing_issue"}
    ]
  }
}

Aquí hay un ejemplo completo en Python:

import requests
import os

subdomain = os.getenv('ZENDESK_SUBDOMAIN')
email = os.getenv('ZENDESK_EMAIL')
token = os.getenv('ZENDESK_TOKEN')

url = f"https://{subdomain}.zendesk.com/api/v2/tickets/12345.json"
auth = (f"{email}/token", token)

data = {
    "ticket": {
        "custom_fields": [
            {"id": 360012345678, "value": "premium"},      # Dropdown
            {"id": 360012345679, "value": "2026-03-15"},  # Date
            {"id": 360012345680, "value": 1500.00},        # Decimal
            {"id": 360012345681, "value": True}            # Checkbox
        ],
        "comment": {
            "body": "Nivel de cliente y fecha de renovación actualizados.",
            "public": False
        }
    }
}

response = requests.put(url, json=data, auth=auth)

if response.status_code == 200:
    print("Campos personalizados actualizados correctamente")
else:
    print(f"Error {response.status_code}: {response.text}")

Errores comunes con campos personalizados

• Tipo de datos incorrecto: Enviar una cadena cuando el campo espera un número devolverá un error 422
• Valores de opción no válidos: Los campos desplegables solo aceptan valores predefinidos. Verifique la configuración del campo si fallan las actualizaciones.
• Permisos de campo: Algunos campos personalizados son de solo lectura o solo pueden ser editados por ciertos roles

Actualización masiva de varios tickets

Cuando necesita actualizar docenas o cientos de tickets, las llamadas API individuales son ineficientes. Zendesk proporciona endpoints de actualización masiva para este escenario.

El endpoint de actualización masiva

PUT /api/v2/tickets/update_many.json?ids=1,2,3,4,5

Puede especificar los tickets por ID o usar una consulta de búsqueda:

PUT /api/v2/tickets/update_many.json?query=status:open+priority:high

Cuándo usar actualizaciones masivas

Las actualizaciones masivas tienen sentido cuando necesita:

• Reasignar todos los tickets de un agente que se va
• Cerrar tickets resueltos de más de 30 días
• Actualizar un valor de campo personalizado en una categoría de tickets
• Agregar etiquetas a los tickets que coincidan con criterios específicos

Consideraciones sobre el límite de frecuencia

Zendesk aplica límites de frecuencia que varían según el plan: los planes Team tienen 200 solicitudes por minuto, los planes Growth y Professional tienen 400 y los planes Enterprise tienen 700. Las actualizaciones masivas cuentan como una sola solicitud, independientemente de cuántos tickets afecten, lo que las hace mucho más eficientes que las llamadas individuales.

Mejores prácticas para actualizaciones a gran escala

1. Pruebe primero en un lote pequeño. Ejecute su actualización en 5-10 tickets para verificar la lógica antes de procesar cientos.
2. Utilice las consultas de búsqueda con cuidado. Una consulta mal construida podría coincidir con miles de tickets sin querer.
3. Maneje la paginación. Si su búsqueda devuelve muchos resultados, procéselos en lotes.
4. Registre sus cambios. Mantenga un registro de qué tickets se actualizaron y cuándo.

Aquí hay un ejemplo que actualiza todos los tickets abiertos asignados a un agente específico:

import requests
import os
import time

subdomain = os.getenv('ZENDESK_SUBDOMAIN')
email = os.getenv('ZENDESK_EMAIL')
token = os.getenv('ZENDESK_TOKEN')

auth = (f"{email}/token", token)
base_url = f"https://{subdomain}.zendesk.com/api/v2"

search_url = f"{base_url}/search.json?query=assignee:987654321+status:open"
response = requests.get(search_url, auth=auth)
results = response.json()

ticket_ids = [str(ticket['id']) for ticket in results['results']]

for i in range(0, len(ticket_ids), 100):
    batch = ticket_ids[i:i+100]
    ids_param = ','.join(batch)

    update_url = f"{base_url}/tickets/update_many.json?ids={ids_param}"
    data = {
        "ticket": {
            "assignee_id": 123456789,  # Nuevo asignado
            "comment": {
                "body": "Reasignado al nuevo miembro del equipo.",
                "public": False
            }
        }
    }

    response = requests.put(update_url, json=data, auth=auth)

    if response.status_code == 200:
        print(f"Lote actualizado {i//100 + 1}: {len(batch)} tickets")
    else:
        print(f"Error en el lote {i//100 + 1}: {response.text}")

    # Sea amable con la API
    time.sleep(1)

Manejo de errores y resolución de problemas

Incluso con una planificación cuidadosa, las llamadas API a veces fallan. Saber cómo interpretar las respuestas de error le ahorrará tiempo de depuración.

Códigos de error HTTP comunes

Manejo de errores de validación

Un error 422 generalmente significa que sus datos no coinciden con lo que espera Zendesk. El cuerpo de la respuesta contiene detalles:

{
  "error": "RecordInvalid",
  "description": "Errores de validación de registros",
  "details": {
    "custom_fields": [
      {
        "description": "El valor del campo no puede estar en blanco",
        "error": "BlankValue"
      }
    ]
  }
}

Consejos para la depuración

1. Habilite el registro detallado en su cliente HTTP para ver los detalles completos de la solicitud y la respuesta
2. Verifique los registros de la API de Zendesk en el Centro de administración para ver las solicitudes fallidas
3. Valide su JSON antes de enviarlo. Una coma final o una comilla faltante causarán errores.
4. Pruebe en Postman o con cURL antes de escribir código para aislar problemas de sintaxis

Cuándo contactar con el soporte de Zendesk

La mayoría de los problemas de la API se pueden resolver consultando la documentación y verificando el formato de su solicitud. Póngase en contacto con el soporte de Zendesk si encuentra:

• Errores 500 constantes (problemas del lado del servidor)
• Limitación de frecuencia inesperada a pesar de estar por debajo de los límites documentados
• Comportamiento que contradice la documentación oficial de la API

Agilización de las actualizaciones de tickets con eesel AI

Crear y mantener integraciones de API requiere tiempo y recursos de ingeniería. Para los equipos que necesitan gestión automatizada de tickets sin escribir código, eesel AI ofrece un enfoque diferente.

Por qué los equipos eligen la automatización en lugar de la creación de scripts manuales

Los scripts de API personalizados funcionan bien para tareas específicas y únicas. Pero se convierten en una carga cuando necesita:

• Actualizar continuamente los tickets en función de las condiciones cambiantes
• Mantener las integraciones a medida que evoluciona su flujo de trabajo
• Capacitar a los miembros del equipo para que utilicen y modifiquen el código
• Escalar la automatización en múltiples tipos de tickets y canales

Cómo eesel AI se conecta a Zendesk

En lugar de escribir llamadas API, invite a eesel AI a su equipo como un agente de IA. Aprende de sus tickets anteriores, artículos del centro de ayuda y macros, luego gestiona las actualizaciones rutinarias automáticamente.

Así es como se ve en la práctica:

• Etiquetado automático: eesel lee los tickets entrantes y aplica etiquetas relevantes según el contenido
• Enrutamiento inteligente: Los tickets se asignan al equipo o agente correcto sin clasificación manual
• Actualizaciones de estado: eesel puede cambiar el estado del ticket cuando se cumplen condiciones específicas
• Manejo de escalamiento: Los problemas complejos se escalan automáticamente a agentes humanos con contexto

Casos de uso para la gestión automatizada de tickets

Los equipos utilizan la integración de Zendesk de eesel AI para escenarios que de otro modo requerirían scripts de API complejos:

• Enrutamiento inmediato de tickets de clientes VIP a agentes senior
• Cierre automático de mensajes de spam o "gracias"
• Actualización de campos personalizados basados en el análisis del contenido del ticket
• Fusión de tickets duplicados del mismo cliente

Cómo comenzar con eesel AI

Si su equipo está dedicando más tiempo a mantener scripts de API que a beneficiarse de la automatización, los precios de eesel AI ofrecen una alternativa sin código. Los planes comienzan en $239 por mes cuando se facturan anualmente, con una prueba gratuita de 7 días para probar cómo se adapta a su flujo de trabajo.

La diferencia está en el enfoque. En lugar de escribir código para actualizar los tickets, describe lo que quiere en inglés sencillo. eesel aprende su negocio, comienza con orientación y sube de nivel para trabajar de forma autónoma a medida que se demuestra.