Tickets
Bandeja compartida, formularios y automatizaciones para las solicitudes de los clientes.
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.
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.
ticket_api_replysiempre publica una respuesta pública, nunca una nota interna. Es el escritorio respondiendo, salvo que pasesas_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_stagemueve un ticket abierto anew,in_progress,waiting_customeroresolved. Un ticket cerrado se rechaza salvo que pasesreopen: true, que lo abre de nuevo en esa etapa. Nombrar la etapa que el ticket ya tiene no cambia nada.ticket_api_assignda un ticket a una persona del equipo porassignee_uidoassignee_email. Nombrar al responsable actual no cambia nada. Si más de un miembro del equipo tiene ese email, la llamada se rechaza con-409y pasas el uid en su lugar.ticket_api_closecierra el ticket. Elreasonopcional 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.