Cómo crear tickets de Zendesk usando la API: Una guía completa de JSON

Si está creando integraciones con Zendesk, es probable que necesite crear tickets mediante programación. Ya sea que esté conectando un formulario web personalizado, sincronizando datos de otro sistema o automatizando flujos de trabajo de soporte, la API de Tickets de Zendesk es la forma estándar de ingresar datos en Zendesk.

Esta guía lo guía a través de todo lo que necesita saber sobre la creación de tickets a través de la API, desde la autenticación hasta las cargas útiles JSON avanzadas.

Lo que necesitará para comenzar

Antes de comenzar a realizar llamadas a la API, asegúrese de tener estos conceptos básicos cubiertos:

• Una cuenta de Zendesk Support con acceso de administrador o agente. Si no tiene una, puede obtener una cuenta de prueba gratuita para desarrollo
• Acceso al token de API habilitado en su Centro de administración en Aplicaciones e integraciones > API > Tokens de API
• Familiaridad básica con las solicitudes HTTP y las estructuras de datos JSON
• Una herramienta para realizar llamadas a la API: cURL, Python con la biblioteca requests o un entorno JavaScript

Si es nuevo en el trabajo con las API REST, la documentación de Zendesk tiene una útil guía de inicio rápido que utiliza la consola de JavaScript de su navegador para probar solicitudes sin ninguna configuración.

Comprender el endpoint de la API de Tickets de Zendesk

El endpoint JSON de creación de tickets de la API de Zendesk sigue un patrón consistente en todas las instancias de Zendesk:

POST https://{subdominio}.zendesk.com/api/v2/tickets.json

Esto es lo que necesita saber sobre el endpoint:

• Método HTTP: POST para crear nuevos tickets
• Encabezado Content-Type: Debe establecerse en application/json
• Autenticación: Autenticación básica utilizando su correo electrónico y token de API
• Límites de velocidad: 700 solicitudes por minuto para la mayoría de los endpoints

La API devuelve un estado 201 Created en caso de éxito, junto con el objeto de ticket completo, incluido el ID de ticket recién asignado. Si algo sale mal, obtendrá un estado 4xx o 5xx con un mensaje de error que explica el problema.

Configuración de la autenticación de la API

La autenticación es donde la mayoría de los desarrolladores encuentran su primer problema. Zendesk utiliza la autenticación básica con un giro: en lugar de su contraseña, utiliza un token de API.

Generación de un token de API

1. Inicie sesión en 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 token
4. Dele un nombre descriptivo (como "Script de creación de tickets")
5. Copie el token inmediatamente (no lo volverá a ver)

Formato de autenticación

Las credenciales siguen este formato:

Nombre de usuario: {su_correo_electrónico}/token
Contraseña: {su_token_de_api}

Por ejemplo, si su correo electrónico es admin@company.com y su token es abc123xyz, usaría:

Nombre de usuario: admin@company.com/token
Contraseña: abc123xyz

Mejores prácticas de seguridad

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

import os

ZENDESK_SUBDOMAIN = os.getenv('ZENDESK_SUBDOMAIN')
ZENDESK_API_TOKEN = os.getenv('ZENDESK_API_TOKEN')
ZENDESK_USER_EMAIL = os.getenv('ZENDESK_USER_EMAIL')

Esto mantiene sus credenciales fuera del control de versiones y hace que su código sea más portátil entre entornos.

Estructura JSON básica de creación de tickets

Como mínimo, un ticket de Zendesk necesita dos cosas: un asunto y un comentario. Aquí está la carga útil JSON válida más simple:

{
  "ticket": {
    "subject": "¡Mi impresora está en llamas!",
    "comment": {
      "body": "El humo es muy colorido."
    }
  }
}

El objeto ticket envuelve todo. Dentro, usted establece:

• subject: El título del ticket (obligatorio)
• comment: Un objeto que contiene al menos un body (obligatorio)

De forma predeterminada, los comentarios son públicos. Si desea crear una nota interna en su lugar, agregue "public": false al objeto de comentario.

Formato de respuesta

Cuando su solicitud tiene éxito, la API devuelve el ticket creado:

{
  "ticket": {
    "id": 35436,
    "url": "https://company.zendesk.com/api/v2/tickets/35436.json",
    "subject": "¡Mi impresora está en llamas!",
    "status": "open",
    "created_at": "2026-03-01T22:55:29Z",
    ...
  }
}

El campo id es lo que usará para hacer referencia a este ticket en futuras llamadas a la API.

Ejemplos de código para crear tickets

Veamos ejemplos prácticos en tres lenguajes comunes.

Ejemplo de cURL

curl https://yourcompany.zendesk.com/api/v2/tickets.json \
  -d '{"ticket": {"subject": "Ticket de prueba", "comment": {"body": "Esto es una prueba"}}}' \
  -H "Content-Type: application/json" \
  -v -u your@email.com/token:your_api_token \
  -X POST

El indicador -v muestra una salida detallada, lo que ayuda con la depuración. Elimínelo en producción.

Ejemplo de Python

import requests
import os
import json

subdomain = os.getenv('ZENDESK_SUBDOMAIN')
email = os.getenv('ZENDESK_USER_EMAIL')
token = os.getenv('ZENDESK_API_TOKEN')

url = f'https://{subdomain}.zendesk.com/api/v2/tickets.json'
auth = (f'{email}/token', token)
headers = {'Content-Type': 'application/json'}

data = {
    'ticket': {
        'subject': 'Problema de la impresora',
        'comment': {
            'body': 'La impresora no responde.',
            'public': True
        }
    }
}

response = requests.post(url, json=data, auth=auth, headers=headers)

if response.status_code == 201:
    ticket = response.json()['ticket']
    print(f"Ticket creado #{ticket['id']}")
else:
    print(f"Error: {response.status_code}")
    print(response.text)

Tenga en cuenta que requests.post() con el parámetro json= serializa automáticamente el diccionario a JSON y establece el encabezado Content-Type.

Ejemplo de JavaScript

Si está trabajando en un navegador con Zendesk ya cargado, puede usar jQuery:

const ticket = {
  ticket: {
    subject: 'Ayuda con el inicio de sesión',
    comment: {
      body: 'No puedo acceder a mi cuenta.'
    }
  }
};

$.ajax({
  url: '/api/v2/tickets.json',
  type: 'POST',
  contentType: 'application/json',
  data: JSON.stringify(ticket)
}).done(data => {
  console.log('Ticket creado:', data.ticket.id);
}).fail(err => {
  console.error('Error:', err);
});

Para Node.js, use la API fetch nativa o una biblioteca como axios:

const response = await fetch('https://company.zendesk.com/api/v2/tickets.json', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Basic ' + Buffer.from(`${email}/token:${token}`).toString('base64')
  },
  body: JSON.stringify(ticket)
});

const data = await response.json();

Propiedades avanzadas del ticket

Una vez que haya dominado los conceptos básicos, puede establecer propiedades adicionales para crear tickets más completos.

Campos personalizados

Si su instancia de Zendesk tiene campos de ticket personalizados, configúrelos utilizando sus ID de campo:

{
  "ticket": {
    "subject": "Consulta de pedido",
    "comment": {"body": "Pregunta sobre un pedido reciente"},
    "custom_fields": [
      {"id": 25356371, "value": "ORD-12345"},
      {"id": 25356634, "value": "2026-03-01"}
    ]
  }
}

Para los campos desplegables, utilice el valor de la etiqueta (no el texto que se muestra). Para los campos de selección múltiple, pase una matriz de valores de etiqueta.

Configuración del solicitante

Puede crear un ticket en nombre de otra persona:

{
  "ticket": {
    "subject": "Solicitud de soporte",
    "comment": {"body": "Necesito ayuda con la facturación"},
    "requester": {
      "name": "John Smith",
      "email": "john@example.com",
      "locale_id": 8
    }
  }
}

Si el correo electrónico no existe en Zendesk, se crea automáticamente un nuevo perfil de usuario.

Colaboradores y seguidores

Agregue colaboradores (usuarios que reciben actualizaciones) o seguidores (agentes que rastrean el ticket):

{
  "ticket": {
    "subject": "Problema del equipo",
    "comment": {"body": "Esto afecta a varios departamentos"},
    "collaborators": ["user1@example.com", "user2@example.com"],
    "followers": [
      {"user_email": "agent@company.com", "action": "put"}
    ]
  }
}

Archivos adjuntos

Para adjuntar archivos, primero debe cargarlos por separado para obtener un token de carga, luego incluir ese token en la creación de su ticket:

{
  "ticket": {
    "subject": "Captura de pantalla adjunta",
    "comment": {
      "body": "Ver mensaje de error adjunto",
      "uploads": ["vz7ll9ud8oofowy"]
    }
  }
}

Creación asíncrona

Para los tickets con reglas comerciales complejas que pueden tardar en procesarse, utilice la creación asíncrona:

POST /api/v2/tickets.json?async=true

Esto devuelve un 202 Accepted inmediatamente con un estado de trabajo que puede sondear para verificar la finalización.

Claves de idempotencia

Para evitar tickets duplicados al reintentar solicitudes fallidas, incluya una clave de idempotencia:

curl ... -H "Idempotency-Key: unique-request-id-123"

Las claves caducan después de 2 horas. Reutilizar la misma clave con diferentes parámetros devuelve un error.

Errores comunes y solución de problemas

Estos son los errores que es más probable que encuentre y cómo solucionarlos.

422 Entidad no procesable

Esto generalmente significa que su JSON está mal formado. Causas comunes:

• Faltan comillas alrededor de los nombres de las propiedades o los valores de las cadenas
• Comas finales en objetos JSON
• Usar comillas simples en lugar de comillas dobles
• Secuencias de escape no válidas en cadenas

Si está creando cadenas JSON manualmente (especialmente en VBA o lenguajes más antiguos), tenga cuidado con los caracteres de comillas adicionales. El JSON debería verse así:

{"ticket": {"subject": "Test", "comment": {"body": "Hello"}}}

No así:

"{"ticket": {"subject": "Test"}}"

401 No autorizado

Sus credenciales de autenticación son incorrectas. Compruebe:

• ¿Es correcta la dirección de correo electrónico?
• ¿Incluyó /token después del correo electrónico?
• ¿Es válido el token de API y no ha caducado?
• ¿El usuario tiene permiso para crear tickets?

429 Límite de velocidad excedido

Ha alcanzado el límite de velocidad de la API. Zendesk permite 700 solicitudes por minuto para la mayoría de los endpoints. Si necesita crear muchos tickets, agregue retrasos entre las solicitudes o utilice el endpoint de creación masiva de tickets.

400 Solicitud incorrecta con errores de campo

Esto sucede cuando los valores de los campos del ticket no son válidos:

• Los ID de campo personalizados no existen
• Los valores desplegables no coinciden con las opciones disponibles
• Faltan campos obligatorios
• Los formatos de fecha son incorrectos (use ISO 8601: 2026-03-01)

Automatización de la creación de tickets sin código

La creación y el mantenimiento de integraciones de API lleva tiempo. Debe manejar la autenticación, la lógica de reintento de errores, la limitación de velocidad y el mantenimiento continuo a medida que cambian las API.

Si su objetivo es automatizar la creación de tickets en lugar de crear una integración personalizada, considere si realmente necesita escribir código. Herramientas como eesel AI pueden manejar la creación de tickets y las respuestas sin ningún trabajo de desarrollo.

Aquí está la diferencia: con el enfoque de la API, está escribiendo scripts para crear tickets a los que los humanos responderán. Con un agente de IA, está capacitando a un sistema para que comprenda su negocio y maneje todo el ciclo de vida del ticket, desde la creación hasta la resolución. Lo conecta a su cuenta de Zendesk y aprende de sus tickets anteriores, artículos del centro de ayuda y macros.

El modelo de lanzamiento progresivo significa que comienza con la IA redactando respuestas para su revisión, luego se expande a la automatización completa a medida que se demuestra. Para los equipos que buscan reducir el volumen de tickets en lugar de simplemente automatizar la creación, esto a menudo ofrece resultados más rápidos que el desarrollo de API personalizado.