API dell'assistenza, eventi ed esportazione in blocco
Tutto quello che serve a un'integrazione dal modulo di assistenza: gli endpoint per casi, conversazioni, SLA, code, catalogo, diritti di assistenza e sondaggi; sottoscrizioni di eventi firmate con nuovi tentativi e riesecuzione; un flusso che riprendi da un cursore; esportazione in blocco di casi e messaggi; e importazione idempotente dello storico dei casi da un altro help desk. Ogni endpoint ha uno strumento corrispondente sul server MCP.
L'assistenza è sempre stata raggiungibile dall'API generica dei record: un caso è un record, quindi elencarne e crearne già funzionava. Quello che non funzionava è tutto ciò che vive accanto al caso e non è un record. La conversazione, l'orologio dello SLA, le code, il catalogo dei servizi, il saldo dei diritti di assistenza e i sondaggi non avevano alcun endpoint, quindi un'integrazione poteva aprire un caso e non poteva rispondergli.
Questo articolo copre gli endpoint dell'assistenza, gli stessi strumenti sul server MCP, le sottoscrizioni di eventi con nuovi tentativi e riesecuzione, il flusso di eventi riprendibile e come portare dentro lo storico dei casi da un altro help desk.
Da dove cominciare - Crea una chiave API in Impostazioni, sezione API e sviluppatori. La chiave individua il tuo account e limita tutto a esso. - Ogni chiamata si autentica come il resto dell'API: Authorization: Bearer seguito dalla tua chiave. - Tutto quello di cui parla questo articolo vive sotto /api/v1/service ed è limitato all'oggetto ticket. Una chiave ristretta ad altri oggetti non ci arriva. - Ogni endpoint ha uno strumento corrispondente sul server MCP, così un agente IA collegato a SellioCRM può fare esattamente le stesse cose.
Casi - GET /api/v1/service/tickets elenca i casi come righe piatte, filtrate per stato, priorità, coda, responsabile o testo libero. Usa updated_since con una marca temporale per portare via solo quello che è cambiato dall'ultima sincronizzazione, e limit e offset per sfogliare le pagine. - GET /api/v1/service/tickets/{id} restituisce un caso con l'orologio dello SLA: la scadenza, se è in pausa, l'obiettivo di prima risposta e quello della risposta successiva. È per quell'orologio che questo endpoint esiste; l'endpoint generico dei record restituisce i campi, non le scadenze. - POST /api/v1/service/tickets apre un caso passando dallo stesso percorso della console, quindi il numero di protocollo, gli obiettivi di SLA, le regole di smistamento e i webhook in uscita avvengono tutti. - PATCH /api/v1/service/tickets/{id} cambia stato, priorità, categoria, coda e assegnatario. Assegnare è lo stesso verbo di cambiare stato, quindi non c'è un endpoint separato. - GET e POST /api/v1/service/tickets/{id}/messages leggono e scrivono la conversazione. kind public risponde al cliente e invia l'e mail; kind internal lascia una nota che vedono solo gli operatori. - POST /api/v1/service/tickets/merge unisce due casi: il secondario viene assorbito dal principale e i suoi messaggi si spostano.
Intorno al caso - GET /api/v1/service/queues elenca le code con la capacità per operatore, gli orari di lavoro e la priorità predefinita. Leggilo prima di smistare: il nome della coda è quello che la chiamata di creazione si aspetta. - GET e POST /api/v1/service/catalog leggono la vetrina del catalogo dei servizi e richiedono un elemento. Una richiesta apre un caso vero con la coda e la priorità dell'elemento; manda un tuo idempotencyKey così un nuovo tentativo restituisce la richiesta esistente invece di aprire un secondo caso. - GET /api/v1/service/entitlements restituisce i diritti di assistenza per account o contratto, con il saldo residuo. - GET /api/v1/service/surveys restituisce gli inviti ai sondaggi di soddisfazione con il loro stato e la data di risposta. I sondaggi anonimi non restituiscono mai chi ha risposto.
Eventi, in tempo reale e per cursore A un'integrazione servono entrambe le metà del tempo reale: essere avvisata nell'istante in cui succede qualcosa e recuperare quello che si è persa mentre era ferma. La prima metà arriva da una sottoscrizione, la seconda dal flusso.
- POST /api/v1/service/subscriptions registra un URL e gli eventi che ti interessano. events accetta tipi esatti oppure un carattere jolly di famiglia, come ticket.* Un evento sconosciuto viene rifiutato per nome, perché una sottoscrizione che non scatta mai è peggio di un errore. Il segreto viene restituito una volta sola; copialo.
- Ogni consegna arriva come POST con tre intestazioni: x-sellio-event con il nome dell'evento, x-sellio-delivery con l'id di quel tentativo e x-sellio-signature nella forma sha256 seguito dal codice calcolato sul corpo esatto con il tuo segreto. Ricalcolalo dalla tua parte e confrontalo; se non coincide, scarta la chiamata.
- Una consegna fallita viene ritentata con attese crescenti, all'incirca un minuto, cinque, trenta, due ore e sei ore. Dopodiché è segnata come morta e resta nel registro.
- GET /api/v1/service/deliveries è la risposta consultabile alla domanda: questo evento è arrivato? Ogni riga porta i tentativi, l'ultimo codice di stato, l'errore e il prossimo tentativo programmato.
- POST /api/v1/service/deliveries/{id}/replay rimanda una consegna. Riesegue il corpo memorizzato, byte per byte lo stesso che era uscito la prima volta. Ricostruire il contenuto adesso manderebbe lo stato di oggi con la data di ieri.
- GET /api/v1/service/events è il flusso. Passa il cursore della risposta precedente e ottieni solo quello che è successo dopo quel punto. nextCursor torna anche su una pagina vuota, ed è quello che devi conservare. Tratta il cursore come opaco: farci sopra dei calcoli è il modo in cui un'integrazione si rompe in silenzio più avanti.
- GET /api/v1/service/event-types elenca ogni evento che il prodotto sa inviare, quale dei tre registri di webhook può sottoscriverlo e se per arrivare a una sottoscrizione dell'assistenza serve il bus degli eventi attivo sul tuo account. Leggilo prima di creare una sottoscrizione.
Esportare casi e messaggi GET /api/v1/service/export accetta entity tickets oppure messages e format json oppure csv. L'esportazione dei messaggi è la ragione per cui questo endpoint esiste: la conversazione non è un record, quindi nessun'altra superficie la consegnava in blocco. Filtra per since, status, queue, ticketId o kind, e sfoglia con limit, fino a 500, e offset. La risposta json porta hasMore, così sai che c'è ancora una pagina che aspetta.
Portare dentro lo storico da un altro help desk POST /api/v1/service/import accetta fino a 500 righe per chiamata. Ogni riga ha bisogno di externalKey, cioè il numero del caso nello strumento che stai lasciando, e di un oggetto. Può portare anche body, e mail, nome e telefono del richiedente, priorità, categoria, coda, canale, stato e createdAt.
- L'importazione è idempotente per externalKey. Importare due volte lo stesso file segnala le righe come già esistenti invece di duplicarle, così puoi rilanciare un lotto fallito senza timori.
- Il caso nasce con la data e lo stato dell'origine. Senza questo, quindicimila casi chiusi entrerebbero come nuovi con la data di oggi, sommergendo la coda di chi sta lavorando adesso e mentendo in ogni report per periodo.
- Manda dryRun true per vedere che cosa succederebbe senza scrivere nulla.
- Una riga che non supera la convalida diventa una voce in problems con la sua posizione nel lotto, e il resto del lotto entra. Una data sbagliata in tre righe non ti costringe a ricominciare da capo.