API de Solicitudes de Zendesk: Una guía completa para usuarios finales (2026)

Cuando está creando un portal de clientes o una integración de autoservicio, necesita una forma para que los usuarios finales creen y vean tickets sin darles acceso completo de administrador. La API de Solicitudes de Zendesk está diseñada exactamente para este propósito.

La API de Solicitudes proporciona la perspectiva de un usuario final sobre los tickets. Los usuarios pueden crear solicitudes, ver su historial de tickets y añadir comentarios, todo ello viendo solo la información pública. Es la alternativa segura y de acceso limitado a la API de Tickets completa.

Si está buscando automatizar el soporte sin crear integraciones de API personalizadas, herramientas como eesel AI pueden gestionar todo el espectro de la automatización del soporte, desde el enrutamiento de tickets hasta las respuestas impulsadas por IA. eesel se integra directamente con Zendesk y aprende de sus tickets y documentación existentes. Pero si necesita acceso directo a la API para integraciones personalizadas, esta guía le guiará a través de todo lo que necesita saber.

Lo que necesitará

Antes de empezar a hacer llamadas a la API, asegúrese de tener:

• Una cuenta de Zendesk con los permisos adecuados (acceso de administrador para configurar los tokens de la API)
• Token de la API o credenciales de OAuth (cubriremos cómo generarlos)
• Familiaridad básica con las API REST (debe entender las solicitudes GET, POST y PUT)
• Un entorno de desarrollo (cURL, Python o Node.js funcionarán bien)

Entendiendo la API de Solicitudes

¿Qué es una solicitud?

En Zendesk, una solicitud es la perspectiva de un usuario final sobre un ticket. Mientras que los agentes ven el ticket completo con notas internas, campos personalizados y comentarios privados, los usuarios finales solo ven los comentarios públicos y un conjunto limitado de campos.

Así es como se ve el formato JSON para una solicitud:

{
  "id": 35436,
  "subject": "¡Ayuda, mi impresora está en llamas!",
  "description": "El fuego es muy colorido.",
  "status": "open",
  "priority": "normal",
  "type": "problem",
  "requester_id": 1462,
  "created_at": "2009-07-20T22:55:29Z",
  "updated_at": "2011-05-05T10:38:52Z"
}

Las propiedades clave incluyen:

• subject (obligatorio) - La línea de asunto visible para el usuario final
• description - Primer comentario de solo lectura en la solicitud
• status - nuevo, abierto, pendiente, en espera, resuelto o cerrado
• priority - baja, normal, alta o urgente
• type - pregunta, incidente, problema o tarea

Fuente: Referencia de la API de Solicitudes de Zendesk

API de Solicitudes vs API de Tickets: ¿Cuál debe usar?

Esta es una decisión crítica que afectará el comportamiento de su integración. Aquí está el desglose:

El problema de Agent Copilot es importante. Cuando crea un ticket a través de la API de Tickets en nombre de un usuario final, Zendesk lo interpreta como creado por un agente. Esto significa que Agent Copilot no se activará porque está esperando una respuesta del cliente que nunca llega. El uso de la API de Solicitudes asegura que los tickets se comporten exactamente como los creados a través del correo electrónico o la mensajería.

Fuente: Nota interna - Solicitudes de API y Agent Copilot

Métodos de autenticación

Autenticación de usuario final

Los usuarios finales pueden autenticarse utilizando sus propias credenciales. Cuando se utiliza el punto final de Solicitudes, los administradores y agentes son tratados como usuarios finales, por lo que ven la misma vista limitada.

Autenticación con Token de API:

curl https://your-subdomain.zendesk.com/api/v2/requests.json \
  -u user@example.com/token:your_api_token_here

Nota importante: Un usuario final no podrá ver sus solicitudes si ha añadido una identidad de correo electrónico después del 17 de septiembre de 2017 y no ha verificado la dirección de correo electrónico. La API devuelve una respuesta 403 en este caso.

Fuente: Referencia de la API de Solicitudes de Zendesk

Hacer solicitudes en nombre de usuarios finales (suplantación de identidad de administrador)

A veces necesitará que un administrador cree tickets para los usuarios finales. Esto requiere OAuth con un alcance de suplantación de identidad.

Paso 1: Cree un cliente OAuth en el Centro de administración (Aplicaciones e integraciones > API > Clientes OAuth)

Paso 2: Solicite un token de acceso con el alcance "impersonate" (suplantar identidad):

curl https://{subdomain}.zendesk.com/api/v2/oauth/tokens.json \
  -H "Content-Type: application/json" \
  -d '{
    "token": {
      "client_id": "your_client_id",
      "scopes": ["impersonate", "write"]
    }
  }' \
  -X POST -v -u {email_address}/token:{api_token}

Paso 3: Incluya la cabecera X-On-Behalf-Of en sus solicitudes:

curl https://z3napi.zendesk.com/api/v2/requests.json \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-On-Behalf-Of: customer@example.com" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "request": {
      "subject": "Solicitud de ayuda",
      "comment": {"body": "Necesito ayuda con mi pedido"}
    }
  }'

Importante: El usuario final suplantado debe tener un perfil de usuario existente. De lo contrario, la solicitud fallará con un error invalid_token.

Fuente: Hacer solicitudes de API en nombre de usuarios finales

Solicitudes anónimas

Si su administrador de Zendesk lo ha habilitado, puede crear solicitudes sin ninguna autenticación. Esto es útil para los formularios de contacto públicos.

Requisitos:

• Las solicitudes anónimas deben estar habilitadas en el Centro de administración
• Incluya un objeto requester con al menos un nombre

{
  "request": {
    "requester": {"name": "Cliente anónimo"},
    "subject": "¡Ayuda!",
    "comment": {"body": "¡Mi impresora está en llamas!"}
  }
}

Límites de velocidad: Las solicitudes anónimas están limitadas a 5 por hora para las cuentas de prueba.

Fuente: Creación y gestión de solicitudes

Puntos finales clave de la API

Listar solicitudes

Recuperar todas las solicitudes para el usuario autenticado:

GET /api/v2/requests

Parámetros:

• page - Paginación (soporta desplazamiento o basado en cursor)
• per_page - Número de registros por página
• sort_by - "updated_at" o "created_at"
• sort_order - "asc" o "desc"

Crear una solicitud

Crear un nuevo ticket desde la perspectiva de un usuario final:

POST /api/v2/requests

Campos obligatorios:

• subject - El asunto del ticket
• comment - Objeto con body que contiene la descripción

Campos opcionales:

• requester - Para solicitudes anónimas (objeto con nombre, correo electrónico)
• collaborators - Array de IDs de usuario o correos electrónicos para CC
• custom_fields - Array de valores de campos personalizados
• tags - Array de etiquetas para aplicar

Actualizar una solicitud

Añadir comentarios o marcar una solicitud como resuelta:

PUT /api/v2/requests/{id}

Propiedades editables:

• comment - Añadir un nuevo comentario
• solved - Establecer en true para marcar como resuelto (solo si can_be_solved_by_me es true)
• additional_collaborators - Añadir CCs a la solicitud

Listar comentarios

Ver el historial de la conversación:

GET /api/v2/requests/{request_id}/comments

Por defecto, los comentarios se ordenan por fecha de creación en orden ascendente.

Fuente: Referencia de la API de Solicitudes de Zendesk

Ejemplos de código

Crear una solicitud con cURL

#!/bin/bash

SUBDOMAIN="your-subdomain"
EMAIL="admin@example.com"
TOKEN="your_api_token"

curl "https://${SUBDOMAIN}.zendesk.com/api/v2/requests.json" \
  -u "${EMAIL}/token:${TOKEN}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "request": {
      "subject": "Consulta sobre el estado del pedido",
      "comment": {
        "body": "Hice un pedido la semana pasada y me gustaría comprobar el estado. Mi número de pedido es #12345."
      },
      "collaborators": ["spouse@example.com"]
    }
  }'

Crear una solicitud con Python

import requests
import json

subdomain = "your-subdomain"
email = "admin@example.com"
api_token = "your_api_token"

url = f"https://{subdomain}.zendesk.com/api/v2/requests.json"

payload = {
    "request": {
        "subject": "Necesito soporte técnico",
        "comment": {
            "body": "Tengo problemas para iniciar sesión en mi cuenta. ¿Puede ayudarme?"
        }
    }
}

auth = (f"{email}/token", api_token)
headers = {"Content-Type": "application/json"}

try:
    response = requests.post(url, json=payload, auth=auth, headers=headers)
    response.raise_for_status()

    data = response.json()
    print(f"¡Solicitud creada con éxito!")
    print(f"ID del ticket: {data['request']['id']}")
    print(f"Estado: {data['request']['status']}")

except requests.exceptions.HTTPError as err:
    print(f"Error HTTP: {err}")
    print(f"Respuesta: {response.text}")
except Exception as err:
    print(f"Error: {err}")

Crear una solicitud con Node.js

const axios = require('axios');

const config = {
  subdomain: 'your-subdomain',
  email: 'admin@example.com',
  apiToken: 'your_api_token'
};

async function createRequest() {
  const url = `https://${config.subdomain}.zendesk.com/api/v2/requests.json`;

  const payload = {
    request: {
      subject: 'Pregunta sobre la facturación',
      comment: {
        body: 'Me cobraron dos veces por mi suscripción este mes. Por favor, ayúdenme a resolver esto.'
      }
    }
  };

  try {
    const response = await axios.post(url, payload, {
      auth: {
        username: `${config.email}/token`,
        password: config.apiToken
      },
      headers: {
        'Content-Type': 'application/json'
      }
    });

    console.log('¡Solicitud creada con éxito!');
    console.log(`ID del ticket: ${response.data.request.id}`);
    console.log(`Estado: ${response.data.request.status}`);

  } catch (error) {
    console.error('Error al crear la solicitud:', error.response?.data || error.message);
  }
}

createRequest();

Errores comunes y solución de problemas

403 Prohibido (Forbidden)

Este es el error más común cuando se trabaja con la API de Solicitudes. Causas comunes:

• Correo electrónico no verificado: El usuario final añadió un correo electrónico después del 17 de septiembre de 2017 sin verificarlo
• Permisos insuficientes: Intentar acceder a puntos finales no permitidos para los usuarios finales
• Falta el alcance de suplantación de identidad: Intentar hacer solicitudes en nombre de los usuarios sin el alcance de OAuth adecuado

Solución: Verifique la dirección de correo electrónico del usuario en el administrador de Zendesk, o asegúrese de que está utilizando el método de autenticación correcto para su caso de uso.

401 No autorizado (Unauthorized)

• Token de API o credenciales de OAuth no válidas
• El token ha caducado (los tokens de OAuth tienen una vida útil limitada)
• La cuenta de usuario está suspendida o eliminada

Solución: Compruebe sus credenciales y regenere los tokens si es necesario.

429 Límite de velocidad excedido (Rate Limit Exceeded)

• API estándar: 700 solicitudes por minuto
• Solicitudes anónimas: 5 por hora (cuentas de prueba)

Solución: Implemente una retirada exponencial en su código. Cuando reciba un 429, espere antes de reintentar:

import time

def make_request_with_retry(url, payload, auth, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(url, json=payload, auth=auth)
            response.raise_for_status()
            return response
        except requests.exceptions.HTTPError as err:
            if response.status_code == 429:
                wait_time = (2 ** attempt)  # Retirada exponencial
                print(f"Límite de velocidad alcanzado. Esperando {wait_time} segundos...")
                time.sleep(wait_time)
            else:
                raise
    raise Exception("Número máximo de reintentos excedido")

Agent Copilot no se activa

Si está utilizando Agent Copilot de Zendesk y no está sugiriendo respuestas para los tickets creados a través de la API, es probable que esté utilizando la API de Tickets en lugar de la API de Solicitudes.

Solución: Cambie a la API de Solicitudes (POST /api/v2/requests.json) en lugar de la API de Tickets (POST /api/v2/tickets.json).

Fuente: Nota interna - Solicitudes de API y Agent Copilot

Mejores prácticas

Utilice la API de Solicitudes para las integraciones orientadas al usuario final

Si está creando un portal de clientes, un widget de autoservicio o cualquier interfaz donde los usuarios finales creen tickets, utilice siempre la API de Solicitudes. Esto asegura:

• Comportamiento adecuado de Agent Copilot
• Cálculos correctos del tiempo de primera respuesta
• Ciclo de vida del ticket consistente con los tickets creados por correo electrónico

Maneje los límites de velocidad con elegancia

Implemente siempre la lógica de reintento con retirada exponencial. La API de Zendesk se comparte entre todos los clientes, y el sondeo agresivo puede hacer que su integración se vea limitada o bloqueada.

Valide el estado de verificación del correo electrónico

Antes de permitir que los usuarios vean sus solicitudes, verifique que su correo electrónico esté confirmado. Puede comprobar esto a través de la API de Usuarios y pedirles que lo verifiquen si es necesario.

Almacene las credenciales de forma segura

No codifique los tokens de la API en su código frontend ni los guarde en el control de versiones. Utilice variables de entorno o sistemas de gestión de secretos seguros.

Considere alternativas sin código

La creación y el mantenimiento de integraciones de API requiere importantes recursos de desarrollo. Si su objetivo es automatizar las respuestas de soporte en lugar de crear portales personalizados, considere herramientas como eesel AI que se integran directamente con Zendesk y proporcionan automatización impulsada por IA sin escribir código. eesel AI no requiere una configuración compleja, simplemente lo invita a su equipo y aprende su negocio en minutos.

Ofrecemos:

• Agente de IA que gestiona el soporte de primera línea de forma autónoma
• Copiloto de IA que redacta respuestas para que los agentes las revisen
• Triaje de IA que etiqueta, enruta y prioriza los tickets automáticamente
• Integración con un solo clic con Zendesk (no se requiere desarrollo de API)

Fuente: Productos de eesel AI

Empiece a construir con la API de Solicitudes de Zendesk

La API de Solicitudes de Zendesk le ofrece una forma segura de permitir que los usuarios finales interactúen con su sistema de soporte. Al comprender la diferencia entre las API de Solicitudes y Tickets, implementar la autenticación adecuada y seguir las mejores prácticas, puede crear integraciones de autoservicio robustas.

Puntos clave:

• Utilice la API de Solicitudes para las integraciones orientadas al usuario final
• Implemente OAuth con alcance de suplantación de identidad cuando los administradores necesiten actuar en nombre de los usuarios
• Maneje los límites de velocidad y los errores con elegancia
• Pruebe a fondo antes de desplegar en producción

Para más detalles, consulte la documentación oficial de la API de Solicitudes de Zendesk.

Si está buscando automatizar el soporte sin la sobrecarga de desarrollo, explore cómo eesel AI puede ayudar. Nuestros agentes de IA se integran directamente con Zendesk, aprenden de su documentación existente y de los tickets anteriores, y pueden gestionar hasta el 81% del soporte de primera línea de forma autónoma.