Aller au contenu

API Gestion des tickets

L'ensemble des méthodes regroupées dans la rubrique "Order" permettent de consulter les commandes et les tickets associés pour l'API client StockTicket. Les méthodes décrites dans cette section permettent de gérer la récupération des tickets (billets) associés aux commandes.

Schéma général

Les tickets (billets) sont générés suite à la création d'une commande confirmée. StockTicket permet de récupérer ces billets dans différents formats (PDF, Apple Wallet, Google Wallet, etc.) en fonction des modules de génération de tickets configurés.

Logique d'enchaînement des méthodes

Le processus de récupération des tickets suit un enchaînement logique en 3 étapes :

  1. GetTicketFormats : Récupère la liste des formats disponibles pour les tickets de la commande
  2. GetTicketFile : Télécharge le fichier de ticket dans le format sélectionné
  3. GetTicketDetail (optionnel) : Consulte les informations détaillées des tickets sans télécharger de fichier

Méthodes de gestion des tickets

GetTicketFormats - Récupération des formats disponibles

Méthode : GET /Order/GetTicketFormats

Récupère la liste des formats de fichiers de ticket disponibles pour une commande donnée. Cette méthode doit être appelée en premier pour déterminer les formats dans lesquels les billets peuvent être générés.

Paramètres :
- orderToken (obligatoire) : Token d'identification de la commande fourni lors de la finalisation du processus de commande
- allowedMimeTypes (optionnel) : Liste des types MIME autorisés pour filtrer les formats (ex: ["application/pdf", "application/vnd.apple.pkpass"])
- usageSubCodes (optionnel) : Liste des sous-codes d'usage des fichiers de ticket à fournir (ex: ["googleWallet", "appleWallet"])
- mustAllowMultipleTickets (optionnel) : Si true, spécifie que le format doit pouvoir fournir un fichier unique pour plusieurs billets

Détails supplémentaires : - La méthode retourne une liste de formats disponibles avec leurs identifiants
- Un modèle d'URL est fourni pour télécharger directement les tickets
- L'URL contient des paramètres variables à remplacer : {{FormatItemToken}} et {{ticketIds}}

Réponses : - 200 OK : Retourne les formats disponibles et l'URL de téléchargement (ClientOrderTicketFormatModel)
- 400 Bad Request : Token invalide
- 404 Not Found : Aucun format de fichier de ticket disponible

Exemple de réponse :

{
  "formats": [
    {
      "formatIdentifier": "string",
      "format": {
        "formatId": "string",
        "allowMultipleTickets": true,
        "usage": "None",
        "usageSubCode": "string",
        "mimeType": "string",
        "extension": "string",
        "friendlyName": "string",
        "shortDescription": "string",
        "description": "string"
      }
    }
  ],
  "ticketUrl": "string"
}

GetTicketFile - Téléchargement d'un fichier de ticket

Méthode : GET /Order/GetTicketFile

Récupère un fichier de ticket au format attendu pour une commande donnée. Cette méthode doit être appelée après avoir récupéré la liste des formats disponibles via GetTicketFormats.

Paramètres : - orderToken (obligatoire) : Token d'identification de la commande
- formatIdentifier (obligatoire) : Identifiant du format dans la liste fournie par GetTicketFormats
- ticketIds (optionnel) : Liste d'identifiants de ticket séparés par une virgule. Si non renseigné, tous les tickets de la commande seront retournés

Note : Le formatIdentifier doit correspondre à l'un des formats retournés par la méthode GetTicketFormats.

Détails supplémentaires : - Le contenu du billet est encodé en base64
- Le fichier retourné contient également des métadonnées (nom de fichier, type MIME, etc.)
- Si plusieurs tickets sont demandés, ils peuvent être regroupés dans un seul fichier selon le format sélectionné
- La méthode fournit également l'URL directe de téléchargement du ticket

Réponses : - 200 OK : Retourne le fichier de ticket avec ses métadonnées (ClientTicketFileModel)
- 400 Bad Request : Token ou format invalide
- 404 Not Found : Aucun ticket trouvé pour la commande

Exemple de réponse :

{
  "file": {
    "mimeType": "application/pdf",
    "suggestedFileName": "file1.pdf",
    "fileSize": 12345,
    "base64Content": ".."
  },
  "ticketUrl": "string"
}

GetTicketDetail - Consultation des informations des tickets

Méthode : GET /Order/GetTicketDetail

Retourne les informations détaillées sur un ou plusieurs tickets associés à une commande, sans télécharger de fichier. Cette méthode permet de consulter les métadonnées des billets (numéro de place, catégorie tarifaire, etc.).

Paramètres : - orderToken (obligatoire) : Token d'identification de la commande
- ticketIds (optionnel) : Liste des identifiants de tickets attendus parmi ceux de la commande, séparés par une virgule. Si non renseigné, le détail de tous les tickets de la commande est retourné

Détails supplémentaires : - La méthode retourne uniquement les informations descriptives des tickets
- Utile pour afficher un récapitulatif des billets avant téléchargement
- Permet de récupérer les identifiants des tickets pour un téléchargement ciblé

Réponses : - 200 OK : Retourne la liste des tickets avec leurs détails (ListResult<TicketInfosDetailModel>)
- 400 Bad Request : Token invalide
- 404 Not Found : Aucun ticket trouvé pour la commande

Scénarios d'utilisation

Scénario 1 : Téléchargement de tous les tickets en PDF

  1. Appeler GetTicketFormats avec l'orderToken
  2. Sélectionner le format PDF dans la liste retournée (ex: formatIdentifier = "FMT-PDF-001")
  3. Appeler GetTicketFile avec l'orderToken et le formatIdentifier, sans spécifier ticketIds
  4. Récupérer le fichier PDF contenant tous les tickets

Scénario 2 : Affichage des informations avant téléchargement

  1. Appeler GetTicketDetail avec l'orderToken
  2. Afficher les informations des tickets à l'utilisateur (places, catégories, etc.)
  3. Proposer le téléchargement via GetTicketFormats puis GetTicketFile

Notes importantes

  1. Token de sécurité : L'orderToken est obligatoire pour toutes les méthodes et permet de sécuriser l'accès aux tickets. Ce token est fourni lors de la finalisation de la commande.

  2. Formats disponibles : Les formats de tickets disponibles dépendent des modules de génération de tickets configurés dans le back-office StockTicket. Si aucun module n'est configuré, aucun format ne sera disponible.

  3. Encodage du contenu : Le contenu binaire des fichiers de tickets est encodé en base64. Il doit être décodé avant utilisation (sauvegarde sur disque, affichage, etc.).

  4. Gestion des tickets multiples : Certains formats permettent de regrouper plusieurs tickets dans un seul fichier (ex: PDF, ZIP), tandis que d'autres nécessitent un fichier par ticket (ex: Apple Wallet). Utilisez le paramètre mustAllowMultipleTickets pour filtrer selon vos besoins.

  5. URL de téléchargement directe : L'URL fournie dans les réponses peut être utilisée directement pour télécharger les tickets, en remplaçant les paramètres variables {{FormatItemToken}} et {{ticketIds}}.