Saltar al contenido

Tickets

Bandeja compartida, formularios y automatizaciones para las solicitudes de los clientes.

Abrir Tickets
Comprobado con el panel el 18 de noviembre de 2026

La API de tickets permite que software externo a Xuda trabaje un escritorio: abrir un ticket, enumerar y leer tickets, responder, asignar, mover un ticket entre etapas y cerrarlo, y leer los temas y el equipo. Los formularios, los flujos de trabajo, los agentes de IA, las notas internas y la configuración se quedan en el dashboard.

Cada llamada es un POST a https://xuda.ai/cpi/<method> con un cuerpo JSON que lleva la clave de API de tu cuenta como api_key. Una llamada trabaja sobre el escritorio de la cuenta propietaria de la clave, bajo el plan de ese escritorio, y no puede nombrar otro escritorio. Crea la clave en el dashboard, en Desarrolladores, y mantenla fuera de páginas y de código público.

La respuesta es { "code": ..., "data": ... }. Un code positivo es éxito. Un rechazo es un código negativo con una frase en data.

curl -s https://xuda.ai/cpi/ticket_api_submit \
  -H 'content-type: application/json' \
  -d '{"api_key":"YOUR_API_KEY","name":"Jordan Lee","email":"[email protected]","subject":"Export fails","details":"The export button returns a 500."}'
const res = await fetch('https://xuda.ai/cpi/ticket_api_submit', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    api_key: 'YOUR_API_KEY',
    name: 'Jordan Lee',
    email: '[email protected]',
    subject: 'Export fails',
    details: 'The export button returns a 500.',
  }),
});
const { code, data } = await res.json();
import requests

res = requests.post(
    'https://xuda.ai/cpi/ticket_api_submit',
    json={
        'api_key': 'YOUR_API_KEY',
        'name': 'Jordan Lee',
        'email': '[email protected]',
        'subject': 'Export fails',
        'details': 'The export button returns a 500.',
    },
)

name y details son obligatorios. Se crea o se reutiliza un contacto a partir de email, el ticket se registra con el origen api, y la respuesta es una vista reducida: número, id, estado, etapa, asunto, tema, solicitante, el id del responsable y las marcas de tiempo. Nunca se devuelven ids internos ni el estado de la automatización.

email es opcional cuando una integración o un agente registra el ticket por sí mismo: envía solo un name, y no se crea ningún contacto ni se envía nada por correo al solicitante.

Los campos opcionales dan al ticket un subject, phone, company, un topic_id y subtopic_id de los temas del escritorio, tu propio reference_id, una priority de 1 (la más alta) a 4, un type (issue, bug, feature o task) y attachments.

Para entregar el ticket nuevo a alguien, nómbralo con assignee_uid o assignee_email, uno de los dos. Debe estar en el equipo del espacio de trabajo del escritorio, que son su propietario y los miembros aceptados del espacio de trabajo. Un responsable rechazado no registra ningún ticket.

Encuentra y lee tickets

ticket_api_list enumera tickets con los filtros que tiene el dashboard: status (open o closed), source, topic_id, type, assignee_uid, reference_id, un search de texto libre sobre asunto, detalles y número de ticket, y un rango created_from y created_to. Ordena con sort (date_created_ts, last_activity_ts, status_ts o priority) y dir, y pagina con limit (hasta 500) y el bookmark de la respuesta anterior.

ticket_api_get lee un ticket por ticket_id, con sus interacciones públicas. Nunca se devuelven notas internas ni borradores de IA.

ticket_api_topics devuelve los temas y subtemas del escritorio, para que tu propio formulario pueda mostrar el mismo selector que el formulario alojado. ticket_api_team devuelve las personas a las que se puede asignar un ticket, cada una con un uid, un nombre y un email.

curl -s https://xuda.ai/cpi/ticket_api_reply \
  -H 'content-type: application/json' \
  -d '{"api_key":"YOUR_API_KEY","ticket_id":"TICKET_ID","body":"Thanks, we are looking into it."}'
curl -s https://xuda.ai/cpi/ticket_api_set_stage \
  -H 'content-type: application/json' \
  -d '{"api_key":"YOUR_API_KEY","ticket_id":"TICKET_ID","status_stage":"in_progress"}'
curl -s https://xuda.ai/cpi/ticket_api_close \
  -H 'content-type: application/json' \
  -d '{"api_key":"YOUR_API_KEY","ticket_id":"TICKET_ID","reason":"Fixed in the latest release."}'
  • ticket_api_reply siempre publica una respuesta pública, nunca una nota interna. Es el escritorio respondiendo, salvo que pases as_requester: true, que la publica como mensaje propio del solicitante. En ese caso se notifica al responsable, o al propietario del escritorio, y no cuenta como la primera respuesta del escritorio.
  • ticket_api_set_stage mueve un ticket abierto a new, in_progress, waiting_customer o resolved. Un ticket cerrado se rechaza salvo que pases reopen: true, que lo abre de nuevo en esa etapa. Nombrar la etapa que el ticket ya tiene no cambia nada.
  • ticket_api_assign da un ticket a una persona del equipo por assignee_uid o assignee_email. Nombrar al responsable actual no cambia nada. Si más de un miembro del equipo tiene ese email, la llamada se rechaza con -409 y pasas el uid en su lugar.
  • ticket_api_close cierra el ticket. El reason opcional se muestra al cliente. Una respuesta del cliente dentro del plazo de reapertura devuelve el ticket.

Lee la lista propia del escritorio

get_support_tickets devuelve los tickets a la cuenta con sesión iniciada que es propietaria del escritorio, y se puede limitar a un ticket con _id. Tiene una forma distinta de la vista ticket_api_*, que está pensada para un llamante externo a Xuda.

Planes y límites

El plan decide qué puede hacer una clave. Leer (ticket_api_list, ticket_api_get, ticket_api_topics, ticket_api_team) requiere acceso de lectura, y escribir (ticket_api_submit, ticket_api_reply, ticket_api_set_stage, ticket_api_assign, ticket_api_close) requiere acceso completo. Un plan sin él responde -402. Cada plan tiene además un número de llamadas por minuto, y al superarlo una llamada se responde -429 hasta el minuto siguiente. El historial sigue la ventana de retención del plan, así que un ticket más antiguo que ella no se puede leer. La página de planes tiene las cifras.

Un ticket nuevo cuenta contra el límite del mes, igual que por cualquier otra vía de entrada.

Métodos

¿Qué te parece esta guía?

Última actualización: 16 de noviembre de 2026