zendesk-api-create-user

{
  "title": "Cómo crear usuarios con la API de Zendesk: Una guía completa",
  "slug": "zendesk-api-create-user",
  "locale": "es",
  "date": "2026-03-02",
  "updated": "2026-03-02",
  "template": "default",
  "excerpt": "Domina la API de Usuarios de Zendesk con esta guía práctica. Desde la configuración de la autenticación hasta la creación de usuarios individuales y masivos, con ejemplos de código funcionales.",
  "categories": [
    "Zendesk",
    "Guides"
  ],
  "tags": [
    "Zendesk API",
    "User Management",
    "API Tutorial",
    "Customer Support",
    "Automation"
  ],
  "readTime": 11,
  "author": 16,
  "reviewer": 14,
  "seo": {
    "title": "Cómo crear usuarios con la API de Zendesk: Una guía completa",
    "description": "Domina la API de Usuarios de Zendesk con esta guía práctica. Desde la configuración de la autenticación hasta la creación de usuarios individuales y masivos, con ejemplos de código funcionales.",
    "image": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-d5ed2efa-d065-4232-8e40-752085db593e"
  },
  "coverImage": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-d5ed2efa-d065-4232-8e40-752085db593e",
  "coverImageAlt": "Imagen de banner para Cómo crear usuarios con la API de Zendesk: Una guía completa",
  "coverImageWidth": 1920,
  "coverImageHeight": 1080,
  "faqs": {
    "heading": "Preguntas Frecuentes",
    "type": "blog",
    "answerType": "html",
    "faqs": [
      {
        "question": "¿Puedo crear usuarios sin enviar un correo electrónico de verificación?",
        "answer": "Sí. Incluya 'verified': true en el objeto de usuario al crear el usuario. Esto marca el correo electrónico como verificado y omite el correo electrónico de verificación."
      },
      {
        "question": "¿Cuál es la diferencia entre la API de Usuarios y la API de Solicitudes?",
        "answer": "La API de Usuarios gestiona las cuentas de usuario (crear, actualizar, eliminar). La API de Solicitudes es para que los usuarios finales creen y vean sus propios tickets. Utilice la API de Usuarios para la gestión administrativa de usuarios."
      },
      {
        "question": "¿Cómo actualizo la dirección de correo electrónico de un usuario?",
        "answer": "No puede actualizar directamente el correo electrónico principal a través de la API de Usuarios. En su lugar, utilice la API de Identidades de Usuario para añadir una nueva identidad de correo electrónico y, a continuación, convertirla en principal."
      },
      {
        "question": "¿Puedo crear usuarios con varias direcciones de correo electrónico?",
        "answer": "Sí. Utilice la matriz 'identities' al crear el usuario para incluir varias direcciones de correo electrónico."
      },
      {
        "question": "¿Qué permisos necesito para crear usuarios a través de la API?",
        "answer": "Necesita permisos de administrador, o permisos de agente con un rol personalizado que incluya los permisos 'Puede gestionar usuarios finales' o 'Puede gestionar miembros del equipo'."
      },
      {
        "question": "¿Existe un límite de velocidad para la creación de usuarios?",
        "answer": "Sí. Zendesk aplica límites de velocidad basados en su plan. Si alcanza los límites, la API devuelve un estado 429 con una cabecera Retry-After que indica cuándo volver a intentarlo."
      }
    ],
    "supportLink": null
  }
}
---

Gestionar cuentas de usuario a escala es una de esas tareas que empieza siendo sencilla y se complica rápidamente. Ya sea que esté incorporando clientes de una nueva adquisición, sincronizando usuarios de su base de datos interna o creando un flujo de registro de autoservicio, eventualmente necesitará crear usuarios de Zendesk de forma programática.

La [API de Usuarios de Zendesk](https://developer.zendesk.com/api-reference/ticketing/users/users/) le brinda las herramientas para hacer esto. Es una API RESTful que maneja todo, desde la creación de usuarios individuales hasta la importación masiva de miles a la vez. Esta guía lo guía a través de los pasos prácticos para que funcione, con ejemplos de código funcionales que puede adaptar a su pila (stack).

Si busca automatizar algo más que la creación de usuarios, herramientas como [eesel AI](https://www.eesel.ai) pueden manejar todo el espectro de la automatización del soporte, desde el enrutamiento de tickets hasta las respuestas impulsadas por IA.

![Página de inicio de Zendesk que muestra la interfaz de la plataforma de servicio al cliente.](https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/screenshots/zendesk-landing-page.png)

## Lo que necesitará

Antes de comenzar a realizar llamadas a la API, asegúrese de tener:

- **Una cuenta de Zendesk con acceso de administrador**: solo los administradores pueden crear tokens de API y administrar usuarios a través de la API
- **Un token de API o credenciales de OAuth**: cubriremos cómo generar estos a continuación
- **Familiaridad básica con las API REST**: debe saber qué es una solicitud POST
- **Un entorno de desarrollo**: cURL, Python o Node.js funcionarán bien

## Paso 1: configurar la autenticación de la API

Zendesk admite dos métodos principales de autenticación para el acceso a la API: tokens de API y OAuth. Para la mayoría de las integraciones de servidor a servidor, los tokens de API son más sencillos de implementar.

### Generación de un token de API

1. Inicie sesión en su cuenta de Zendesk como administrador
2. Navegue al **Centro de administración** (haga clic en el icono de engranaje, luego en "Ir al Centro de administración")
3. Vaya a **Aplicaciones e integraciones** → **API** → **API de Zendesk**
4. Haga clic en la pestaña **Configuración** y asegúrese de que **Acceso de token** esté habilitado
5. Cambie a la pestaña **Tokens de API** y haga clic en **Agregar token de API**
6. Ingrese un nombre descriptivo como "Integración de sincronización de usuarios"
7. Copie el token inmediatamente: Zendesk solo lo muestra una vez

![Página de configuración del token de API del Centro de administración de Zendesk que muestra el botón Agregar token de API y una lista de tokens de API](https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ac_api_token_list2.png)

### Formateo de su encabezado de autenticación

Zendesk utiliza la autenticación básica con su token de API. El formato es:

- **Nombre de usuario**: su dirección de correo electrónico de Zendesk con `/token` añadido (por ejemplo, `you@company.com/token`)
- **Contraseña**: el token de API en sí

Codifique en Base64 estas credenciales e inclúyalas en el encabezado de autorización:

```bash
curl https://your-subdomain.zendesk.com/api/v2/users.json \
  -u you@company.com/token:your_api_token_here

O en Python:

import requests
from requests.auth import HTTPBasicAuth

subdomain = "your-subdomain"
email = "you@company.com"
token = "your_api_token_here"

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

url = f"https://{subdomain}.zendesk.com/api/v2/users.json"
response = requests.get(url, auth=auth, headers=headers)
print(response.json())

Mejores prácticas de seguridad

• Almacene los tokens de API en variables de entorno, nunca en su código
• Rote los tokens periódicamente: elimine los antiguos y genere nuevos
• Utilice nombres de token descriptivos para que sepa para qué es cada uno
• Elimine los tokens cuando las integraciones se retiren
• Considere la posibilidad de crear un usuario de servicio dedicado con permisos limitados en lugar de utilizar el token de un administrador

Paso 2: crear un solo usuario

La forma más sencilla de crear un usuario es a través del punto final POST /api/v2/users. Como mínimo, debe proporcionar un nombre.

Parámetros obligatorios y opcionales

Parámetro	Obligatorio	Descripción
name	Sí	El nombre completo del usuario
email	No	Dirección de correo electrónico principal (crea una identidad)
role	No	end-user (predeterminado), agent o admin
organization_id	No	ID de la organización a asignar
external_id	No	El identificador único de su sistema para este usuario
verified	No	Establecer en true para omitir la verificación por correo electrónico

Comprensión de los roles de usuario

Zendesk tiene tres roles integrados:

• end-user: Clientes que envían tickets (predeterminado si no se especifica ningún rol)
• agent: Personal de soporte que gestiona los tickets
• admin: Acceso administrativo completo

Para los planes Enterprise, también puede asignar roles de agente personalizados utilizando el parámetro custom_role_id. Tenga en cuenta que los roles personalizados deben crearse primero en el Centro de administración; no puede crearlos a través de la API.

Ejemplos de código

cURL:

curl https://your-subdomain.zendesk.com/api/v2/users.json \
  -d '{"user": {"name": "Jane Smith", "email": "jane@example.com", "role": "end-user"}}' \
  -H "Content-Type: application/json" \
  -X POST \
  -u you@company.com/token:your_api_token

Python:

import requests
import json
from requests.auth import HTTPBasicAuth

subdomain = "your-subdomain"
auth = HTTPBasicAuth("you@company.com/token", "your_api_token")
headers = {"Content-Type": "application/json"}

user_data = {
    "user": {
        "name": "Jane Smith",
        "email": "jane@example.com",
        "role": "end-user",
        "external_id": "user_12345"
    }
}

response = requests.post(
    f"https://{subdomain}.zendesk.com/api/v2/users.json",
    auth=auth,
    headers=headers,
    json=user_data
)

if response.status_code == 201:
    user = response.json()["user"]
    print(f"Created user {user['id']}: {user['name']}")
else:
    print(f"Error: {response.status_code} - {response.text}")

JavaScript (Node.js con axios):

const axios = require('axios');

const subdomain = 'your-subdomain';
const email = 'you@company.com';
const token = 'your_api_token';

const userData = {
  user: {
    name: 'Jane Smith',
    email: 'jane@example.com',
    role: 'end-user',
    external_id: 'user_12345'
  }
};

axios.post(
  `https://${subdomain}.zendesk.com/api/v2/users.json`,
  userData,
  {
    auth: {
      username: `${email}/token`,
      password: token
    },
    headers: {
      'Content-Type': 'application/json'
    }
  }
)
.then(response => {
  const user = response.data.user;
  console.log(`Created user ${user.id}: ${user.name}`);
})
.catch(error => {
  console.error('Error:', error.response?.data || error.message);
});

Interpretación de la respuesta

Una creación exitosa devuelve HTTP 201 Created con el objeto de usuario:

{
  "user": {
    "id": 9873843,
    "name": "Jane Smith",
    "email": "jane@example.com",
    "role": "end-user",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "active": true,
    "verified": false
  }
}

Paso 3: crear o actualizar usuarios (upsert)

¿Qué sucede si intenta crear un usuario que ya existe? El punto final de creación estándar devuelve un error 422. Para escenarios de sincronización en los que importa usuarios regularmente desde un sistema externo, utilice el punto final create_or_update en su lugar.

Cuándo utilizar create_or_update

Utilice POST /api/v2/users/create_or_update cuando:

• Esté sincronizando usuarios desde una base de datos externa
• Desee operaciones idempotentes (la misma solicitud produce el mismo resultado)
• No desee comprobar si existe un usuario antes de crearlo

Cómo funciona la coincidencia

Zendesk hace coincidir a los usuarios por:

1. ID externo: si se proporciona, tiene prioridad
2. Dirección de correo electrónico: si no se encuentra ninguna coincidencia de ID externo

Códigos de respuesta

Estado	Significado
201 Created	Se creó un nuevo usuario
200 OK	Se actualizó el usuario existente

Ejemplo práctico: sincronización desde un sistema externo

import requests
from requests.auth import HTTPBasicAuth

auth = HTTPBasicAuth("you@company.com/token", "your_api_token")
headers = {"Content-Type": "application/json"}

external_users = [
    {"name": "Jane Smith", "email": "jane@example.com", "external_id": "usr_001"},
    {"name": "John Doe", "email": "john@example.com", "external_id": "usr_002"}
]

for external_user in external_users:
    user_data = {"user": external_user}

    response = requests.post(
        "https://your-subdomain.zendesk.com/api/v2/users/create_or_update.json",
        auth=auth,
        headers=headers,
        json=user_data
    )

    if response.status_code == 201:
        print(f"Created: {external_user['email']}")
    elif response.status_code == 200:
        print(f"Updated: {external_user['email']}")
    else:
        print(f"Failed: {external_user['email']} - {response.text}")

Paso 4: crear varios usuarios en masa

Si necesita crear cientos o miles de usuarios, las llamadas API individuales son ineficientes. Zendesk proporciona un punto final masivo que acepta hasta 100 usuarios por solicitud.

Punto final y limitaciones

• Punto final: POST /api/v2/users/create_many
• Límite: 100 usuarios por solicitud
• Habilitación: Las importaciones masivas deben ser habilitadas por el soporte de Zendesk (póngase en contacto con ellos si recibe errores 403)

Comprensión de las respuestas job_status

A diferencia de la creación de un solo usuario, las operaciones masivas son asíncronas. La API devuelve inmediatamente un objeto job_status y la creación real se realiza en segundo plano:

{
  "job_status": {
    "id": "82de0b044094f0c67893ac9fe64f1a99",
    "status": "queued",
    "total": 50,
    "progress": 0,
    "url": "https://your-subdomain.zendesk.com/api/v2/job_statuses/82de0b044094f0c67893ac9fe64f1a99"
  }
}

Sondee la URL del estado del trabajo para realizar un seguimiento del progreso:

def check_job_status(job_url):
    response = requests.get(job_url, auth=auth)
    job = response.json()["job_status"]

    print(f"Status: {job['status']}, Progress: {job['progress']}/{job['total']}")

    if job["status"] == "completed":
        for result in job.get("results", []):
            print(f"  {result['action']}: User {result['id']} - {result['status']}")

    return job["status"]

import time
while check_job_status(job_url) != "completed":
    time.sleep(5)

Cuándo tiene sentido la creación masiva

Escenario	Enfoque
1-50 usuarios	Llamadas API individuales
50-10,000 usuarios	API masiva con procesamiento por lotes
Más de 10,000 usuarios	Póngase en contacto con Zendesk para obtener ayuda con la importación

Ejemplo de creación masiva

users_to_create = [
    {"name": "User One", "email": "user1@example.com", "role": "end-user"},
    {"name": "User Two", "email": "user2@example.com", "role": "end-user"},
    # ... hasta 100 usuarios
]

response = requests.post(
    "https://your-subdomain.zendesk.com/api/v2/users/create_many.json",
    auth=auth,
    headers=headers,
    json={"users": users_to_create}
)

if response.status_code == 200:
    job = response.json()["job_status"]
    print(f"Job queued: {job['id']}")
else:
    print(f"Error: {response.status_code} - {response.text}")

Errores comunes y solución de problemas

Incluso con el código correcto, las cosas pueden salir mal. Aquí le mostramos cómo manejar los problemas más comunes:

401 No autorizado

Sus credenciales de autenticación no son válidas. Compruebe:

• ¿Es correcta la dirección de correo electrónico?
• ¿Añadió /token al nombre de usuario?
• ¿El token de API sigue activo (no eliminado)?
• ¿Está utilizando el subdominio correcto?

403 Prohibido

No tiene permiso para esta acción. Causas comunes:

• El token de API pertenece a un agente, no a un administrador
• Las importaciones masivas no están habilitadas en su cuenta (póngase en contacto con el soporte de Zendesk)
• Está intentando crear un usuario administrador sin los permisos suficientes

422 Entidad no procesable

Los datos de la solicitud no son válidos. Compruebe:

• ¿Está presente el campo name? (es obligatorio)
• ¿Es válido el formato del correo electrónico?
• ¿Es el rol uno de los siguientes: end-user, agent, admin?
• ¿Existe el organization_id?

429 Demasiadas solicitudes

Ha alcanzado el límite de velocidad de Zendesk. La API devuelve un encabezado Retry-After que indica cuántos segundos debe esperar. Implemente una retirada exponencial en su código:

import time

def api_call_with_retry(url, auth, headers, json_data, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(url, auth=auth, headers=headers, json=json_data)

        if response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 60))
            print(f"Rate limited. Waiting {retry_after} seconds...")
            time.sleep(retry_after)
            continue

        return response

    raise Exception("Max retries exceeded")

Errores de correo electrónico duplicado

Si recibe un error 422 que menciona "El correo electrónico ya ha sido tomado", ya sea:

• Utilice el punto final create_or_update en su lugar
• Compruebe primero si el usuario existe con GET /api/v2/users/search?query=email@example.com

Mejores prácticas para la automatización de la gestión de usuarios

Después de trabajar con la API de Usuarios de Zendesk, estos son los patrones que funcionan consistentemente bien:

Utilice external_id para la idempotencia

Incluya siempre un external_id que se asigne a su ID de usuario interno. Esto hace que las operaciones sean idempotentes y simplifica la sincronización:

user_data = {
    "user": {
        "name": "Jane Smith",
        "email": "jane@example.com",
        "external_id": f"internal_db_{internal_user_id}"
    }
}

Establezca el estado verificado para omitir la verificación por correo electrónico

Si está creando usuarios desde una fuente confiable (como su propia base de datos), establezca verified: true para evitar que Zendesk envíe correos electrónicos de verificación:

user_data = {
    "user": {
        "name": "Jane Smith",
        "email": "jane@example.com",
        "verified": True  # Omitir el correo electrónico de verificación
    }
}

Maneje los roles personalizados correctamente

Los roles personalizados son una característica de Enterprise. Para asignarlos:

1. Cree primero el rol personalizado en el Centro de administración
2. Obtenga el custom_role_id de la URL o API del rol
3. Establezca tanto role: "agent" como custom_role_id: 12345

Implemente un manejo de errores adecuado

No asuma que las llamadas API tienen éxito. Incluya las llamadas en bloques try/except y maneje casos de error específicos:

try:
    response = requests.post(url, auth=auth, headers=headers, json=data)
    response.raise_for_status()
except requests.exceptions.HTTPError as e:
    if response.status_code == 422:
        errors = response.json().get("details", {})
        print(f"Validation error: {errors}")
    else:
        raise

Almacene las credenciales de forma segura

Nunca codifique los tokens de API. Utilice variables de entorno:

import os

ZENDESK_SUBDOMAIN = os.environ.get("ZENDESK_SUBDOMAIN")
ZENDESK_EMAIL = os.environ.get("ZENDESK_EMAIL")
ZENDESK_TOKEN = os.environ.get("ZENDESK_TOKEN")

Considere las necesidades de automatización más amplias

Si está automatizando la creación de usuarios, es probable que esté gestionando una operación de soporte cada vez mayor. Si bien la API de Zendesk gestiona la gestión de usuarios, es posible que también necesite automatizar la gestión, el enrutamiento y las respuestas de los tickets. eesel AI se integra con Zendesk para gestionar estos flujos de trabajo automáticamente, desde clasificar y etiquetar tickets hasta redactar respuestas impulsadas por IA.

Comience a automatizar sus flujos de trabajo de Zendesk

Ahora tiene la base para crear usuarios de Zendesk de forma programática. Ya sea que esté creando una integración de sincronización de usuarios, automatizando la incorporación o gestionando una gran base de clientes, la API de Usuarios le brinda el control que necesita.

Los patrones de esta guía (autenticación, creación única, upserts y operaciones masivas) cubren la mayoría de los escenarios del mundo real. Comience con el punto final de usuario único para validar su configuración, luego pase a las operaciones masivas a medida que aumente su escala.

Si busca automatizar más allá de la creación de usuarios, considere cómo la IA puede optimizar todo su flujo de trabajo de soporte. eesel AI se integra con Zendesk para gestionar la clasificación de tickets, la redacción de respuestas y el enrutamiento inteligente, lo que reduce el trabajo manual y mejora los tiempos de respuesta. Puede explorar nuestro agente de IA para el servicio de atención al cliente para ver cómo la automatización puede extenderse a lo largo de su pila de soporte.