Punto di arrivo dei biglietti

Esempio: Creazione di un ticket

POST /Import/JSON/tickets
Authorization: Bearer {token}
Content-Type: application/json

{
  "type": "tickets",
  "data": [{
    "ticket_subject": "API-Test-Ticket",
    "ticket_customers_email": "kunde@example.com",
    "ticket_customers_name": "Max Mustermann",
    "ticket_priority_id": 2,
    "ticket_department_id": 1,
    "ticket_comments": "Erstellt via xoPort API",
    "admin_id": 0,
    "attachments": [
      { "name": "bestellung.pdf", "content_base64": "JVBERi0xLjQKJcfs…" }
    ],
    "assigned_admins": [1, 3]
  }]
}

Formato dei commenti

"ticket_comments": "Nota interna tramite API",
"admin_id": 1

ticket_comments è il testo del commento, admin_id è il suo autore (0 = sistema, >0 = ID amministratore, viene convalidato).

Esempio: aggiornamento di un ticket con commento

PUT /Import/JSON/tickets
Authorization: Bearer {token}
Content-Type: application/json

{
  "type": "tickets",
  "data": [{
    "ticket_id": 42,
    "ticket_status_id": 3,
    "ticket_priority_id": 1,
    "ticket_comments": "Status auf Erledigt gesetzt",
    "admin_id": 1,
    "assigned_admins": [1, 5]
  }]
}

Nell'esportazione, ogni ticket contiene un array linked_appointments[] con gli appuntamenti CRM collegati:

"linked_appointments": [
 {
    "appointment_id": 15,
    "startdate": "2026-04-14 10:00:00",
    "enddate": "2026-04-14 11:00:00",
    "allday": 0,
    "done": 0,
    "status_id": 1,
    "title": "Rückruf Kunde",
    "description": "Bezüglich offener Rückfrage",
    "location": ""
  } 
]

Gli appuntamenti vengono collegati tramite xocrm_appointments_relationships (target_type = ticket_id). L'eliminazione di un ticket rimuove solo il collegamento, non l'appuntamento stesso.

Corretto nella v2.118.1: linked_appointments su POST/PUT /Import/JSON/tickets generava anche l’avviso UNKNOWN_FIELD, sebbene gli appuntamenti fossero stati creati. L’avviso non viene più visualizzato; l’elaborazione rimane invariata.

Gli allegati vengono identificati tramite l’ID del ticket:

Listing: GET /ticket_attachments/{id}

{
  "success": true,
  "ticket_id": 42,
  "ticket_link_id": "8i1c5O8g7w8b5c",
  "files": [
    {
      "name": "screenshot.png",
      "size": 245760,
      "mime_type": "image/png",
      "last_modified": "2026-03-15 14:30:22"
    }
  ]
}

Download: GET /ticket_attachment/{id}?file=screenshot.png

Download di file binari con Content-Type e Content-Disposition corretti : header "attachment". Protezione dal path traversal tramite validazione basename() + realpath().

Caricamento: attachments[] su POST/PUT NOVITÀ v2.60.0

Fino alla v2.59.0 gli allegati erano solo in lettura — venivano caricati esclusivamente tramite il modulo del backend. Un ticket creato tramite API rimaneva quindi privo di allegati (PDF, .eml, screenshot). A partire dalla v2.60.0,POST/PUT /Import/JSON/tickets accetta il campo opzionale attachments[]:

"ticket_comments": "Allegato relativo al reclamo",
"admin_id": 1,
"attachments": [
 {
    "name": "rechnung.pdf",
    "content_base64": "JVBERi0xLjQKJcfs…"
  } 
]

L'archiviazione avviene tramite lo stesso meccanismo del caricamento sul backend: stessa lista di estensioni consentite, convenzione di denominazione __ e deduplicazione tramite hash per evitare il doppio salvataggio. Il nome del file effettivamente assegnato è riportato nella risposta alla voce attachments per ogni record. Il limite massimo per ogni file corrisponde all’endpoint /media(XOPORT_MEDIA_MAX_FILESIZE, valore predefinito 10 MB).

Le voci errate (estensione non consentita, Base64 non valido, superamento della dimensione massima) generano un errore per ogni file; l’aggiornamento del ticket stesso va comunque a buon fine. Se is_public_reply: true è impostato insieme a notify_customer: true, i file vengono inviati tramite l’e-mail del cliente — vengono scritti prima dell’invio.

Un claim indica che qualcuno sta attualmente lavorando su un ticket, ad esempio un agente IA per conto di un collaboratore. Gli altri responsabili lo vedono nell’esportazione e nel backend (elenco ticket e vista ticket) e non iniziano a lavorarci in parallelo. La richiesta di elaborazione è un’indicazione, non un blocco: non è protetta da accesso in scrittura, il ticket rimane modificabile da tutti.

PUT /Import/JSON/ticket_claims
{
  "type": "ticket_claims",
  "data": [
    { "ticket_id": 33999, "admin_id": 12, "state": "claimed", "ttl_minutes": 60, "label": "KI-Agent" }
  ]
}

Risultato per ogni record

records[].status indica il risultato, records[].claim lo stato dopo la chiamata:

Risposta (HTTP 200) se un altro amministratore effettua una richiesta mentre Max Mustermann detiene il claim:

{
  "success": false,
  "outcome": "failed",
  "api_version": "2.118.1",
  "type": "ticket_claims",
  "stats": { "total": 1, "claimed": 0, "refreshed": 0, "taken_over": 0, "released": 0, "unchanged": 0, "failed": 1 },
  "errors": [
    { "record": 1, "error": "Ticket 33999 is claimed by Max Mustermann (admin_id 12) until 2026-09-17 14:05:10. Send force=true to take it over." }
  ],
  "timestamp": "2026-09-17 13:20:02",
  "records": [
    {
      "index": 1,
      "ticket_id": 33999,
      "status": "conflict",
      "claim": {
        "admin_id": 12,
        "admin_name": "Max Mustermann",
        "label": "KI-Agent",
        "claimed_at": "2026-09-17 13:05:10",
        "expires_at": "2026-09-17 14:05:10",
        "expires_in_seconds": 2708
      }
    }
  ]
}

Rilascio automatico

• Risposta pubblica al cliente, tramite API (PUT /Import/JSON/tickets) o nel backend. Non importa chi risponde.
• Passaggio a uno stato di chiusura. Chi salva nuovamente un ticket già chiuso non rilascia alcun claim.
• Scadenza del periodo di validità.

Una nota interna non sblocca il claim. Le operazioni di impostazione e sblocco non modificano né ticket_date_last_modified né la cronologia e non attivano eventi; l’ordinamento e l’esportazione delta (?last_modified=) rimangono inalterati. Per ogni ticket esiste al massimo un claim: su due richieste simultanee, solo una riceve conflict.

A partire dalla versione 4.9.73 dello Shop. Se la tabella ticket_claims non è ancora presente, l’endpoint risponde con un codice HTTP 503 TICKET_CLAIMS_UNAVAILABLE; lo Shop la creerà al prossimo allineamento dello schema (all’apertura di una pagina xoCRM o dell’HealthCheck).