Présentation de l'API de rapports

Cet article présente l'API de rapports de ROLLER et les bonnes pratiques pour utiliser ses endpoints.

Consultez le journal des modifications de l'API pour rester informé des mises à jour de l'API ROLLER.

L'accès à l'API est une fonctionnalité payante de ROLLER. Contactez votre chargé de succès client ou l'équipe d'assistance si vous souhaitez vous abonner à cette fonctionnalité.

Aperçu

L'API de reporting permet aux établissements d'extraire une copie des données ROLLER et de les syndiquer vers une base de données externe, telle que des plateformes de business intelligence, d'analytique ou de cloud.

L'API de reporting ne permet pas d'écrire des données dans ROLLER et ne doit pas être utilisée pour des cas d'usage en temps réel, car elle ne permet pas d'interroger des enregistrements spécifiques et renvoie des données paginées sur une période donnée. Elle est optimisée pour l'export périodique d'enregistrements à une fréquence horaire ou quotidienne.

Documentation

Visitez le centre développeur ROLLER pour consulter la documentation des endpoints de l'API.

Accès

Pour les informations relatives à l'accès, à l'authentification, aux scopes et aux limites de débit, consultez le guide Présentation de l'API.

Bonnes pratiques

Selon le type et la quantité de données, les endpoints seront soit filtrés par date, soit fourniront toutes les données disponibles sans possibilité de filtrer davantage les enregistrements. Les endpoints qui exportent des types de données évoluant dans le temps seront filtrés selon la date de modification des enregistrements.

Les endpoints nécessitant un paramètre de date fournissent un maximum d'une journée de données par appel.

Date de modification

Les endpoints filtrés par date nécessitent un paramètre de requête de date de début et de fin au format yyyy-MM-dd ou yyyy-MM-ddTHH:mm:ss, basé sur le fuseau horaire associé à l'établissement, avec une plage de dates maximale d'un jour.

Le renvoi de données basé sur une date de modification exposera une version modifiée (modifications/mises à jour de données antérieures) et permettra à l'application consommatrice d'interroger efficacement les deltas des requêtes précédentes.

Si un enregistrement existant est mis à jour, nous vous recommandons d'effectuer l'une des actions suivantes :

1. Effectuer un PUT dans vos données, de sorte que la version modifiée remplace la version d'origine ; ou

2. Supprimer l'enregistrement d'origine et l'insérer avec la version modifiée.

Fréquence

Pour les fréquences quotidiennes, nous recommandons des appels programmés en début de matinée, par exemple à 02h00, pour la journée précédente en utilisant le paramètre de requête de date yyyy-MM-dd.

Si le cas d'usage nécessite des mises à jour plus fréquentes, des appels horaires doivent être mis en place en utilisant le format yyyy-MM-ddTHH:mm:ss, où startDate correspond à l'endDate du dernier appel.

De plus, nous recommandons aux applications consommatrices d'exécuter également un appel quotidien et de mettre à jour/remplacer les enregistrements comme décrit ci-dessus.

Endpoint de revenu

Le point de terminaison Revenus est une exception et NE filtre PAS en fonction de la date de modification, il filtre en fonction de la date de l'événement. Les enregistrements de réservation peuvent être mis à jour sans aucune modification de la date de l'événement.

Cependant, le point de terminaison Revenus permet à l'application consommatrice d'effectuer des requêtes en fonction de la référence de réservation, ce qui permet de récupérer des données ajustées sans interroger de grandes plages de dates, comme suit :

1. Identification d'un événement de revenu mis à jour
   Cette occurrence peut être identifiée lorsqu'un enregistrement dans la réponse du point de terminaison BookingItem contient un BookingModifiedDate qui ne se situe pas à +/- 5 secondes du BookingCreatedDate 

2. Appeler l'enregistrement de revenu associé
   Appelez le point de terminaison Revenus en interrogeant la réservation spécifique à l'aide des données de la réponse BookingItem pour filtrer, à savoir :

   • startDate et endDate = BookingDate 

   • bookingReferences = BookingReference

3. Mettre à jour l'enregistrement
   Comme décrit ci-dessus, effectuez un PUT ou supprimez et insérez ces données de revenu modifiées.

Cas d'utilisation

Dépenses et visites des invités

Création de fiches invités dans ROLLER

Les fiches invités sont créées dans ROLLER via deux méthodes principales.

1. Via une réservation en tant que titulaire de la réservation

2. En signant une décharge ou en faisant signer une décharge en leur nom

Point de terminaison des fiches invités - GET Customers.

Association des décharges signées et des invités

Un enregistrement de décharge signée comporte trois identifiants importants.

• SignedWaiverId – L'identifiant unique de l'enregistrement de décharge de cette personne spécifique

• ParentSignedWaiverId – L'identifiant unique (SignedWaiverId) de la décharge signée du parent qui a signé au nom d'un mineur

• CustomerId – Correspond au CustomerId dans le point de terminaison Customers

ParentSignedWaiverId ne sera renvoyé que pour les mineurs dont la décharge a été signée par un parent. Chaque individu disposera de son propre enregistrement de décharge signée. Ainsi, un parent ayant signé au nom de deux mineurs obtiendra trois enregistrements de décharge signée, ce qui entraînera la création ou la mise à jour de trois fiches invités uniques.

 Point de terminaison des enregistrements clients - GET Signed Waivers.

Association des invités aux réservations et aux billets

Les invités peuvent être associés à des réservations de deux façons :

1. En tant que propriétaire de la réservation (il ne peut y en avoir qu'un par réservation)

2. En ayant leur enregistrement de renonciation signé associé à un billet dans la réservation (un enregistrement de renonciation signé unique associé à chaque billet)

Dans le point de terminaison BookingItem, il existe un champ BookingCustomerId qui correspond au CustomerId du propriétaire de la réservation. Si un propriétaire de réservation est assigné, les dépenses liées à cette réservation peuvent être attribuées directement à cet invité.

Un propriétaire de réservation est assigné pour chaque réservation créée via la commande en ligne ; toutefois, il n'est souvent pas assigné par les opérateurs pour les réservations en point de vente.

Lorsque les établissements exigent des renonciations, ils demandent qu'une renonciation soit associée à un billet, et BookingSignedWaivers permet cette association avec le client. Une renonciation signée dans une réservation est un enregistrement d'une renonciation liée à un billet au sein de la réservation, et le point de terminaison BookingSignedWaivers renvoie trois identifiants clés :

1. L'attribut BookingReference est également présent dans la réponse du point de terminaison BookingItems ;

2. L'attribut TicketId est également présent dans la réponse du point de terminaison Tickets ;

3. SignedWaiverId L'attribut est également présent dans la réponse du point de terminaison Signed Waivers ;

Ces identifiants vous permettent d'associer des invités spécifiques à des réservations et à des billets individuels.

Fréquentation

Chaque BookingSignedWaiver peut être considéré comme une visite.

La réponse du point de terminaison Tickets inclut ProductId qui peut être utilisé pour quantifier le nombre de visites pour un produit spécifique si nécessaire. Cela peut être réalisé en associant les BookingSignedWaivers aux Tickets avec un ProductId particulier.

Le nombre de réservations dont un invité est propriétaire peut être utilisé ; cependant, le propriétaire de la réservation n'est souvent pas lui-même un participant (détenteur de billet) et ne serait donc pas associé à un BookingSignedWaiver.

Dépenses

Les dépenses peuvent être quantifiées de deux façons :

1. Propriétaire de la réservation
   Via le CustomerId associé aux réservations ; cependant, de nombreuses réservations en point de vente ne sont pas associées à un propriétaire de réservation.

2. Renonciations signées dans une réservation
   Cette méthode vous permet d'associer des clients spécifiques à des billets et de référencer le TicketId depuis le point de terminaison Revenu pour identifier les dépenses pour chaque billet.
   Si vous ne souhaitez pas attribuer des dépenses aux mineurs, vous devrez ajouter une logique pour référencer le ParentSignedWaiverId du mineur et attribuer les dépenses de manière appropriée.

Indicateurs d'adhésion

Identification des réservations d'adhésion

Les réservations d'adhésion n'ont pas de point de terminaison isolé ; elles constituent un type de produit. Le point de terminaison Products permet d'identifier les produits d'adhésion via l'attribut ProductSubType.

Avec le point de terminaison ProductId et le point de terminaison BookingItem, les articles d'adhésion peuvent être identifiés. Les réservations peuvent contenir plusieurs articles d'adhésion ; cependant, chaque adhésion disposera d'un enregistrement d'article de réservation unique avec une quantité de 1.

Identification des propriétés clés d'une adhésion

• Le statut de l'adhésion peut être identifié à partir du champ Meta du point de terminaison BookingItem. L'attribut Meta MembershipStatus renvoie le statut de l'adhésion.

• Le point de terminaison Statut de l'adhésion fournit un journal des données retraçant l'historique des changements de statut d'adhésion.

• Date de début de l'adhésion : l'attribut BookingDate de la réponse BookingItems indique la date à partir de laquelle l'adhésion était valide.

• Date d'annulation ou d'expiration : le point de terminaison Statut de l'adhésion fournit l'historique des événements d'annulation ou d'expiration.

• Le cycle de facturation de l'adhésion peut être identifié à partir du point de terminaison Tickets via l'attribut  RecurringPaymentFrequency , qui renvoie les valeurs quotidien, hebdomadaire, mensuel ou annuel. La date anniversaire correspond à la BookingDate renvoyée par le point de terminaison BookingItems.

• Les paiements récurrents d'adhésion peuvent être identifiés via l'attribut TransactionLocation (RecurringPayment) des données Revenues.
  Remarque : pensez à filtrer les enregistrements pour lesquels EventType est Transaction, afin d'exclure les tentatives de collecte de paiement ayant échoué. La valeur FundsReceived correspond au montant du paiement récurrent.

• Les échanges d'adhésion sont enregistrés de deux manières différentes. Le point de terminaison Échanges d'adhésion regroupe ces deux actions dans un seul ensemble de données d'échange :

  1. L'enregistrement de l'adhésion lors du check-in, qui génère un enregistrement dans le point de terminaison des présences

  2. L'utilisation de l'identifiant d'adhésion comme code de réduction pour acheter un autre produit (cas le plus courant)