yTicket Core API Documentazione

Le API di yTicket sono presenti in modalità “sleeping” in ogni yTicket attivato e vanno quindi attivate per potervisi interfacciare.
L’attivazione delle API può essere fatta dall’amministratore andando in Utility->API
e cliccando sul tasto Attiva
Fatto ciò il sistema fornisce una USername ed una Password da utilizzare, insieme alla url del proprio yTicket, per interfacciarsi a yTicket attraverso le API.
Per effettuare una chiamata alle API di yTicket tramite PHP, è sufficente utilizzare la funzione file_get_contents(). Attraverso una URL correttamente parametrizzata, verrà  prodotta una risposta in formato XML formattata secondo il compito richiesto.
La url punta direttamente alla piattaforma yTicket ( http://myname.ticketingsystem.it/api/ ) e si compone di alcuni paramentri obbligatori e facoltativi a seconda della richiesta.
Vediamo di seguito i parametri obbligatori, ovvero quelli che saranno sempre presenti nella nostra url:
  • yws_user
  • yws_password
  • yws_service
yws_user e yws_password sono i parametri che individuano le credenziali per poter accedere ai servizi tramite le nostre API, e vengono firniti da yTIcket all’attivazione delle API, come mostrato in testa a questa guida.
yws_service indica il tipo di richiesta e può assumere i seguenti valori:
open, per l’apertura di un nuovo ticket
details, per ottenere i dettagli relativi ad un ticket
– departements, per ottenere l’elenco dei dipartimenti
– list, per ottenere l’elenco dei tickets
I parametri facoltativi saranno analizzati successivamente, diversificandosi a seconda del tipo di richiesta inoltrata.
ESEMPI
Ipotizziamo di voler ottenere la lista dei dipartimenti attivi sul nostro yTicket, fondamentale se successivamente vorremo, ad esempio, aprire un ticket attraverso un form e dare la possibilità all’utente di scegliere uno di questi dipartimenti tramite un menù a tendina:
$url = 'http://myname.ticketingsystem.it/api/?';
$params = 'yws_user=demouser&yws_password=demopassword&yws_service=departements';
$XMLresult = simplexml_load_file(urlencode($url.$params));
$url è la variabile che contiene la URL, appunto, che punta alle api del nostro yTicket;
– in $param vengono definiti i parametri ed assegnati loro un valore;
– la variabile $XMLresult contiene la risposta alla nostra richiesta nel formato SimpleXMLElement object e, quindi, l’elenco dei dipartimenti come nell’esempio:
echo $XMLresult->item->nome. '('.$XMLresult->item->descrizione.')';
che stampa a video il nome e la descrizione del dipartimento supporto_tecnico (Reparto Tecnico)
Di seguito sono elencati altri pratici esempi che fanno rierimento a tutti i tipi di richiesta sulle API di yTicket:
ELENCO DEI DIPARTIMENTI
Parametri obbligatori: yws_user, yws_password, yws_service
Parametri facoltativi: nessuno
$url = 'http://myname.ticketingsystem.it/api/?';
$params = 'yws_user=demouser&yws_password=demopassword&yws_service=departements';
$XMLresult = simplexml_load_file(urlencode($url.$params));
LISTA TICKET PER DIPARTIMENTO (APERTI E CHIUSI)
Parametri obbligatori: yws_user, yws_password, yws_service, departement_id
Parametri facoltativi: status
$url = 'http://myname.ticketingsystem.it/api/?';
$params = 'yws_user=demouser&yws_password=demopassword&yws_service=list&';
$params.= 'departement_id=1';
$XMLresult = simplexml_load_file(urlencode($url.$params));
Volendo filtrare la lista per stato, bisogna aggiungere il parametro facoltativo status.
Quindi:
status=open per quelli aperti;
status=closed per quelli chiusi.
Di seguito un esempio:
$url = 'http://myname.ticketingsystem.it/api/?';
$params = 'yws_user=demouser&yws_password=demopassword&yws_service=list&';
$params.= 'departement_id=1&status=open';
$XMLresult = simplexml_load_file(urlencode($url.$params));
per tutti i ticket aperti del dipartimento con ID=1 (departement_id=1)
DETTAGLIO TICKET TRAMITE ID
Parametri obbligatori: yws_user, yws_password, yws_service, ticket_id
Parametri facoltativi: nessuno
$url = 'http://myname.ticketingsystem.it/api/?';
$params = 'yws_user=demouser&yws_password=demopassword&yws_service=details&';
$params.= 'ticket_id=125835&customercode=XXXXX';
$XMLresult = simplexml_load_file(urlencode($url.$params));
Ovviamente il parametro ticket_id fa riferimento all’ID stesso del ticket in questione.
Il parametro customercode è il codice cliente assegnato in anagrafica al cliente.
APERTURA DI UN NUOVO TICKET
Parametri obbligatori: yws_user, yws_password, yws_service, departement_id, customer_code, email, subject, description
Parametri facoltativi: contact
$url = 'http://myname.ticketingsystem.it/api/?';
$params = 'yws_user=demouser&yws_password=demopassword&yws_service=open&';
$params.= 'departement_id=1&customer_code=IMSEO&';
$params.= 'email=user@test.com&subject=Ticket TEST&';
$params.= 'description=Lorem ipsum';
$params.= '&contact=Mario Rossi';
$XMLresult = simplexml_load_file(urlencode($url.$params));
I parametri obbligatori da impostare nella variabile $params per l’apertura di un ticket sono molteplici ma li analizzeremo uno per uno:
– departement_id, nulla di nuovo, rappresenta l’ID del dipartimento su cui si vuol aprire il nuovo ticket;
– customer_code, rappresenta il codice identificativo univoco dato da IMSEO;
– email, la mail dell’utente che sta aprendo il ticket;
– subject, è l’oggetto del ticket;
– description, contiene il testo del ticket stesso.
L’unico parametro facoltativo è “contact”, che rappresenta il nome dell’utente che vuole aprire un ticket.
2014-10-16T10:09:09+00:00