API Billetterie Mapado Pro - Faire un premier appel en lecture (GET) et comprendre les paramètres

API Billetterie Mapado Pro - Faire un premier appel en lecture (GET) et comprendre les paramètres

La billetterie Mapado Pro est construite sur une API. Ce parti pris d'ouverture permet de faire communiquer la billetterie Mapado Pro avec des systèmes d'information tiers.

Voici quelques usages que permet l'API Billetterie Mapado Pro : 
  1. Intégrer les événements qui ont été publiés dans la billetterie Mapado Pro dans votre site web (éviter la double saisie)
  2. Pré-publier les événements saisis sur votre site dans la billetterie Mapado Pro (éviter une partie de la double saisie)
  3. Mettre à jour la disponibilité d'un spectacle sur votre site en fonction des places restantes
  4. Importer dynamiquement les données de vente de la billetterie Mapado Pro dans un logiciel tiers

Pour profiter de l'API Billetterie Mapado Pro, il faut disposer de quelques compétences en programmation. Nous vous recommandons de vous adresser à votre agence ou à votre webmaster pour savoir ce qu'il est possible de faire dans votre situation.

L'API Billetterie Mapado Pro est une API de type REST dont vous trouverez la documentation sur le lien ci-dessous :

Vous identifier sur l'API Billetterie Mapado Pro


Pour accéder à l'API, il faut disposer d'un jeton d'authentification (token) a passer dans les headers des requêtes HTTP.
Chaque appel à l'API doit intégrer le jeton d'authentification dans le header de l'appel avec une clé "Authorization" qui contient "Bearer xxxxxxxxx"
(remplacer xxxxxxx par le jeton obtenu précédemment)

Nous vous conseillons d'utiliser l'outil gratuit Postman afin d'effectuer vos premiers tests.

Réaliser votre premier appel d'API Billetterie Mapado Pro


En utilisant l'outil Postman, effectuez une premier appel GET sur le endpoint suivant.
  1. GET https://ticketing.mapado.net/v1/ticketings?contract=xxxx&itemsPerPage=10&fields=@id,title
N'oubliez pas d'ajouter la clé "Authorization" comme évoqué dans le chapitre sur l'identification.

Ci-dessous, l'appel en question effectué avec l'outil curl.
  1. curl -X GET   'https://ticketing.mapado.net/v1/ticketings?contract=xxxx&itemsPerPage=10&fields=title' \
  2. -H 'Authorization: Bearer MmU3ZTQ2MmM5ZjVsZZMTEyYWUzMjA5YjE0MGVhMTZhNzA1NmE2NGY0Y2Y1N2JhN2RlYzQ3Yjg5ZDExOGEzYQ'

Ce premier appel devrait vous renvoyer un résultat au format .json dont le début ressemble à ce qui se trouve ci-dessous (remplacez xxxxxx et yyyyyy par les titres de vos événements)
  1. {
  2. "@context": "/v1/contexts/Ticketing",
  3. "@id": "/v1/ticketings",
  4. "@type": "hydra:PagedCollection",
  5. "hydra:member": [
    1. {
      1. "@id": "/v1/ticketings/599",
      2. "@type": "Ticketing",
      3. "@context": "/v1/contexts/Ticketing",
      4. "title": "xxxxxxxxxxxx"
    2. },
    3. {
      1. "@id": "/v1/ticketings/601",
      2. "@type": "Ticketing",
      3. "@context": "/v1/contexts/Ticketing",
      4. "title": "yyyyyyyyyyyyyyy"
    4. },

Si vous obtenez une erreur 401 c'est que vous avez oublié d'ajouter la clé "Authorization" ou bien que votre jeton d'authentification est incorrect.
Si vous obtenez une erreur 403 c'est que votre jeton est bien reconnu mais que vous n'avez pas les droits d'accès à cette ressource.

Explication des paramètres fréquents

Décomposons le premier appel effectué
  1. https://ticketing.mapado.net/ : indique l'url de l'API Mapado billetterie
  2. /v1 : indique que l'API Mapado est dans sa version n°1.
  3. /ticketings : indique que c'est le endpoint "ticketings" qui est appelé (consulter la liste des endpoints)

Un certain nombre d'autres paramètres sont présents dans la requête.

Paramètre "contract=xxxx"

Celui-ci est a passer systématiquement pour limiter la recherche uniquement à vos données.
Certaines données publiques sont accessible au delà de votre compte mais l'usage est très rare.

Paramètre "itemsPerPage"

Il permet de limiter le nombre de résultats renvoyés par l'API.

Nous vous déconseillons de dépasser un nombre d'itemsPerPage supérieur à 100 : cela peut fortement ralentir votre application.
Nous pourrions être amené à suspendre les comptes API qui abuseraient sur cette valeur

A noter que le .json renvoyé contient également le nombre d'items total de la requête dans la clé : "hydra:totalItems" ainsi que l'adresse de la requête pour la première, dernière et prochaine page dans respectivement les clés : hydra:first, hydra:last et hydra:next stockées dans la clé hydra:view (cf exemple ci-dessous)

  1.     "hydra:totalItems": 190,
  2.     "hydra:view": {
  3.         "@id": "/v1/ticketings?user=me&itemsPerPage=5&fields=%40id%2Ctitle&page=1",
  4.         "@type": "hydra:PartialCollectionView",
  5.         "hydra:first": "/v1/ticketings?user=me&itemsPerPage=5&fields=%40id%2Ctitle&page=1",
  6.         "hydra:last": "/v1/ticketings?user=me&itemsPerPage=5&fields=%40id%2Ctitle&page=38",
  7.         "hydra:next": "/v1/ticketings?user=me&itemsPerPage=5&fields=%40id%2Ctitle&page=2"


Paramètre "Fields"

C'est un paramètre obligatoire qui permet de limiter les champs retournés par le endpoint. En limitant les données renvoyées, vous rendez vos appels plus rapides.
Dans notre exemple, nous avons limité les champs renvoyés aux champs id et title.

Si vous n'avez besoin que du titre de votre événement, inutile de demander tous les autres champs ce qui aura pour effet d'augmenter la quantité de données transférée.

Vous pouvez obtenir un liste exhaustive des champs (fields) disponibles pour une endpoint donné en effectuant un appel GET sur le endpoint suivant : 

A noter que le nom à passer en fin d'url est celui de l'objet indiqué en tête de page de la documentation d'API : 
Pour le endpoint /ticketing, l'appel contexts a effectuer se fait sur https://ticketing.mapado.net/v1/contexts/Ticketing (avec un T majuscule)

Il est possible de chaîner les fields pour récupérer des informations d'un enpoint lié. Par exemple
Permet de récupérer la séance numéro 145020 tout en demandant le titre de l'événement (ticketing) lié.

Champs de type "borne" pour les dates

Les champs before et after, disponibles sur certains endpoint permettent de fixer des "bornes" de date, pour filtrer par mois par exemple.

Description des endpoint les plus utiles

Vous trouverez ci-dessous une liste des enpoints les plus utilisés.

  1. Ticketing : décrit un événement (nom, description, localisation)
  2. Venue : décrit un lieu dans lequel se passe un événement : adresse, ville, ...
  3. EventDate : décrit une séance (dates auxquelles se déroulent un événement). Un événement peut être relié à plusieurs séances
  4. TicketPrice : décrit un tarif (d'une place) : montant, nom, taux de tva, disponibilité, ... Plusieurs tarifs peuvent être reliés à une séance
  5. Order : liste les commandes effectuées : numéro, identifiant du client, ...
  6. OrderItem : détaille les éléments d'une commande
  7. Customer : l'acheteur d'une commande : nom, prénom, adresse, ...
  8. Ticket : décrit un billet : nom, code barre, événement associé, date de validité


Article associé
  1. API Billetterie Mapado Pro - Obtenir des clés d'API