Aller au contenu

API catalogue/agenda

L'ensemble des méthodes regroupées dans la rubrique "Catalog" permet à une application cliente de rechercher des représentations (dates d'événements) et d'obtenir le détail d'une représentation dans le catalogue StockTicket.

Elle contient 2 méthodes:
- GetEventDateList : pour rechercher des représentations selon différents critères
- GetEventDateDetail : pour obtenir le détail d'une représentation spécifique

L'appel à ces méthodes nécessite de fournir une clé d'API valide pour s'authentifier (voir le guide Authentification).

Dans une cinématique classique, une application cliente (site web, application mobile, etc.) interrogera en premier lieu la méthode GetEventDateList pour obtenir une liste de représentations disponibles selon des critères choisis et les identifiants et données nécessaires pour interroger la méthode GetEventDateDetail.

1. Rechercher des représentations

Méthode POST /api/v1/Catalog/GetEventDateList

Description

Permet de rechercher les représentations disponibles selon différents critères : dates, lieu, événement, étiquettes, classifications, attractions, etc.
La réponse contient une liste paginée d'éléments résumés pour chaque représentation. La propriété TemporalityMode de chaque item indique la temporalité de la représentation, qui peut être standard, horodatée ou à open. - Les reprénsetations standard ont une date et heure fixes et sont associées à un plan de salle. - Les représentations horodatées disposent d'un calendrier de disponibilités, accessible depuis le détail de la représentation ou via les endpoints GetEventDateCalendar et GetEventDateCalendarDateDetail.

Paramètres d'entrée

Le corps de la requête doit contenir un objet CatalogListParameters. Pour plus de détails sur les paramètres disponibles, consultez la documentation Swagger de la méthode.

Au sujet du paramètre MediaRequests

Le paramètre MediaRequests permet de décrire une demande de médias asspcoiés à récupérer. La clé de chaque propriété est un nom libre que vous définissez pour identifier le type de média souhaité. En retour, le même objet sera retourné avec les informations de média récupérées, ou null si le média n'a pas été trouvé.

Structure
{ "nomPersonnalise1": { "targetId": "identifiant_cible_image", "height": 100, "width": 200 }, "nomPersonnalise2": { "targetId": "autre_cible", "height": 50 } }

Propriétés de chaque élément MediaRequest

Champ Type Requis Description
targetId string? Non Identifiant de la cible d'utilisation de l'image (ex: "event1x1", "banner", "thumbnail")
height int? Non Hauteur souhaitée en pixels (pour aider à la sélection si plusieurs images disponibles)
width int? Non Largeur souhaitée en pixels (pour aider à la sélection si plusieurs images disponibles)

Exemples de requête

** Recherche basique**

{ "FromDate": "2025-01-01", "ToDate": "2026-10-31", "SearchString": "festival", "PageSize": 10, "PageNumber": 0, "SealeableOnly": false}
** Recherche avec médias ** 
{ "FromDate": "2025-01-01", "ToDate": "2026-10-31", "PageSize": 10, "PageNumber": 0, "SortOrders": "DateAndTime", "SealeableOnly": true, "MediaRequests": { "thumbnail": { "targetId": "event1x1small", "height": 100, "width": 100 }, "banner": { "targetId": "r15x2", "height": 50 } } }

Exemple de réponse

** Exemple de réponse avec médias**

{ "totalCount": 45, "list": [ { "eventDateId": "ed-123456", "label": "Concert Jazz Quartet", "dateAndTime": "2025-10-15T20:30:00", "event": { "eventId": "evt-789", "label": "Festival Jazz d'Automne" }, "state": { "isAvail": true, "minAvailPrice": { "price": 25.00 } }, "mediaReferences": { "thumbnail": { "url": "https://media.stockticket.com/eventdate/ed-123456/imgt/event1x1small?width=100&height=100", "width": 100, "height": 100 }, "banner": { "url": "https://media.stockticket.com/eventdate/ed-123456/imgt/r15x2?height=50", "width": 375, "height": 50 } } } ] }

2. Détail d'une représentation

Méthode POST /api/v1/Catalog/GetEventDateDetail?eventDateId={id}

Description

Permet d'obtenir les informations détaillées sur une représentation spécifique, en précisant le niveau de détail attendu pour chaque section (infos générales, lieu, classifications, attractions, tarifs, salle, médias…).
⚠️ Les paramètres d'appel et le résultat peuvent être influencés par la temporalité de l'événement (standard, horodaté, ...) :

  • Evénement standard :

    • PricingDetailLevel : indique la présence ou non ainsi que le niveau de détail des informations tarifaires PricesInfos de la représentation dans les informations retournées.
    • RoomDetailLevel : indique la présence ou non ainsi que le niveau de détail des informations sur la salle VenueInfos de la représentation dans les informations retournées.
    • CalendarLevel, CalendarStart, CalendarEnd : non pris en compte.

  • Evénement horodaté :

    • CalendarLevel : si différent de None, demande à ce que le calendrier des disponibilités soit retourné dans le détail de la représentation (propriété CalendarInfos).
    • CalendarStart : date de début du calendrier des disponibilités; si non spécifié, on prend la date de fin ou à défaut la première date disponible dans le calendrier.
    • CalendarEnd : date de fin du calendrier des disponibilités; si non spécifié, on prend la date de début + 42 jours (6 semaines).
    • PricingDetailLevel : niveau de détail des prix intégrés dans le calendrier des disponibilités.
    • RoomDetailLevel : non pris en compte.

Exemples de requête

`POST /api/v1/Catalog/GetEventDateDetail?eventDateId=EVTD-xyz`
{ "GeneralInfosDetailLevel": "Full", "VenueDetailLevel": "Basic", "PricingDetailLevel": "Full" }

Exemple de réponse

{ "eventDateId": "ed-123456", "label": "Concert Jazz Quartet - Soirée Exceptionnelle", "dateAndTime": "2025-10-15T20:30:00", "maxTicketsInBasket": 10, "venueInfos": { "name": "Salle Pleyel", "address": "252 Rue du Faubourg Saint-Honoré, 75008 Paris" }, "pricesInfos": { "isAvail": true, "priceCategories": [ { "id": "cat-standard", "name": "Tarif Standard", "priceItems": [ { "id": "item-adult", "label": "Adulte", "isDefault": true, "prices": [ { "minQuantity": 1, "price": 35.00 } ] } ] } ] }, "mediaReferences": { "hero": { "url": "https://media.stockticket.com/eventdate/ed-123456/imgt/event16x9?width=800&height=450", "width": 800, "height": 450, "legend": "Concert Jazz Quartet en live" }, "gallery": { "url": "https://media.stockticket.com/eventdate/ed-123456/imgt/event4x3?width=400&height=300", "width": 400, "height": 300 }, "description": null } }

3. Calendrier de disponibilités d'une représentation horodatée

Méthodes POST /api/v1/Catalog/GetEventDateCalendar?eventDateId={id}
et POST /api/v1/Catalog/GetEventDateCalendarDateDetail?eventDateId={id}

Description

Permettent d'obtenir le calendrier des disponibilités d'une représentation horodatée.

  • GetEventDateCalendar retourne la liste des dates disponibles avec un niveau de détail réduit (sans les créneaux de chaque jour ni le détail des tarifs disponibles).
  • GetEventDateCalendarDateDetail retourne le détail d'une date spécifique du calendrier, avec la liste des créneaux disponibles pour cette date et le détail des tarifs associés à chaque créneau.
    Ce sont les éléments retournés par ce endpoint qui peuvent être placés dans un panier.