Point d'arrivée du billet

Exemple : créer 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]
  }]
}

Format des commentaires

« ticket_comments » : « Note interne via l'API »,
« admin_id » : 1

ticket_comments correspond au texte du commentaire, admin_id à son auteur (0 = système, >0 = ID d'administrateur, validé).

Exemple : mise à jour d'un ticket avec un commentaire

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]
  }]
}

Dans l'exportation, chaque ticket contient un tableau linked_appointments[] avec les rendez-vous CRM associés :

« 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": ""
  } 
]

Les rendez-vous sont associés via xocrm_appointments_relationships (target_type = ticket_id). La suppression d'un ticket supprime uniquement le lien, et non le rendez-vous lui-même.

Corrigé dans la v2.118.1 : l'appel de ` linked_appointments ` vers ` POST` / `PUT /Import/JSON/tickets ` générait en plus l'avertissement « UNKNOWN_FIELD », bien que les rendez-vous aient été créés. L'avertissement a été supprimé ; le traitement reste inchangé.

Les pièces jointes sont identifiées par l'ID du ticket :

Extrait : 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"
    }
  ]
}

Téléchargement : GET /ticket_attachment/{id}?file=screenshot.png

Téléchargement binaire avec un type de contenu (Content-Type) et une disposition de contenu (Content-Disposition) corrects : en-tête « attachment ». Protection contre le parcours de chemin via la validation basename() + realpath().

Téléversement : attachments[] via POST/PUT NOUVEAU v2.60.0

Jusqu’à la v2.59.0, les pièces jointes étaient uniquement en lecture — elles étaient exclusivement ajoutées via le formulaire du backend. Un ticket créé via l’API restait donc sans pièce jointe (PDF, .eml, capture d’écran). Depuis la v2.60.0, la requêtePOST/PUT /Import/JSON/tickets accepte le champ optionnel attachments[]:

« ticket_comments » : « Pièce jointe à la réclamation »,
« admin_id » : 1,
« attachments » : [
 {
    "name": "rechnung.pdf",
    "content_base64": "JVBERi0xLjQKJcfs…"
  } 
]

Le stockage s'effectue selon le même mécanisme que le téléchargement vers le backend : même liste blanche d'extensions, même convention de nommage __ et déduplication par hachage pour éviter les doublons. Le nom de fichier effectivement attribué figure, pour chaque enregistrement, dans la réponse sous « attachments ». La limite maximale par fichier correspond au point de terminaison /media(XOPORT_MEDIA_MAX_FILESIZE, par défaut 10 Mo).

Les entrées erronées (extension non autorisée, Base64 non valide, taille dépassée) génèrent une erreur par fichier; la mise à jour du ticket elle-même reste réussie. Si is_public_reply : true est associé à notify_customer : true, les fichiers sont envoyés avec l’e-mail du client — ils sont enregistrés avant l’envoi.

Une revendication indique qu’une personne travaille actuellement sur un ticket, par exemple un agent IA mandaté par un collaborateur. Les autres intervenants le voient dans l’exportation et dans le backend (liste des tickets et vue du ticket) et ne commencent pas à travailler en parallèle. La revendication est une indication, pas un verrouillage : aucun accès en écriture ne la vérifie, le ticket reste modifiable par tous.

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

Résultat par enregistrement

records[].status indique le résultat, records[].claim l'état après l'appel :

Réponse (HTTP 200) lorsqu’un autre administrateur envoie une requête alors que Max Mustermann détient la revendication :

{
  "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
      }
    }
  ]
}

Validation automatique

• Réponse publique au client, via l’API (PUT /Import/JSON/tickets) ou dans le backend. Peu importe qui répond.
• Passage à un statut « Fermé ». Quiconque enregistre à nouveau un ticket déjà fermé ne libère pas de réclamation.
• Expiration de la durée de validité.

Une note interne ne libère pas la revendication. Les actions « Définir » et « Libérer » ne modifient ni ticket_date_last_modified ni l’historique et ne déclenchent aucun événement ; le tri et l’exportation delta (?last_modified=) ne sont pas affectés. Il n’y a qu’une seule revendication par ticket : parmi deux demandes simultanées, une seule reçoit conflict.

À partir de la version 4.9.73 de la boutique. Si le tableau ticket_claims n’existe pas encore, le point de terminaison renvoie un code HTTP 503 TICKET_CLAIMS_UNAVAILABLE; la boutique le crée lors de la prochaine synchronisation du schéma (à l’ouverture d’une page xoCRM ou du HealthCheck).