Vai al contenuto

Tickets

Casella condivisa, moduli e automazioni per le richieste dei clienti.

Apri Tickets
Verificato rispetto alla dashboard il 18 novembre 2026

L'API dei ticket permette a un software esterno a Xuda di lavorare un help desk: aprire un ticket, elencare e leggere i ticket, rispondere, assegnare, spostare un ticket tra le fasi e chiuderlo, e leggere gli argomenti e il team. Moduli, flussi di lavoro, agenti AI, note interne e impostazioni restano nella dashboard.

Ogni chiamata è una POST a https://xuda.ai/cpi/<method> con un corpo JSON che porta la chiave API del tuo conto come api_key. Una chiamata lavora sull'help desk del conto che possiede la chiave, secondo il piano di quell'help desk, e non può nominarne un altro. Crea la chiave nella dashboard in Sviluppatori e tienila fuori da pagine e codice pubblico.

La risposta è { "code": ..., "data": ... }. Un code positivo indica successo. Un rifiuto è un codice negativo con una frase in 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 e details sono obbligatori. Un contatto viene creato o riutilizzato a partire da email, il ticket viene registrato con l'origine api, e la risposta è una vista ridotta: numero, id, stato, fase, oggetto, argomento, richiedente, l'id dell'assegnatario e i timestamp. Gli id interni e lo stato dell'automazione non vengono mai restituiti.

email è facoltativa quando un'integrazione o un agente registra il ticket per sé: invia solo un name, e non viene creato alcun contatto e non viene inviato nulla al richiedente.

I campi facoltativi danno al ticket un subject, phone, company, un topic_id e un subtopic_id tra gli argomenti dell'help desk, un tuo reference_id, una priority da 1 (la più alta) a 4, un type (issue, bug, feature o task) e attachments.

Per affidare il nuovo ticket a qualcuno, indicalo con assignee_uid o assignee_email, uno dei due. Deve far parte del team del workspace dell'help desk, cioè il suo proprietario e i membri accettati del workspace. Un assegnatario rifiutato non fa registrare alcun ticket.

Trova e leggi i ticket

ticket_api_list elenca i ticket con i filtri che ha la dashboard: status (open o closed), source, topic_id, type, assignee_uid, reference_id, una search a testo libero su oggetto, dettagli e numero del ticket, e un intervallo created_from e created_to. Ordina con sort (date_created_ts, last_activity_ts, status_ts o priority) e dir, e scorri con limit (fino a 500) e il bookmark della risposta precedente.

ticket_api_get legge un ticket per ticket_id, con le sue interazioni pubbliche. Le note interne e le bozze dell'AI non vengono mai restituite.

ticket_api_topics restituisce gli argomenti e i sottoargomenti dell'help desk, così il tuo modulo può mostrare lo stesso selettore del modulo ospitato. ticket_api_team restituisce le persone a cui si può assegnare un ticket, ciascuna con un uid, un nome e 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 pubblica sempre una risposta pubblica, mai una nota interna. È l'help desk che risponde, a meno che tu non passi as_requester: true, che la pubblica come messaggio del richiedente stesso. In quel caso l'assegnatario, o il proprietario dell'help desk, riceve una notifica, e non conta come prima risposta dell'help desk.
  • ticket_api_set_stage sposta un ticket aperto a new, in_progress, waiting_customer o resolved. Un ticket chiuso viene rifiutato a meno che tu non passi reopen: true, che lo riapre in quella fase. Indicare la fase che il ticket ha già non cambia nulla.
  • ticket_api_assign affida un ticket a una persona del team tramite assignee_uid o assignee_email. Indicare l'assegnatario attuale non cambia nulla. Se più di un membro del team ha quell'email, la chiamata viene rifiutata con -409 e passi invece l'uid.
  • ticket_api_close chiude il ticket. Il reason facoltativo viene mostrato al cliente. Una risposta del cliente entro la finestra di riapertura riporta indietro il ticket.

Leggi l'elenco dell'help desk stesso

get_support_tickets rilegge i ticket per il conto con accesso effettuato che possiede l'help desk, e può essere limitato a un ticket con _id. Ha una forma diversa dalla vista ticket_api_*, che è pensata per chi chiama dall'esterno di Xuda.

Piani e limiti

Il piano decide che cosa può fare una chiave. Leggere (ticket_api_list, ticket_api_get, ticket_api_topics, ticket_api_team) richiede l'accesso in lettura, e scrivere (ticket_api_submit, ticket_api_reply, ticket_api_set_stage, ticket_api_assign, ticket_api_close) richiede l'accesso completo. Un piano che non lo prevede risponde -402. Ogni piano ha inoltre un numero di chiamate al minuto, e oltre quel numero una chiamata riceve -429 fino al minuto successivo. La cronologia segue la finestra di conservazione del piano, quindi un ticket più vecchio di essa non può essere letto. La pagina dei piani ha le cifre.

Un nuovo ticket conta rispetto al limite del mese, come da qualsiasi altro canale di accesso.

Metodi

Come ti sembra questa guida?

Ultimo aggiornamento il 16 novembre 2026